Skip to content

Commit 8cfacb0

Browse files
authored
Document missing config items from v1.6.0, v1.10.0 & improve existing config items (#311)
1 parent 41ddbc9 commit 8cfacb0

2 files changed

Lines changed: 69 additions & 1 deletion

File tree

‎docs/config/listen.mdx‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,3 +43,40 @@ Configure socket buffers for the udp side (outside), leave unset to use the syst
4343
the kernel. Default is `net.core.rmem_default` and `net.core.wmem_default` (`/proc/sys/net/core/rmem_default` and
4444
`/proc/sys/net/core/rmem_default`). Maximum is limited by memory in the system, `SO_RCVBUFFORCE` and `SO_SNDBUFFORCE` is
4545
used to avoid having to raise the system wide max, `net.core.rmem_max` and `net.core.wmem_max`
46+
47+
## listen.send_recv_error
48+
49+
<Pill className="mb-24">Reloadable</Pill> <Pill className="mb-24">Default: `always`</Pill>
50+
<Pill className="mb-24">Added in v1.6.0</Pill>
51+
52+
By default, Nebula replies to packets it has no tunnel for with a `recv_error` packet. This packet helps speed up
53+
reconnection in the case that Nebula on either side did not shut down cleanly. This response can be abused however as a
54+
way to discover if Nebula is running on a host. `send_recv_error` lets you configure if you want to send `recv_error`
55+
packets `always`, `never`, or only to `private` network remotes.
56+
57+
Valid values: `always`, `never`, `private`
58+
59+
## listen.so_mark
60+
61+
<Pill className="mb-24">Added in v1.10.0</Pill>
62+
63+
On Linux systems, Nebula can now mark packets using the
64+
[SO_MARK socket option](<https://www.man7.org/linux/man-pages/man7/socket.7.html#:~:text=SO_MARK%20(since%20Linux,Linux%205.17)%20capability.>)
65+
to enable advanced routing scenarios. This is particularly useful for full subnet routing (including `0.0.0.0/0`)
66+
without the complexity of network namespaces, allowing administrators to route Nebula traffic through custom routing
67+
tables.
68+
69+
```yaml
70+
# Mark Nebula packets with firewall mark 4242
71+
listen:
72+
so_mark: 4242
73+
```
74+
75+
Example setup for `0.0.0.0/0` routing through Nebula:
76+
77+
```console
78+
# Create routing rules to handle marked traffic
79+
ip rule add not from all fwmark 4242 lookup 4242
80+
ip rule add from all lookup main suppress_prefixlength 0
81+
ip route add default dev nebula1 via &lt;nebula_unsafe_route_gw&gt; table 4242
82+
```

‎docs/config/tun.mdx‎

Lines changed: 32 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -62,12 +62,14 @@ Default is 500.
6262

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

65+
See below for per-route overrides ([`tun.routes`](#tunroutes)).
66+
6567
## tun.routes
6668

6769
<Pill className="mb-24">Reloadable</Pill>
6870

6971
Route based MTU overrides. If you have known VPN IP paths that can support larger MTUs you can increase/decrease them
70-
here.
72+
here. This will override the default MTU ([`tun.mtu`](#tunmtu)) for Nebula packets on a per-route basis.
7173

7274
```yml
7375
tun:
@@ -102,6 +104,35 @@ tun:
102104

103105
For more information, see the [Extend network access beyond overlay hosts](/docs/guides/unsafe_routes/) guide.
104106

107+
### ECMP support for `unsafe_routes`
108+
109+
<Pill className="mb-24">Added in v1.10.0</Pill>
110+
111+
[Equal-Cost Multi-Path routing](https://en.wikipedia.org/wiki/Equal-cost_multi-path_routing) is now available for
112+
unsafe_routes, enabling load balancing and redundancy within a single host. You can now configure multiple gateways for
113+
the same route on one host, with optional weighting for unequal load distribution.
114+
115+
```yaml
116+
unsafe_routes:
117+
# Multiple gateways with equal weighting (default weight: 1)
118+
- route: 192.168.100.0/24
119+
via:
120+
- gateway: 10.0.0.1
121+
- gateway: 10.0.0.2
122+
123+
# Multiple gateways with custom weights
124+
- route: 192.168.101.0/24
125+
via:
126+
- gateway: 10.0.0.1
127+
weight: 10
128+
- gateway: 10.0.0.2
129+
weight: 5
130+
```
131+
132+
The implementation uses [hash-threshold mapping](https://tools.ietf.org/html/rfc2992) (similar to the Linux kernel) to
133+
distribute traffic based on packet hashing. When a gateway becomes unreachable, traffic automatically fails over to the
134+
remaining available gateways, though load balancing may become uneven until the failed gateway recovers.
135+
105136
## tun.use_system_route_table
106137

107138
<Pill className="mb-24">Default: False</Pill>

0 commit comments

Comments
 (0)