docs: add Masquerade configuration page

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,

src/pages/manage/network-routes/advanced-configuration.mdx

@@ -20,6 +20,8 @@ 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.
+
 <Warning>
 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.
 </Warning>

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',
         },

src/pages/manage/networks/masquerade.mdx

@@ -0,0 +1,130 @@
+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 network 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).
+
+<Note>
+Masquerade can only be turned off on Linux routing peers.
+</Note>
+
+## Inputs to substitute
+
+The examples below use placeholders. Swap in:
+
+- `100.64.0.0/10` — default NetBird CIDR. Substitute your account's range if it's narrower.
+- `<PEER_LAN_IP>` — the routing peer's IP on the destination subnet.
+- `<IFACE>` — 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
+```
+
+Substitute that `/16` for `100.64.0.0/10` in every example below.
+
+## 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 <PEER_LAN_IP>
+```
+
+From a NetBird peer, confirm reachability with a protocol/port your NetBird policy allows — for example `curl http://<destination-ip>:<port>`, or `nc -zv <destination-ip> <port>` 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
+```
+
+## 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`). Add a `routes:` entry to the interface stanza. 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:
+    <IFACE>:                         # 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: <PEER_LAN_IP>         # 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
+```
+
+<Note>
+Recent netplan versions require `0600` permissions on yaml files under `/etc/netplan/`. Set with `sudo chmod 0600 /etc/netplan/*.yaml` if `netplan apply` warns.
+</Note>
+
+### systemd-networkd
+
+Either append to the relevant `.network` file in `/etc/systemd/network/`, or drop a snippet into `/etc/systemd/network/<IFACE>.network.d/100-netbird.conf`:
+
+```ini
+[Route]
+Destination=100.64.0.0/10
+Gateway=<PEER_LAN_IP>
+```
+
+Apply:
+
+```bash
+sudo networkctl reload
+```
+
+<Note>
+The drop-in path only takes effect when a `.network` file already matches the interface. Run `networkctl status <IFACE>` and check the **Network File** line to confirm which one — on netplan-managed hosts it's generated under `/run/systemd/network/`.
+</Note>
+
+## Verify after reboot
+
+```bash
+ip route show 100.64.0.0/10
+```
+
+Expect output like:
+
+```
+100.64.0.0/10 via 192.168.1.50 dev eth0
+```
+
+Trailing fields such as `proto static`, `onlink`, or `metric 100` may appear depending on the network manager — those are normal.
+
+## Security considerations
+
+<Warning>
+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.
+</Warning>