sendnrw/netbird-docs
2
0
Fork 0
mirror of https://github.com/netbirdio/docs.git synced 2026-08-25 01:01:27 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: add Masquerade configuration page (#751)

Browse Source 
* 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 <IFACE> placeholder in netplan example

* docs: clarify <IFACE> is the destination's LAN interface

* docs: comment <PEER_LAN_IP> placeholder in netplan example

* docs: tighten <PEER_LAN_IP> 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 <PEER_LAN_IP> 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
This commit is contained in:
Jack Carter
2026-05-19 15:07:07 +02:00
committed by GitHub
parent 8f06376f4f
commit 84a3532943
4 changed files with 167 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
src/components/NavigationDocs.jsx
View File

@@ -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,

4
src/pages/manage/network-routes/advanced-configuration.mdx
View File

@@ -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.
<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.
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).
</Warning>
### Choosing the right approach

2
src/pages/manage/networks/how-routing-peers-work.mdx
View File

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

159
src/pages/manage/networks/masquerade.mdx Normal file
View File

@@ -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).
<Note>
Masquerade can only be turned off on Linux routing peers.
</Note>
## 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/<NETWORK_ID>/routers/<ROUTER_ID> \
-H "Authorization: Token <API_TOKEN>" \
-H "Content-Type: application/json" \
-d '{"peer": "<PEER_ID>", "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.
- `<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
```
<Note>
Wherever the examples below show `100.64.0.0/10`, use your account's `/16` instead.
</Note>
## 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 via <PEER_LAN_IP>
```
## 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:
<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 (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://<destination-ip>:<port>
# on the destination, tail the relevant log or capture briefly:
sudo tcpdump -ni <IFACE> "src net 100.64.0.0/10 and port <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
<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>