Skip to main content

tun

tun:
  disabled: false
  dev: nebula1
  drop_local_broadcast: false
  drop_multicast: false
  tx_queue: 5000
  mtu: 1300
  routes:
    - mtu: 8800
      route: 10.0.0.0/16
  unsafe_routes:
    - route: 172.16.1.0/24
      via: 192.168.100.99
      mtu: 1300 # mtu will default to tun mtu if this option is not specified
      install: true # controls whether this route is installed in the systems routing table.

tun.disabled​

Default: false

Allows the nebula interface (tun) to be disabled, which lets you run a lighthouse without a nebula interface (and therefore without root). You will not be able to communicate over IP with a nebula node that uses this setting.

tun.dev​

dev sets the interface name for your nebula interface. If not set, a default will be chosen by the OS.

  • Linux: any valid interface name. Nebula refuses to start if an interface with that name already exists, including a persistent tun device created ahead of time with ip tuntap add, or one held by another running nebula.
  • macOS: if set, must be in the form utun[0-9]+. Any other name logs a warning and the first free utun device is used.
  • FreeBSD: any valid interface name. If /dev/<dev> does not exist, a new tun device is created and renamed to dev.
  • OpenBSD and NetBSD: if set, must be in the form tun[0-9]+. Any other name logs a warning and the first free tun device is used.

Changing dev takes effect after a restart. On macOS, OpenBSD, and NetBSD a reload only asks for a restart when dev names a specific device other than the one in use.

tun.drop_local_broadcast​

Default: false

Toggles forwarding of local broadcast packets, the address of which depends on the ip/mask encoded in pki.cert

tun.drop_multicast​

Default: false

Toggles forwarding of multicast packets

tun.tx_queue​

Default: 5000

Sets the transmit queue length, if you notice lots of transmit drops on the tun it may help to raise this number. Default is 5000. This setting only applies on Linux.

tun.mtu​

Default: 1300 Reloadable: Linux

Default MTU for every packet, safe setting is (and the default) 1300 for internet routed packets.

The largest MTU Nebula can carry is 8937. A larger value here, or on any route in tun.routes or tun.unsafe_routes, is capped to 8937 with a warning. On Windows, the MTU must be at least 1280 when the overlay carries IPv6, the same as on Linux.

Where the tun device is handed to Nebula by a host app, such as on iOS, Android, or a macOS network extension, the host app owns the MTU and this setting is ignored.

See below for per-route overrides (tun.routes).

tun.routes​

Reloadable

Route based MTU overrides. If you have known VPN IP paths that can support larger MTUs you can increase/decrease them here. This will override the default MTU (tun.mtu) for Nebula packets on a per-route basis. Route MTUs are only applied on Linux, other platforms log a warning and use tun.mtu.

tun:
  routes:
    - mtu: 8800
      route: 10.0.0.0/16

tun.unsafe_routes​

Reloadable
warning

The nebula certificate of the via node MUST have the route defined in the subnets list in its certificate or it will silently refuse to route traffic.

Unsafe routes allows you to route traffic over nebula to non-nebula nodes. Unsafe routes should be avoided unless you have hosts/services that cannot run nebula.

tun:
  unsafe_routes:
    - route: 172.16.1.0/24
      via: 192.168.100.99
      mtu: 1300
      metric: 100
      install: true # controls whether this route is installed in the systems routing table.

Each entry takes:

  • route: the CIDR to route over nebula. Required.
  • via: the vpn address of the nebula host that forwards the traffic, or a list of gateways (see ECMP support). Required.
  • mtu: the MTU for this route. Defaults to tun.mtu, must be at least 500, and is capped to 8937. Only applied on Linux.
  • metric: the metric of the installed system route, from 0 to 2147483647. Defaults to 0. Applied on Linux and Windows. On Windows, changing only the metric on reload updates the existing route in place.
  • install: whether the route is installed in the system routing table. Defaults to true. Set to false when something else, such as a routing daemon, installs the route.

Numbers may be quoted, e.g. metric: "100". If the same route is listed more than once, Nebula logs a warning and only the last entry is used.

For more information, see the Extending network access beyond overlay hosts guide.

unsafe_routes on macOS​

macOS keeps a single route per destination. If another interface already routes an unsafe route's destination, such as the local network you are connected to, Nebula logs a warning and leaves that route alone. Nebula installs its own route once the other one is removed, for example after moving to a different network.

If Nebula's route is deleted by hand, it stays deleted until Nebula reloads or restarts, or until another interface routes the destination and later lets it go.

ECMP support for unsafe_routes​

Added in v1.10.0

Equal-Cost Multi-Path routing is now available for unsafe_routes, enabling load balancing and redundancy within a single host. You can now configure multiple gateways for the same route on one host, with optional weighting for unequal load distribution.

