How Routing Peers Work

A routing peer is a NetBird agent that bridges your overlay network to private networks and resources that do not run the agent. This page covers what routing peers are, how traffic flows through them, the requirements they impose on the host, how high availability and access control behave, and how to harden them.

What is a routing peer

A routing peer is a NetBird peer installed inside a private network that forwards traffic between the NetBird overlay and resources that cannot or should not run the agent themselves. It is the bridge between your Zero Trust mesh and the LANs, VPCs, datacenter networks, or individual hosts you need to reach.

A single peer can serve multiple roles at once. The same machine can be a client peer, a routing peer for one or more networks, and an exit node simultaneously.

Because routing peers are typically headless servers, register them with setup keys rather than interactive login.

When to use a routing peer

• Site or LAN access. NetBird peers need to reach resources on a remote subnet, office network, datacenter, or cloud VPC without installing the agent on every host.
• Domain-based access. Traffic must be routed by FQDN or wildcard domain to services whose IPs change.
• Exit node. All internet-bound traffic from a group of peers must egress through a controlled location.
• Kubernetes. Pods or services need to be reachable from NetBird peers without putting an agent on every node.

Networks vs Network Routes

NetBird offers two ways to configure routing peers. Both are actively maintained.

Networks (newer, recommended where possible)

• Mandatory groups for both routing peers and resources. Traffic is denied by default until a policy permits it.
• Resources are typed: IP, IP range, or domain.
• Access control is built in from the start.

Routes (legacy, deprecated)

• Distribution Groups and ACL Groups are configured separately.
• ACL Groups are optional, which means a route without them grants unrestricted access to the destination CIDR for every peer in the Distribution Group.
• Only needed today for exit node setups. Use Networks for everything else, including site-to-site.

Mental model: how traffic flows

The walkthrough below describes the Linux kernel-mode path, where forwarding and firewalling happen in the kernel via nftables / iptables. On other platforms, NetBird performs the same logical steps in a userspace filter, but the implementation differs.

1. The originating peer encrypts the packet to the routing peer's WireGuard public key. The packet enters the tunnel at the source and exits on the routing peer's NetBird interface.
2. The routing peer's kernel forwards the packet according to the host routing table. If the destination is on a directly attached network or reachable via the host's gateway, the packet is forwarded.
3. Forwarded packets traverse the host firewall's forward chain. NetBird applies the policies attached to the route or network resource here. Policies that target the routing peer itself live in the input chain and are evaluated separately.
4. If masquerade is enabled (the default), the routing peer SNATs the source IP to its own LAN-side address before the packet leaves. With masquerade disabled, the original NetBird IP is preserved and the destination network must route return traffic back through the routing peer.
5. Replies follow the reverse path. The stateful firewall on the routing peer tracks established connections so return traffic does not need an explicit policy.

Requirements

Operating system

Linux, Windows, macOS, FreeBSD, Android, tvOS, and Docker peers can act as routing peers. Linux is the most common production choice because the agent runs in kernel space and integrates with native kernel firewalls (nftables / iptables). On other platforms the forwarding path runs in userspace.

IP forwarding

The agent enables IP forwarding automatically on Linux. If the agent cannot modify sysctl on its own, set it yourself on the host and persist it:

# Runtime
sudo sysctl -w net.ipv4.ip_forward=1
sudo sysctl -w net.ipv6.conf.all.forwarding=1

# Persistent
echo "net.ipv4.ip_forward=1" | sudo tee /etc/sysctl.d/99-netbird.conf
echo "net.ipv6.conf.all.forwarding=1" | sudo tee -a /etc/sysctl.d/99-netbird.conf

Local forwarding

IP forwarding (above) carries traffic to machines behind the routing peer. Reaching a service on the routing peer's own address is a separate case (self-access), and it needs NB_ENABLE_LOCAL_FORWARDING — and only on peers that forward in software (the userspace router):

The flag is off by default on every platform (see Client Environment Variables):

netbird service reconfigure --service-env NB_ENABLE_LOCAL_FORWARDING=true

This flag is only one of three things self-access needs — the peer also needs a route and a peer-to-peer policy. See Reaching the routing peer itself for the full picture. This is the common shape when the service host is the routing peer: a file server that runs the NetBird client, whose clients resolve its name to its LAN IP.

Leave it off otherwise. With it on, any permitted peer can reach services bound to the routing peer's LAN addresses, not just the networks behind it — so don't enable it on a peer running local-only services you don't want exposed.

Container capabilities

A containerized routing peer needs NET_ADMIN. The Kubernetes manifest also adds SYS_RESOURCE and SYS_ADMIN for tunnel and firewall management.

Network reachability

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.

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 high availability control.

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.

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.

Latency switching (equal metrics)

When two routing peers share the same metric, each client picks the one with lower latency. A switch only happens when the latency difference exceeds 20 ms, which prevents flapping between peers that are roughly equivalent.

Useful when routing peers are geographically distributed and you want each client to land on the closest one automatically — for example, an EU-based peer and a US-based peer serving the same network, with users on both continents.

Failure domains

Place highly available peers in different failure domains within the same network: separate AZs in cloud, separate hypervisors or hosts on-prem.

