Netbird Feature Request: Tunnel-Aware Relay/Transport Mode

Nov 30, 2025 by Alex Johnson 59 views

Introduction

This article delves into a feature request for Netbird, focusing on the implementation of a tunnel-aware relay/transport mode. The primary goal is to enable Netbird traffic to seamlessly traverse existing HTTPS/WebSocket tunnels and reverse-proxy setups, such as those provided by Tailscale Funnel or Cloudflare Tunnel. This enhancement aims to streamline the process of relaying Netbird packets through a single entry point, thereby simplifying network configurations and improving overall efficiency.Currently, achieving this functionality requires a complex amalgamation of tools like wstunnel, TProxy, nftables, and custom routing. The user proposes a more straightforward, officially supported method that would significantly ease the deployment and management of Netbird in environments with stringent network restrictions. This article will explore the existing challenges, the proposed solutions, and the potential benefits of incorporating a tunnel-aware relay/transport mode into Netbird.

Summary of the Feature Request

At its core, this feature request aims to simplify the way Netbird handles traffic in environments where direct UDP connections are not feasible. The current workaround involves a complex setup using tools like wstunnel and nftables to route traffic through tunnels. This setup is not only intricate but also prone to issues, such as connection drops and P2P connectivity problems. The user proposes two primary solutions:

A simple WG-style local UDP frontend that can be tunneled through tools like wstunnel, Tailscale Funnel, or Cloudflare Tunnel.
Allowing native WireGuard clients to connect directly to netbird-manager, so Netbird can handle routing/peering while reusing existing WG-over-HTTPS/WebSocket setups.

These solutions would provide a more robust and easier-to-manage way to deploy Netbird in restricted networks, reducing the complexity and potential points of failure. By implementing one of these approaches, Netbird can better cater to users who need to operate in environments where direct UDP traffic is blocked or heavily filtered.

Current Working Solution with WireGuard + wstunnel

To illustrate the complexity of the current workaround, let's examine the user's existing solution for WireGuard. This setup involves using wstunnel to forward WireGuard traffic over WebSocket. The wstunnel configuration is as follows:

ExecStart=/usr/bin/wstunnel client \
  --http-headers-file /etc/wstunnel/headers \
  --connection-retry-max-backoff 120s \
  --websocket-ping-frequency 60s \
  --dns-resolver dns+https://1.1.1.1?sni=cloudflare-dns.com \
  -P v1/specialpath \
  -L udp://8080:targetvg_server:51822?timeout_sec=0 \
  -R socks5://127.0.0.1:8822 \
  wss://trustedserver:443

