diff --git a/src/components/NavigationDocs.jsx b/src/components/NavigationDocs.jsx index 05226995b..32873de11 100644 --- a/src/components/NavigationDocs.jsx +++ b/src/components/NavigationDocs.jsx @@ -191,6 +191,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 b9d27721d..508a76e4c 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 67ad06148..8bdd48659 100644 --- a/src/pages/manage/networks/how-routing-peers-work.mdx +++ b/src/pages/manage/networks/how-routing-peers-work.mdx @@ -225,7 +225,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 000000000..27a949fa5 --- /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. +