From 7e60fc20fc3cd963565c2c3d7a22e916e5a345db Mon Sep 17 00:00:00 2001 From: Jack Carter <128555021+SunsetDrifter@users.noreply.github.com> Date: Tue, 5 May 2026 14:09:11 +0200 Subject: [PATCH 1/3] docs(routing-peers): apply outstanding review feedback - Drop the unverified Cloud-specific settings subsection (AWS/GCP/Azure bullets) and the related AWS source/destination pitfall bullet - Spell out "high availability" in the Masquerade note for clarity --- src/pages/manage/networks/how-routing-peers-work.mdx | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/src/pages/manage/networks/how-routing-peers-work.mdx b/src/pages/manage/networks/how-routing-peers-work.mdx index 28fe3bb4..813fcf73 100644 --- a/src/pages/manage/networks/how-routing-peers-work.mdx +++ b/src/pages/manage/networks/how-routing-peers-work.mdx @@ -88,12 +88,6 @@ A containerized routing peer needs `NET_ADMIN`. The Kubernetes manifest also add The routing peer must have direct network reachability to the resources it serves. This is the most common cause of failed deployments in cloud environments: the peer ends up in the wrong subnet, the wrong security group, or on the wrong side of a VPC peering boundary. -### Cloud-specific settings - -- **AWS.** Disable source/destination check on the EC2 instance acting as the routing peer. -- **GCP.** Enable IP forwarding at the instance level (`--can-ip-forward`). -- **Azure.** Enable IP forwarding on the NIC. - ## High availability Multiple routing peers can serve the same network or route. Behavior depends on the **metric** you assign each routing peer in the dashboard. There are no tunable thresholds — the metric is the only HA control. @@ -126,7 +120,7 @@ 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. -Masquerade can only be turned off on Linux routing peers. HA 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. 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. ## Access control behavior @@ -205,7 +199,6 @@ Specifics: ## Common pitfalls -- Skipping the AWS source/destination check disable. - Network Route with no ACL Groups, granting blanket access. - Policy to a network resource works, but SSH to the routing peer itself is denied because the input chain has no matching policy. - HA peers in the same AZ, defeating the purpose of HA. From 8015de5a0b6ce301be41b9cf8669bb7131db98ac Mon Sep 17 00:00:00 2001 From: Jack Carter <128555021+SunsetDrifter@users.noreply.github.com> Date: Tue, 5 May 2026 14:09:22 +0200 Subject: [PATCH 2/3] docs(routing-peers): expand inbound cross-links to How Routing Peers Work Surface the routing peer primer from 11 high-leverage pages so readers landing in a configuration or scenario guide can find the mental model without having to backtrack through the sidebar. - Index pages (manage/networks, manage/network-routes): move the cross-link from the page top into the Routing Peer(s) subsection, where it sits adjacent to existing routing-peer guidance - exit-nodes scenario: cross-link inside the Routing Peer subsection, anchored at #exit-node-mode - internal-dns-servers: cross-link under Domain Resources and Routing Peer DNS, anchored at #routing-peer-dns-resolution - Procedural and comparison pages (access-control, by-scenario VPN-to-Site guides, site-to-site overview, Kubernetes operator, routing peers in Kubernetes): cross-link near the page top with section-specific anchors --- src/pages/manage/dns/internal-dns-servers.mdx | 4 ++++ src/pages/manage/integrations/kubernetes/index.mdx | 4 ++++ src/pages/manage/network-routes/index.mdx | 8 ++++---- .../use-cases/by-configuration/access-control.mdx | 4 ++++ .../network-routes/use-cases/by-scenario/exit-nodes.mdx | 4 ++++ src/pages/manage/networks/index.mdx | 8 ++++---- .../use-cases/by-scenario/access-home-devices.mdx | 4 ++++ .../use-cases/by-scenario/cloud-to-on-premise.mdx | 4 ++++ .../use-cases/by-scenario/remote-worker-access.mdx | 4 ++++ .../use-cases/cloud/routing-peers-and-kubernetes.mdx | 4 ++++ src/pages/use-cases/site-to-site/index.mdx | 4 ++++ 11 files changed, 44 insertions(+), 8 deletions(-) diff --git a/src/pages/manage/dns/internal-dns-servers.mdx b/src/pages/manage/dns/internal-dns-servers.mdx index 1d993767..df566c0d 100644 --- a/src/pages/manage/dns/internal-dns-servers.mdx +++ b/src/pages/manage/dns/internal-dns-servers.mdx @@ -13,6 +13,10 @@ You can also use wildcard domains as resources (e.g., `*.corp.local`), but this ## Domain Resources and Routing Peer DNS + +For the mental model — see [How Routing Peers Work — Routing Peer DNS Resolution](/manage/networks/how-routing-peers-work#routing-peer-dns-resolution). + + When you define a [Network resource](/manage/networks) using a domain name (e.g., `crm.corp.local`), the **routing peer** resolves that domain using its own local DNS configuration. The client sends DNS queries to the routing peer, which looks up the domain and returns the result. This means the routing peer must be able to resolve the domain. If it can't — for example, a Linux routing peer that isn't configured to use your Active Directory DNS — domain resource lookups will fail. diff --git a/src/pages/manage/integrations/kubernetes/index.mdx b/src/pages/manage/integrations/kubernetes/index.mdx index 2ed5c51e..4671ed15 100644 --- a/src/pages/manage/integrations/kubernetes/index.mdx +++ b/src/pages/manage/integrations/kubernetes/index.mdx @@ -7,6 +7,10 @@ to your Kubernetes clusters using custom resource configurations and annotations The NetBird Kubernetes operator automatically creates [Networks and Resources](/manage/networks) in your NetBird account, allowing you to seamlessly access your Kubernetes services and control plane from your NetBird network. + +For the mental model — see [How Routing Peers Work — Requirements](/manage/networks/how-routing-peers-work#requirements). + + ## Deployment ### Prerequisites diff --git a/src/pages/manage/network-routes/index.mdx b/src/pages/manage/network-routes/index.mdx index c5c761e0..8acb00ca 100644 --- a/src/pages/manage/network-routes/index.mdx +++ b/src/pages/manage/network-routes/index.mdx @@ -17,10 +17,6 @@ Network Routes require NetBird [v0.9.0](https://github.com/netbirdio/netbird/rel By default, Network Routes bypass Access Control rules. Traffic flows freely to routed networks unless you [configure access control explicitly](/manage/network-routes/use-cases/by-configuration/access-control). See [Network Routes caveats](#network-routes-caveats) for details. - -For the mental model behind routing peers — how traffic flows, host requirements, HA, masquerade, the forward-vs-input-chain rule, and hardening — see [How Routing Peers Work](/manage/networks/how-routing-peers-work). - - ## Network Routes vs Networks [Networks](/manage/networks) is the newer, simpler replacement for Network Routes. We recommend using Networks where possible; however, Networks do not yet support all remote access scenarios. Network Routes will continue to be maintained, so choose whichever fits your use case. @@ -41,6 +37,10 @@ A routing peer is a NetBird device that forwards traffic between the NetBird net A network route grants access to the network behind the routing peer, not to the routing peer machine itself. If you need to reach services running on the routing peer, create a separate peer-to-peer [access control policy](/manage/access-control) that targets the routing peer's group as the destination. + +For the mental model — how traffic flows, host requirements, HA, masquerade, and the forward-vs-input-chain rule — see [How Routing Peers Work](/manage/networks/how-routing-peers-work). + + ### Routing Group A routing group is a set of routing peers. Each peer in the group routes packets between your routed network and other NetBird peers. Using a routing group provides automatic high availability. diff --git a/src/pages/manage/network-routes/use-cases/by-configuration/access-control.mdx b/src/pages/manage/network-routes/use-cases/by-configuration/access-control.mdx index 235b6be6..f033652f 100644 --- a/src/pages/manage/network-routes/use-cases/by-configuration/access-control.mdx +++ b/src/pages/manage/network-routes/use-cases/by-configuration/access-control.mdx @@ -6,6 +6,10 @@ By default, network routes allow unrestricted access when no access control groups are assigned. When you assign access control groups to a route, only traffic that matches the defined policies can access the routed network. + +For the mental model — see [How Routing Peers Work — Access control behavior](/manage/networks/how-routing-peers-work#access-control-behavior). + + ## How Route Access Policies Work Route access policies are unidirectional and apply only from routing clients to routing peers. The access control group takes effect only when used as a destination group in a policy. diff --git a/src/pages/manage/network-routes/use-cases/by-scenario/exit-nodes.mdx b/src/pages/manage/network-routes/use-cases/by-scenario/exit-nodes.mdx index a0702645..f42637d4 100644 --- a/src/pages/manage/network-routes/use-cases/by-scenario/exit-nodes.mdx +++ b/src/pages/manage/network-routes/use-cases/by-scenario/exit-nodes.mdx @@ -20,6 +20,10 @@ A default route (`0.0.0.0/0` for IPv4) directs all internet traffic through a de The routing peer acts as the exit node for internet traffic. It applies masquerading so that traffic appears to originate from the routing peer's public IP address. + +For the mental model — see [How Routing Peers Work — Exit node mode](/manage/networks/how-routing-peers-work#exit-node-mode). + + ### Distribution Groups Peers in the distribution groups send their internet traffic through the routing peer once it connects. diff --git a/src/pages/manage/networks/index.mdx b/src/pages/manage/networks/index.mdx index 8d9e09e5..0afbf39b 100644 --- a/src/pages/manage/networks/index.mdx +++ b/src/pages/manage/networks/index.mdx @@ -4,10 +4,6 @@ NetBird creates a secure peer-to-peer mesh network where devices running the Net However, installing the agent on every machine is not always feasible. Networks solve this by letting you route traffic to entire LANs, office networks, or cloud VPCs without requiring the NetBird agent on each device. - -For the mental model behind routing peers — how traffic flows, host requirements, HA, masquerade, the forward-vs-input-chain rule, and hardening — see [How Routing Peers Work](/manage/networks/how-routing-peers-work). - -

