From 84a35329433147b3bb2348b2f19d71cfbe06a831 Mon Sep 17 00:00:00 2001 From: Jack Carter <128555021+SunsetDrifter@users.noreply.github.com> Date: Tue, 19 May 2026 15:07:07 +0200 Subject: [PATCH] docs: add Masquerade configuration page (#751) * docs: add Masquerade configuration page Documents persistent return-route setup on the destination host when masquerade is disabled on a routing peer. Covers Netplan, systemd-networkd, NetworkManager, ifupdown, and RHEL legacy network-scripts, plus verification and a security note. Resolves the previously dangling "Related" tile in how-routing-peers-work.mdx. * docs: clarify masquerade page and trim persistent recipes - Netplan: show as a fragment with addresses/default route context so readers don't paste it as a standalone file - systemd-networkd: note the drop-in needs a matching .network file and point at networkctl status to find it - Test section: add ping/curl reachability examples - Verify section: call out that proto/onlink/metric fields are normal - Remove NetworkManager, ifupdown, and RHEL legacy sections * docs: clarify netplan section when /etc/netplan is empty Lead with the common case (cloud-init / installer yaml already exists), and call out the placeholders in the example. Add a fallback path for the rare case where /etc/netplan/ is empty. * docs: comment placeholder in netplan example * docs: clarify is the destination's LAN interface * docs: comment placeholder in netplan example * docs: tighten comment to 'local IP on this subnet' * docs: make 'pick one' explicit for the persistent-config methods Replace the weak one-liner with a bold "pick one" callout and a two-bullet decision criterion (ls /etc/netplan/) so readers don't mistake the two H3 sections for sequential steps. * docs: add 'Find your account's NetBird range' to the masquerade page Mirror the section already on the site-to-vpn page so readers learn to use their account's /16 block rather than pinning the whole /10. Same prose and netbird status recipe; trailing line adapted to reference 100.64.0.0/10 (the placeholder used elsewhere on this page). * docs: remove 'Related' Tiles block from masquerade page * docs: align security warning with the recommended /16 range * docs: restore cross-link from advanced-configuration to masquerade * docs: drop ping from the test-route example ping would fail for ACL reasons (not routing reasons) on policies scoped to specific TCP ports, misdirecting troubleshooting. Use curl or nc against an allowed port instead. * docs: apply review findings to masquerade page and legacy warning masquerade.mdx - add "Disable masquerade on the routing peer" section (dashboard + API path), so the page actually documents the toggle, not just the prerequisite - "What changes when masquerade is off": say the route lives on the destination host (or its gateway for multi-hop) - forward-ref "Find your account's NetBird range" from the inputs list to remove the substitute-then-rewind loop - ip route del: include via so the test takedown is unambiguous - netplan prose: spell out that you append to the existing routes: list, not add a second routes: key (YAML rejects that) - verify output: use 192.168.1.10 for the routing peer so it stops colliding with the 192.168.1.50 used as the destination's own IP in the netplan example - add an end-to-end verification step (curl + tcpdump) so a reader confirms source IPs are actually preserved, not just that a route exists in the table advanced-configuration.mdx - rewrite the contradictory Warning so it scopes correctly to legacy Network Routes (which match peer NetBird IPs only) and points readers to the Networks path when they want policy-layer ACLs with masquerade off * docs: promote the /16 substitution reminder to a Note callout * docs: clearer wording for the /16 substitution Note --- src/components/NavigationDocs.jsx | 4 + .../network-routes/advanced-configuration.mdx | 4 +- .../networks/how-routing-peers-work.mdx | 2 +- src/pages/manage/networks/masquerade.mdx | 159 ++++++++++++++++++ 4 files changed, 167 insertions(+), 2 deletions(-) create mode 100644 src/pages/manage/networks/masquerade.mdx diff --git a/src/components/NavigationDocs.jsx b/src/components/NavigationDocs.jsx index 709852c6..07e6cf7a 100644 --- a/src/components/NavigationDocs.jsx +++ b/src/components/NavigationDocs.jsx @@ -195,6 +195,10 @@ export const docsNavigation = [ title: 'How Routing Peers Work', href: '/manage/networks/how-routing-peers-work', }, + { + title: 'Masquerade', + href: '/manage/networks/masquerade', + }, { title: 'Use Cases', isOpen: false, diff --git a/src/pages/manage/network-routes/advanced-configuration.mdx b/src/pages/manage/network-routes/advanced-configuration.mdx index b9d27721..508a76e4 100644 --- a/src/pages/manage/network-routes/advanced-configuration.mdx +++ b/src/pages/manage/network-routes/advanced-configuration.mdx @@ -20,8 +20,10 @@ For the basics — masquerade behavior, ACL Groups, HA — see [Network Routes C - Required if your compliance regime needs source-IP visibility on the remote network - Requires a return route on the remote network's infrastructure back to the NetBird CIDR +See [Masquerade](/manage/networks/masquerade) for persistent return-route configuration on the destination host. + -Without masquerade, traffic from unknown source IPs is rejected by NetBird's policy engine. You cannot use ACL Groups or Network Resources with masquerade disabled. +ACL Groups on **Network Routes** (this page) match against peer NetBird IPs only, which limits source-IP-preserving access control on this path. For masquerade-off deployments with policy-layer ACLs, use the newer **Networks** path — see [Masquerade](/manage/networks/masquerade). ### Choosing the right approach diff --git a/src/pages/manage/networks/how-routing-peers-work.mdx b/src/pages/manage/networks/how-routing-peers-work.mdx index fc6e327d..573fe2c8 100644 --- a/src/pages/manage/networks/how-routing-peers-work.mdx +++ b/src/pages/manage/networks/how-routing-peers-work.mdx @@ -223,7 +223,7 @@ Specifics: description: 'Use ACL Groups to restrict who reaches a routed network', }, { - href: '/manage/network-routes/advanced-configuration', + href: '/manage/networks/masquerade', name: 'Masquerade', description: 'When to enable or disable source IP rewriting on a route', }, diff --git a/src/pages/manage/networks/masquerade.mdx b/src/pages/manage/networks/masquerade.mdx new file mode 100644 index 00000000..27a949fa --- /dev/null +++ b/src/pages/manage/networks/masquerade.mdx @@ -0,0 +1,159 @@ +import { Note, Warning } from '@/components/mdx' + +# Masquerade + +Masquerade is on by default. The routing peer SNATs forwarded traffic to its own LAN-side IP, so the destination network does not need any awareness of NetBird. Turn it off when you need: + +- Source IP visibility for auditing, compliance, or application logic. +- The destination network's existing firewalls to filter NetBird peers by their overlay IP. + +## What changes when masquerade is off + +- The original NetBird overlay IP is preserved end-to-end. +- The destination host (or, if it sits in a different subnet, its gateway) must have a return route for the NetBird CIDR (default `100.64.0.0/10`) pointing at the routing peer's LAN IP. +- High availability stops working — return traffic must flow back through one specific routing peer, so the destination network has no way to follow a failover. See [How Routing Peers Work — Masquerade](/manage/networks/how-routing-peers-work#masquerade). + + +Masquerade can only be turned off on Linux routing peers. + + +## Disable masquerade on the routing peer + +In the dashboard: **Networks** → your network → the **routing peer** row → toggle **Masquerade** off. The change takes effect within seconds; the routing peer stops SNATing forwarded traffic for this network. + +You can also flip it through the API: + +```bash +curl -X PUT https://api.netbird.io/api/networks//routers/ \ + -H "Authorization: Token " \ + -H "Content-Type: application/json" \ + -d '{"peer": "", "masquerade": false, "metric": 9999, "enabled": true}' +``` + +The rest of this page covers the return-route prerequisite the destination network needs once masquerade is off. + +## Inputs to substitute + +The examples below use placeholders. Swap in: + +- `100.64.0.0/10` — default NetBird CIDR. See [Find your account's NetBird range](#find-your-accounts-netbird-range) below for the narrower `/16` you should use in practice. +- `` — the routing peer's IP on the destination subnet. +- `` — the LAN interface on the destination host. Use `ip -br addr` to identify it. + +## Find your account's NetBird range + +NetBird assigns each account a single `/16` block from inside the `100.64.0.0/10` CGNAT range (one of 64 possible blocks such as `100.64.0.0/16`, `100.121.0.0/16`, `100.127.0.0/16`, …). The block is chosen randomly per account and can be customised. Use that `/16` for the return route below — not the whole `/10` — so you don't funnel unrelated CGNAT ranges through your routing peer. + +Read it off any enrolled peer: + +```bash +$ netbird status | grep "NetBird IP" +NetBird IP: 100.121.195.4/16 +# → this account's block is 100.121.0.0/16 +``` + + +Wherever the examples below show `100.64.0.0/10`, use your account's `/16` instead. + + +## Test the route before making it persistent + +Add the route temporarily on the destination host: + +```bash +sudo ip route add 100.64.0.0/10 via +``` + +From a NetBird peer, confirm reachability with a protocol/port your NetBird policy allows — for example `curl http://:`, or `nc -zv ` for a non-HTTP service. Then remove the test route before committing the persistent version: + +```bash +sudo ip route del 100.64.0.0/10 via +``` + +## Persistent configuration + +Pick **one** of the methods below — your host uses one network manager, not both: + +- **Netplan** if `/etc/netplan/` already has yaml files (most Ubuntu hosts). +- **systemd-networkd** otherwise (Debian Server, minimal installs, or hosts using systemd-networkd directly without a netplan frontend). + +### Netplan (Ubuntu 18.04+) + +On Ubuntu Server, `/etc/netplan/` usually already has a yaml from cloud-init (`50-cloud-init.yaml`) or the installer (`00-installer-config.yaml`). Append a new entry to the interface's `routes:` list (don't add a second `routes:` key — YAML won't accept that). The `addresses:` and default-route values shown below are placeholders for whatever is already in your file — not values to copy as-is: + +```yaml +network: + version: 2 + ethernets: + : # destination's LAN interface, e.g. eth0 + addresses: [192.168.1.50/24] # existing + routes: + - to: default # existing + via: 192.168.1.1 + - to: 100.64.0.0/10 # add this + via: # routing peer's local IP on this subnet +``` + +If `/etc/netplan/` is empty (uncommon, but possible on minimal installs or when netplan was just `apt install`ed), create `/etc/netplan/01-netbird.yaml` with the full stanza, substituting real values for `addresses:` and the default gateway. + +Apply: + +```bash +sudo netplan apply +``` + + +Recent netplan versions require `0600` permissions on yaml files under `/etc/netplan/`. Set with `sudo chmod 0600 /etc/netplan/*.yaml` if `netplan apply` warns. + + +### systemd-networkd + +Either append to the relevant `.network` file in `/etc/systemd/network/`, or drop a snippet into `/etc/systemd/network/.network.d/100-netbird.conf`: + +```ini +[Route] +Destination=100.64.0.0/10 +Gateway= +``` + +Apply: + +```bash +sudo networkctl reload +``` + + +The drop-in path only takes effect when a `.network` file already matches the interface. Run `networkctl status ` and check the **Network File** line to confirm which one — on netplan-managed hosts it's generated under `/run/systemd/network/`. + + +## Verify after reboot + +```bash +ip route show 100.64.0.0/10 +``` + +Expect output like (where `192.168.1.10` stands for the routing peer's LAN IP — not the destination's own address): + +``` +100.64.0.0/10 via 192.168.1.10 dev eth0 +``` + +Trailing fields such as `proto static`, `onlink`, or `metric 100` may appear depending on the network manager — those are normal. + +Then send a request from a NetBird peer and confirm the destination logs the original overlay IP: + +```bash +# from a NetBird peer +curl http://: + +# on the destination, tail the relevant log or capture briefly: +sudo tcpdump -ni "src net 100.64.0.0/10 and port " +``` + +The source IP should fall inside your account's `/16` (e.g. `100.121.x.x`), not the routing peer's LAN IP. + +## Security considerations + + +The return route exposes the destination subnet to whatever NetBird range you configured — your account's `/16` if you narrowed it (recommended), otherwise the full `100.64.0.0/10`. The OS-level route does no filtering on its own — source IP transparency is the whole reason masquerade is off, so tighten access at the NetBird policy layer with source groups, ports, and posture checks. If only a subset of the destination subnet should reach NetBird peers, add host-level firewall rules (iptables, nftables, firewalld) alongside the route. +