This configuration sets up wstunnel as a client that connects to a trusted server over WebSocket (wss://trustedserver:443). It forwards UDP traffic from 127.0.0.1:8080 to the target WireGuard server and uses a SOCKS5 proxy for routing. The WireGuard configuration is as follows:

[connection]
id=SomeID
type=wireguard
autoconnect=false

[wireguard]
mtu=1200
private-key=xxx=

[wireguard-peer.xxx=]
endpoint=127.0.0.1:8080
preshared-key=xxxx=
preshared-key-flags=0
persistent-keepalive=20
allowed-ips=x.x.x.x/24;

[ipv4]
address1=x.x.x.x/32
gateway=x.x.x.x
method=manual

In this setup, WireGuard communicates with 127.0.0.1:8080 over UDP, and wstunnel handles the forwarding over WebSocket. While this solution works, it requires careful configuration and is not easily scalable or maintainable. Each component must be meticulously configured, and any changes to the network environment may necessitate significant adjustments to the setup. This complexity underscores the need for a more integrated and user-friendly approach within Netbird itself.

Current Workaround for Netbird + wstunnel TProxy

Replicating the above setup with Netbird is even more complex, involving the use of wstunnel’s TPROXY mode. The wstunnel configuration for Netbird is as follows:

ExecStart=/usr/bin/wstunnel client \
  --http-headers-file /etc/wstunnel/headers \
  --connection-retry-max-backoff 5m \
  --websocket-ping-frequency 30s \
  --connection-min-idle 2 \
  --dns-resolver dns+https://1.1.1.1?sni=cloudflare-dns.com \
  -P v1/a9f0b1c2d3e4f5 \
  -L 'tproxy+tcp://15001' \
  -L 'tproxy+udp://15001?timeout_sec=3600' \
  wss://trustedserver:443

This configuration uses wstunnel in TPROXY mode, which allows it to intercept and forward TCP and UDP traffic. To ensure that Netbird traffic is routed through wstunnel, the user employs nftables rules to mark traffic originating from the netbird user and redirect it to wstunnel. The /etc/firewalld/direct.xml file contains the nftables rules:

<?xml version="1.0" encoding="utf-8"?>
<direct>
  <rule ipv="ipv4" table="mangle" chain="OUTPUT" priority="0">-o lo -j RETURN</rule>
  <rule ipv="ipv4" table="mangle" chain="OUTPUT" priority="1">-m owner --uid-owner wstunnel -j RETURN</rule>

  <rule ipv="ipv4" table="mangle" chain="OUTPUT" priority="2">-m owner --uid-owner netbird -d <netbird_iprange> -j RETURN</rule>
  <rule ipv="ipv4" table="mangle" chain="OUTPUT" priority="2">-m owner --uid-owner netbird -d 100.100.100.200/32 -j RETURN</rule>
  <rule ipv="ipv4" table="mangle" chain="OUTPUT" priority="2">-m owner --uid-owner netbird -d 169.254.169.254/32 -j RETURN</rule>
  <rule ipv="ipv4" table="mangle" chain="OUTPUT" priority="2">-m owner --uid-owner netbird -p udp --dport 53 -j RETURN</rule>
  <rule ipv="ipv4" table="mangle" chain="OUTPUT" priority="2">-m owner --uid-owner netbird -p tcp --dport 53 -j RETURN</rule>

  <rule ipv="ipv4" table="mangle" chain="OUTPUT" priority="3">-m owner --uid-owner netbird -j MARK --set-mark 0x66</rule>

  <rule ipv="ipv4" table="mangle" chain="PREROUTING" priority="0">-d <network_ip_relay> -m mark --mark 0x66 -j RETURN</rule>
  <rule ipv="ipv4" table="mangle" chain="PREROUTING" priority="0">-d 100.100.100.200/32 -m mark --mark 0x66 -j RETURN</rule>
  <rule ipv="ipv4" table="mangle" chain="PREROUTING" priority="0">-d 169.254.169.254/32 -m mark --mark 0x66 -j RETURN</rule>

  <rule ipv="ipv4" table="mangle" chain="PREROUTING" priority="1">-p udp -m mark --mark 0x66 -j TPROXY --on-port 15001 --on-ip 127.0.0.1</rule>
  <rule ipv="ipv4" table="mangle" chain="PREROUTING" priority="2">-p tcp -m mark --mark 0x66 -j TPROXY --on-port 15001 --on-ip 127.0.0.1</rule>

  <rule ipv="ipv4" table="nat" chain="POSTROUTING" priority="0">-s <network_ip_relay> -o ens192 -j MASQUERADE</rule>
  <rule ipv="ipv4" table="nat" chain="OUTPUT" priority="0">-m owner --uid-owner netbird -p udp --dport 53 -j DNAT --to-destination 1.1.1.1:53</rule>
  <rule ipv="ipv4" table="nat" chain="OUTPUT" priority="1">-m owner --uid-owner netbird -p tcp --dport 53 -j DNAT --to-destination 1.1.1.1:53</rule>
</direct>

Additionally, a systemd service (/etc/systemd/system/wstunnel-tproxy-routing.service) is used to configure policy routing for Netbird traffic:

[Unit]
Description=policy routing for netbird→wstunnel
After=network.target

[Service]
Type=oneshot
ExecStart=/usr/bin/ip rule add pref 98 fwmark 0x66 lookup 101
ExecStart=/usr/bin/ip route replace local 0.0.0.0/0 dev lo table 101
RemainAfterExit=yes

[Install]
WantedBy=multi-user.target

This setup, while functional, is highly complex and fragile. It interferes with Netbird’s own routing table and requires a deep understanding of networking concepts and tools like nftables and TPROXY. The complexity of this workaround highlights the need for a more integrated and user-friendly solution within Netbird.

Problems with the Current Workaround

The current workaround, while functional, suffers from several issues:

After approximately 6 hours (likely due to key exchange intervals), Netbird loses its TProxy port mapping and fails to reconnect, necessitating a service restart.
P2P connectivity is unreliable due to ICE (Interactive Connectivity Establishment) issues, even with UDP TProxy configured.
TURN (Traversal Using Relays around NAT) proxy functionality is limited, with only rels:// URLs working.
Each internal IP address that requires relaying must be manually added to nftables, making the setup cumbersome to manage and scale.

These issues underscore the instability and management overhead associated with the current workaround. A more integrated solution would address these problems and provide a more reliable and maintainable experience for users.

Proposed Solutions

To address the limitations of the current workaround, the user proposes several solutions.

1. Minimal Requirement: Simple “WG-style” UDP Frontend

The first proposed solution is to allow Netbird to send its tunnel traffic to a single local UDP endpoint, similar to how WireGuard works with wstunnel. This approach would significantly simplify the setup and reduce the complexity of the current workaround. The key idea is to configure Netbird to send all traffic destined for the relay/manager to a local UDP endpoint, such as 127.0.0.1:8080. A local wstunnel instance would then listen on this endpoint and forward the traffic over wss://trustedserver:443 to the real Netbird/relay endpoint.

From Netbird’s perspective, this would be a normal UDP endpoint, with all WebSocket/HTTPS handling managed by wstunnel. This approach would eliminate the need for TProxy, fwmarks, extra routing tables, and most of the nftables complexity on the client. By abstracting the tunneling mechanism behind a simple UDP interface, Netbird can focus on its core functionality without being encumbered by the intricacies of WebSocket or HTTPS tunneling.

2. Alternative: Allow Native WireGuard Clients to Connect to `netbird-manager`

Another proposed solution is to allow native WireGuard clients (using standard wg/wg-quick) to connect directly to netbird-manager as first-class peers. In this scenario, netbird-manager would issue proper WireGuard configurations for these peers and ensure that Netbird clients treat them as regular Netbird peers, routing traffic accordingly.

This approach would enable users to leverage the well-tested wg + wstunnel combination on restricted networks while still benefiting from Netbird’s control plane, ACLs, and mesh logic. By integrating native WireGuard clients into the Netbird ecosystem, users can seamlessly combine the flexibility of WireGuard with the advanced management capabilities of Netbird. This integration would provide a powerful and versatile solution for users operating in complex network environments.

3. Nice to Have: Tunnel-Aware Manager / Obfuscation

Beyond the minimal requirements, the user suggests several enhancements that would further improve tunnel setups. One such enhancement is making netbird-manager tunnel-aware. This would involve the manager preferring local tunnel/relay addresses for peers known to be behind a tunnel/WebSocket, instead of serving public relay information. This would prevent peers from attempting to connect via unreachable public IPs when they can only communicate through the tunnel.

Additionally, the user suggests providing a native obfuscation / pluggable transport mode that wraps Netbird traffic in something HTTP(S)/WebSocket-like. This would enable Netbird traffic to be forwarded via generic tunnel providers such as Tailscale Funnel and Cloudflare Tunnel, eliminating the need for complex workarounds like TProxy and nftables. By providing built-in obfuscation and transport capabilities, Netbird can significantly simplify deployment in restrictive network environments and enhance the user experience.

Conclusion

The feature request for a tunnel-aware relay/transport mode in Netbird highlights the need for a more streamlined and user-friendly approach to deploying Netbird in restricted network environments. The current workaround, while functional, is complex and prone to issues. The proposed solutions, such as a simple UDP frontend and native WireGuard client support, would significantly simplify the setup and improve the reliability of Netbird in these environments.

While tunnel-awareness and obfuscation are valuable additions, the core of the request lies in enabling Netbird to operate effectively behind tunnels without requiring complex configurations. By implementing one of the proposed solutions, Netbird can better serve users who need to operate in restrictive network environments and solidify its position as a versatile and powerful network management solution.

For more information on related topics, you might find the WireGuard website a valuable resource: WireGuard