high-level-dia

@@ -46,6 +42,10 @@ To get alerted when a routing peer goes offline, enable the **Routing Peer Disco A network resource policy grants access to the network **behind** the routing peer, not to the routing peer machine itself. If you need to access services running on the routing peer (for example, Pi-hole, Home Assistant, or a monitoring dashboard), add the routing peer to a group and create a peer-to-peer [access control policy](/manage/access-control) with that group as the destination. + +For the mental model — how traffic flows, host requirements, HA, masquerade, and the forward-vs-input-chain rule — see [How Routing Peers Work](/manage/networks/how-routing-peers-work). + + ### Resources Resources are the machines, services, or subnets you want to access within your internal network. You can define resources as: diff --git a/src/pages/manage/networks/use-cases/by-scenario/access-home-devices.mdx b/src/pages/manage/networks/use-cases/by-scenario/access-home-devices.mdx index e741c4e1..a41fdcb4 100644 --- a/src/pages/manage/networks/use-cases/by-scenario/access-home-devices.mdx +++ b/src/pages/manage/networks/use-cases/by-scenario/access-home-devices.mdx @@ -4,6 +4,10 @@ import { Note } from '@/components/mdx' This guide shows how to access your home network devices from anywhere using the Networks feature. + +For the mental model — see [How Routing Peers Work — Mental model](/manage/networks/how-routing-peers-work#mental-model-how-traffic-flows). + + ## What You'll Achieve After following this guide, you'll be able to access your home NAS, media server, home automation, or any device on your home network from your laptop or phone—anywhere in the world. diff --git a/src/pages/manage/networks/use-cases/by-scenario/cloud-to-on-premise.mdx b/src/pages/manage/networks/use-cases/by-scenario/cloud-to-on-premise.mdx index d39bc3eb..1fd80928 100644 --- a/src/pages/manage/networks/use-cases/by-scenario/cloud-to-on-premise.mdx +++ b/src/pages/manage/networks/use-cases/by-scenario/cloud-to-on-premise.mdx @@ -4,6 +4,10 @@ import { Note } from '@/components/mdx' This guide shows how to connect cloud workloads to on-premise databases and services using the Networks feature. + +For the mental model — see [How Routing Peers Work — Mental model](/manage/networks/how-routing-peers-work#mental-model-how-traffic-flows). + + ## What You'll Achieve After following this guide, your cloud applications will be able to securely access on-premise databases, APIs, and services without exposing them to the public internet. diff --git a/src/pages/manage/networks/use-cases/by-scenario/remote-worker-access.mdx b/src/pages/manage/networks/use-cases/by-scenario/remote-worker-access.mdx index 41794624..3030cbad 100644 --- a/src/pages/manage/networks/use-cases/by-scenario/remote-worker-access.mdx +++ b/src/pages/manage/networks/use-cases/by-scenario/remote-worker-access.mdx @@ -4,6 +4,10 @@ import { Note } from '@/components/mdx' This guide shows how to enable remote workers to securely access office resources using the Networks feature. + +For the mental model — see [How Routing Peers Work — Mental model](/manage/networks/how-routing-peers-work#mental-model-how-traffic-flows). + + ## What You'll Achieve After following this guide, employees will be able to access office servers, applications, and services while working remotely—without exposing those resources to the internet. diff --git a/src/pages/use-cases/cloud/routing-peers-and-kubernetes.mdx b/src/pages/use-cases/cloud/routing-peers-and-kubernetes.mdx index def17b5f..597471d4 100644 --- a/src/pages/use-cases/cloud/routing-peers-and-kubernetes.mdx +++ b/src/pages/use-cases/cloud/routing-peers-and-kubernetes.mdx @@ -4,6 +4,10 @@ import {Note} from "@/components/mdx"; This guide provides instructions on how to use NetBird agent within a Kubernetes cluster to establish secure, peer-to-peer networking between your Kubernetes pods and external services or other clusters. + +For the mental model — see [How Routing Peers Work — Requirements](/manage/networks/how-routing-peers-work#requirements). + + ## Prerequisites - Access to a Kubernetes cluster - Kubernetes CLI (kubectl) installed and configured diff --git a/src/pages/use-cases/site-to-site/index.mdx b/src/pages/use-cases/site-to-site/index.mdx index f085e6f3..e8f1adc6 100644 --- a/src/pages/use-cases/site-to-site/index.mdx +++ b/src/pages/use-cases/site-to-site/index.mdx @@ -4,6 +4,10 @@ import { Tiles } from '@/components/Tiles' Site-to-site connectivity allows you to connect entire networks together, enabling devices to communicate across locations without installing the NetBird client on every device. + +For the mental model — see [How Routing Peers Work — Networks vs Network Routes](/manage/networks/how-routing-peers-work#networks-vs-network-routes). + + ## Understanding Remote Access Scenarios NetBird supports three distinct remote access scenarios. Understanding which one you need is the first step to a successful setup. From 51a693d124f8e942ce24c4c81ca01eb12ff3db67 Mon Sep 17 00:00:00 2001 From: Jack Carter <128555021+SunsetDrifter@users.noreply.github.com> Date: Tue, 5 May 2026 14:38:05 +0200 Subject: [PATCH 3/3] docs(routing-peers): spell out HA across the primer and cross-link notes - Index-page cross-link notes (manage/networks, manage/network-routes): expand "HA" to "high availability" in the bullet list - Primer page: spell out the three remaining HA references in the High availability section and Common pitfalls; use "highly available peers" as the adjective form --- src/pages/manage/network-routes/index.mdx | 2 +- src/pages/manage/networks/how-routing-peers-work.mdx | 6 +++--- src/pages/manage/networks/index.mdx | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/src/pages/manage/network-routes/index.mdx b/src/pages/manage/network-routes/index.mdx index 8acb00ca..5fafc9d3 100644 --- a/src/pages/manage/network-routes/index.mdx +++ b/src/pages/manage/network-routes/index.mdx @@ -38,7 +38,7 @@ A network route grants access to the network behind the routing peer, not to the -For the mental model — how traffic flows, host requirements, HA, masquerade, and the forward-vs-input-chain rule — see [How Routing Peers Work](/manage/networks/how-routing-peers-work). +For the mental model — how traffic flows, host requirements, high availability, masquerade, and the forward-vs-input-chain rule — see [How Routing Peers Work](/manage/networks/how-routing-peers-work). ### Routing Group diff --git a/src/pages/manage/networks/how-routing-peers-work.mdx b/src/pages/manage/networks/how-routing-peers-work.mdx index 813fcf73..e85242c9 100644 --- a/src/pages/manage/networks/how-routing-peers-work.mdx +++ b/src/pages/manage/networks/how-routing-peers-work.mdx @@ -90,7 +90,7 @@ The routing peer must have direct network reachability to the resources it serve ## High availability -Multiple routing peers can serve the same network or route. Behavior depends on the **metric** you assign each routing peer in the dashboard. There are no tunable thresholds — the metric is the only HA control. +Multiple routing peers can serve the same network or route. Behavior depends on the **metric** you assign each routing peer in the dashboard. There are no tunable thresholds — the metric is the only high availability control. ### Primary / failover (different metrics) @@ -106,7 +106,7 @@ Useful when routing peers are geographically distributed and you want each clien ### Failure domains -Place HA peers in different failure domains within the same network: separate AZs in cloud, separate hypervisors or hosts on-prem. +Place highly available peers in different failure domains within the same network: separate AZs in cloud, separate hypervisors or hosts on-prem. ## Masquerade @@ -201,7 +201,7 @@ Specifics: - Network Route with no ACL Groups, granting blanket access. - Policy to a network resource works, but SSH to the routing peer itself is denied because the input chain has no matching policy. -- HA peers in the same AZ, defeating the purpose of HA. +- Highly available peers in the same AZ, defeating the redundancy. - Mixing domain and IP-range resources in the same network. - Exit node missing the ICMP policy, so clients can't connect to the routing peer in the first place. - DNS port mismatch when an account has a mix of pre-0.59 and post-0.59 peers. diff --git a/src/pages/manage/networks/index.mdx b/src/pages/manage/networks/index.mdx index 0afbf39b..5d89dd2b 100644 --- a/src/pages/manage/networks/index.mdx +++ b/src/pages/manage/networks/index.mdx @@ -43,7 +43,7 @@ A network resource policy grants access to the network **behind** the routing pe -For the mental model — how traffic flows, host requirements, HA, masquerade, and the forward-vs-input-chain rule — see [How Routing Peers Work](/manage/networks/how-routing-peers-work). +For the mental model — how traffic flows, host requirements, high availability, masquerade, and the forward-vs-input-chain rule — see [How Routing Peers Work](/manage/networks/how-routing-peers-work). ### Resources