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

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,