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 that does not already exist.
  • macOS: if set, must be in the form utun[0-9]+.
  • 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]+.

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. 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 maximum MTU is 8937, here and on any route in tun.routes or tun.unsafe_routes. When the overlay carries IPv6, the MTU must be at least 1280.

On iOS, Android, and macOS network extensions, the MTU is set by the host app 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.

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, from 500 to 8937. Defaults to tun.mtu. Only applied on Linux.
  • metric: the metric of the installed system route, from 0 to 2147483647. Defaults to 0. Applied on Linux and Windows.
  • 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.

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

unsafe_routes on macOS​

macOS allows 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's route is installed only after the other one is removed, for example after moving to a different network. A Nebula route deleted by hand stays deleted until Nebula reloads or restarts.

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. Otherwise Windows often treats the network as Public, which applies a more restrictive host firewall profile. 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: keep the category Windows assigns.

tun.windows_bypass_wdf​

Default: true Added in v1.11.0

This option is only supported on Windows.

When true, a WFP (Windows Filtering Platform) PERMIT filter is installed for the nebula interface. WFP is evaluated below Windows Defender Firewall, so inbound traffic on the nebula interface is controlled only by Nebula's own firewall. When false, Defender Firewall rules also apply. See listen.windows_bypass_wdf for the UDP listener.

DNS registration on Windows​

DNS registration is disabled on the nebula interface, so 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.

Enables segmentation offloads on the tun device, so TCP and UDP payloads much larger than the MTU are read and written in a single operation, reducing per-packet overhead for high-throughput flows. The best supported mode is selected at startup (TSO with USO, TSO alone on kernels older than 6.2, or none) and logged in the TUN offload status message. Offloads are not used on a tun device that is passed 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 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 each thread's batched sends on one XPS-selected NIC transmit ring, so packets within a flow are not reordered across transmit rings.

Unless tun.cpu_affinity overrides it, CPUs are selected automatically. Performance cores are preferred on heterogeneous CPUs (ARM big.LITTLE, Intel P/E hybrids, AMD compact cores), readers are kept on one NUMA node and on distinct physical cores when possible (SMT siblings last), CPU 0's physical core is a last resort, and the starting point rotates per instance so multiple Nebula instances on the same host don't share cores.

tun.cpu_affinity​

Added in v1.12.0

This option is only supported on Linux, and 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. 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.

tun:
  cpu_affinity:
    - 2
    - 4

tun.pin_threads_key​

Default: pid Added in v1.12.0

This option is only supported on Linux, and 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 selection varies its starting point between Nebula instances. Valid values are pid and port. Use port to select the same cores on every run (keyed by the bound UDP port), for reproducible benchmarking.