unsafe_routes:
  # Multiple gateways with equal weighting (default weight: 1)
  - route: 192.168.100.0/24
    via:
      - gateway: 10.0.0.1
      - gateway: 10.0.0.2

  # Multiple gateways with custom weights
  - route: 192.168.101.0/24
    via:
      - gateway: 10.0.0.1
        weight: 10
      - gateway: 10.0.0.2
        weight: 5

The implementation uses hash-threshold mapping (similar to the Linux kernel) to distribute traffic based on packet hashing. When a gateway becomes unreachable, traffic automatically fails over to the remaining available gateways, though load balancing may become uneven until the failed gateway recovers.

tun.network_category​

Default: private Added in v1.11.0

This option is only supported on Windows.

Sets the Windows network category of the nebula interface. Without it, Windows often leaves the network as "Unidentified" and treats it as Public, which makes the host firewall more restrictive than you usually want for an overlay between trusted peers. Valid values are:

  • private: treat the nebula network as a private, trusted network.
  • public: treat it as a public, untrusted network.
  • domain: treat it as a domain-authenticated network.
  • unset: leave whatever Windows decided alone.

Changing this takes effect after a restart. An invalid value refuses to start, and fails the reload.

tun.windows_bypass_wdf​

Default: true Added in v1.11.0

This option is only supported on Windows.

When true, Nebula installs a WFP (Windows Filtering Platform) PERMIT filter scoped to the nebula interface. WFP sits below Windows Defender Firewall, so inbound traffic on the nebula interface is allowed regardless of Defender Firewall rules, and Nebula's own firewall decides what is allowed. The filter is removed when the interface goes away. Set to false to leave Windows Defender Firewall in charge. See listen.windows_bypass_wdf for the matching control over Nebula's UDP listener. Changing this takes effect after a restart.

DNS registration on Windows​

Nebula turns off DNS registration for its Windows interface, so the overlay addresses are not registered in Active Directory DNS or any other dynamic DNS server the host uses.

tun.use_system_route_table​

Default: false Added in v1.7.0

This option is only supported on Linux.

Set to true to manage unsafe routes directly on the system route table with gateway routes instead of in nebula configuration files.

tun.use_system_route_table_buffer_size​

Default: 0 Added in v1.10.0

This option is only supported on Linux.

Buffer size for reading route updates. 0 means the system default buffer size is used (/proc/sys/net/core/rmem_default). If using massive route updates, for example BGP, you may need to increase this value to avoid packet loss. SO_RCVBUFFORCE is used to avoid having to raise the system wide max.

tun.use_offloads​

Default: false Added in v1.12.0

This option is only supported on Linux and is not reloadable.

When enabled, Nebula attempts to enable segmentation offloads on the tun device. The host network stack can then hand Nebula TCP and UDP payloads much larger than the MTU in a single read, and accept large coalesced packets on write, substantially reducing per-packet overhead for high-throughput flows. Nebula negotiates the best supported mode at startup (TSO with USO, then TSO alone on kernels older than 6.2, then no offloads) and logs the result in the TUN offload status message. Offloads are never used on a tun device that is handed to Nebula already open.

For the biggest throughput gains, pair this option with listen.udp_offloads.

tun.pin_threads​

Default: true Added in v1.12.0

This option is only supported on Linux and is not reloadable. It only takes effect when routines is greater than 1.

When enabled, each tun reader/encrypt OS thread is pinned to a single CPU. This keeps every thread's batched sends flowing through one XPS-selected NIC transmit ring, so packets within a flow stay ordered on the wire instead of being sprayed across multiple transmit rings and reordered.

Unless tun.cpu_affinity overrides it, Nebula picks the CPUs to pin to automatically: it prefers performance cores on heterogeneous CPUs (ARM big.LITTLE, Intel P/E hybrids, AMD compact cores), keeps all readers on one NUMA node and on distinct physical cores when the topology allows (SMT siblings last), leaves CPU 0's physical core as a last resort, and rotates its starting point per instance so multiple Nebula instances on the same host don't stack their readers onto the same cores.

tun.cpu_affinity​

Added in v1.12.0

This option is only supported on Linux and is not reloadable. It only applies while tun.pin_threads is true and routines is greater than 1.

Overrides which CPUs the tun reader threads pin to: a list of CPU IDs, one per routine (see routines). A list shorter than routines is cycled across the queues; extra entries are ignored. IDs must be within the process's allowed CPU set, so the list respects taskset and cgroup cpusets. If any entry is not an integer or not in the allowed set, the whole override is ignored and Nebula falls back to the automatic selection described under tun.pin_threads.

tun:
  cpu_affinity:
    - 2
    - 4

tun.pin_threads_key​

Default: pid Added in v1.12.0

This option is only supported on Linux and is not reloadable. It only applies while tun.pin_threads is true, routines is greater than 1, and no tun.cpu_affinity override is set.

Controls how the automatic CPU selector varies its starting point between Nebula instances. Valid values are pid and port. Use port if you want Nebula to choose the same cores every run (keyed by the bound UDP port), which is useful for reproducible benchmarking. An unknown value, or port when Nebula cannot read its bound port, logs a warning and uses pid.