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: 10485760
  write_buffer: 10485760

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. host may also contain a hostname.

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

When listen.udp_offloads has enabled GRO (Linux kernel 5.10+), 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​

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/rmem_default). Maximum is limited by memory in the system, SO_RCVBUFFORCE and SO_SNDBUFFORCE is used to avoid having to raise the system wide max, net.core.rmem_max and net.core.wmem_max

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​

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, Linux kernel 5.10+) 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.

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.