Skip to main content

listen

listen sets the UDP port Nebula will use for sending/receiving traffic and for handshakes.

listen:
  host: 0.0.0.0
  port: 4242
  batch: 64
  read_buffer: 3412512
  write_buffer: 3412512

listen.host and listen.port are not reloadable. Changing either takes effect after a restart.

listen.host​

Default: 0.0.0.0

host is the ip of the interface to use when binding the listener. The default is 0.0.0.0 for all IPv4 interfaces. To enable IPv6, use '::' instead, which listens on both IPv4 and IPv6. The older '[::]' form is still accepted. host may also contain a hostname.

host decides whether Nebula uses IPv6 on the underlay network at all. With an IPv4 address here, including the default 0.0.0.0, Nebula cannot send to or receive from IPv6 addresses, so it ignores the IPv6 addresses of its peers, whether learned from a lighthouse or from static_host_map, and it does not report its own IPv6 interface addresses to lighthouses. IPv6 addresses listed in lighthouse.advertise_addrs are still advertised. A lighthouse with an IPv4 socket still stores and hands out the IPv6 addresses other hosts report.

listen.port​

port is the UDP port nebula should use on a host. For a lighthouse node, the port should be defined, conventionally to 4242, however using port 0 or leaving port unset will dynamically assign a port and is recommended for roaming nodes. Using 0 on lighthouses and relay hosts will likely lead to connectivity issues.

listen.batch​

Default: 64

Sets the max number of packets to pull from the kernel for each syscall (under systems that support recvmmsg). Only used on Linux. Values below 1 are treated as 1. Not reloadable.

When listen.udp_offloads has enabled GRO, each receive slot is sized for a full 64KiB coalesced superpacket, so the receive scratch memory is batch × 64KiB per listening socket (about 4MiB per routine at the default of 64). Lower this value to trade peak per-syscall throughput for memory on constrained hosts.

listen.read_buffer, listen.write_buffer​

Reloadable

This option is only supported on Linux.

Configure socket buffers for the udp side (outside), leave unset to use the system defaults. Values will be doubled by the kernel. Default is net.core.rmem_default and net.core.wmem_default (/proc/sys/net/core/rmem_default and /proc/sys/net/core/wmem_default).

Nebula first tries SO_RCVBUFFORCE and SO_SNDBUFFORCE, which avoid having to raise the system wide max (net.core.rmem_max and net.core.wmem_max) but need the CAP_NET_ADMIN capability. Without it, Nebula falls back to SO_RCVBUF and SO_SNDBUF, which the kernel limits to the system wide max. When the buffer ends up smaller than requested, Nebula logs a warning such as listen.read_buffer was limited by the system; raise net.core.rmem_max / net.core.wmem_max or grant CAP_NET_ADMIN to fix it.

Removing a value on reload leaves the socket at its current size until Nebula restarts.

listen.send_recv_error​

Reloadable Default: always Added in v1.6.0

By default, Nebula replies to packets it has no tunnel for with a recv_error packet. This packet helps speed up reconnection in the case that Nebula on either side did not shut down cleanly. This response can be abused however as a way to discover if Nebula is running on a host. send_recv_error lets you configure if you want to send recv_error packets always, never, or only to private network remotes.

Valid values: always, never, private

listen.accept_recv_error​

Reloadable Default: always Added in v1.10.1

Controls whether Nebula accepts recv_error packets from remote hosts. This is the counterpart to send_recv_error — while send_recv_error controls whether your node sends these packets, accept_recv_error controls whether your node acts on them when received.

Valid values: always, never, private

listen.so_mark​

Default: 0 Reloadable Added in v1.10.0

On Linux systems, Nebula can now mark packets using the SO_MARK socket option to enable advanced routing scenarios. This is particularly useful for full subnet routing (including 0.0.0.0/0) without the complexity of network namespaces, allowing administrators to route Nebula traffic through custom routing tables.

# Mark Nebula packets with firewall mark 4242 (choose a number to associate with Nebula)
listen:
  so_mark: 4242

Example setup for 0.0.0.0/0 routing through Nebula:

# Create routing rules to handle marked traffic (use the number you marked Nebula traffic with)
ip rule add not from all fwmark 4242 lookup 4242
ip rule add from all lookup main suppress_prefixlength 0
ip route add default dev nebula1 via <nebula_unsafe_route_g> table 4242

listen.rebind_on_network_change​

Default: true Added in v1.11.0

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

macOS scopes the UDP socket to the interface it was created on, so moving between networks (wifi to wired, office to home) leaves Nebula sending out an interface that no longer has a route. When enabled, Nebula watches the routing socket and rebinds the listener once the change settles, so devices moving between networks recover without waiting for dead tunnel detection. iOS does not use this option, the host app drives the same rebind itself.

listen.udp_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 UDP Generic Segmentation Offload (GSO, Linux kernel 4.18+) and Generic Receive Offload (GRO) on its UDP socket(s). With GSO, batches of packets bound for the same host are handed to the kernel as a single "superpacket" along with the size to split it back into individual datagrams, reducing per-packet syscall and network stack overhead on the send path. With GRO, the kernel coalesces bursts of datagrams arriving from the same host into a single large read. Support for each feature is probed when the socket is created, and Nebula falls back to standard sends and receives on kernels that lack it. GRO is only used when listen.batch is greater than 1.

Enabling GRO increases the fixed memory used by the receive path, see listen.batch for details. For the biggest throughput gains, pair this option with tun.use_offloads.

listen.windows_bypass_wdf​

Default: true Added in v1.11.0

This option is only supported on Windows (amd64 and arm64).

When true, Nebula installs a WFP (Windows Filtering Platform) PERMIT filter scoped to UDP at the listener port. WFP sits below Windows Defender Firewall, so this lets peer handshakes reach Nebula's UDP socket regardless of Defender Firewall inbound rules. Set to false to leave Windows Defender Firewall in charge of inbound traffic to the listener port. See tun.windows_bypass_wdf for the nebula interface. Changing this takes effect after a restart.