Skip to main content

tun

tun:
  disabled: false
  dev: nebula1
  drop_local_broadcast: false
  drop_multicast: false
  tx_queue: 500
  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. For macOS: Not required. If set, must be in the form utun[0-9]+. For FreeBSD: Required to be 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: 500

Sets the transmit queue length, if you notice lots of transmit drops on the tun it may help to raise this number. Default is 500.

tun.mtu​

Default: 1300 Reloadable: Linux

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

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.

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.

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

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.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.

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.

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 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.