docs: masquerade-off HA is achievable, not impossible - #893
Conversation
Both the routing-peers page and the masquerade page stated that high availability "stops working" with masquerade off. That reads as a flat impossibility and loses a legitimate use case (source IP preservation for audit, per-user database rules, or firewall policy keyed on the real source). What is actually true is narrower: NetBird's half of the failover still works, clients move to the standby peer on their own. What is missing is the return route inside the destination network following that move. State the condition instead of the impossibility, and add a short section on what meeting it takes: distinct metrics so the active peer is the same for every client, plus a virtual IP or a router-moved route so the next hop follows. Both live outside NetBird, so the section names the pattern rather than shipping a third-party config we would then own. Also: - Soften "failover is automatic and immediate". Clients re-select within seconds, which is fast but not instant, and "immediate" invites a support ticket from anyone who measures it. Phrased so it does not assert whether the client or the management side detects the loss, which this change did not verify. - Warn against pointing the return route at both peers, as two static routes or an equal-cost pair. It is the intuitive fix and it fails silently. - Note that the second interruption on recovery cannot be avoided by pinning the virtual IP to the standby, since the client's switch back is automatic. Pinning the route while the client moves back strands the return path. - The return route can live on the destination subnet's default gateway even when the gateway and the routing peer share that subnet, which is the only option when the destination host is not the customer's to configure. The page previously offered the gateway only for a different-subnet destination, and its persistent-config steps assume host access throughout.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Caution Review failedThe pull request is closed. ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (3)
📝 WalkthroughWalkthroughThe documentation updates clarify automatic routing peer failover timing, masquerade-off return-route placement, and high-availability configurations that keep return traffic aligned with the active peer. ChangesRouting and masquerade documentation
Estimated code review effort: 2 (Simple) | ~10 minutes Suggested reviewers: Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Warning There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure. 🔧 ESLint
src/pages/manage/networks/how-routing-peers-work.mdxOops! Something went wrong! :( ESLint: 9.39.2 TypeError: Converting circular structure to JSON src/pages/manage/networks/index.mdxOops! Something went wrong! :( ESLint: 9.39.2 TypeError: Converting circular structure to JSON src/pages/manage/networks/masquerade.mdxOops! Something went wrong! :( ESLint: 9.39.2 TypeError: Converting circular structure to JSON Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@src/pages/manage/networks/masquerade.mdx`:
- Line 184: Update the recovery interruption statement in the masquerade
failover documentation to make it conditional: recovery can cause a second brief
interruption when clients return before the route does, and the behavior depends
on convergence timing. Preserve the surrounding explanation about automatic
client switching and virtual IP pinning.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: da772466-f08a-4d07-8b2a-ce88319d735a
📒 Files selected for processing (2)
src/pages/manage/networks/how-routing-peers-work.mdxsrc/pages/manage/networks/masquerade.mdx
A routing peer can stay enrolled and report healthy, with its WireGuard interface present, while being unable to forward from the tunnel to the destination subnet: a failed LAN interface, or a firewall change. Nothing fails over in that state. NetBird sees a reachable peer, and a health check that only looks for the interface sees a healthy one, so the return route stays pointed at a peer that forwards nothing until someone intervenes. Say that the check has to reach a destination through the tunnel.
Measured on a routing-peer pair with masquerade off: a held TCP connection survives the switch. Four failovers, graceful shutdown and hard kill, all showed the same signature — one round trip with multi-second latency, then the same connection continuing with monotonic sequence numbers. No resets, and no RST on the wire in any of them. The reason is a property of masquerade being off: the addresses on the connection do not change when another peer takes over, so the flow is portable between peers, and the routed ACL accepts on addresses rather than on connection state, so the standby forwards mid-stream packets it never saw a handshake for. Note this is specific to masquerade being off. The general high-availability section still says established connections reset, which is the masquerade-on default, where the standby would translate to a different source address. Also trims the mechanism guidance to name the pattern rather than lean on any one implementation, since which mechanism is right may change.
Review of the branch turned up three problems. The Networks overview still said disabling masquerade 'breaks high availability', one click from the page arguing it does not. Reworded to say it makes high availability something you arrange rather than something you get. Neither reset/stall sentence named its masquerade scope, so a reader with masquerade off met both and they flatly disagreed. The general failover section now scopes its reset claim to masquerade on, names the reason (the standby translates to a different source address), and links onward. 'Stalls for the length of the failover' understated it. Measured stalls were 6 to 13 seconds against a 6 second failover, because the sender waits for its next retransmit after the path returns. Says so, with the range, and keeps the claim hedged to what was observed rather than asserting connections are never broken.
2 participants
Why
Two pages state that high availability "stops working" when masquerade is off:
manage/networks/how-routing-peers-work— "High availability also stops working with masquerade off, because return traffic must flow back through one specific routing peer's LAN address"manage/networks/masquerade— "High availability stops working"That reads as a flat impossibility, and it turns away a legitimate use case: preserving the client source IP for auditing, per-user database permissions, or firewall policy keyed on the real source.
The true statement is narrower. NetBird's half of a failover still works, clients move to the standby peer on their own. What is missing is the return route inside the destination network following that move. That is a condition to meet, not a dead end.
What changed
masquerade.mdxBoth mechanisms live outside NetBird, so the section names the pattern without shipping a third-party configuration we would then own.
how-routing-peers-work.mdxNotes for review
#high-availability-with-masquerade-off(new) and#high-availability(already referenced from the Kubernetes use-case page).Need help on this PR? Tag
@codesmith-botwith what you need. Autofix is disabled.Summary by CodeRabbit