[reverse-proxy] Add listener side proxy protocol support and enable it in traefik

go.mod

@@ -83,6 +83,7 @@ require (
 	github.com/pion/stun/v3 v3.1.0
 	github.com/pion/transport/v3 v3.1.1
 	github.com/pion/turn/v3 v3.0.1
+	github.com/pires/go-proxyproto v0.11.0
 	github.com/pkg/sftp v1.13.9
 	github.com/prometheus/client_golang v1.23.2
 	github.com/quic-go/quic-go v0.55.0

go.sum

@@ -474,6 +474,8 @@ github.com/pion/turn/v3 v3.0.1 h1:wLi7BTQr6/Q20R0vt/lHbjv6y4GChFtC33nkYbasoT8=
 github.com/pion/turn/v3 v3.0.1/go.mod h1:MrJDKgqryDyWy1/4NT9TWfXWGMC7UHT6pJIv1+gMeNE=
 github.com/pion/turn/v4 v4.1.1 h1:9UnY2HB99tpDyz3cVVZguSxcqkJ1DsTSZ+8TGruh4fc=
 github.com/pion/turn/v4 v4.1.1/go.mod h1:2123tHk1O++vmjI5VSD0awT50NywDAq5A2NNNU4Jjs8=
+github.com/pires/go-proxyproto v0.11.0 h1:gUQpS85X/VJMdUsYyEgyn59uLJvGqPhJV5YvG68wXH4=
+github.com/pires/go-proxyproto v0.11.0/go.mod h1:ZKAAyp3cgy5Y5Mo4n9AlScrkCZwUy0g3Jf+slqQVcuU=
 github.com/pkg/errors v0.8.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
 github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=

infrastructure_files/getting-started.sh

@@ -329,6 +329,9 @@ initialize_default_values() {
   BIND_LOCALHOST_ONLY="true"
   EXTERNAL_PROXY_NETWORK=""
 
+  # Traefik static IP within the internal bridge network
+  TRAEFIK_IP="172.30.0.10"
+
   # NetBird Proxy configuration
   ENABLE_PROXY="false"
   PROXY_DOMAIN=""
@@ -393,7 +396,7 @@ check_existing_installation() {
     echo "Generated files already exist, if you want to reinitialize the environment, please remove them first."
     echo "You can use the following commands:"
     echo "  $DOCKER_COMPOSE_COMMAND down --volumes # to remove all containers and volumes"
-    echo "  rm -f docker-compose.yml dashboard.env config.yaml proxy.env nginx-netbird.conf caddyfile-netbird.txt npm-advanced-config.txt"
+    echo "  rm -f docker-compose.yml dashboard.env config.yaml proxy.env traefik-dynamic.yaml nginx-netbird.conf caddyfile-netbird.txt npm-advanced-config.txt"
     echo "Be aware that this will remove all data from the database, and you will have to reconfigure the dashboard."
     exit 1
   fi
@@ -412,6 +415,8 @@ generate_configuration_files() {
         # This will be overwritten with the actual token after netbird-server starts
         echo "# Placeholder - will be updated with token after netbird-server starts" > proxy.env
         echo "NB_PROXY_TOKEN=placeholder" >> proxy.env
+        # TCP ServersTransport for PROXY protocol v2 to the proxy backend
+        render_traefik_dynamic > traefik-dynamic.yaml
       fi
       ;;
     1)
@@ -559,18 +564,22 @@ init_environment() {
 ############################################
 
 render_docker_compose_traefik_builtin() {
-  # Generate proxy service section if enabled
+  # Generate proxy service section and Traefik dynamic config if enabled
   local proxy_service=""
   local proxy_volumes=""
+  local traefik_file_provider=""
+  local traefik_dynamic_volume=""
   if [[ "$ENABLE_PROXY" == "true" ]]; then
+    traefik_file_provider='      - "--providers.file.filename=/etc/traefik/dynamic.yaml"'
+    traefik_dynamic_volume="      - ./traefik-dynamic.yaml:/etc/traefik/dynamic.yaml:ro"
     proxy_service="
   # NetBird Proxy - exposes internal resources to the internet
   proxy:
     image: $NETBIRD_PROXY_IMAGE
     container_name: netbird-proxy
     # Hairpin NAT fix: route domain back to traefik's static IP within Docker
     extra_hosts:
-      - \"$NETBIRD_DOMAIN:172.30.0.10\"
+      - \"$NETBIRD_DOMAIN:$TRAEFIK_IP\"
     ports:
     - 51820:51820/udp
     restart: unless-stopped
@@ -590,6 +599,7 @@ render_docker_compose_traefik_builtin() {
       - traefik.tcp.routers.proxy-passthrough.service=proxy-tls
       - traefik.tcp.routers.proxy-passthrough.priority=1
       - traefik.tcp.services.proxy-tls.loadbalancer.server.port=8443
+      - traefik.tcp.services.proxy-tls.loadbalancer.serverstransport=pp-v2@file
     logging:
       driver: \"json-file\"
       options:
@@ -609,7 +619,7 @@ services:
     restart: unless-stopped
     networks:
       netbird:
-        ipv4_address: 172.30.0.10
+        ipv4_address: $TRAEFIK_IP
     command:
       # Logging
       - "--log.level=INFO"
@@ -636,12 +646,14 @@ services:
       # gRPC transport settings
       - "--serverstransport.forwardingtimeouts.responseheadertimeout=0s"
       - "--serverstransport.forwardingtimeouts.idleconntimeout=0s"
+$traefik_file_provider
     ports:
       - '443:443'
       - '80:80'
     volumes:
       - /var/run/docker.sock:/var/run/docker.sock:ro
       - netbird_traefik_letsencrypt:/letsencrypt
+$traefik_dynamic_volume
     logging:
       driver: "json-file"
       options:
@@ -751,6 +763,10 @@ server:
     cliRedirectURIs:
       - "http://localhost:53000/"
 
+  reverseProxy:
+    trustedHTTPProxies:
+      - "$TRAEFIK_IP/32"
+
   store:
     engine: "sqlite"
     encryptionKey: "$DATASTORE_ENCRYPTION_KEY"
@@ -780,6 +796,17 @@ EOF
   return 0
 }
 
+render_traefik_dynamic() {
+  cat <<'EOF'
+tcp:
+  serversTransports:
+    pp-v2:
+      proxyProtocol:
+        version: 2
+EOF
+  return 0
+}
+
 render_proxy_env() {
   cat <<EOF
 # NetBird Proxy Configuration
@@ -799,6 +826,10 @@ NB_PROXY_OIDC_CLIENT_ID=netbird-proxy
 NB_PROXY_OIDC_ENDPOINT=$NETBIRD_HTTP_PROTOCOL://$NETBIRD_DOMAIN/oauth2
 NB_PROXY_OIDC_SCOPES=openid,profile,email
 NB_PROXY_FORWARDED_PROTO=https
+# Enable PROXY protocol to preserve client IPs through L4 proxies (Traefik TCP passthrough)
+NB_PROXY_PROXY_PROTOCOL=true
+# Trust Traefik's IP for PROXY protocol headers
+NB_PROXY_TRUSTED_PROXIES=$TRAEFIK_IP
 EOF
   return 0
 }

proxy/cmd/proxy/cmd/root.go

@@ -56,6 +56,7 @@ var (
 	certKeyFile       string
 	certLockMethod    string
 	wgPort            int
+	proxyProtocol     bool
 )
 
 var rootCmd = &cobra.Command{
@@ -90,6 +91,7 @@ func init() {
 	rootCmd.Flags().StringVar(&certKeyFile, "cert-key-file", envStringOrDefault("NB_PROXY_CERTIFICATE_KEY_FILE", "tls.key"), "TLS certificate key filename within the certificate directory")
 	rootCmd.Flags().StringVar(&certLockMethod, "cert-lock-method", envStringOrDefault("NB_PROXY_CERT_LOCK_METHOD", "auto"), "Certificate lock method for cross-replica coordination: auto, flock, or k8s-lease")
 	rootCmd.Flags().IntVar(&wgPort, "wg-port", envIntOrDefault("NB_PROXY_WG_PORT", 0), "WireGuard listen port (0 = random). Fixed port only works with single-account deployments")
+	rootCmd.Flags().BoolVar(&proxyProtocol, "proxy-protocol", envBoolOrDefault("NB_PROXY_PROXY_PROTOCOL", false), "Enable PROXY protocol on TCP listeners to preserve client IPs behind L4 proxies")
 }
 
 // Execute runs the root command.
@@ -165,6 +167,7 @@ func runServer(cmd *cobra.Command, args []string) error {
 		TrustedProxies:           parsedTrustedProxies,
 		CertLockMethod:           nbacme.CertLockMethod(certLockMethod),
 		WireguardPort:            wgPort,
+		ProxyProtocol:            proxyProtocol,
 	}
 
 	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGTERM, syscall.SIGINT)

proxy/proxyprotocol_test.go

@@ -0,0 +1,106 @@
+package proxy
+
+import (
+	"net"
+	"net/netip"
+	"testing"
+	"time"
+
+	proxyproto "github.com/pires/go-proxyproto"
+	log "github.com/sirupsen/logrus"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestWrapProxyProtocol_OverridesRemoteAddr(t *testing.T) {
+	srv := &Server{
+		Logger:         log.StandardLogger(),
+		TrustedProxies: []netip.Prefix{netip.MustParsePrefix("127.0.0.1/32")},
+		ProxyProtocol:  true,
+	}
+
+	raw, err := net.Listen("tcp", "127.0.0.1:0")
+	require.NoError(t, err)
+	defer raw.Close()
+
+	ln := srv.wrapProxyProtocol(raw)
+
+	realClientIP := "203.0.113.50"
+	realClientPort := uint16(54321)
+
+	accepted := make(chan net.Conn, 1)
+	go func() {
+		conn, err := ln.Accept()
+		if err != nil {
+			return
+		}
+		accepted <- conn
+	}()
+
+	// Connect and send a PROXY v2 header.
+	conn, err := net.Dial("tcp", ln.Addr().String())
+	require.NoError(t, err)
+	defer conn.Close()
+
+	header := &proxyproto.Header{
+		Version:           2,
+		Command:           proxyproto.PROXY,
+		TransportProtocol: proxyproto.TCPv4,
+		SourceAddr:        &net.TCPAddr{IP: net.ParseIP(realClientIP), Port: int(realClientPort)},
+		DestinationAddr:   &net.TCPAddr{IP: net.ParseIP("10.0.0.1"), Port: 443},
+	}
+	_, err = header.WriteTo(conn)
+	require.NoError(t, err)
+
+	select {
+	case accepted := <-accepted:
+		defer accepted.Close()
+		host, _, err := net.SplitHostPort(accepted.RemoteAddr().String())
+		require.NoError(t, err)
+		assert.Equal(t, realClientIP, host, "RemoteAddr should reflect the PROXY header source IP")
+	case <-time.After(2 * time.Second):
+		t.Fatal("timed out waiting for connection")
+	}
+}
+
+func TestProxyProtocolPolicy_TrustedRequires(t *testing.T) {
+	srv := &Server{
+		Logger:         log.StandardLogger(),
+		TrustedProxies: []netip.Prefix{netip.MustParsePrefix("10.0.0.0/8")},
+	}
+
+	opts := proxyproto.ConnPolicyOptions{
+		Upstream: &net.TCPAddr{IP: net.ParseIP("10.0.0.1"), Port: 1234},
+	}
+	policy, err := srv.proxyProtocolPolicy(opts)
+	require.NoError(t, err)
+	assert.Equal(t, proxyproto.REQUIRE, policy, "trusted source should require PROXY header")
+}
+
+func TestProxyProtocolPolicy_UntrustedIgnores(t *testing.T) {
+	srv := &Server{
+		Logger:         log.StandardLogger(),
+		TrustedProxies: []netip.Prefix{netip.MustParsePrefix("10.0.0.0/8")},
+	}
+
+	opts := proxyproto.ConnPolicyOptions{
+		Upstream: &net.TCPAddr{IP: net.ParseIP("203.0.113.50"), Port: 1234},
+	}
+	policy, err := srv.proxyProtocolPolicy(opts)
+	require.NoError(t, err)
+	assert.Equal(t, proxyproto.IGNORE, policy, "untrusted source should have PROXY header ignored")
+}
+
+func TestProxyProtocolPolicy_InvalidIPRejects(t *testing.T) {
+	srv := &Server{
+		Logger:         log.StandardLogger(),
+		TrustedProxies: []netip.Prefix{netip.MustParsePrefix("10.0.0.0/8")},
+	}
+
+	opts := proxyproto.ConnPolicyOptions{
+		Upstream: &net.UnixAddr{Name: "/tmp/test.sock", Net: "unix"},
+	}
+	policy, err := srv.proxyProtocolPolicy(opts)
+	require.NoError(t, err)
+	assert.Equal(t, proxyproto.REJECT, policy, "unparsable address should be rejected")
+}