Masquerade

Masquerade is on by default. The routing peer SNATs forwarded traffic to its own LAN-side IP. This is the simplest configuration because the destination network does not need any awareness of NetBird.

Turn masquerade off when:

• You need source IP visibility for auditing, compliance, or application logic.
• You want the destination network's existing firewalls to filter peers by their NetBird IP.

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.

Access control behavior

This is the subtlest part of the model and the source of most policy mistakes.

Two chains, two policy types

• Forward chain. Packets routed through the peer to backend resources. Network resource policies (Networks) and ACL Groups (Routes) apply here.
• Input chain. Packets destined to the routing peer's own IP. Peer-to-peer policies apply here.

If users need to reach both the resources behind a routing peer and services running on the routing peer itself (Pi-hole, monitoring, jump-host SSH), you need one policy of each kind.

Example. A routing peer fronts the 10.10.0.0/16 office network and also runs Grafana on TCP/3000 plus SSH on TCP/22. To let the Engineers group reach both, create two policies:

1. Network resource policy (forward chain): Engineers → 10.10.0.0/16 resource. Permits traffic through the routing peer.
2. Peer-to-peer policy (input chain): Engineers → routing peer group, on TCP/22 and TCP/3000. Permits traffic to the routing peer.

Reaching the routing peer itself

Every peer has two addresses — its NetBird IP (its 100.x overlay address, the one in netbird status) and its LAN IP (its address on the local network). Reaching the routing peer at each needs different things:

• At its NetBird IP — a single peer-to-peer policy (input chain) is enough. Every client already has an overlay route to every peer.
• At its LAN IP — when DNS (or a DFS path) resolves the service to its LAN address, the client has no route to that IP yet. Reaching it needs three things together:
  • a resource that covers the LAN IP (the route),
  • a peer-to-peer policy (the input-chain accept), and
  • on userspace peers (Windows, macOS, Linux netstack), NB_ENABLE_LOCAL_FORWARDING.

For the full setup — the file-server scenario, the commands, the Active Directory tie-in, and a fallback for when you can't set the flag — see Reach Services on the Routing Peer.

Directionality is forced for routed traffic

Policies whose destination is a network resource are always unidirectional from source to destination. The resource has no agent and cannot initiate connections back through the overlay. The bidirectional toggle is disabled in the UI for these policies.

Network Routes default-allow caveat

DNS and domain routing

Routing peers can serve DNS-based routes in addition to CIDR-based ones.

Local DNS Forwarder

The client runs a local DNS forwarder. Queries for a routed domain go to the routing peer's resolver:

• Port 22054 for clients on 0.59.0 and newer.
• Port 5353 for clients on 0.58.x and older.

The Management service only flips an account to 22054 once every peer is on 0.59.0 or newer. Mixed-version accounts continue using 5353.

Routing Peer DNS Resolution

Domain resources rely on Routing Peer DNS Resolution, which is enabled by default. With it on, DNS resolution happens on the routing peer rather than on the client: the client forwards its name-to-IP lookups (A/AAAA) for a domain resource to the routing peer's resolver, and needs no nameserver of its own for that name. With it off, each client resolves the domain itself using its own DNS, so it must already be able to resolve the name — via a nameserver or its network adapter's DNS. Either way, this covers name-to-IP lookups only; Active Directory clients also need a nameserver for the SRV records Windows uses to find a domain controller.

Pitfall: domains and IP ranges in the same network

Exit node mode

An exit node is a routing peer with a 0.0.0.0/0 route. Internet-bound traffic from peers in the assigned distribution groups egresses through it.

Specifics:

• IPv6 is blocked to prevent leakage outside the tunnel.
• Masquerade is on by default and required in practice.
• The minimum policy for an exit node to function is ICMP from source group to the routing peer group.
• Auto Apply controls whether clients use the exit node automatically (v0.55.0+) or only when manually selected.
• Set a DNS server with match domain ALL to prevent DNS-based location leaks. Local DNS servers may not be reachable from the exit node in any case.

Observability and troubleshooting

When a peer is Connected but a resource behind it is still unreachable, Troubleshooting resource connectivity walks these checks in order, from the peer through to the TCP handshake at the resource.

• netbird status -d shows the connection type, status, and details for every peer the client is connected to.
• netbird networks ls shows which networks the client is currently using.
• netbird debug trace simulates a packet against the firewall rules without sending real traffic. Useful when policies look right but traffic is dropped. On Linux this is most informative when the kernel firewall backend is active.
• On the routing peer host:
  • sysctl net.ipv4.ip_forward to confirm forwarding.
  • ip route to confirm reachability to the destination CIDR.
  • nft list ruleset (or iptables-save) to inspect the rules NetBird installed.

Common pitfalls

• 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.
• 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.
• Reaching a service on the routing peer's own LAN IP (not its NetBird IP) with only an input policy — it also needs a resource for the route, and on userspace peers NB_ENABLE_LOCAL_FORWARDING. See Reaching the routing peer itself.
• Health-checking that path with ping — ICMP needs its own peer-to-peer policy; a service up while ping is down is a missing ICMP policy, not a routing failure.