Advanced Configuration

This page covers masquerade trade-offs, a Networks-vs-Network-Routes comparison, and troubleshooting.

For the basics — masquerade behavior, ACL Groups, HA — see Network Routes Concepts. For ACL Group setup, see Access Control. For Site-to-Site walkthroughs, see Site-to-Site.

Masquerade: when to enable or disable

Masquerade is the default. It NATs traffic through the routing peer so the remote network sees the routing peer's IP instead of the original source.

With masquerade (default):

• Works out of the box — no return route needed on the remote network
• Compatible with ACL Groups and Network Resources
• Source IP is hidden, so audit logs show the routing peer IP rather than the originating device

Without masquerade:

• Original source IPs are preserved for accurate auditing
• Required if your compliance regime needs source-IP visibility on the remote network
• Requires a return route on the remote network's infrastructure back to the NetBird CIDR

Choosing the right approach

Networks vs Network Routes

Troubleshooting

Route not active

Symptoms: Peers do not see the route; netbird routes list shows nothing.

Causes:

1. No access policy grants access to the routing peer
2. Routing peer is offline
3. ACL Group has no policies granting access

Solution:

• Ensure at least one policy connects to the routing peer's group
• Verify routing peer status in the dashboard
• Check that ACL Group policies exist

Traffic times out

Symptoms: Ping or connections hang with no response.

Causes:

1. Routing peer cannot reach the destination network
2. Masquerade is disabled and no return route exists
3. Firewall is blocking traffic

Solution:

• Test from the routing peer: ping <destination> directly
• If masquerade is off, verify return routes are configured on the remote network
• Check the OS firewall on the routing peer: iptables -L -n or equivalent

Connection works one way

Symptoms: Can reach the remote site but responses do not return.

Causes:

1. Missing reverse route (Site-to-Site)
2. Asymmetric policies
3. Stateful firewall issues

Solution:

• Ensure routes exist in both directions
• Verify policies allow return traffic
• Check firewall state tracking

Wrong traffic routed

Symptoms: Unexpected traffic going through NetBird.

Causes:

1. Overlapping routes
2. Route priority issues
3. Incorrect subnet configuration

Solution:

• Review all Network Routes for overlaps — see Overlapping Routes
• Use more specific routes where needed
• Verify subnet CIDR notation is correct

Debug commands

On the routing peer:

# NetBird status
netbird status

# Active routes
netbird routes list

# System routes
ip route show

# Monitor traffic (Linux)
sudo tcpdump -i any -n host <destination>

# Confirm IP forwarding is enabled
cat /proc/sys/net/ipv4/ip_forward

On a client peer:

# Which networks/routes are selected
netbird networks ls

# Trace the path
traceroute <destination>

Performance

• Place routing peers on machines with good network connectivity to the resources they serve and to the internet
• Avoid routing through bandwidth-constrained links
• For high-throughput scenarios, consider dedicated hardware
• Track CPU, memory, network throughput, and connection count on routing peers
• Use activity logging to monitor access patterns and troubleshoot issues

For high availability (multiple routing peers per route), see High Availability on the concept page.