docs: masquerade-off HA is achievable, not impossible

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

@@ -102,9 +102,9 @@ Multiple routing peers can serve the same network or route. Behavior depends on
 
 ### Primary / failover (different metrics)
 
-The lower-metric peer carries all traffic. The higher-metric peer is held in reserve and only takes over when the primary becomes unreachable. Failover is automatic and immediate — clients begin sending traffic through the standby as soon as the primary stops responding. When the primary comes back online, clients switch back to it immediately. Established TCP connections through the previous peer reset and applications must reconnect.
+The lower-metric peer carries all traffic. The higher-metric peer is held in reserve and only takes over when the primary becomes unreachable. Failover is automatic: clients start sending traffic through the standby once the primary is seen as unreachable, normally within seconds. When the primary comes back online, clients switch back to it. With masquerade on, the default, established TCP connections through the previous peer reset and applications must reconnect, because the standby translates them to a different source address. With masquerade off they are not translated, and behave differently: see [High availability with masquerade off](/manage/networks/masquerade#high-availability-with-masquerade-off).
 
-**Example.** Routing Peer A has a lower metric than Routing Peer B. When Peer A goes down, all traffic fails over to Peer B. When Peer A comes back online, all traffic switches back to Peer A immediately.
+**Example.** Routing Peer A has a lower metric than Routing Peer B. When Peer A goes down, all traffic fails over to Peer B. When Peer A comes back online, all traffic switches back to Peer A.
 
 ### Latency switching (equal metrics)
 
@@ -131,8 +131,10 @@ Turn masquerade off when:
 
 With masquerade off, you must add a return route on the destination network pointing the NetBird CIDR (default `100.64.0.0/10`) at the routing peer.
 
+High availability then needs one more thing from you. Clients still move to the standby peer on their own, but that return route keeps pointing at the peer that just failed, so replies are dropped even though the outbound direction has recovered. The destination network has to be able to follow the failover too. See [High availability with masquerade off](/manage/networks/masquerade#high-availability-with-masquerade-off).
+
 <Note>
-Masquerade can only be turned off on Linux routing peers. High availability also stops working with masquerade off, because return traffic must flow back through one specific routing peer's LAN address — the destination network has no way to follow a failover.
+Masquerade can only be turned off on Linux routing peers.
 </Note>
 
 ## Access control behavior

src/pages/manage/networks/index.mdx

@@ -167,7 +167,7 @@ Before you depend on a Network in production, work through these:
 
 - **High availability.** Add more than one routing peer to the same Network for redundancy. Added individually, each peer gets its own metric: a lower metric is the primary and a higher one the failover, while equal metrics balance traffic by latency. Added as a group, the peers share one metric, so they balance by latency only and can't act as primary and failover. Keep highly available peers in different failure domains. See [High availability](/manage/networks/how-routing-peers-work#high-availability).
 - **Monitoring.** Enable the **Routing Peer Disconnected** event in [Notifications](/manage/settings/notifications) to get alerted by email, webhook, or Slack when a routing peer goes offline.
-- **Masquerade.** On by default and the simplest option. Turn it off only when you need source-IP visibility, and only on Linux routing peers, as that's the only platform where it can be disabled. Note that disabling it breaks high availability and requires a return route. See [Masquerade](/manage/networks/masquerade).
+- **Masquerade.** On by default and the simplest option. Turn it off only when you need source-IP visibility, and only on Linux routing peers, as that's the only platform where it can be disabled. Disabling it requires a return route in the destination network, and makes high availability something you have to arrange rather than something you get. See [Masquerade](/manage/networks/masquerade).
 - **Internal DNS.** Domain resources resolve on the routing peer, so it must be able to resolve the name. If it already can, nothing more is needed; if it can't, distribute a nameserver to the routing peer's group. See [Internal DNS Servers](/manage/dns/internal-dns-servers).
 - **Access to the routing peer itself.** If users also need services on the routing peer host (SSH, a dashboard), add a separate peer-to-peer [access policy](/manage/access-control) for the input chain, as explained above.
 

src/pages/manage/networks/masquerade.mdx

@@ -10,8 +10,8 @@ Masquerade is on by default. The routing peer SNATs forwarded traffic to its own
 ## 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).
+- A return route for the NetBird CIDR (default `100.64.0.0/10`) must point at the routing peer's LAN IP. Put it on the destination host, or on that subnet's default gateway when the host is not yours to change.
+- High availability takes extra work, because the return route has to follow a failover. See [High availability with masquerade off](#high-availability-with-masquerade-off).
 
 <Note>
 Masquerade can only be turned off on Linux routing peers.
@@ -32,6 +32,10 @@ curl -X PUT https://api.netbird.io/api/networks/<NETWORK_ID>/routers/<ROUTER_ID>
 
 The rest of this page covers the return-route prerequisite the destination network needs once masquerade is off.
 
+<Note>
+The steps below add the route on the destination host itself. If that host is not yours to configure, put the same route on the subnet's default gateway instead. This works even when the gateway and the routing peer sit on the same subnet: replies leave the host, reach the gateway, and are sent back out of the interface they arrived on.
+</Note>
+
 ## Inputs to substitute
 
 The examples below use placeholders. Swap in:
@@ -164,6 +168,25 @@ 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.
 
+## High availability with masquerade off
+
+The return route points at one peer, so it has to follow whichever routing peer is currently active. NetBird moves clients to the standby on its own, but it cannot change a route inside your network: left alone, the route keeps pointing at the peer that failed and replies are dropped.
+
+Two steps:
+
+1. **Give the routing peers different metrics**, so the active peer is the same one for every client. With equal metrics each client picks its own by latency, and then no single next hop is correct for all of them. See [High availability](/manage/networks/how-routing-peers-work#high-availability).
+2. **Make the route's next hop follow the active peer.** Either a shared virtual IP across the peers (VRRP, using `keepalived` on Linux, which needs them on the same subnet), or a router that moves the route when a health check fails. The mechanism lives outside NetBird. Whichever you choose, make its health check reach a destination through the tunnel rather than testing the peer itself: a routing peer whose agent is running and whose WireGuard interface is present can still be unable to forward, and neither NetBird nor an interface check notices.
+
+<Warning>
+Do not point the return route at both peers at once, as two static routes or an equal-cost pair. Replies reaching the peer a client is not using are silently discarded, so both ends look healthy while traffic fails.
+</Warning>
+
+Established TCP connections behave better here than with masquerade on. Because nothing translates them, their addresses do not change when a different peer takes over, so a held connection can stall through the failover and then continue rather than resetting. Expect the stall to outlast the failover itself, since the sender waits for its next retransmit before trying again: in our testing a 6 second failover stalled held connections for 6 to 13 seconds. Applications with short timeouts will still give up on their own.
+
+New connections fail until both sides have converged. Recovery then costs a second brief interruption, because clients return to the primary faster than the route does, and you cannot avoid that by pinning the virtual IP to the standby: the client's switch back is automatic.
+
+If you do not need source IP visibility, leaving masquerade on gives you high availability with none of this to operate, which is why it is the default.
+
 ## Security considerations
 
 <Warning>