client/dns/mgmt: strip wildcard prefix in pool-root membership check

isUnderPoolRoot lowercased and trimmed the trailing dot, but did not
strip a leading "*." wildcard the way server.toZone does via
nbdns.NormalizeZone. If a mgmt-advertised Relay URL ever comes through
as "*.relay.netbird.io", the handler-chain registration side strips
the wildcard (toZone) but the membership check here would keep it,
so HasSuffix(".*.relay.netbird.io") would never match legitimate
instance subdomains and on-demand resolves would not fire.

Today the extractor lowercases + IDNA-normalizes URLs and rejects the
wildcard form, so the divergence is latent. Close it anyway by running
both sides of the membership check through a shared
canonicalizePoolDomain helper that mirrors toZone's transformation
(modulo trailing-dot orientation, which is self-consistent within
this function). toZone itself lives in the parent dns package and
cannot be imported here without a cycle.

.github/workflows/proto-version-check.yml

@@ -0,0 +1,62 @@
+name: Proto Version Check
+
+on:
+  pull_request:
+    paths:
+      - "**/*.pb.go"
+
+jobs:
+  check-proto-versions:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check for proto tool version changes
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const files = await github.paginate(github.rest.pulls.listFiles, {
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: context.issue.number,
+              per_page: 100,
+            });
+
+            const pbFiles = files.filter(f => f.filename.endsWith('.pb.go'));
+            const missingPatch = pbFiles.filter(f => !f.patch).map(f => f.filename);
+            if (missingPatch.length > 0) {
+              core.setFailed(
+                `Cannot inspect patch data for:\n` +
+                missingPatch.map(f => `- ${f}`).join('\n') +
+                `\nThis can happen with very large PRs. Verify proto versions manually.`
+              );
+              return;
+            }
+            const versionPattern = /^[+-]\s*\/\/\s+protoc(?:-gen-go)?\s+v[\d.]+/;
+            const violations = [];
+
+            for (const file of pbFiles) {
+              const changed = file.patch
+                .split('\n')
+                .filter(line => versionPattern.test(line));
+              if (changed.length > 0) {
+                violations.push({
+                  file: file.filename,
+                  lines: changed,
+                });
+              }
+            }
+
+            if (violations.length > 0) {
+              const details = violations.map(v =>
+                `${v.file}:\n${v.lines.map(l => '  ' + l).join('\n')}`
+              ).join('\n\n');
+
+              core.setFailed(
+                `Proto version strings changed in generated files.\n` +
+                `This usually means the wrong protoc or protoc-gen-go version was used.\n` +
+                `Regenerate with the matching tool versions.\n\n` +
+                details
+              );
+              return;
+            }
+
+            console.log('No proto version string changes detected');

.github/workflows/release.yml

@@ -9,7 +9,7 @@ on:
   pull_request:
 
 env:
-  SIGN_PIPE_VER: "v0.1.1"
+  SIGN_PIPE_VER: "v0.1.2"
   GORELEASER_VER: "v2.14.3"
   PRODUCT_NAME: "NetBird"
   COPYRIGHT: "NetBird GmbH"

Makefile

@@ -5,7 +5,7 @@ GOLANGCI_LINT := $(shell pwd)/bin/golangci-lint
 $(GOLANGCI_LINT):
 	@echo "Installing golangci-lint..."
 	@mkdir -p ./bin
-	@GOBIN=$(shell pwd)/bin go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
+	@GOBIN=$(shell pwd)/bin go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest
 
 # Lint only changed files (fast, for pre-push)
 lint: $(GOLANGCI_LINT)

client/android/client.go

@@ -8,6 +8,7 @@ import (
 	"os"
 	"slices"
 	"sync"
+	"time"
 
 	"golang.org/x/exp/maps"
 
@@ -15,6 +16,7 @@ import (
 
 	"github.com/netbirdio/netbird/client/iface/device"
 	"github.com/netbirdio/netbird/client/internal"
+	"github.com/netbirdio/netbird/client/internal/debug"
 	"github.com/netbirdio/netbird/client/internal/dns"
 	"github.com/netbirdio/netbird/client/internal/listener"
 	"github.com/netbirdio/netbird/client/internal/peer"
@@ -26,6 +28,7 @@ import (
 	"github.com/netbirdio/netbird/formatter"
 	"github.com/netbirdio/netbird/route"
 	"github.com/netbirdio/netbird/shared/management/domain"
+	types "github.com/netbirdio/netbird/upload-server/types"
 )
 
 // ConnectionListener export internal Listener for mobile
@@ -68,7 +71,30 @@ type Client struct {
 	uiVersion             string
 	networkChangeListener listener.NetworkChangeListener
 
+	stateMu       sync.RWMutex
 	connectClient *internal.ConnectClient
+	config        *profilemanager.Config
+	cacheDir      string
+}
+
+func (c *Client) setState(cfg *profilemanager.Config, cacheDir string, cc *internal.ConnectClient) {
+	c.stateMu.Lock()
+	defer c.stateMu.Unlock()
+	c.config = cfg
+	c.cacheDir = cacheDir
+	c.connectClient = cc
+}
+
+func (c *Client) stateSnapshot() (*profilemanager.Config, string, *internal.ConnectClient) {
+	c.stateMu.RLock()
+	defer c.stateMu.RUnlock()
+	return c.config, c.cacheDir, c.connectClient
+}
+
+func (c *Client) getConnectClient() *internal.ConnectClient {
+	c.stateMu.RLock()
+	defer c.stateMu.RUnlock()
+	return c.connectClient
 }
 
 // NewClient instantiate a new Client
@@ -93,6 +119,7 @@ func (c *Client) Run(platformFiles PlatformFiles, urlOpener URLOpener, isAndroid
 
 	cfgFile := platformFiles.ConfigurationFilePath()
 	stateFile := platformFiles.StateFilePath()
+	cacheDir := platformFiles.CacheDir()
 
 	log.Infof("Starting client with config: %s, state: %s", cfgFile, stateFile)
 
@@ -124,8 +151,9 @@ func (c *Client) Run(platformFiles PlatformFiles, urlOpener URLOpener, isAndroid
 
 	// todo do not throw error in case of cancelled context
 	ctx = internal.CtxInitState(ctx)
-	c.connectClient = internal.NewConnectClient(ctx, cfg, c.recorder)
-	return c.connectClient.RunOnAndroid(c.tunAdapter, c.iFaceDiscover, c.networkChangeListener, slices.Clone(dns.items), dnsReadyListener, stateFile)
+	connectClient := internal.NewConnectClient(ctx, cfg, c.recorder)
+	c.setState(cfg, cacheDir, connectClient)
+	return connectClient.RunOnAndroid(c.tunAdapter, c.iFaceDiscover, c.networkChangeListener, slices.Clone(dns.items), dnsReadyListener, stateFile, cacheDir)
 }
 
 // RunWithoutLogin we apply this type of run function when the backed has been started without UI (i.e. after reboot).
@@ -135,6 +163,7 @@ func (c *Client) RunWithoutLogin(platformFiles PlatformFiles, dns *DNSList, dnsR
 
 	cfgFile := platformFiles.ConfigurationFilePath()
 	stateFile := platformFiles.StateFilePath()
+	cacheDir := platformFiles.CacheDir()
 
 	log.Infof("Starting client without login with config: %s, state: %s", cfgFile, stateFile)
 
@@ -157,8 +186,9 @@ func (c *Client) RunWithoutLogin(platformFiles PlatformFiles, dns *DNSList, dnsR
 
 	// todo do not throw error in case of cancelled context
 	ctx = internal.CtxInitState(ctx)
-	c.connectClient = internal.NewConnectClient(ctx, cfg, c.recorder)
-	return c.connectClient.RunOnAndroid(c.tunAdapter, c.iFaceDiscover, c.networkChangeListener, slices.Clone(dns.items), dnsReadyListener, stateFile)
+	connectClient := internal.NewConnectClient(ctx, cfg, c.recorder)
+	c.setState(cfg, cacheDir, connectClient)
+	return connectClient.RunOnAndroid(c.tunAdapter, c.iFaceDiscover, c.networkChangeListener, slices.Clone(dns.items), dnsReadyListener, stateFile, cacheDir)
 }
 
 // Stop the internal client and free the resources
@@ -173,11 +203,12 @@ func (c *Client) Stop() {
 }
 
 func (c *Client) RenewTun(fd int) error {
-	if c.connectClient == nil {
+	cc := c.getConnectClient()
+	if cc == nil {
 		return fmt.Errorf("engine not running")
 	}
 
-	e := c.connectClient.Engine()
+	e := cc.Engine()
 	if e == nil {
 		return fmt.Errorf("engine not initialized")
 	}
@@ -185,6 +216,73 @@ func (c *Client) RenewTun(fd int) error {
 	return e.RenewTun(fd)
 }
 
+// DebugBundle generates a debug bundle, uploads it, and returns the upload key.
+// It works both with and without a running engine.
+func (c *Client) DebugBundle(platformFiles PlatformFiles, anonymize bool) (string, error) {
+	cfg, cacheDir, cc := c.stateSnapshot()
+
+	// If the engine hasn't been started, load config from disk
+	if cfg == nil {
+		var err error
+		cfg, err = profilemanager.UpdateOrCreateConfig(profilemanager.ConfigInput{
+			ConfigPath: platformFiles.ConfigurationFilePath(),
+		})
+		if err != nil {
+			return "", fmt.Errorf("load config: %w", err)
+		}
+		cacheDir = platformFiles.CacheDir()
+	}
+
+	deps := debug.GeneratorDependencies{
+		InternalConfig: cfg,
+		StatusRecorder: c.recorder,
+		TempDir:        cacheDir,
+	}
+
+	if cc != nil {
+		resp, err := cc.GetLatestSyncResponse()
+		if err != nil {
+			log.Warnf("get latest sync response: %v", err)
+		}
+		deps.SyncResponse = resp
+
+		if e := cc.Engine(); e != nil {
+			if cm := e.GetClientMetrics(); cm != nil {
+				deps.ClientMetrics = cm
+			}
+		}
+	}
+
+	bundleGenerator := debug.NewBundleGenerator(
+		deps,
+		debug.BundleConfig{
+			Anonymize:         anonymize,
+			IncludeSystemInfo: true,
+		},
+	)
+
+	path, err := bundleGenerator.Generate()
+	if err != nil {
+		return "", fmt.Errorf("generate debug bundle: %w", err)
+	}
+	defer func() {
+		if err := os.Remove(path); err != nil {
+			log.Errorf("failed to remove debug bundle file: %v", err)
+		}
+	}()
+
+	uploadCtx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
+	defer cancel()
+
+	key, err := debug.UploadDebugBundle(uploadCtx, types.DefaultBundleURL, cfg.ManagementURL.String(), path)
+	if err != nil {
+		return "", fmt.Errorf("upload debug bundle: %w", err)
+	}
+
+	log.Infof("debug bundle uploaded with key %s", key)
+	return key, nil
+}
+
 // SetTraceLogLevel configure the logger to trace level
 func (c *Client) SetTraceLogLevel() {
 	log.SetLevel(log.TraceLevel)
@@ -214,12 +312,13 @@ func (c *Client) PeersList() *PeerInfoArray {
 }
 
 func (c *Client) Networks() *NetworkArray {
-	if c.connectClient == nil {
+	cc := c.getConnectClient()
+	if cc == nil {
 		log.Error("not connected")
 		return nil
 	}
 
-	engine := c.connectClient.Engine()
+	engine := cc.Engine()
 	if engine == nil {
 		log.Error("could not get engine")
 		return nil
@@ -300,7 +399,7 @@ func (c *Client) toggleRoute(command routeCommand) error {
 }
 
 func (c *Client) getRouteManager() (routemanager.Manager, error) {
-	client := c.connectClient
+	client := c.getConnectClient()
 	if client == nil {
 		return nil, fmt.Errorf("not connected")
 	}

client/android/platform_files.go

@@ -7,4 +7,5 @@ package android
 type PlatformFiles interface {
 	ConfigurationFilePath() string
 	StateFilePath() string
+	CacheDir() string
 }

client/cmd/root.go

@@ -75,6 +75,7 @@ var (
 	mtu                     uint16
 	profilesDisabled        bool
 	updateSettingsDisabled  bool
+	networksDisabled        bool
 
 	rootCmd = &cobra.Command{
 		Use:          "netbird",

client/cmd/service.go

@@ -44,10 +44,13 @@ func init() {
 	serviceCmd.AddCommand(runCmd, startCmd, stopCmd, restartCmd, svcStatusCmd, installCmd, uninstallCmd, reconfigureCmd, resetParamsCmd)
 	serviceCmd.PersistentFlags().BoolVar(&profilesDisabled, "disable-profiles", false, "Disables profiles feature. If enabled, the client will not be able to change or edit any profile. To persist this setting, use: netbird service install --disable-profiles")
 	serviceCmd.PersistentFlags().BoolVar(&updateSettingsDisabled, "disable-update-settings", false, "Disables update settings feature. If enabled, the client will not be able to change or edit any settings. To persist this setting, use: netbird service install --disable-update-settings")
+	serviceCmd.PersistentFlags().BoolVar(&networksDisabled, "disable-networks", false, "Disables network selection. If enabled, the client will not allow listing, selecting, or deselecting networks. To persist, use: netbird service install --disable-networks")
 
 	rootCmd.PersistentFlags().StringVarP(&serviceName, "service", "s", defaultServiceName, "Netbird system service name")
 	serviceEnvDesc := `Sets extra environment variables for the service. ` +
 		`You can specify a comma-separated list of KEY=VALUE pairs. ` +
+		`New keys are merged with previously saved env vars; existing keys are overwritten. ` +
+		`Use --service-env "" to clear all saved env vars. ` +
 		`E.g. --service-env NB_LOG_LEVEL=debug,CUSTOM_VAR=value`
 
 	installCmd.Flags().StringSliceVar(&serviceEnvVars, "service-env", nil, serviceEnvDesc)

client/cmd/service_controller.go

@@ -61,7 +61,7 @@ func (p *program) Start(svc service.Service) error {
 			}
 		}
 
-		serverInstance := server.New(p.ctx, util.FindFirstLogPath(logFiles), configPath, profilesDisabled, updateSettingsDisabled)
+		serverInstance := server.New(p.ctx, util.FindFirstLogPath(logFiles), configPath, profilesDisabled, updateSettingsDisabled, networksDisabled)
 		if err := serverInstance.Start(); err != nil {
 			log.Fatalf("failed to start daemon: %v", err)
 		}

client/cmd/service_installer.go

@@ -59,6 +59,10 @@ func buildServiceArguments() []string {
 		args = append(args, "--disable-update-settings")
 	}
 
+	if networksDisabled {
+		args = append(args, "--disable-networks")
+	}
+
 	return args
 }
 

client/cmd/service_params.go

@@ -28,6 +28,7 @@ type serviceParams struct {
 	LogFiles              []string          `json:"log_files,omitempty"`
 	DisableProfiles       bool              `json:"disable_profiles,omitempty"`
 	DisableUpdateSettings bool              `json:"disable_update_settings,omitempty"`
+	DisableNetworks       bool              `json:"disable_networks,omitempty"`
 	ServiceEnvVars        map[string]string `json:"service_env_vars,omitempty"`
 }
 
@@ -78,11 +79,12 @@ func currentServiceParams() *serviceParams {
 		LogFiles:              logFiles,
 		DisableProfiles:       profilesDisabled,
 		DisableUpdateSettings: updateSettingsDisabled,
+		DisableNetworks:       networksDisabled,
 	}
 
 	if len(serviceEnvVars) > 0 {
 		parsed, err := parseServiceEnvVars(serviceEnvVars)
-		if err == nil && len(parsed) > 0 {
+		if err == nil {
 			params.ServiceEnvVars = parsed
 		}
 	}
@@ -142,31 +144,46 @@ func applyServiceParams(cmd *cobra.Command, params *serviceParams) {
 		updateSettingsDisabled = params.DisableUpdateSettings
 	}
 
+	if !serviceCmd.PersistentFlags().Changed("disable-networks") {
+		networksDisabled = params.DisableNetworks
+	}
+
 	applyServiceEnvParams(cmd, params)
 }
 
 // applyServiceEnvParams merges saved service environment variables.
-// If --service-env was explicitly set, explicit values win on key conflict
-// but saved keys not in the explicit set are carried over.
+// If --service-env was explicitly set with values, explicit values win on key
+// conflict but saved keys not in the explicit set are carried over.
+// If --service-env was explicitly set to empty, all saved env vars are cleared.
 // If --service-env was not set, saved env vars are used entirely.
 func applyServiceEnvParams(cmd *cobra.Command, params *serviceParams) {
-	if len(params.ServiceEnvVars) == 0 {
-		return
-	}
-
 	if !cmd.Flags().Changed("service-env") {
-		// No explicit env vars: rebuild serviceEnvVars from saved params.
-		serviceEnvVars = envMapToSlice(params.ServiceEnvVars)
+		if len(params.ServiceEnvVars) > 0 {
+			// No explicit env vars: rebuild serviceEnvVars from saved params.
+			serviceEnvVars = envMapToSlice(params.ServiceEnvVars)
+		}
 		return
 	}
 
-	// Explicit env vars were provided: merge saved values underneath.
+	// Flag was explicitly set: parse what the user provided.
 	explicit, err := parseServiceEnvVars(serviceEnvVars)
 	if err != nil {
 		cmd.PrintErrf("Warning: parse explicit service env vars for merge: %v\n", err)
 		return
 	}
 
+	// If the user passed an empty value (e.g. --service-env ""), clear all
+	// saved env vars rather than merging.
+	if len(explicit) == 0 {
+		serviceEnvVars = nil
+		return
+	}
+
+	if len(params.ServiceEnvVars) == 0 {
+		return
+	}
+
+	// Merge saved values underneath explicit ones.
 	merged := make(map[string]string, len(params.ServiceEnvVars)+len(explicit))
 	maps.Copy(merged, params.ServiceEnvVars)
 	maps.Copy(merged, explicit) // explicit wins on conflict

client/cmd/service_params_test.go

@@ -327,6 +327,41 @@ func TestApplyServiceEnvParams_NotChanged(t *testing.T) {
 	assert.Equal(t, map[string]string{"FROM_SAVED": "val"}, result)
 }
 
+func TestApplyServiceEnvParams_ExplicitEmptyClears(t *testing.T) {
+	origServiceEnvVars := serviceEnvVars
+	t.Cleanup(func() { serviceEnvVars = origServiceEnvVars })
+
+	// Simulate --service-env "" which produces [""] in the slice.
+	serviceEnvVars = []string{""}
+
+	cmd := &cobra.Command{}
+	cmd.Flags().StringSlice("service-env", nil, "")
+	require.NoError(t, cmd.Flags().Set("service-env", ""))
+
+	saved := &serviceParams{
+		ServiceEnvVars: map[string]string{"OLD_VAR": "should_be_cleared"},
+	}
+
+	applyServiceEnvParams(cmd, saved)
+
+	assert.Nil(t, serviceEnvVars, "explicit empty --service-env should clear all saved env vars")
+}
+
+func TestCurrentServiceParams_EmptyEnvVarsAfterParse(t *testing.T) {
+	origServiceEnvVars := serviceEnvVars
+	t.Cleanup(func() { serviceEnvVars = origServiceEnvVars })
+
+	// Simulate --service-env "" which produces [""] in the slice.
+	serviceEnvVars = []string{""}
+
+	params := currentServiceParams()
+
+	// After parsing, the empty string is skipped, resulting in an empty map.
+	// The map should still be set (not nil) so it overwrites saved values.
+	assert.NotNil(t, params.ServiceEnvVars, "empty env vars should produce empty map, not nil")
+	assert.Empty(t, params.ServiceEnvVars, "no valid env vars should be parsed from empty string")
+}
+
 // TestServiceParams_FieldsCoveredInFunctions ensures that all serviceParams fields are
 // referenced in both currentServiceParams() and applyServiceParams(). If a new field is
 // added to serviceParams but not wired into these functions, this test fails.
@@ -500,6 +535,7 @@ func fieldToGlobalVar(field string) string {
 		"LogFiles":              "logFiles",
 		"DisableProfiles":       "profilesDisabled",
 		"DisableUpdateSettings": "updateSettingsDisabled",
+		"DisableNetworks":       "networksDisabled",
 		"ServiceEnvVars":        "serviceEnvVars",
 	}
 	if v, ok := m[field]; ok {

client/cmd/testutil_test.go

@@ -13,6 +13,8 @@ import (
 
 	"github.com/netbirdio/management-integrations/integrations"
 
+	nbcache "github.com/netbirdio/netbird/management/server/cache"
+
 	"github.com/netbirdio/netbird/management/internals/controllers/network_map/controller"
 	"github.com/netbirdio/netbird/management/internals/controllers/network_map/update_channel"
 	"github.com/netbirdio/netbird/management/internals/modules/peers"
@@ -100,9 +102,16 @@ func startManagement(t *testing.T, config *config.Config, testFile string) (*grp
 
 	jobManager := job.NewJobManager(nil, store, peersmanager)
 
-	iv, _ := integrations.NewIntegratedValidator(context.Background(), peersmanager, settingsManagerMock, eventStore)
+	ctx := context.Background()
 
-	metrics, err := telemetry.NewDefaultAppMetrics(context.Background())
+	cacheStore, err := nbcache.NewStore(ctx, 100*time.Millisecond, 300*time.Millisecond, 100)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	iv, _ := integrations.NewIntegratedValidator(ctx, peersmanager, settingsManagerMock, eventStore, cacheStore)
+
+	metrics, err := telemetry.NewDefaultAppMetrics(ctx)
 	require.NoError(t, err)
 
 	settingsMockManager := settings.NewMockManager(ctrl)
@@ -113,12 +122,11 @@ func startManagement(t *testing.T, config *config.Config, testFile string) (*grp
 		Return(&types.Settings{}, nil).
 		AnyTimes()
 
-	ctx := context.Background()
 	updateManager := update_channel.NewPeersUpdateManager(metrics)
 	requestBuffer := mgmt.NewAccountRequestBuffer(ctx, store)
 	networkMapController := controller.NewController(ctx, store, metrics, updateManager, requestBuffer, mgmt.MockIntegratedValidator{}, settingsMockManager, "netbird.cloud", port_forwarding.NewControllerMock(), manager.NewEphemeralManager(store, peersmanager), config)
 
-	accountManager, err := mgmt.BuildManager(context.Background(), config, store, networkMapController, jobManager, nil, "", eventStore, nil, false, iv, metrics, port_forwarding.NewControllerMock(), settingsMockManager, permissionsManagerMock, false)
+	accountManager, err := mgmt.BuildManager(ctx, config, store, networkMapController, jobManager, nil, "", eventStore, nil, false, iv, metrics, port_forwarding.NewControllerMock(), settingsMockManager, permissionsManagerMock, false, cacheStore)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -152,7 +160,7 @@ func startClientDaemon(
 	s := grpc.NewServer()
 
 	server := client.New(ctx,
-		"", "", false, false)
+		"", "", false, false, false)
 	if err := server.Start(); err != nil {
 		t.Fatal(err)
 	}

client/firewall/create_linux.go

@@ -56,6 +56,13 @@ func NewFirewall(iface IFaceMapper, stateManager *statemanager.Manager, flowLogg
 		return createUserspaceFirewall(iface, nil, disableServerRoutes, flowLogger, mtu)
 	}
 
+	// Native firewall handles packet filtering, but the userspace WireGuard bind
+	// needs a device filter for DNS interception hooks. Install a minimal
+	// hooks-only filter that passes all traffic through to the kernel firewall.
+	if err := iface.SetFilter(&uspfilter.HooksFilter{}); err != nil {
+		log.Warnf("failed to set hooks filter, DNS via memory hooks will not work: %v", err)
+	}
+
 	return fm, nil
 }
 

client/firewall/firewalld/firewalld.go

@@ -0,0 +1,11 @@
+// Package firewalld integrates with the firewalld daemon so NetBird can place
+// its wg interface into firewalld's "trusted" zone. This is required because
+// firewalld's nftables chains are created with NFT_CHAIN_OWNER on recent
+// versions, which returns EPERM to any other process that tries to insert
+// rules into them. The workaround mirrors what Tailscale does: let firewalld
+// itself add the accept rules to its own chains by trusting the interface.
+package firewalld
+
+// TrustedZone is the firewalld zone name used for interfaces whose traffic
+// should bypass firewalld filtering.
+const TrustedZone = "trusted"

client/firewall/firewalld/firewalld_linux.go

@@ -0,0 +1,260 @@
+//go:build linux
+
+package firewalld
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os/exec"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/godbus/dbus/v5"
+	log "github.com/sirupsen/logrus"
+)
+
+const (
+	dbusDest      = "org.fedoraproject.FirewallD1"
+	dbusPath      = "/org/fedoraproject/FirewallD1"
+	dbusRootIface = "org.fedoraproject.FirewallD1"
+	dbusZoneIface = "org.fedoraproject.FirewallD1.zone"
+
+	errZoneAlreadySet = "ZONE_ALREADY_SET"
+	errAlreadyEnabled = "ALREADY_ENABLED"
+	errUnknownIface   = "UNKNOWN_INTERFACE"
+	errNotEnabled     = "NOT_ENABLED"
+
+	// callTimeout bounds each individual DBus or firewall-cmd invocation.
+	// A fresh context is created for each call so a slow DBus probe can't
+	// exhaust the deadline before the firewall-cmd fallback gets to run.
+	callTimeout = 3 * time.Second
+)
+
+var (
+	errDBusUnavailable = errors.New("firewalld dbus unavailable")
+
+	// trustLogOnce ensures the "added to trusted zone" message is logged at
+	// Info level only for the first successful add per process; repeat adds
+	// from other init paths are quieter.
+	trustLogOnce sync.Once
+
+	parentCtxMu sync.RWMutex
+	parentCtx   context.Context = context.Background()
+)
+
+// SetParentContext installs a parent context whose cancellation aborts any
+// in-flight TrustInterface call. It does not affect UntrustInterface, which
+// always uses a fresh Background-rooted timeout so cleanup can still run
+// during engine shutdown when the engine context is already cancelled.
+func SetParentContext(ctx context.Context) {
+	parentCtxMu.Lock()
+	parentCtx = ctx
+	parentCtxMu.Unlock()
+}
+
+func getParentContext() context.Context {
+	parentCtxMu.RLock()
+	defer parentCtxMu.RUnlock()
+	return parentCtx
+}
+
+// TrustInterface places iface into firewalld's trusted zone if firewalld is
+// running. It is idempotent and best-effort: errors are returned so callers
+// can log, but a non-running firewalld is not an error. Only the first
+// successful call per process logs at Info. Respects the parent context set
+// via SetParentContext so startup-time cancellation unblocks it.
+func TrustInterface(iface string) error {
+	parent := getParentContext()
+	if !isRunning(parent) {
+		return nil
+	}
+	if err := addTrusted(parent, iface); err != nil {
+		return fmt.Errorf("add %s to firewalld trusted zone: %w", iface, err)
+	}
+	trustLogOnce.Do(func() {
+		log.Infof("added %s to firewalld trusted zone", iface)
+	})
+	log.Debugf("firewalld: ensured %s is in trusted zone", iface)
+	return nil
+}
+
+// UntrustInterface removes iface from firewalld's trusted zone if firewalld
+// is running. Idempotent. Uses a Background-rooted timeout so it still runs
+// during shutdown after the engine context has been cancelled.
+func UntrustInterface(iface string) error {
+	if !isRunning(context.Background()) {
+		return nil
+	}
+	if err := removeTrusted(context.Background(), iface); err != nil {
+		return fmt.Errorf("remove %s from firewalld trusted zone: %w", iface, err)
+	}
+	return nil
+}
+
+func newCallContext(parent context.Context) (context.Context, context.CancelFunc) {
+	return context.WithTimeout(parent, callTimeout)
+}
+
+func isRunning(parent context.Context) bool {
+	ctx, cancel := newCallContext(parent)
+	ok, err := isRunningDBus(ctx)
+	cancel()
+	if err == nil {
+		return ok
+	}
+	if errors.Is(err, errDBusUnavailable) || errors.Is(err, context.DeadlineExceeded) {
+		ctx, cancel = newCallContext(parent)
+		defer cancel()
+		return isRunningCLI(ctx)
+	}
+	return false
+}
+
+func addTrusted(parent context.Context, iface string) error {
+	ctx, cancel := newCallContext(parent)
+	err := addDBus(ctx, iface)
+	cancel()
+	if err == nil {
+		return nil
+	}
+	if !errors.Is(err, errDBusUnavailable) {
+		log.Debugf("firewalld: dbus add failed, falling back to firewall-cmd: %v", err)
+	}
+	ctx, cancel = newCallContext(parent)
+	defer cancel()
+	return addCLI(ctx, iface)
+}
+
+func removeTrusted(parent context.Context, iface string) error {
+	ctx, cancel := newCallContext(parent)
+	err := removeDBus(ctx, iface)
+	cancel()
+	if err == nil {
+		return nil
+	}
+	if !errors.Is(err, errDBusUnavailable) {
+		log.Debugf("firewalld: dbus remove failed, falling back to firewall-cmd: %v", err)
+	}
+	ctx, cancel = newCallContext(parent)
+	defer cancel()
+	return removeCLI(ctx, iface)
+}
+
+func isRunningDBus(ctx context.Context) (bool, error) {
+	conn, err := dbus.SystemBus()
+	if err != nil {
+		return false, fmt.Errorf("%w: %v", errDBusUnavailable, err)
+	}
+	obj := conn.Object(dbusDest, dbusPath)
+
+	var zone string
+	if err := obj.CallWithContext(ctx, dbusRootIface+".getDefaultZone", 0).Store(&zone); err != nil {
+		return false, fmt.Errorf("firewalld getDefaultZone: %w", err)
+	}
+	return true, nil
+}
+
+func isRunningCLI(ctx context.Context) bool {
+	if _, err := exec.LookPath("firewall-cmd"); err != nil {
+		return false
+	}
+	return exec.CommandContext(ctx, "firewall-cmd", "--state").Run() == nil
+}
+
+func addDBus(ctx context.Context, iface string) error {
+	conn, err := dbus.SystemBus()
+	if err != nil {
+		return fmt.Errorf("%w: %v", errDBusUnavailable, err)
+	}
+	obj := conn.Object(dbusDest, dbusPath)
+
+	call := obj.CallWithContext(ctx, dbusZoneIface+".addInterface", 0, TrustedZone, iface)
+	if call.Err == nil {
+		return nil
+	}
+
+	if dbusErrContains(call.Err, errAlreadyEnabled) {
+		return nil
+	}
+
+	if dbusErrContains(call.Err, errZoneAlreadySet) {
+		move := obj.CallWithContext(ctx, dbusZoneIface+".changeZoneOfInterface", 0, TrustedZone, iface)
+		if move.Err != nil {
+			return fmt.Errorf("firewalld changeZoneOfInterface: %w", move.Err)
+		}
+		return nil
+	}
+
+	return fmt.Errorf("firewalld addInterface: %w", call.Err)
+}
+
+func removeDBus(ctx context.Context, iface string) error {
+	conn, err := dbus.SystemBus()
+	if err != nil {
+		return fmt.Errorf("%w: %v", errDBusUnavailable, err)
+	}
+	obj := conn.Object(dbusDest, dbusPath)
+
+	call := obj.CallWithContext(ctx, dbusZoneIface+".removeInterface", 0, TrustedZone, iface)
+	if call.Err == nil {
+		return nil
+	}
+
+	if dbusErrContains(call.Err, errUnknownIface) || dbusErrContains(call.Err, errNotEnabled) {
+		return nil
+	}
+
+	return fmt.Errorf("firewalld removeInterface: %w", call.Err)
+}
+
+func addCLI(ctx context.Context, iface string) error {
+	if _, err := exec.LookPath("firewall-cmd"); err != nil {
+		return fmt.Errorf("firewall-cmd not available: %w", err)
+	}
+
+	// --change-interface (no --permanent) binds the interface for the
+	// current runtime only; we do not want membership to persist across
+	// reboots because netbird re-asserts it on every startup.
+	out, err := exec.CommandContext(ctx,
+		"firewall-cmd", "--zone="+TrustedZone, "--change-interface="+iface,
+	).CombinedOutput()
+	if err != nil {
+		return fmt.Errorf("firewall-cmd change-interface: %w: %s", err, strings.TrimSpace(string(out)))
+	}
+	return nil
+}
+
+func removeCLI(ctx context.Context, iface string) error {
+	if _, err := exec.LookPath("firewall-cmd"); err != nil {
+		return fmt.Errorf("firewall-cmd not available: %w", err)
+	}
+
+	out, err := exec.CommandContext(ctx,
+		"firewall-cmd", "--zone="+TrustedZone, "--remove-interface="+iface,
+	).CombinedOutput()
+	if err != nil {
+		msg := strings.TrimSpace(string(out))
+		if strings.Contains(msg, errUnknownIface) || strings.Contains(msg, errNotEnabled) {
+			return nil
+		}
+		return fmt.Errorf("firewall-cmd remove-interface: %w: %s", err, msg)
+	}
+	return nil
+}
+
+func dbusErrContains(err error, code string) bool {
+	if err == nil {
+		return false
+	}
+	var de dbus.Error
+	if errors.As(err, &de) {
+		for _, b := range de.Body {
+			if s, ok := b.(string); ok && strings.Contains(s, code) {
+				return true
+			}
+		}
+	}
+	return strings.Contains(err.Error(), code)
+}

client/firewall/firewalld/firewalld_linux_test.go

@@ -0,0 +1,49 @@
+//go:build linux
+
+package firewalld
+
+import (
+	"errors"
+	"testing"
+
+	"github.com/godbus/dbus/v5"
+)
+
+func TestDBusErrContains(t *testing.T) {
+	tests := []struct {
+		name string
+		err  error
+		code string
+		want bool
+	}{
+		{"nil error", nil, errZoneAlreadySet, false},
+		{"plain error match", errors.New("ZONE_ALREADY_SET: wt0"), errZoneAlreadySet, true},
+		{"plain error miss", errors.New("something else"), errZoneAlreadySet, false},
+		{
+			"dbus.Error body match",
+			dbus.Error{Name: "org.fedoraproject.FirewallD1.Exception", Body: []any{"ZONE_ALREADY_SET: wt0"}},
+			errZoneAlreadySet,
+			true,
+		},
+		{
+			"dbus.Error body miss",
+			dbus.Error{Name: "org.fedoraproject.FirewallD1.Exception", Body: []any{"INVALID_INTERFACE"}},
+			errAlreadyEnabled,
+			false,
+		},
+		{
+			"dbus.Error non-string body falls back to Error()",
+			dbus.Error{Name: "x", Body: []any{123}},
+			"x",
+			true,
+		},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got := dbusErrContains(tc.err, tc.code)
+			if got != tc.want {
+				t.Fatalf("dbusErrContains(%v, %q) = %v; want %v", tc.err, tc.code, got, tc.want)
+			}
+		})
+	}
+}

client/firewall/firewalld/firewalld_other.go

@@ -0,0 +1,25 @@
+//go:build !linux
+
+package firewalld
+
+import "context"
+
+// SetParentContext is a no-op on non-Linux platforms because firewalld only
+// runs on Linux.
+func SetParentContext(context.Context) {
+	// intentionally empty: firewalld is a Linux-only daemon
+}
+
+// TrustInterface is a no-op on non-Linux platforms because firewalld only
+// runs on Linux.
+func TrustInterface(string) error {
+	// intentionally empty: firewalld is a Linux-only daemon
+	return nil
+}
+
+// UntrustInterface is a no-op on non-Linux platforms because firewalld only
+// runs on Linux.
+func UntrustInterface(string) error {
+	// intentionally empty: firewalld is a Linux-only daemon
+	return nil
+}

client/firewall/iptables/acl_linux.go

@@ -21,6 +21,10 @@ const (
 
 	// rules chains contains the effective ACL rules
 	chainNameInputRules = "NETBIRD-ACL-INPUT"
+
+	// mangleFwdKey is the entries map key for mangle FORWARD guard rules that prevent
+	// external DNAT from bypassing ACL rules.
+	mangleFwdKey = "MANGLE-FORWARD"
 )
 
 type aclEntries map[string][][]string
@@ -274,6 +278,12 @@ func (m *aclManager) cleanChains() error {
 		}
 	}
 
+	for _, rule := range m.entries[mangleFwdKey] {
+		if err := m.iptablesClient.DeleteIfExists(tableMangle, chainFORWARD, rule...); err != nil {
+			log.Errorf("failed to delete mangle FORWARD guard rule: %v, %s", rule, err)
+		}
+	}
+
 	for _, ipsetName := range m.ipsetStore.ipsetNames() {
 		if err := m.flushIPSet(ipsetName); err != nil {
 			if errors.Is(err, ipset.ErrSetNotExist) {
@@ -303,6 +313,10 @@ func (m *aclManager) createDefaultChains() error {
 	}
 
 	for chainName, rules := range m.entries {
+		// mangle FORWARD guard rules are handled separately below
+		if chainName == mangleFwdKey {
+			continue
+		}
 		for _, rule := range rules {
 			if err := m.iptablesClient.InsertUnique(tableName, chainName, 1, rule...); err != nil {
 				log.Debugf("failed to create input chain jump rule: %s", err)
@@ -322,6 +336,13 @@ func (m *aclManager) createDefaultChains() error {
 	}
 	clear(m.optionalEntries)
 
+	// Insert mangle FORWARD guard rules to prevent external DNAT bypass.
+	for _, rule := range m.entries[mangleFwdKey] {
+		if err := m.iptablesClient.AppendUnique(tableMangle, chainFORWARD, rule...); err != nil {
+			log.Errorf("failed to add mangle FORWARD guard rule: %v", err)
+		}
+	}
+
 	return nil
 }
 
@@ -343,6 +364,22 @@ func (m *aclManager) seedInitialEntries() {
 
 	m.appendToEntries("FORWARD", []string{"-o", m.wgIface.Name(), "-j", chainRTFWDOUT})
 	m.appendToEntries("FORWARD", []string{"-i", m.wgIface.Name(), "-j", chainRTFWDIN})
+
+	// Mangle FORWARD guard: when external DNAT redirects traffic from the wg interface, it
+	// traverses FORWARD instead of INPUT, bypassing ACL rules. ACCEPT rules in filter FORWARD
+	// can be inserted above ours. Mangle runs before filter, so these guard rules enforce the
+	// ACL mark check where it cannot be overridden.
+	m.appendToEntries(mangleFwdKey, []string{
+		"-i", m.wgIface.Name(),
+		"-m", "conntrack", "--ctstate", "RELATED,ESTABLISHED",
+		"-j", "ACCEPT",
+	})
+	m.appendToEntries(mangleFwdKey, []string{
+		"-i", m.wgIface.Name(),
+		"-m", "conntrack", "--ctstate", "DNAT",
+		"-m", "mark", "!", "--mark", fmt.Sprintf("%#x", nbnet.PreroutingFwmarkRedirected),
+		"-j", "DROP",
+	})
 }
 
 func (m *aclManager) seedInitialOptionalEntries() {

client/firewall/iptables/manager_linux.go

@@ -12,6 +12,7 @@ import (
 	log "github.com/sirupsen/logrus"
 
 	nberrors "github.com/netbirdio/netbird/client/errors"
+	"github.com/netbirdio/netbird/client/firewall/firewalld"
 	firewall "github.com/netbirdio/netbird/client/firewall/manager"
 	"github.com/netbirdio/netbird/client/iface/wgaddr"
 	"github.com/netbirdio/netbird/client/internal/statemanager"
@@ -86,6 +87,12 @@ func (m *Manager) Init(stateManager *statemanager.Manager) error {
 		log.Warnf("raw table not available, notrack rules will be disabled: %v", err)
 	}
 
+	// Trust after all fatal init steps so a later failure doesn't leave the
+	// interface in firewalld's trusted zone without a corresponding Close.
+	if err := firewalld.TrustInterface(m.wgIface.Name()); err != nil {
+		log.Warnf("failed to trust interface in firewalld: %v", err)
+	}
+
 	// persist early to ensure cleanup of chains
 	go func() {
 		if err := stateManager.PersistState(context.Background()); err != nil {
@@ -191,6 +198,12 @@ func (m *Manager) Close(stateManager *statemanager.Manager) error {
 		merr = multierror.Append(merr, fmt.Errorf("reset router: %w", err))
 	}
 
+	// Appending to merr intentionally blocks DeleteState below so ShutdownState
+	// stays persisted and the crash-recovery path retries firewalld cleanup.
+	if err := firewalld.UntrustInterface(m.wgIface.Name()); err != nil {
+		merr = multierror.Append(merr, err)
+	}
+
 	// attempt to delete state only if all other operations succeeded
 	if merr == nil {
 		if err := stateManager.DeleteState(&ShutdownState{}); err != nil {
@@ -217,6 +230,11 @@ func (m *Manager) AllowNetbird() error {
 	if err != nil {
 		return fmt.Errorf("allow netbird interface traffic: %w", err)
 	}
+
+	if err := firewalld.TrustInterface(m.wgIface.Name()); err != nil {
+		log.Warnf("failed to trust interface in firewalld: %v", err)
+	}
+
 	return nil
 }
 

client/firewall/nftables/manager_linux.go

@@ -14,6 +14,7 @@ import (
 	log "github.com/sirupsen/logrus"
 	"golang.org/x/sys/unix"
 
+	"github.com/netbirdio/netbird/client/firewall/firewalld"
 	firewall "github.com/netbirdio/netbird/client/firewall/manager"
 	"github.com/netbirdio/netbird/client/iface/wgaddr"
 	"github.com/netbirdio/netbird/client/internal/statemanager"
@@ -217,6 +218,10 @@ func (m *Manager) AllowNetbird() error {
 		return fmt.Errorf("flush allow input netbird rules: %w", err)
 	}
 
+	if err := firewalld.TrustInterface(m.wgIface.Name()); err != nil {
+		log.Warnf("failed to trust interface in firewalld: %v", err)
+	}
+
 	return nil
 }
 

client/firewall/nftables/router_linux.go

@@ -19,6 +19,7 @@ import (
 	"golang.org/x/sys/unix"
 
 	nberrors "github.com/netbirdio/netbird/client/errors"
+	"github.com/netbirdio/netbird/client/firewall/firewalld"
 	firewall "github.com/netbirdio/netbird/client/firewall/manager"
 	nbid "github.com/netbirdio/netbird/client/internal/acl/id"
 	"github.com/netbirdio/netbird/client/internal/routemanager/ipfwdstate"
@@ -40,6 +41,8 @@ const (
 	chainNameForward       = "FORWARD"
 	chainNameMangleForward = "netbird-mangle-forward"
 
+	firewalldTableName = "firewalld"
+
 	userDataAcceptForwardRuleIif = "frwacceptiif"
 	userDataAcceptForwardRuleOif = "frwacceptoif"
 	userDataAcceptInputRule      = "inputaccept"
@@ -133,6 +136,10 @@ func (r *router) Reset() error {
 		merr = multierror.Append(merr, fmt.Errorf("remove accept filter rules: %w", err))
 	}
 
+	if err := firewalld.UntrustInterface(r.wgIface.Name()); err != nil {
+		merr = multierror.Append(merr, err)
+	}
+
 	if err := r.removeNatPreroutingRules(); err != nil {
 		merr = multierror.Append(merr, fmt.Errorf("remove filter prerouting rules: %w", err))
 	}
@@ -280,6 +287,10 @@ func (r *router) createContainers() error {
 		log.Errorf("failed to add accept rules for the forward chain: %s", err)
 	}
 
+	if err := firewalld.TrustInterface(r.wgIface.Name()); err != nil {
+		log.Warnf("failed to trust interface in firewalld: %v", err)
+	}
+
 	if err := r.refreshRulesMap(); err != nil {
 		log.Errorf("failed to refresh rules: %s", err)
 	}
@@ -1319,6 +1330,13 @@ func (r *router) isExternalChain(chain *nftables.Chain) bool {
 		return false
 	}
 
+	// Skip firewalld-owned chains. Firewalld creates its chains with the
+	// NFT_CHAIN_OWNER flag, so inserting rules into them returns EPERM.
+	// We delegate acceptance to firewalld by trusting the interface instead.
+	if chain.Table.Name == firewalldTableName {
+		return false
+	}
+
 	// Skip all iptables-managed tables in the ip family
 	if chain.Table.Family == nftables.TableFamilyIPv4 && isIptablesTable(chain.Table.Name) {
 		return false

client/firewall/uspfilter/allow_netbird.go

@@ -3,6 +3,9 @@
 package uspfilter
 
 import (
+	log "github.com/sirupsen/logrus"
+
+	"github.com/netbirdio/netbird/client/firewall/firewalld"
 	"github.com/netbirdio/netbird/client/internal/statemanager"
 )
 
@@ -16,6 +19,9 @@ func (m *Manager) Close(stateManager *statemanager.Manager) error {
 	if m.nativeFirewall != nil {
 		return m.nativeFirewall.Close(stateManager)
 	}
+	if err := firewalld.UntrustInterface(m.wgIface.Name()); err != nil {
+		log.Warnf("failed to untrust interface in firewalld: %v", err)
+	}
 	return nil
 }
 
@@ -24,5 +30,8 @@ func (m *Manager) AllowNetbird() error {
 	if m.nativeFirewall != nil {
 		return m.nativeFirewall.AllowNetbird()
 	}
+	if err := firewalld.TrustInterface(m.wgIface.Name()); err != nil {
+		log.Warnf("failed to trust interface in firewalld: %v", err)
+	}
 	return nil
 }

client/firewall/uspfilter/common/hooks.go

@@ -0,0 +1,37 @@
+package common
+
+import (
+	"net/netip"
+	"sync/atomic"
+)
+
+// PacketHook stores a registered hook for a specific IP:port.
+type PacketHook struct {
+	IP   netip.Addr
+	Port uint16
+	Fn   func([]byte) bool
+}
+
+// HookMatches checks if a packet's destination matches the hook and invokes it.
+func HookMatches(h *PacketHook, dstIP netip.Addr, dport uint16, packetData []byte) bool {
+	if h == nil {
+		return false
+	}
+	if h.IP == dstIP && h.Port == dport {
+		return h.Fn(packetData)
+	}
+	return false
+}
+
+// SetHook atomically stores a hook, handling nil removal.
+func SetHook(ptr *atomic.Pointer[PacketHook], ip netip.Addr, dPort uint16, hook func([]byte) bool) {
+	if hook == nil {
+		ptr.Store(nil)
+		return
+	}
+	ptr.Store(&PacketHook{
+		IP:   ip,
+		Port: dPort,
+		Fn:   hook,
+	})
+}

client/firewall/uspfilter/common/iface.go

@@ -9,6 +9,7 @@ import (
 
 // IFaceMapper defines subset methods of interface required for manager
 type IFaceMapper interface {
+	Name() string
 	SetFilter(device.PacketFilter) error
 	Address() wgaddr.Address
 	GetWGDevice() *wgdevice.Device

client/firewall/uspfilter/filter.go

@@ -142,15 +142,8 @@ type Manager struct {
 	mssClampEnabled bool
 
 	// Only one hook per protocol is supported. Outbound direction only.
-	udpHookOut atomic.Pointer[packetHook]
-	tcpHookOut atomic.Pointer[packetHook]
-}
-
-// packetHook stores a registered hook for a specific IP:port.
-type packetHook struct {
-	ip   netip.Addr
-	port uint16
-	fn   func([]byte) bool
+	udpHookOut atomic.Pointer[common.PacketHook]
+	tcpHookOut atomic.Pointer[common.PacketHook]
 }
 
 // decoder for packages
@@ -912,21 +905,11 @@ func (m *Manager) trackInbound(d *decoder, srcIP, dstIP netip.Addr, ruleID []byt
 }
 
 func (m *Manager) udpHooksDrop(dport uint16, dstIP netip.Addr, packetData []byte) bool {
-	return hookMatches(m.udpHookOut.Load(), dstIP, dport, packetData)
+	return common.HookMatches(m.udpHookOut.Load(), dstIP, dport, packetData)
 }
 
 func (m *Manager) tcpHooksDrop(dport uint16, dstIP netip.Addr, packetData []byte) bool {
-	return hookMatches(m.tcpHookOut.Load(), dstIP, dport, packetData)
-}
-
-func hookMatches(h *packetHook, dstIP netip.Addr, dport uint16, packetData []byte) bool {
-	if h == nil {
-		return false
-	}
-	if h.ip == dstIP && h.port == dport {
-		return h.fn(packetData)
-	}
-	return false
+	return common.HookMatches(m.tcpHookOut.Load(), dstIP, dport, packetData)
 }
 
 // filterInbound implements filtering logic for incoming packets.
@@ -1337,28 +1320,12 @@ func (m *Manager) ruleMatches(rule *RouteRule, srcAddr, dstAddr netip.Addr, prot
 
 // SetUDPPacketHook sets the outbound UDP packet hook. Pass nil hook to remove.
 func (m *Manager) SetUDPPacketHook(ip netip.Addr, dPort uint16, hook func(packet []byte) bool) {
-	if hook == nil {
-		m.udpHookOut.Store(nil)
-		return
-	}
-	m.udpHookOut.Store(&packetHook{
-		ip:   ip,
-		port: dPort,
-		fn:   hook,
-	})
+	common.SetHook(&m.udpHookOut, ip, dPort, hook)
 }
 
 // SetTCPPacketHook sets the outbound TCP packet hook. Pass nil hook to remove.
 func (m *Manager) SetTCPPacketHook(ip netip.Addr, dPort uint16, hook func(packet []byte) bool) {
-	if hook == nil {
-		m.tcpHookOut.Store(nil)
-		return
-	}
-	m.tcpHookOut.Store(&packetHook{
-		ip:   ip,
-		port: dPort,
-		fn:   hook,
-	})
+	common.SetHook(&m.tcpHookOut, ip, dPort, hook)
 }
 
 // SetLogLevel sets the log level for the firewall manager

client/firewall/uspfilter/filter_test.go

@@ -31,12 +31,20 @@ var logger = log.NewFromLogrus(logrus.StandardLogger())
 var flowLogger = netflow.NewManager(nil, []byte{}, nil).GetLogger()
 
 type IFaceMock struct {
+	NameFunc        func() string
 	SetFilterFunc   func(device.PacketFilter) error
 	AddressFunc     func() wgaddr.Address
 	GetWGDeviceFunc func() *wgdevice.Device
 	GetDeviceFunc   func() *device.FilteredDevice
 }
 
+func (i *IFaceMock) Name() string {
+	if i.NameFunc == nil {
+		return "wgtest"
+	}
+	return i.NameFunc()
+}
+
 func (i *IFaceMock) GetWGDevice() *wgdevice.Device {
 	if i.GetWGDeviceFunc == nil {
 		return nil
@@ -202,9 +210,9 @@ func TestSetUDPPacketHook(t *testing.T) {
 
 	h := manager.udpHookOut.Load()
 	require.NotNil(t, h)
-	assert.Equal(t, netip.MustParseAddr("10.168.0.1"), h.ip)
-	assert.Equal(t, uint16(8000), h.port)
-	assert.True(t, h.fn(nil))
+	assert.Equal(t, netip.MustParseAddr("10.168.0.1"), h.IP)
+	assert.Equal(t, uint16(8000), h.Port)
+	assert.True(t, h.Fn(nil))
 	assert.True(t, called)
 
 	manager.SetUDPPacketHook(netip.MustParseAddr("10.168.0.1"), 8000, nil)
@@ -226,9 +234,9 @@ func TestSetTCPPacketHook(t *testing.T) {
 
 	h := manager.tcpHookOut.Load()
 	require.NotNil(t, h)
-	assert.Equal(t, netip.MustParseAddr("10.168.0.1"), h.ip)
-	assert.Equal(t, uint16(53), h.port)
-	assert.True(t, h.fn(nil))
+	assert.Equal(t, netip.MustParseAddr("10.168.0.1"), h.IP)
+	assert.Equal(t, uint16(53), h.Port)
+	assert.True(t, h.Fn(nil))
 	assert.True(t, called)
 
 	manager.SetTCPPacketHook(netip.MustParseAddr("10.168.0.1"), 53, nil)

client/firewall/uspfilter/hooks_filter.go

@@ -0,0 +1,90 @@
+package uspfilter
+
+import (
+	"encoding/binary"
+	"net/netip"
+	"sync/atomic"
+
+	"github.com/netbirdio/netbird/client/firewall/uspfilter/common"
+	"github.com/netbirdio/netbird/client/iface/device"
+)
+
+const (
+	ipv4HeaderMinLen = 20
+	ipv4ProtoOffset  = 9
+	ipv4FlagsOffset  = 6
+	ipv4DstOffset    = 16
+	ipProtoUDP       = 17
+	ipProtoTCP       = 6
+	ipv4FragOffMask  = 0x1fff
+	// dstPortOffset is the offset of the destination port within a UDP or TCP header.
+	dstPortOffset = 2
+)
+
+// HooksFilter is a minimal packet filter that only handles outbound DNS hooks.
+// It is installed on the WireGuard interface when the userspace bind is active
+// but a full firewall filter (Manager) is not needed because a native kernel
+// firewall (nftables/iptables) handles packet filtering.
+type HooksFilter struct {
+	udpHook atomic.Pointer[common.PacketHook]
+	tcpHook atomic.Pointer[common.PacketHook]
+}
+
+var _ device.PacketFilter = (*HooksFilter)(nil)
+
+// FilterOutbound checks outbound packets for DNS hook matches.
+// Only IPv4 packets matching the registered hook IP:port are intercepted.
+// IPv6 and non-IP packets pass through unconditionally.
+func (f *HooksFilter) FilterOutbound(packetData []byte, _ int) bool {
+	if len(packetData) < ipv4HeaderMinLen {
+		return false
+	}
+
+	// Only process IPv4 packets, let everything else pass through.
+	if packetData[0]>>4 != 4 {
+		return false
+	}
+
+	ihl := int(packetData[0]&0x0f) * 4
+	if ihl < ipv4HeaderMinLen || len(packetData) < ihl+4 {
+		return false
+	}
+
+	// Skip non-first fragments: they don't carry L4 headers.
+	flagsAndOffset := binary.BigEndian.Uint16(packetData[ipv4FlagsOffset : ipv4FlagsOffset+2])
+	if flagsAndOffset&ipv4FragOffMask != 0 {
+		return false
+	}
+
+	dstIP, ok := netip.AddrFromSlice(packetData[ipv4DstOffset : ipv4DstOffset+4])
+	if !ok {
+		return false
+	}
+
+	proto := packetData[ipv4ProtoOffset]
+	dstPort := binary.BigEndian.Uint16(packetData[ihl+dstPortOffset : ihl+dstPortOffset+2])
+
+	switch proto {
+	case ipProtoUDP:
+		return common.HookMatches(f.udpHook.Load(), dstIP, dstPort, packetData)
+	case ipProtoTCP:
+		return common.HookMatches(f.tcpHook.Load(), dstIP, dstPort, packetData)
+	default:
+		return false
+	}
+}
+
+// FilterInbound allows all inbound packets (native firewall handles filtering).
+func (f *HooksFilter) FilterInbound([]byte, int) bool {
+	return false
+}
+
+// SetUDPPacketHook registers the UDP packet hook.
+func (f *HooksFilter) SetUDPPacketHook(ip netip.Addr, dPort uint16, hook func([]byte) bool) {
+	common.SetHook(&f.udpHook, ip, dPort, hook)
+}
+
+// SetTCPPacketHook registers the TCP packet hook.
+func (f *HooksFilter) SetTCPPacketHook(ip netip.Addr, dPort uint16, hook func([]byte) bool) {
+	common.SetHook(&f.tcpHook, ip, dPort, hook)
+}

client/iface/bind/ice_bind_test.go

@@ -239,8 +239,12 @@ func TestICEBind_HandlesConcurrentMixedTraffic(t *testing.T) {
 		ipv6Count++
 	}
 
-	assert.Equal(t, packetsPerFamily, ipv4Count)
-	assert.Equal(t, packetsPerFamily, ipv6Count)
+	// Allow some UDP packet loss under load (e.g. FreeBSD/QEMU runners). The
+	// routing-correctness checks above are the real assertions; the counts
+	// are a sanity bound to catch a totally silent path.
+	minDelivered := packetsPerFamily * 80 / 100
+	assert.GreaterOrEqual(t, ipv4Count, minDelivered, "IPv4 delivery below threshold")
+	assert.GreaterOrEqual(t, ipv6Count, minDelivered, "IPv6 delivery below threshold")
 }
 
 func TestICEBind_DetectsAddressFamilyFromConnection(t *testing.T) {

client/iface/iface.go

@@ -217,7 +217,6 @@ func (w *WGIface) RemoveAllowedIP(peerKey string, allowedIP netip.Prefix) error
 // Close closes the tunnel interface
 func (w *WGIface) Close() error {
 	w.mu.Lock()
-	defer w.mu.Unlock()
 
 	var result *multierror.Error
 
@@ -225,7 +224,15 @@ func (w *WGIface) Close() error {
 		result = multierror.Append(result, fmt.Errorf("failed to free WireGuard proxy: %w", err))
 	}
 
-	if err := w.tun.Close(); err != nil {
+	// Release w.mu before calling w.tun.Close(): the underlying
+	// wireguard-go device.Close() waits for its send/receive goroutines
+	// to drain. Some of those goroutines re-enter WGIface methods that
+	// take w.mu (e.g. the packet filter DNS hook calls GetDevice()), so
+	// holding the mutex here would deadlock the shutdown path.
+	tun := w.tun
+	w.mu.Unlock()
+
+	if err := tun.Close(); err != nil {
 		result = multierror.Append(result, fmt.Errorf("failed to close wireguard interface %s: %w", w.Name(), err))
 	}
 

client/iface/iface_close_test.go

@@ -0,0 +1,113 @@
+//go:build !android
+
+package iface
+
+import (
+	"errors"
+	"sync"
+	"testing"
+	"time"
+
+	wgdevice "golang.zx2c4.com/wireguard/device"
+	"golang.zx2c4.com/wireguard/tun/netstack"
+
+	"github.com/netbirdio/netbird/client/iface/device"
+	"github.com/netbirdio/netbird/client/iface/udpmux"
+	"github.com/netbirdio/netbird/client/iface/wgaddr"
+	"github.com/netbirdio/netbird/client/iface/wgproxy"
+)
+
+// fakeTunDevice implements WGTunDevice and lets the test control when
+// Close() returns. It mimics the wireguard-go shutdown path, which blocks
+// until its goroutines drain. Some of those goroutines (e.g. the packet
+// filter DNS hook in client/internal/dns) call back into WGIface, so if
+// WGIface.Close() held w.mu across tun.Close() the shutdown would
+// deadlock.
+type fakeTunDevice struct {
+	closeStarted chan struct{}
+	unblockClose chan struct{}
+}
+
+func (f *fakeTunDevice) Create() (device.WGConfigurer, error) {
+	return nil, errors.New("not implemented")
+}
+func (f *fakeTunDevice) Up() (*udpmux.UniversalUDPMuxDefault, error) {
+	return nil, errors.New("not implemented")
+}
+func (f *fakeTunDevice) UpdateAddr(wgaddr.Address) error      { return nil }
+func (f *fakeTunDevice) WgAddress() wgaddr.Address            { return wgaddr.Address{} }
+func (f *fakeTunDevice) MTU() uint16                          { return DefaultMTU }
+func (f *fakeTunDevice) DeviceName() string                   { return "nb-close-test" }
+func (f *fakeTunDevice) FilteredDevice() *device.FilteredDevice { return nil }
+func (f *fakeTunDevice) Device() *wgdevice.Device             { return nil }
+func (f *fakeTunDevice) GetNet() *netstack.Net                { return nil }
+func (f *fakeTunDevice) GetICEBind() device.EndpointManager   { return nil }
+
+func (f *fakeTunDevice) Close() error {
+	close(f.closeStarted)
+	<-f.unblockClose
+	return nil
+}
+
+type fakeProxyFactory struct{}
+
+func (fakeProxyFactory) GetProxy() wgproxy.Proxy { return nil }
+func (fakeProxyFactory) GetProxyPort() uint16    { return 0 }
+func (fakeProxyFactory) Free() error             { return nil }
+
+// TestWGIface_CloseReleasesMutexBeforeTunClose guards against a deadlock
+// that surfaces as a macOS test-timeout in
+// TestDNSPermanent_updateUpstream: WGIface.Close() used to hold w.mu
+// while waiting for the wireguard-go device goroutines to finish, and
+// one of those goroutines (the DNS filter hook) calls back into
+// WGIface.GetDevice() which needs the same mutex. The fix is to drop
+// the lock before tun.Close() returns control.
+func TestWGIface_CloseReleasesMutexBeforeTunClose(t *testing.T) {
+	tun := &fakeTunDevice{
+		closeStarted: make(chan struct{}),
+		unblockClose: make(chan struct{}),
+	}
+	w := &WGIface{
+		tun:            tun,
+		wgProxyFactory: fakeProxyFactory{},
+	}
+
+	closeDone := make(chan error, 1)
+	go func() {
+		closeDone <- w.Close()
+	}()
+
+	select {
+	case <-tun.closeStarted:
+	case <-time.After(2 * time.Second):
+		close(tun.unblockClose)
+		t.Fatal("tun.Close() was never invoked")
+	}
+
+	// Simulate the WireGuard read goroutine calling back into WGIface
+	// via the packet filter's DNS hook. If Close() still held w.mu
+	// during tun.Close(), this would block until the test timeout.
+	getDeviceDone := make(chan struct{})
+	var wg sync.WaitGroup
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		_ = w.GetDevice()
+		close(getDeviceDone)
+	}()
+
+	select {
+	case <-getDeviceDone:
+	case <-time.After(2 * time.Second):
+		close(tun.unblockClose)
+		wg.Wait()
+		t.Fatal("GetDevice() deadlocked while WGIface.Close was closing the tun")
+	}
+
+	close(tun.unblockClose)
+	select {
+	case <-closeDone:
+	case <-time.After(2 * time.Second):
+		t.Fatal("WGIface.Close() never returned after the tun was unblocked")
+	}
+}

client/iface/udpmux/universal.go

@@ -171,7 +171,7 @@ func (u *UDPConn) performFilterCheck(addr net.Addr) error {
 	}
 
 	if u.address.Network.Contains(a) {
-		log.Warnf("Address %s is part of the NetBird network %s, refusing to write", addr, u.address)
+		log.Warnf("address %s is part of the NetBird network %s, refusing to write", addr, u.address)
 		return fmt.Errorf("address %s is part of the NetBird network %s, refusing to write", addr, u.address)
 	}
 
@@ -181,7 +181,7 @@ func (u *UDPConn) performFilterCheck(addr net.Addr) error {
 		u.addrCache.Store(addr.String(), isRouted)
 		if isRouted {
 			// Extra log, as the error only shows up with ICE logging enabled
-			log.Infof("Address %s is part of routed network %s, refusing to write", addr, prefix)
+			log.Infof("address %s is part of routed network %s, refusing to write", addr, prefix)
 			return fmt.Errorf("address %s is part of routed network %s, refusing to write", addr, prefix)
 		}
 	}

client/internal/connect.go

@@ -94,6 +94,7 @@ func (c *ConnectClient) RunOnAndroid(
 	dnsAddresses []netip.AddrPort,
 	dnsReadyListener dns.ReadyListener,
 	stateFilePath string,
+	cacheDir string,
 ) error {
 	// in case of non Android os these variables will be nil
 	mobileDependency := MobileDependency{
@@ -103,6 +104,7 @@ func (c *ConnectClient) RunOnAndroid(
 		HostDNSAddresses:      dnsAddresses,
 		DnsReadyListener:      dnsReadyListener,
 		StateFilePath:         stateFilePath,
+		TempDir:               cacheDir,
 	}
 	return c.run(mobileDependency, nil, "")
 }
@@ -338,6 +340,7 @@ func (c *ConnectClient) run(mobileDependency MobileDependency, runningChan chan
 			log.Error(err)
 			return wrapErr(err)
 		}
+		engineConfig.TempDir = mobileDependency.TempDir
 
 		relayManager := relayClient.NewManager(engineCtx, relayURLs, myPrivateKey.PublicKey().String(), engineConfig.MTU)
 		c.statusRecorder.SetRelayMgr(relayManager)

client/internal/debug/debug.go

@@ -16,7 +16,6 @@ import (
 	"path/filepath"
 	"runtime"
 	"runtime/pprof"
-	"slices"
 	"sort"
 	"strings"
 	"time"
@@ -31,7 +30,6 @@ import (
 	"github.com/netbirdio/netbird/client/internal/updater/installer"
 	nbstatus "github.com/netbirdio/netbird/client/status"
 	mgmProto "github.com/netbirdio/netbird/shared/management/proto"
-	"github.com/netbirdio/netbird/util"
 )
 
 const readmeContent = `Netbird debug bundle
@@ -234,6 +232,7 @@ type BundleGenerator struct {
 	statusRecorder *peer.Status
 	syncResponse   *mgmProto.SyncResponse
 	logPath        string
+	tempDir        string
 	cpuProfile     []byte
 	refreshStatus  func() // Optional callback to refresh status before bundle generation
 	clientMetrics  MetricsExporter
@@ -256,6 +255,7 @@ type GeneratorDependencies struct {
 	StatusRecorder *peer.Status
 	SyncResponse   *mgmProto.SyncResponse
 	LogPath        string
+	TempDir        string // Directory for temporary bundle zip files. If empty, os.TempDir() is used.
 	CPUProfile     []byte
 	RefreshStatus  func() // Optional callback to refresh status before bundle generation
 	ClientMetrics  MetricsExporter
@@ -275,6 +275,7 @@ func NewBundleGenerator(deps GeneratorDependencies, cfg BundleConfig) *BundleGen
 		statusRecorder: deps.StatusRecorder,
 		syncResponse:   deps.SyncResponse,
 		logPath:        deps.LogPath,
+		tempDir:        deps.TempDir,
 		cpuProfile:     deps.CPUProfile,
 		refreshStatus:  deps.RefreshStatus,
 		clientMetrics:  deps.ClientMetrics,
@@ -287,7 +288,7 @@ func NewBundleGenerator(deps GeneratorDependencies, cfg BundleConfig) *BundleGen
 
 // Generate creates a debug bundle and returns the location.
 func (g *BundleGenerator) Generate() (resp string, err error) {
-	bundlePath, err := os.CreateTemp("", "netbird.debug.*.zip")
+	bundlePath, err := os.CreateTemp(g.tempDir, "netbird.debug.*.zip")
 	if err != nil {
 		return "", fmt.Errorf("create zip file: %w", err)
 	}
@@ -373,15 +374,8 @@ func (g *BundleGenerator) createArchive() error {
 		log.Errorf("failed to add wg show output: %v", err)
 	}
 
-	if g.logPath != "" && !slices.Contains(util.SpecialLogs, g.logPath) {
-		if err := g.addLogfile(); err != nil {
-			log.Errorf("failed to add log file to debug bundle: %v", err)
-			if err := g.trySystemdLogFallback(); err != nil {
-				log.Errorf("failed to add systemd logs as fallback: %v", err)
-			}
-		}
-	} else if err := g.trySystemdLogFallback(); err != nil {
-		log.Errorf("failed to add systemd logs: %v", err)
+	if err := g.addPlatformLog(); err != nil {
+		log.Errorf("failed to add logs to debug bundle: %v", err)
 	}
 
 	if err := g.addUpdateLogs(); err != nil {

client/internal/debug/debug_android.go

@@ -0,0 +1,41 @@
+//go:build android
+
+package debug
+
+import (
+	"fmt"
+	"io"
+	"os/exec"
+
+	log "github.com/sirupsen/logrus"
+)
+
+func (g *BundleGenerator) addPlatformLog() error {
+	cmd := exec.Command("/system/bin/logcat", "-d")
+	stdout, err := cmd.StdoutPipe()
+	if err != nil {
+		return fmt.Errorf("logcat stdout pipe: %w", err)
+	}
+
+	if err := cmd.Start(); err != nil {
+		return fmt.Errorf("start logcat: %w", err)
+	}
+
+	var logReader io.Reader = stdout
+	if g.anonymize {
+		var pw *io.PipeWriter
+		logReader, pw = io.Pipe()
+		go anonymizeLog(stdout, pw, g.anonymizer)
+	}
+
+	if err := g.addFileToZip(logReader, "logcat.txt"); err != nil {
+		return fmt.Errorf("add logcat to zip: %w", err)
+	}
+
+	if err := cmd.Wait(); err != nil {
+		return fmt.Errorf("wait logcat: %w", err)
+	}
+
+	log.Debug("added logcat output to debug bundle")
+	return nil
+}

client/internal/debug/debug_nonandroid.go

@@ -0,0 +1,25 @@
+//go:build !android
+
+package debug
+
+import (
+	"slices"
+
+	log "github.com/sirupsen/logrus"
+
+	"github.com/netbirdio/netbird/util"
+)
+
+func (g *BundleGenerator) addPlatformLog() error {
+	if g.logPath != "" && !slices.Contains(util.SpecialLogs, g.logPath) {
+		if err := g.addLogfile(); err != nil {
+			log.Errorf("failed to add log file to debug bundle: %v", err)
+			if err := g.trySystemdLogFallback(); err != nil {
+				return err
+			}
+		}
+	} else if err := g.trySystemdLogFallback(); err != nil {
+		return err
+	}
+	return nil
+}

client/internal/debug/upload_test.go

@@ -3,10 +3,12 @@ package debug
 import (
 	"context"
 	"errors"
+	"net"
 	"net/http"
 	"os"
 	"path/filepath"
 	"testing"
+	"time"
 
 	"github.com/stretchr/testify/require"
 
@@ -19,8 +21,10 @@ func TestUpload(t *testing.T) {
 		t.Skip("Skipping upload test on docker ci")
 	}
 	testDir := t.TempDir()
-	testURL := "http://localhost:8080"
+	addr := reserveLoopbackPort(t)
+	testURL := "http://" + addr
 	t.Setenv("SERVER_URL", testURL)
+	t.Setenv("SERVER_ADDRESS", addr)
 	t.Setenv("STORE_DIR", testDir)
 	srv := server.NewServer()
 	go func() {
@@ -33,6 +37,7 @@ func TestUpload(t *testing.T) {
 			t.Errorf("Failed to stop server: %v", err)
 		}
 	})
+	waitForServer(t, addr)
 
 	file := filepath.Join(t.TempDir(), "tmpfile")
 	fileContent := []byte("test file content")
@@ -47,3 +52,30 @@ func TestUpload(t *testing.T) {
 	require.NoError(t, err)
 	require.Equal(t, fileContent, createdFileContent)
 }
+
+// reserveLoopbackPort binds an ephemeral port on loopback to learn a free
+// address, then releases it so the server under test can rebind. The close/
+// rebind window is racy in theory; on loopback with a kernel-assigned port
+// it's essentially never contended in practice.
+func reserveLoopbackPort(t *testing.T) string {
+	t.Helper()
+	l, err := net.Listen("tcp", "127.0.0.1:0")
+	require.NoError(t, err)
+	addr := l.Addr().String()
+	require.NoError(t, l.Close())
+	return addr
+}
+
+func waitForServer(t *testing.T, addr string) {
+	t.Helper()
+	deadline := time.Now().Add(5 * time.Second)
+	for time.Now().Before(deadline) {
+		c, err := net.DialTimeout("tcp", addr, 100*time.Millisecond)
+		if err == nil {
+			_ = c.Close()
+			return
+		}
+		time.Sleep(20 * time.Millisecond)
+	}
+	t.Fatalf("server did not start listening on %s in time", addr)
+}

client/internal/dns/file_parser_unix.go

@@ -13,6 +13,7 @@ import (
 
 const (
 	defaultResolvConfPath = "/etc/resolv.conf"
+	nsswitchConfPath      = "/etc/nsswitch.conf"
 )
 
 type resolvConf struct {

client/internal/dns/handler_chain.go

@@ -1,7 +1,10 @@
 package dns
 
 import (
+	"context"
 	"fmt"
+	"math"
+	"net"
 	"slices"
 	"strconv"
 	"strings"
@@ -192,6 +195,12 @@ func (c *HandlerChain) logHandlers() {
 }
 
 func (c *HandlerChain) ServeDNS(w dns.ResponseWriter, r *dns.Msg) {
+	c.dispatch(w, r, math.MaxInt)
+}
+
+// dispatch routes a DNS request through the chain, skipping handlers with
+// priority > maxPriority. Shared by ServeDNS and ResolveInternal.
+func (c *HandlerChain) dispatch(w dns.ResponseWriter, r *dns.Msg, maxPriority int) {
 	if len(r.Question) == 0 {
 		return
 	}
@@ -216,6 +225,9 @@ func (c *HandlerChain) ServeDNS(w dns.ResponseWriter, r *dns.Msg) {
 
 	// Try handlers in priority order
 	for _, entry := range handlers {
+		if entry.Priority > maxPriority {
+			continue
+		}
 		if !c.isHandlerMatch(qname, entry) {
 			continue
 		}
@@ -273,6 +285,55 @@ func (c *HandlerChain) logResponse(logger *log.Entry, cw *ResponseWriterChain, q
 		cw.response.Len(), meta, time.Since(startTime))
 }
 
+// ResolveInternal runs an in-process DNS query against the chain, skipping any
+// handler with priority > maxPriority. Used by internal callers (e.g. the mgmt
+// cache refresher) that must bypass themselves to avoid loops. Honors ctx
+// cancellation; on ctx.Done the dispatch goroutine is left to drain on its own
+// (bounded by the invoked handler's internal timeout).
+func (c *HandlerChain) ResolveInternal(ctx context.Context, r *dns.Msg, maxPriority int) (*dns.Msg, error) {
+	if len(r.Question) == 0 {
+		return nil, fmt.Errorf("empty question")
+	}
+
+	base := &internalResponseWriter{}
+	done := make(chan struct{})
+	go func() {
+		c.dispatch(base, r, maxPriority)
+		close(done)
+	}()
+
+	select {
+	case <-done:
+	case <-ctx.Done():
+		// Prefer a completed response if dispatch finished concurrently with cancellation.
+		select {
+		case <-done:
+		default:
+			return nil, fmt.Errorf("resolve %s: %w", strings.ToLower(r.Question[0].Name), ctx.Err())
+		}
+	}
+
+	if base.response == nil || base.response.Rcode == dns.RcodeRefused {
+		return nil, fmt.Errorf("no handler resolved %s at priority ≤ %d",
+			strings.ToLower(r.Question[0].Name), maxPriority)
+	}
+	return base.response, nil
+}
+
+// HasRootHandlerAtOrBelow reports whether any "." handler is registered at
+// priority ≤ maxPriority.
+func (c *HandlerChain) HasRootHandlerAtOrBelow(maxPriority int) bool {
+	c.mu.RLock()
+	defer c.mu.RUnlock()
+
+	for _, h := range c.handlers {
+		if h.Pattern == "." && h.Priority <= maxPriority {
+			return true
+		}
+	}
+	return false
+}
+
 func (c *HandlerChain) isHandlerMatch(qname string, entry HandlerEntry) bool {
 	switch {
 	case entry.Pattern == ".":
@@ -291,3 +352,36 @@ func (c *HandlerChain) isHandlerMatch(qname string, entry HandlerEntry) bool {
 		}
 	}
 }
+
+// internalResponseWriter captures a dns.Msg for in-process chain queries.
+type internalResponseWriter struct {
+	response *dns.Msg
+}
+
+func (w *internalResponseWriter) WriteMsg(m *dns.Msg) error { w.response = m; return nil }
+func (w *internalResponseWriter) LocalAddr() net.Addr       { return nil }
+func (w *internalResponseWriter) RemoteAddr() net.Addr      { return nil }
+
+// Write unpacks raw DNS bytes so handlers that call Write instead of WriteMsg
+// still surface their answer to ResolveInternal.
+func (w *internalResponseWriter) Write(p []byte) (int, error) {
+	msg := new(dns.Msg)
+	if err := msg.Unpack(p); err != nil {
+		return 0, err
+	}
+	w.response = msg
+	return len(p), nil
+}
+
+func (w *internalResponseWriter) Close() error      { return nil }
+func (w *internalResponseWriter) TsigStatus() error { return nil }
+
+// TsigTimersOnly is part of dns.ResponseWriter.
+func (w *internalResponseWriter) TsigTimersOnly(bool) {
+	// no-op: in-process queries carry no TSIG state.
+}
+
+// Hijack is part of dns.ResponseWriter.
+func (w *internalResponseWriter) Hijack() {
+	// no-op: in-process queries have no underlying connection to hand off.
+}

client/internal/dns/handler_chain_test.go

@@ -1,11 +1,15 @@
 package dns_test
 
 import (
+	"context"
+	"net"
 	"testing"
+	"time"
 
 	"github.com/miekg/dns"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/mock"
+	"github.com/stretchr/testify/require"
 
 	nbdns "github.com/netbirdio/netbird/client/internal/dns"
 	"github.com/netbirdio/netbird/client/internal/dns/test"
@@ -1042,3 +1046,163 @@ func TestHandlerChain_AddRemoveRoundtrip(t *testing.T) {
 		})
 	}
 }
+
+// answeringHandler writes a fixed A record to ack the query. Used to verify
+// which handler ResolveInternal dispatches to.
+type answeringHandler struct {
+	name string
+	ip   string
+}
+
+func (h *answeringHandler) ServeDNS(w dns.ResponseWriter, r *dns.Msg) {
+	resp := &dns.Msg{}
+	resp.SetReply(r)
+	resp.Answer = []dns.RR{&dns.A{
+		Hdr: dns.RR_Header{Name: r.Question[0].Name, Rrtype: dns.TypeA, Class: dns.ClassINET, Ttl: 60},
+		A:   net.ParseIP(h.ip).To4(),
+	}}
+	_ = w.WriteMsg(resp)
+}
+
+func (h *answeringHandler) String() string { return h.name }
+
+func TestHandlerChain_ResolveInternal_SkipsAboveMaxPriority(t *testing.T) {
+	chain := nbdns.NewHandlerChain()
+
+	high := &answeringHandler{name: "high", ip: "10.0.0.1"}
+	low := &answeringHandler{name: "low", ip: "10.0.0.2"}
+
+	chain.AddHandler("example.com.", high, nbdns.PriorityMgmtCache)
+	chain.AddHandler("example.com.", low, nbdns.PriorityUpstream)
+
+	r := new(dns.Msg)
+	r.SetQuestion("example.com.", dns.TypeA)
+
+	resp, err := chain.ResolveInternal(context.Background(), r, nbdns.PriorityUpstream)
+	assert.NoError(t, err)
+	assert.NotNil(t, resp)
+	assert.Equal(t, 1, len(resp.Answer))
+	a, ok := resp.Answer[0].(*dns.A)
+	assert.True(t, ok)
+	assert.Equal(t, "10.0.0.2", a.A.String(), "should skip mgmtCache handler and resolve via upstream")
+}
+
+func TestHandlerChain_ResolveInternal_ErrorWhenNoMatch(t *testing.T) {
+	chain := nbdns.NewHandlerChain()
+	high := &answeringHandler{name: "high", ip: "10.0.0.1"}
+	chain.AddHandler("example.com.", high, nbdns.PriorityMgmtCache)
+
+	r := new(dns.Msg)
+	r.SetQuestion("example.com.", dns.TypeA)
+
+	_, err := chain.ResolveInternal(context.Background(), r, nbdns.PriorityUpstream)
+	assert.Error(t, err, "no handler at or below maxPriority should error")
+}
+
+// rawWriteHandler packs a response and calls ResponseWriter.Write directly
+// (instead of WriteMsg), exercising the internalResponseWriter.Write path.
+type rawWriteHandler struct {
+	ip string
+}
+
+func (h *rawWriteHandler) ServeDNS(w dns.ResponseWriter, r *dns.Msg) {
+	resp := &dns.Msg{}
+	resp.SetReply(r)
+	resp.Answer = []dns.RR{&dns.A{
+		Hdr: dns.RR_Header{Name: r.Question[0].Name, Rrtype: dns.TypeA, Class: dns.ClassINET, Ttl: 60},
+		A:   net.ParseIP(h.ip).To4(),
+	}}
+	packed, err := resp.Pack()
+	if err != nil {
+		return
+	}
+	_, _ = w.Write(packed)
+}
+
+func TestHandlerChain_ResolveInternal_CapturesRawWrite(t *testing.T) {
+	chain := nbdns.NewHandlerChain()
+	chain.AddHandler("example.com.", &rawWriteHandler{ip: "10.0.0.3"}, nbdns.PriorityUpstream)
+
+	r := new(dns.Msg)
+	r.SetQuestion("example.com.", dns.TypeA)
+
+	resp, err := chain.ResolveInternal(context.Background(), r, nbdns.PriorityUpstream)
+	assert.NoError(t, err)
+	require.NotNil(t, resp)
+	require.Len(t, resp.Answer, 1)
+	a, ok := resp.Answer[0].(*dns.A)
+	require.True(t, ok)
+	assert.Equal(t, "10.0.0.3", a.A.String(), "handlers calling Write(packed) must still surface their answer")
+}
+
+func TestHandlerChain_ResolveInternal_EmptyQuestion(t *testing.T) {
+	chain := nbdns.NewHandlerChain()
+	_, err := chain.ResolveInternal(context.Background(), new(dns.Msg), nbdns.PriorityUpstream)
+	assert.Error(t, err)
+}
+
+// hangingHandler blocks indefinitely until closed, simulating a wedged upstream.
+type hangingHandler struct {
+	block chan struct{}
+}
+
+func (h *hangingHandler) ServeDNS(w dns.ResponseWriter, r *dns.Msg) {
+	<-h.block
+	resp := &dns.Msg{}
+	resp.SetReply(r)
+	_ = w.WriteMsg(resp)
+}
+
+func (h *hangingHandler) String() string { return "hangingHandler" }
+
+func TestHandlerChain_ResolveInternal_HonorsContextTimeout(t *testing.T) {
+	chain := nbdns.NewHandlerChain()
+	h := &hangingHandler{block: make(chan struct{})}
+	defer close(h.block)
+
+	chain.AddHandler("example.com.", h, nbdns.PriorityUpstream)
+
+	r := new(dns.Msg)
+	r.SetQuestion("example.com.", dns.TypeA)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
+	defer cancel()
+
+	start := time.Now()
+	_, err := chain.ResolveInternal(ctx, r, nbdns.PriorityUpstream)
+	elapsed := time.Since(start)
+
+	assert.Error(t, err)
+	assert.ErrorIs(t, err, context.DeadlineExceeded)
+	assert.Less(t, elapsed, 500*time.Millisecond, "ResolveInternal must return shortly after ctx deadline")
+}
+
+func TestHandlerChain_HasRootHandlerAtOrBelow(t *testing.T) {
+	chain := nbdns.NewHandlerChain()
+	h := &answeringHandler{name: "h", ip: "10.0.0.1"}
+
+	assert.False(t, chain.HasRootHandlerAtOrBelow(nbdns.PriorityUpstream), "empty chain")
+
+	chain.AddHandler("example.com.", h, nbdns.PriorityUpstream)
+	assert.False(t, chain.HasRootHandlerAtOrBelow(nbdns.PriorityUpstream), "non-root handler does not count")
+
+	chain.AddHandler(".", h, nbdns.PriorityMgmtCache)
+	assert.False(t, chain.HasRootHandlerAtOrBelow(nbdns.PriorityUpstream), "root handler above threshold excluded")
+
+	chain.AddHandler(".", h, nbdns.PriorityDefault)
+	assert.True(t, chain.HasRootHandlerAtOrBelow(nbdns.PriorityUpstream), "root handler at PriorityDefault included")
+
+	chain.RemoveHandler(".", nbdns.PriorityDefault)
+	assert.False(t, chain.HasRootHandlerAtOrBelow(nbdns.PriorityUpstream))
+
+	// Primary nsgroup case: root handler lands at PriorityUpstream.
+	chain.AddHandler(".", h, nbdns.PriorityUpstream)
+	assert.True(t, chain.HasRootHandlerAtOrBelow(nbdns.PriorityUpstream), "root at PriorityUpstream included")
+	chain.RemoveHandler(".", nbdns.PriorityUpstream)
+
+	// Fallback case: original /etc/resolv.conf entries land at PriorityFallback.
+	chain.AddHandler(".", h, nbdns.PriorityFallback)
+	assert.True(t, chain.HasRootHandlerAtOrBelow(nbdns.PriorityUpstream), "root at PriorityFallback included")
+	chain.RemoveHandler(".", nbdns.PriorityFallback)
+	assert.False(t, chain.HasRootHandlerAtOrBelow(nbdns.PriorityUpstream))
+}

client/internal/dns/host_unix.go

@@ -46,12 +46,12 @@ type restoreHostManager interface {
 }
 
 func newHostManager(wgInterface string) (hostManager, error) {
-	osManager, err := getOSDNSManagerType()
+	osManager, reason, err := getOSDNSManagerType()
 	if err != nil {
 		return nil, fmt.Errorf("get os dns manager type: %w", err)
 	}
 
-	log.Infof("System DNS manager discovered: %s", osManager)
+	log.Infof("System DNS manager discovered: %s (%s)", osManager, reason)
 	mgr, err := newHostManagerFromType(wgInterface, osManager)
 	// need to explicitly return nil mgr on error to avoid returning a non-nil interface containing a nil value
 	if err != nil {
@@ -74,17 +74,49 @@ func newHostManagerFromType(wgInterface string, osManager osManagerType) (restor
 	}
 }
 
-func getOSDNSManagerType() (osManagerType, error) {
+func getOSDNSManagerType() (osManagerType, string, error) {
+	resolved := isSystemdResolvedRunning()
+	nss := isLibnssResolveUsed()
+	stub := checkStub()
+
+	// Prefer systemd-resolved whenever it owns libc resolution, regardless of
+	// who wrote /etc/resolv.conf. File-mode rewrites do not affect lookups
+	// that go through nss-resolve, and in foreign mode they can loop back
+	// through resolved as an upstream.
+	if resolved && (nss || stub) {
+		return systemdManager, fmt.Sprintf("systemd-resolved active (nss-resolve=%t, stub=%t)", nss, stub), nil
+	}
+
+	mgr, reason, rejected, err := scanResolvConfHeader()
+	if err != nil {
+		return 0, "", err
+	}
+	if reason != "" {
+		return mgr, reason, nil
+	}
+
+	fallback := fmt.Sprintf("no manager matched (resolved=%t, nss-resolve=%t, stub=%t)", resolved, nss, stub)
+	if len(rejected) > 0 {
+		fallback += "; rejected: " + strings.Join(rejected, ", ")
+	}
+	return fileManager, fallback, nil
+}
+
+// scanResolvConfHeader walks /etc/resolv.conf header comments and returns the
+// matching manager. If reason is empty the caller should pick file mode and
+// use rejected for diagnostics.
+func scanResolvConfHeader() (osManagerType, string, []string, error) {
 	file, err := os.Open(defaultResolvConfPath)
 	if err != nil {
-		return 0, fmt.Errorf("unable to open %s for checking owner, got error: %w", defaultResolvConfPath, err)
+		return 0, "", nil, fmt.Errorf("unable to open %s for checking owner, got error: %w", defaultResolvConfPath, err)
 	}
 	defer func() {
-		if err := file.Close(); err != nil {
-			log.Errorf("close file %s: %s", defaultResolvConfPath, err)
+		if cerr := file.Close(); cerr != nil {
+			log.Errorf("close file %s: %s", defaultResolvConfPath, cerr)
 		}
 	}()
 
+	var rejected []string
 	scanner := bufio.NewScanner(file)
 	for scanner.Scan() {
 		text := scanner.Text()
@@ -92,41 +124,48 @@ func getOSDNSManagerType() (osManagerType, error) {
 			continue
 		}
 		if text[0] != '#' {
-			return fileManager, nil
+			break
 		}
-		if strings.Contains(text, fileGeneratedResolvConfContentHeader) {
-			return netbirdManager, nil
-		}
-		if strings.Contains(text, "NetworkManager") && isDbusListenerRunning(networkManagerDest, networkManagerDbusObjectNode) && isNetworkManagerSupported() {
-			return networkManager, nil
-		}
-		if strings.Contains(text, "systemd-resolved") && isSystemdResolvedRunning() {
-			if checkStub() {
-				return systemdManager, nil
-			} else {
-				return fileManager, nil
-			}
-		}
-		if strings.Contains(text, "resolvconf") {
-			if isSystemdResolveConfMode() {
-				return systemdManager, nil
-			}
-
-			return resolvConfManager, nil
+		if mgr, reason, rej := matchResolvConfHeader(text); reason != "" {
+			return mgr, reason, nil, nil
+		} else if rej != "" {
+			rejected = append(rejected, rej)
 		}
 	}
 	if err := scanner.Err(); err != nil && err != io.EOF {
-		return 0, fmt.Errorf("scan: %w", err)
+		return 0, "", nil, fmt.Errorf("scan: %w", err)
 	}
-
-	return fileManager, nil
+	return 0, "", rejected, nil
 }
 
-// checkStub checks if the stub resolver is disabled in systemd-resolved. If it is disabled, we fall back to file manager.
+// matchResolvConfHeader inspects a single comment line. Returns either a
+// definitive (manager, reason) or a non-empty rejected diagnostic.
+func matchResolvConfHeader(text string) (osManagerType, string, string) {
+	if strings.Contains(text, fileGeneratedResolvConfContentHeader) {
+		return netbirdManager, "netbird-managed resolv.conf header detected", ""
+	}
+	if strings.Contains(text, "NetworkManager") {
+		if isDbusListenerRunning(networkManagerDest, networkManagerDbusObjectNode) && isNetworkManagerSupported() {
+			return networkManager, "NetworkManager header + supported version on dbus", ""
+		}
+		return 0, "", "NetworkManager header (no dbus or unsupported version)"
+	}
+	if strings.Contains(text, "resolvconf") {
+		if isSystemdResolveConfMode() {
+			return systemdManager, "resolvconf header in systemd-resolved compatibility mode", ""
+		}
+		return resolvConfManager, "resolvconf header detected", ""
+	}
+	return 0, "", ""
+}
+
+// checkStub reports whether systemd-resolved's stub (127.0.0.53) is listed
+// in /etc/resolv.conf. On parse failure we assume it is, to avoid dropping
+// into file mode while resolved is active.
 func checkStub() bool {
 	rConf, err := parseDefaultResolvConf()
 	if err != nil {
-		log.Warnf("failed to parse resolv conf: %s", err)
+		log.Warnf("failed to parse resolv conf, assuming stub is active: %s", err)
 		return true
 	}
 
@@ -139,3 +178,36 @@ func checkStub() bool {
 
 	return false
 }
+
+// isLibnssResolveUsed reports whether nss-resolve is listed before dns on
+// the hosts: line of /etc/nsswitch.conf. When it is, libc lookups are
+// delegated to systemd-resolved regardless of /etc/resolv.conf.
+func isLibnssResolveUsed() bool {
+	bs, err := os.ReadFile(nsswitchConfPath)
+	if err != nil {
+		log.Debugf("read %s: %v", nsswitchConfPath, err)
+		return false
+	}
+	return parseNsswitchResolveAhead(bs)
+}
+
+func parseNsswitchResolveAhead(data []byte) bool {
+	for _, line := range strings.Split(string(data), "\n") {
+		if i := strings.IndexByte(line, '#'); i >= 0 {
+			line = line[:i]
+		}
+		fields := strings.Fields(line)
+		if len(fields) < 2 || fields[0] != "hosts:" {
+			continue
+		}
+		for _, module := range fields[1:] {
+			switch module {
+			case "dns":
+				return false
+			case "resolve":
+				return true
+			}
+		}
+	}
+	return false
+}

client/internal/dns/host_unix_test.go

@@ -0,0 +1,76 @@
+//go:build (linux && !android) || freebsd
+
+package dns
+
+import "testing"
+
+func TestParseNsswitchResolveAhead(t *testing.T) {
+	tests := []struct {
+		name string
+		in   string
+		want bool
+	}{
+		{
+			name: "resolve before dns with action token",
+			in:   "hosts: mymachines resolve [!UNAVAIL=return] files myhostname dns\n",
+			want: true,
+		},
+		{
+			name: "dns before resolve",
+			in:   "hosts: files mdns4_minimal [NOTFOUND=return] dns resolve\n",
+			want: false,
+		},
+		{
+			name: "debian default with only dns",
+			in:   "hosts: files mdns4_minimal [NOTFOUND=return] dns mymachines\n",
+			want: false,
+		},
+		{
+			name: "neither resolve nor dns",
+			in:   "hosts: files myhostname\n",
+			want: false,
+		},
+		{
+			name: "no hosts line",
+			in:   "passwd: files systemd\ngroup: files systemd\n",
+			want: false,
+		},
+		{
+			name: "empty",
+			in:   "",
+			want: false,
+		},
+		{
+			name: "comments and blank lines ignored",
+			in:   "# comment\n\n# another\nhosts: resolve dns\n",
+			want: true,
+		},
+		{
+			name: "trailing inline comment",
+			in:   "hosts: resolve [!UNAVAIL=return] dns # fallback\n",
+			want: true,
+		},
+		{
+			name: "hosts token must be the first field",
+			in:   "  hosts: resolve dns\n",
+			want: true,
+		},
+		{
+			name: "other db line mentioning resolve is ignored",
+			in:   "networks: resolve\nhosts: dns\n",
+			want: false,
+		},
+		{
+			name: "only resolve, no dns",
+			in:   "hosts: files resolve\n",
+			want: true,
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := parseNsswitchResolveAhead([]byte(tt.in)); got != tt.want {
+				t.Errorf("parseNsswitchResolveAhead() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}

client/internal/dns/mgmt/bypass_resolver.go

@@ -0,0 +1,55 @@
+package mgmt
+
+import (
+	"context"
+	"fmt"
+	"net"
+	"net/netip"
+
+	nbnet "github.com/netbirdio/netbird/client/net"
+)
+
+// NewBypassResolver builds a *net.Resolver that sends queries directly to
+// the supplied nameservers through a socket that bypasses the NetBird
+// overlay interface. This lets the mgmt cache refresh control-plane
+// FQDNs (api/signal/relay/stun/turn) even when an exit-node default
+// route is installed on the overlay before its peer is live.
+//
+// Returns nil if nameservers is empty. The caller must not pass
+// loopback/overlay IPs (e.g. 127.0.0.1, the overlay listener address);
+// those would defeat the purpose of bypassing.
+func NewBypassResolver(nameservers []netip.Addr) *net.Resolver {
+	if len(nameservers) == 0 {
+		return nil
+	}
+
+	servers := make([]string, 0, len(nameservers))
+	for _, ns := range nameservers {
+		if !ns.IsValid() || ns.IsLoopback() || ns.IsUnspecified() {
+			continue
+		}
+		servers = append(servers, netip.AddrPortFrom(ns, 53).String())
+	}
+	if len(servers) == 0 {
+		return nil
+	}
+
+	return &net.Resolver{
+		PreferGo: true,
+		Dial: func(ctx context.Context, network, _ string) (net.Conn, error) {
+			nbDialer := nbnet.NewDialer()
+			var lastErr error
+			for _, ns := range servers {
+				conn, err := nbDialer.DialContext(ctx, network, ns)
+				if err == nil {
+					return conn, nil
+				}
+				lastErr = err
+			}
+			if lastErr == nil {
+				return nil, fmt.Errorf("no bypass nameservers configured")
+			}
+			return nil, fmt.Errorf("dial bypass nameservers: %w", lastErr)
+		},
+	}
+}

client/internal/dns/mgmt/mgmt.go

@@ -2,40 +2,92 @@ package mgmt
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"net"
-	"net/netip"
 	"net/url"
+	"os"
+	"slices"
+	"strconv"
 	"strings"
 	"sync"
+	"sync/atomic"
 	"time"
 
 	"github.com/miekg/dns"
 	log "github.com/sirupsen/logrus"
+	"golang.org/x/sync/singleflight"
 
 	dnsconfig "github.com/netbirdio/netbird/client/internal/dns/config"
+	"github.com/netbirdio/netbird/client/internal/dns/resutil"
 	"github.com/netbirdio/netbird/shared/management/domain"
 )
 
-const dnsTimeout = 5 * time.Second
+const (
+	dnsTimeout     = 5 * time.Second
+	defaultTTL     = 300 * time.Second
+	refreshBackoff = 30 * time.Second
 
-// Resolver caches critical NetBird infrastructure domains
+	// envMgmtCacheTTL overrides defaultTTL for integration/dev testing.
+	envMgmtCacheTTL = "NB_MGMT_CACHE_TTL"
+)
+
+// ChainResolver lets the cache refresh stale entries through the DNS handler
+// chain instead of net.DefaultResolver, avoiding loopback when NetBird is the
+// system resolver.
+type ChainResolver interface {
+	ResolveInternal(ctx context.Context, msg *dns.Msg, maxPriority int) (*dns.Msg, error)
+	HasRootHandlerAtOrBelow(maxPriority int) bool
+}
+
+// cachedRecord holds DNS records plus timestamps used for TTL refresh.
+// records and cachedAt are set at construction and treated as immutable;
+// lastFailedRefresh and consecFailures are mutable and must be accessed under
+// Resolver.mutex.
+type cachedRecord struct {
+	records           []dns.RR
+	cachedAt          time.Time
+	lastFailedRefresh time.Time
+	consecFailures    int
+}
+
+// Resolver caches critical NetBird infrastructure domains.
+// records, refreshing, mgmtDomain and serverDomains are all guarded by mutex.
 type Resolver struct {
-	records       map[dns.Question][]dns.RR
+	records       map[dns.Question]*cachedRecord
 	mgmtDomain    *domain.Domain
 	serverDomains *dnsconfig.ServerDomains
 	mutex         sync.RWMutex
-}
 
-type ipsResponse struct {
-	ips []netip.Addr
-	err error
+	chain            ChainResolver
+	chainMaxPriority int
+	refreshGroup     singleflight.Group
+
+	// refreshing tracks questions whose refresh is running via the OS
+	// fallback path. A ServeDNS hit for a question in this map indicates
+	// the OS resolver routed the recursive query back to us (loop). Only
+	// the OS path arms this so chain-path refreshes don't produce false
+	// positives. The atomic bool is CAS-flipped once per refresh to
+	// throttle the warning log.
+	refreshing map[dns.Question]*atomic.Bool
+
+	cacheTTL time.Duration
+
+	// bypassResolver, when non-nil, is used by osLookup instead of
+	// net.DefaultResolver. It is constructed by the caller to dial the
+	// original (pre-NetBird) system nameservers through a socket that
+	// bypasses the overlay interface (control-plane fwmark / bound iface),
+	// so that when an exit-node default route is installed before a peer
+	// is handshaked the refresh does not fail with ENOKEY.
+	bypassResolver *net.Resolver
 }
 
 // NewResolver creates a new management domains cache resolver.
 func NewResolver() *Resolver {
 	return &Resolver{
-		records: make(map[dns.Question][]dns.RR),
+		records:    make(map[dns.Question]*cachedRecord),
+		refreshing: make(map[dns.Question]*atomic.Bool),
+		cacheTTL:   resolveCacheTTL(),
 	}
 }
 
@@ -44,7 +96,39 @@ func (m *Resolver) String() string {
 	return "MgmtCacheResolver"
 }
 
-// ServeDNS implements dns.Handler interface.
+// SetChainResolver wires the handler chain used to refresh stale cache entries.
+// maxPriority caps which handlers may answer refresh queries (typically
+// PriorityUpstream, so upstream/default/fallback handlers are consulted and
+// mgmt/route/local handlers are skipped).
+func (m *Resolver) SetChainResolver(chain ChainResolver, maxPriority int) {
+	m.mutex.Lock()
+	m.chain = chain
+	m.chainMaxPriority = maxPriority
+	m.mutex.Unlock()
+}
+
+// SetBypassResolver installs a resolver that osLookup uses instead of
+// net.DefaultResolver. It is intended to dial the original (pre-NetBird)
+// system nameservers through a socket that does not follow the overlay
+// default route, so that a refresh initiated while an exit node is active
+// but its WireGuard peer is not yet installed cannot deadlock on ENOKEY.
+// Passing nil restores use of net.DefaultResolver.
+func (m *Resolver) SetBypassResolver(r *net.Resolver) {
+	m.mutex.Lock()
+	m.bypassResolver = r
+	m.mutex.Unlock()
+}
+
+// ServeDNS serves cached A/AAAA records. Stale entries are returned
+// immediately and refreshed asynchronously (stale-while-revalidate).
+//
+// If the query name is not in the cache but falls under a pool-root
+// domain (a domain the mgmt advertised in ServerDomains.Relay, whose
+// instance subdomains like streamline-de-fra1-0.relay.netbird.io are
+// part of the relay pool), resolve it on demand through the bypass
+// resolver and cache the result. This is what lets the daemon reach
+// a foreign relay FQDN after an exit-node default route has been
+// installed on the overlay before its peer is live.
 func (m *Resolver) ServeDNS(w dns.ResponseWriter, r *dns.Msg) {
 	if len(r.Question) == 0 {
 		m.continueToNext(w, r)
@@ -60,20 +144,42 @@ func (m *Resolver) ServeDNS(w dns.ResponseWriter, r *dns.Msg) {
 	}
 
 	m.mutex.RLock()
-	records, found := m.records[question]
+	cached, found := m.records[question]
+	inflight := m.refreshing[question]
+	var shouldRefresh bool
+	if found {
+		stale := time.Since(cached.cachedAt) > m.cacheTTL
+		inBackoff := !cached.lastFailedRefresh.IsZero() && time.Since(cached.lastFailedRefresh) < refreshBackoff
+		shouldRefresh = stale && !inBackoff
+	}
 	m.mutex.RUnlock()
 
 	if !found {
+		if m.isUnderPoolRoot(question.Name) {
+			m.resolveOnDemand(w, r, question)
+			return
+		}
 		m.continueToNext(w, r)
 		return
 	}
 
+	if inflight != nil && inflight.CompareAndSwap(false, true) {
+		log.Warnf("mgmt cache: possible resolver loop for domain=%s: served stale while an OS-fallback refresh was inflight (if NetBird is the system resolver, the OS-path predicate is wrong)",
+			question.Name)
+	}
+
+	// Skip scheduling a refresh goroutine if one is already inflight for
+	// this question; singleflight would dedup anyway but skipping avoids
+	// a parked goroutine per stale hit under bursty load.
+	if shouldRefresh && inflight == nil {
+		m.scheduleRefresh(question, cached)
+	}
+
 	resp := &dns.Msg{}
 	resp.SetReply(r)
 	resp.Authoritative = false
 	resp.RecursionAvailable = true
-
-	resp.Answer = append(resp.Answer, records...)
+	resp.Answer = cloneRecordsWithTTL(cached.records, m.responseTTL(cached.cachedAt))
 
 	log.Debugf("serving %d cached records for domain=%s", len(resp.Answer), question.Name)
 
@@ -82,12 +188,117 @@ func (m *Resolver) ServeDNS(w dns.ResponseWriter, r *dns.Msg) {
 	}
 }
 
-// MatchSubdomains returns false since this resolver only handles exact domain matches
-// for NetBird infrastructure domains (signal, relay, flow, etc.), not their subdomains.
+// MatchSubdomains returns false by default: the bare resolver is registered
+// against exact domains. Pool-root domains (currently Relay entries from
+// ServerDomains) are registered through a subdomain-matching wrapper at
+// the call site instead, so instance subdomains hit this handler and get
+// the on-demand resolve path in ServeDNS.
 func (m *Resolver) MatchSubdomains() bool {
 	return false
 }
 
+// isUnderPoolRoot reports whether fqdn is an instance subdomain under any
+// pool-root domain advertised by the mgmt (currently ServerDomains.Relay),
+// e.g. "streamline-de-fra1-0.relay.netbird.io." is under "relay.netbird.io".
+// The pool-root itself is not considered a subdomain (it matches the exact
+// cache entry populated by AddDomain instead).
+//
+// Canonicalization mirrors server.toZone — lowercase, strip trailing dot,
+// and strip a leading "*." wildcard (via canonicalizePoolDomain) — so the
+// membership check is consistent with the handler-chain registration that
+// runs the same set through toZone. toZone itself lives in the parent dns
+// package and cannot be imported from here without a cycle.
+func (m *Resolver) isUnderPoolRoot(fqdn string) bool {
+	m.mutex.RLock()
+	defer m.mutex.RUnlock()
+	if m.serverDomains == nil {
+		return false
+	}
+	fqdn = canonicalizePoolDomain(fqdn)
+	if fqdn == "" {
+		return false
+	}
+	for _, root := range m.serverDomains.Relay {
+		r := canonicalizePoolDomain(root.PunycodeString())
+		if r == "" || fqdn == r {
+			continue
+		}
+		if strings.HasSuffix(fqdn, "."+r) {
+			return true
+		}
+	}
+	return false
+}
+
+// canonicalizePoolDomain normalizes a domain for pool-root membership
+// comparison: lowercase, trailing dot stripped, leading "*." wildcard
+// stripped. Matches the transformation server.toZone applies on the
+// handler-registration side (modulo trailing-dot orientation, which is
+// self-consistent within this file).
+func canonicalizePoolDomain(s string) string {
+	s = strings.ToLower(strings.TrimSuffix(s, "."))
+	s = strings.TrimPrefix(s, "*.")
+	return s
+}
+
+// resolveOnDemand resolves an uncached pool-root subdomain (e.g. a relay
+// instance FQDN) through the bypass resolver path, caches the result, and
+// writes it back to w. Falls through to the next handler on error so the
+// normal chain can still attempt the resolve.
+func (m *Resolver) resolveOnDemand(w dns.ResponseWriter, r *dns.Msg, question dns.Question) {
+	d, err := domain.FromString(strings.TrimSuffix(question.Name, "."))
+	if err != nil {
+		log.Debugf("on-demand resolve: parse domain %q: %v", question.Name, err)
+		m.continueToNext(w, r)
+		return
+	}
+
+	// Collapse concurrent on-demand lookups for the same (name, qtype) into
+	// a single upstream query via singleflight. A burst of parallel queries
+	// for a freshly-learned pool-root subdomain (e.g. multiple peer workers
+	// dialing the same foreign relay, or A + AAAA racing each other) would
+	// otherwise each hit the bypass resolver independently. The prefix
+	// namespaces this key off scheduleRefresh's keyspace so the two paths
+	// can coexist without collisions.
+	key := "ondemand:" + question.Name + ":" + strconv.Itoa(int(question.Qtype))
+	result, err, _ := m.refreshGroup.Do(key, func() (any, error) {
+		ctx, cancel := context.WithTimeout(context.Background(), dnsTimeout)
+		defer cancel()
+		return m.lookupRecords(ctx, d, question)
+	})
+	if err != nil {
+		log.Debugf("on-demand resolve %s type=%s: %v",
+			d.SafeString(), dns.TypeToString[question.Qtype], err)
+		m.continueToNext(w, r)
+		return
+	}
+	records, _ := result.([]dns.RR)
+	if len(records) == 0 {
+		m.continueToNext(w, r)
+		return
+	}
+
+	now := time.Now()
+	m.mutex.Lock()
+	if _, exists := m.records[question]; !exists {
+		m.records[question] = &cachedRecord{records: records, cachedAt: now}
+	}
+	m.mutex.Unlock()
+
+	resp := &dns.Msg{}
+	resp.SetReply(r)
+	resp.Authoritative = false
+	resp.RecursionAvailable = true
+	resp.Answer = cloneRecordsWithTTL(records, uint32(m.cacheTTL.Seconds()))
+
+	log.Debugf("on-demand resolved %d records for domain=%s", len(resp.Answer), question.Name)
+
+	if err := w.WriteMsg(resp); err != nil {
+		log.Errorf("failed to write on-demand response: %v", err)
+	}
+}
+
+
 // continueToNext signals the handler chain to continue to the next handler.
 func (m *Resolver) continueToNext(w dns.ResponseWriter, r *dns.Msg) {
 	resp := &dns.Msg{}
@@ -98,101 +309,289 @@ func (m *Resolver) continueToNext(w dns.ResponseWriter, r *dns.Msg) {
 	}
 }
 
-// AddDomain manually adds a domain to cache by resolving it.
+// AddDomain resolves a domain and stores its A/AAAA records in the cache.
+// A family that resolves NODATA (nil err, zero records) evicts any stale
+// entry for that qtype.
 func (m *Resolver) AddDomain(ctx context.Context, d domain.Domain) error {
 	dnsName := strings.ToLower(dns.Fqdn(d.PunycodeString()))
 
 	ctx, cancel := context.WithTimeout(ctx, dnsTimeout)
 	defer cancel()
 
-	ips, err := lookupIPWithExtraTimeout(ctx, d)
-	if err != nil {
-		return err
+	aRecords, aaaaRecords, errA, errAAAA := m.lookupBoth(ctx, d, dnsName)
+
+	if errA != nil && errAAAA != nil {
+		return fmt.Errorf("resolve %s: %w", d.SafeString(), errors.Join(errA, errAAAA))
 	}
 
-	var aRecords, aaaaRecords []dns.RR
-	for _, ip := range ips {
-		if ip.Is4() {
-			rr := &dns.A{
-				Hdr: dns.RR_Header{
-					Name:   dnsName,
-					Rrtype: dns.TypeA,
-					Class:  dns.ClassINET,
-					Ttl:    300,
-				},
-				A: ip.AsSlice(),
-			}
-			aRecords = append(aRecords, rr)
-		} else if ip.Is6() {
-			rr := &dns.AAAA{
-				Hdr: dns.RR_Header{
-					Name:   dnsName,
-					Rrtype: dns.TypeAAAA,
-					Class:  dns.ClassINET,
-					Ttl:    300,
-				},
-				AAAA: ip.AsSlice(),
-			}
-			aaaaRecords = append(aaaaRecords, rr)
+	if len(aRecords) == 0 && len(aaaaRecords) == 0 {
+		if err := errors.Join(errA, errAAAA); err != nil {
+			return fmt.Errorf("resolve %s: no A/AAAA records: %w", d.SafeString(), err)
 		}
+		return fmt.Errorf("resolve %s: no A/AAAA records", d.SafeString())
 	}
 
+	now := time.Now()
 	m.mutex.Lock()
+	defer m.mutex.Unlock()
 
-	if len(aRecords) > 0 {
-		aQuestion := dns.Question{
-			Name:   dnsName,
-			Qtype:  dns.TypeA,
-			Qclass: dns.ClassINET,
-		}
-		m.records[aQuestion] = aRecords
-	}
+	m.applyFamilyRecords(dnsName, dns.TypeA, aRecords, errA, now)
+	m.applyFamilyRecords(dnsName, dns.TypeAAAA, aaaaRecords, errAAAA, now)
 
-	if len(aaaaRecords) > 0 {
-		aaaaQuestion := dns.Question{
-			Name:   dnsName,
-			Qtype:  dns.TypeAAAA,
-			Qclass: dns.ClassINET,
-		}
-		m.records[aaaaQuestion] = aaaaRecords
-	}
-
-	m.mutex.Unlock()
-
-	log.Debugf("added domain=%s with %d A records and %d AAAA records",
+	log.Debugf("added/updated domain=%s with %d A records and %d AAAA records",
 		d.SafeString(), len(aRecords), len(aaaaRecords))
 
 	return nil
 }
 
-func lookupIPWithExtraTimeout(ctx context.Context, d domain.Domain) ([]netip.Addr, error) {
-	log.Infof("looking up IP for mgmt domain=%s", d.SafeString())
-	defer log.Infof("done looking up IP for mgmt domain=%s", d.SafeString())
-	resultChan := make(chan *ipsResponse, 1)
+// applyFamilyRecords writes records, evicts on NODATA, leaves the cache
+// untouched on error. Caller holds m.mutex.
+func (m *Resolver) applyFamilyRecords(dnsName string, qtype uint16, records []dns.RR, err error, now time.Time) {
+	q := dns.Question{Name: dnsName, Qtype: qtype, Qclass: dns.ClassINET}
+	switch {
+	case len(records) > 0:
+		m.records[q] = &cachedRecord{records: records, cachedAt: now}
+	case err == nil:
+		delete(m.records, q)
+	}
+}
 
-	go func() {
-		ips, err := net.DefaultResolver.LookupNetIP(ctx, "ip", d.PunycodeString())
-		resultChan <- &ipsResponse{
-			err: err,
-			ips: ips,
+// scheduleRefresh kicks off an async refresh. DoChan spawns one goroutine per
+// unique in-flight key; bursty stale hits share its channel. expected is the
+// cachedRecord pointer observed by the caller; the refresh only mutates the
+// cache if that pointer is still the one stored, so a stale in-flight refresh
+// can't clobber a newer entry written by AddDomain or a competing refresh.
+func (m *Resolver) scheduleRefresh(question dns.Question, expected *cachedRecord) {
+	key := question.Name + "|" + dns.TypeToString[question.Qtype]
+	_ = m.refreshGroup.DoChan(key, func() (any, error) {
+		return nil, m.refreshQuestion(question, expected)
+	})
+}
+
+// refreshQuestion replaces the cached records on success, or marks the entry
+// failed (arming the backoff) on failure. While this runs, ServeDNS can detect
+// a resolver loop by spotting a query for this same question arriving on us.
+// expected pins the cache entry observed at schedule time; mutations only apply
+// if m.records[question] still points at it.
+func (m *Resolver) refreshQuestion(question dns.Question, expected *cachedRecord) error {
+	ctx, cancel := context.WithTimeout(context.Background(), dnsTimeout)
+	defer cancel()
+
+	d, err := domain.FromString(strings.TrimSuffix(question.Name, "."))
+	if err != nil {
+		m.markRefreshFailed(question, expected)
+		return fmt.Errorf("parse domain: %w", err)
+	}
+
+	records, err := m.lookupRecords(ctx, d, question)
+	if err != nil {
+		fails := m.markRefreshFailed(question, expected)
+		logf := log.Warnf
+		if fails == 0 || fails > 1 {
+			logf = log.Debugf
 		}
-	}()
-
-	var resp *ipsResponse
-
-	select {
-	case <-time.After(dnsTimeout + time.Millisecond*500):
-		log.Warnf("timed out waiting for IP for mgmt domain=%s", d.SafeString())
-		return nil, fmt.Errorf("timed out waiting for ips to be available for domain %s", d.SafeString())
-	case <-ctx.Done():
-		return nil, ctx.Err()
-	case resp = <-resultChan:
+		logf("refresh mgmt cache domain=%s type=%s: %v (consecutive failures=%d)",
+			d.SafeString(), dns.TypeToString[question.Qtype], err, fails)
+		return err
 	}
 
-	if resp.err != nil {
-		return nil, fmt.Errorf("resolve domain %s: %w", d.SafeString(), resp.err)
+	// NOERROR/NODATA: family gone upstream, evict so we stop serving stale.
+	if len(records) == 0 {
+		m.mutex.Lock()
+		if m.records[question] == expected {
+			delete(m.records, question)
+			m.mutex.Unlock()
+			log.Infof("removed mgmt cache domain=%s type=%s: no records returned",
+				d.SafeString(), dns.TypeToString[question.Qtype])
+			return nil
+		}
+		m.mutex.Unlock()
+		log.Debugf("skipping refresh evict for domain=%s type=%s: entry changed during refresh",
+			d.SafeString(), dns.TypeToString[question.Qtype])
+		return nil
 	}
-	return resp.ips, nil
+
+	now := time.Now()
+	m.mutex.Lock()
+	if m.records[question] != expected {
+		m.mutex.Unlock()
+		log.Debugf("skipping refresh write for domain=%s type=%s: entry changed during refresh",
+			d.SafeString(), dns.TypeToString[question.Qtype])
+		return nil
+	}
+	m.records[question] = &cachedRecord{records: records, cachedAt: now}
+	m.mutex.Unlock()
+
+	log.Infof("refreshed mgmt cache domain=%s type=%s",
+		d.SafeString(), dns.TypeToString[question.Qtype])
+	return nil
+}
+
+func (m *Resolver) markRefreshing(question dns.Question) {
+	m.mutex.Lock()
+	m.refreshing[question] = &atomic.Bool{}
+	m.mutex.Unlock()
+}
+
+func (m *Resolver) clearRefreshing(question dns.Question) {
+	m.mutex.Lock()
+	delete(m.refreshing, question)
+	m.mutex.Unlock()
+}
+
+// markRefreshFailed arms the backoff and returns the new consecutive-failure
+// count so callers can downgrade subsequent failure logs to debug.
+func (m *Resolver) markRefreshFailed(question dns.Question, expected *cachedRecord) int {
+	m.mutex.Lock()
+	defer m.mutex.Unlock()
+	c, ok := m.records[question]
+	if !ok || c != expected {
+		return 0
+	}
+	c.lastFailedRefresh = time.Now()
+	c.consecFailures++
+	return c.consecFailures
+}
+
+// lookupBoth resolves A and AAAA via bypass resolver, chain, or OS.
+// Per-family errors let callers tell records, NODATA (nil err, no records),
+// and failure apart.
+//
+// Preference order:
+//  1. bypassResolver (direct, overlay-bypassing dial to original system
+//     nameservers; immune to the exit-node ENOKEY race).
+//  2. chain (handler chain; used when NetBird is the system resolver and
+//     no bypass resolver is installed).
+//  3. net.DefaultResolver via osLookup (legacy fallback).
+func (m *Resolver) lookupBoth(ctx context.Context, d domain.Domain, dnsName string) (aRecords, aaaaRecords []dns.RR, errA, errAAAA error) {
+	m.mutex.RLock()
+	chain := m.chain
+	maxPriority := m.chainMaxPriority
+	bypass := m.bypassResolver
+	m.mutex.RUnlock()
+
+	if bypass != nil {
+		aRecords, errA = m.osLookup(ctx, d, dnsName, dns.TypeA)
+		aaaaRecords, errAAAA = m.osLookup(ctx, d, dnsName, dns.TypeAAAA)
+		return
+	}
+
+	if chain != nil && chain.HasRootHandlerAtOrBelow(maxPriority) {
+		aRecords, errA = m.lookupViaChain(ctx, chain, maxPriority, dnsName, dns.TypeA)
+		aaaaRecords, errAAAA = m.lookupViaChain(ctx, chain, maxPriority, dnsName, dns.TypeAAAA)
+		return
+	}
+
+	// TODO: drop once every supported OS registers a fallback resolver. Safe
+	// today: no root handler at priority ≤ PriorityUpstream means NetBird is
+	// not the system resolver, so net.DefaultResolver will not loop back.
+	aRecords, errA = m.osLookup(ctx, d, dnsName, dns.TypeA)
+	aaaaRecords, errAAAA = m.osLookup(ctx, d, dnsName, dns.TypeAAAA)
+	return
+}
+
+// lookupRecords resolves a single record type. See lookupBoth for the
+// preference order. The OS branch arms the loop detector for the duration
+// of its call so that ServeDNS can spot the OS resolver routing the
+// recursive query back to us; the bypass branch skips the loop detector
+// because its dial does not enter the system resolver.
+func (m *Resolver) lookupRecords(ctx context.Context, d domain.Domain, q dns.Question) ([]dns.RR, error) {
+	m.mutex.RLock()
+	chain := m.chain
+	maxPriority := m.chainMaxPriority
+	bypass := m.bypassResolver
+	m.mutex.RUnlock()
+
+	if bypass != nil {
+		return m.osLookup(ctx, d, q.Name, q.Qtype)
+	}
+
+	if chain != nil && chain.HasRootHandlerAtOrBelow(maxPriority) {
+		return m.lookupViaChain(ctx, chain, maxPriority, q.Name, q.Qtype)
+	}
+
+	// TODO: drop once every supported OS registers a fallback resolver.
+	m.markRefreshing(q)
+	defer m.clearRefreshing(q)
+
+	return m.osLookup(ctx, d, q.Name, q.Qtype)
+}
+
+// lookupViaChain resolves via the handler chain and rewrites each RR to use
+// dnsName as owner and m.cacheTTL as TTL, so CNAME-backed domains don't cache
+// target-owned records or upstream TTLs. NODATA returns (nil, nil).
+func (m *Resolver) lookupViaChain(ctx context.Context, chain ChainResolver, maxPriority int, dnsName string, qtype uint16) ([]dns.RR, error) {
+	msg := &dns.Msg{}
+	msg.SetQuestion(dnsName, qtype)
+	msg.RecursionDesired = true
+
+	resp, err := chain.ResolveInternal(ctx, msg, maxPriority)
+	if err != nil {
+		return nil, fmt.Errorf("chain resolve: %w", err)
+	}
+	if resp == nil {
+		return nil, fmt.Errorf("chain resolve returned nil response")
+	}
+	if resp.Rcode != dns.RcodeSuccess {
+		return nil, fmt.Errorf("chain resolve rcode=%s", dns.RcodeToString[resp.Rcode])
+	}
+
+	ttl := uint32(m.cacheTTL.Seconds())
+	owners := cnameOwners(dnsName, resp.Answer)
+	var filtered []dns.RR
+	for _, rr := range resp.Answer {
+		h := rr.Header()
+		if h.Class != dns.ClassINET || h.Rrtype != qtype {
+			continue
+		}
+		if !owners[strings.ToLower(dns.Fqdn(h.Name))] {
+			continue
+		}
+		if cp := cloneIPRecord(rr, dnsName, ttl); cp != nil {
+			filtered = append(filtered, cp)
+		}
+	}
+	return filtered, nil
+}
+
+// osLookup resolves a single family via the bypass resolver (if configured)
+// or net.DefaultResolver using resutil, which disambiguates NODATA from
+// NXDOMAIN and Unmaps v4-mapped-v6. NODATA returns (nil, nil).
+func (m *Resolver) osLookup(ctx context.Context, d domain.Domain, dnsName string, qtype uint16) ([]dns.RR, error) {
+	network := resutil.NetworkForQtype(qtype)
+	if network == "" {
+		return nil, fmt.Errorf("unsupported qtype %s", dns.TypeToString[qtype])
+	}
+
+	log.Infof("looking up IP for mgmt domain=%s type=%s", d.SafeString(), dns.TypeToString[qtype])
+	defer log.Infof("done looking up IP for mgmt domain=%s type=%s", d.SafeString(), dns.TypeToString[qtype])
+
+	m.mutex.RLock()
+	resolver := m.bypassResolver
+	m.mutex.RUnlock()
+	if resolver == nil {
+		resolver = net.DefaultResolver
+	}
+
+	result := resutil.LookupIP(ctx, resolver, network, d.PunycodeString(), qtype)
+	if result.Rcode == dns.RcodeSuccess {
+		return resutil.IPsToRRs(dnsName, result.IPs, uint32(m.cacheTTL.Seconds())), nil
+	}
+
+	if result.Err != nil {
+		return nil, fmt.Errorf("resolve %s type=%s: %w", d.SafeString(), dns.TypeToString[qtype], result.Err)
+	}
+	return nil, fmt.Errorf("resolve %s type=%s: rcode=%s", d.SafeString(), dns.TypeToString[qtype], dns.RcodeToString[result.Rcode])
+}
+
+// responseTTL returns the remaining cache lifetime in seconds (rounded up),
+// so downstream resolvers don't cache an answer for longer than we will.
+func (m *Resolver) responseTTL(cachedAt time.Time) uint32 {
+	remaining := m.cacheTTL - time.Since(cachedAt)
+	if remaining <= 0 {
+		return 0
+	}
+	return uint32((remaining + time.Second - 1) / time.Second)
 }
 
 // PopulateFromConfig extracts and caches domains from the client configuration.
@@ -224,24 +623,35 @@ func (m *Resolver) RemoveDomain(d domain.Domain) error {
 	m.mutex.Lock()
 	defer m.mutex.Unlock()
 
-	aQuestion := dns.Question{
-		Name:   dnsName,
-		Qtype:  dns.TypeA,
-		Qclass: dns.ClassINET,
-	}
-	delete(m.records, aQuestion)
-
-	aaaaQuestion := dns.Question{
-		Name:   dnsName,
-		Qtype:  dns.TypeAAAA,
-		Qclass: dns.ClassINET,
-	}
-	delete(m.records, aaaaQuestion)
+	qA := dns.Question{Name: dnsName, Qtype: dns.TypeA, Qclass: dns.ClassINET}
+	qAAAA := dns.Question{Name: dnsName, Qtype: dns.TypeAAAA, Qclass: dns.ClassINET}
+	delete(m.records, qA)
+	delete(m.records, qAAAA)
+	delete(m.refreshing, qA)
+	delete(m.refreshing, qAAAA)
 
 	log.Debugf("removed domain=%s from cache", d.SafeString())
 	return nil
 }
 
+// GetPoolRootDomains returns the set of domains that should be registered
+// with subdomain matching (currently the Relay entries from ServerDomains).
+// Instance subdomains under these roots are resolved on demand in ServeDNS.
+func (m *Resolver) GetPoolRootDomains() domain.List {
+	m.mutex.RLock()
+	defer m.mutex.RUnlock()
+	if m.serverDomains == nil {
+		return nil
+	}
+	out := make(domain.List, 0, len(m.serverDomains.Relay))
+	for _, d := range m.serverDomains.Relay {
+		if d != "" {
+			out = append(out, d)
+		}
+	}
+	return out
+}
+
 // GetCachedDomains returns a list of all cached domains.
 func (m *Resolver) GetCachedDomains() domain.List {
 	m.mutex.RLock()
@@ -394,3 +804,73 @@ func (m *Resolver) extractDomainsFromServerDomains(serverDomains dnsconfig.Serve
 
 	return domains
 }
+
+// cloneIPRecord returns a deep copy of rr retargeted to owner with ttl. Non
+// A/AAAA records return nil.
+func cloneIPRecord(rr dns.RR, owner string, ttl uint32) dns.RR {
+	switch r := rr.(type) {
+	case *dns.A:
+		cp := *r
+		cp.Hdr.Name = owner
+		cp.Hdr.Ttl = ttl
+		cp.A = slices.Clone(r.A)
+		return &cp
+	case *dns.AAAA:
+		cp := *r
+		cp.Hdr.Name = owner
+		cp.Hdr.Ttl = ttl
+		cp.AAAA = slices.Clone(r.AAAA)
+		return &cp
+	}
+	return nil
+}
+
+// cloneRecordsWithTTL clones A/AAAA records preserving their owner and
+// stamping ttl so the response shares no memory with the cached slice.
+func cloneRecordsWithTTL(records []dns.RR, ttl uint32) []dns.RR {
+	out := make([]dns.RR, 0, len(records))
+	for _, rr := range records {
+		if cp := cloneIPRecord(rr, rr.Header().Name, ttl); cp != nil {
+			out = append(out, cp)
+		}
+	}
+	return out
+}
+
+// cnameOwners returns dnsName plus every target reachable by following CNAMEs
+// in answer, iterating until fixed point so out-of-order chains resolve.
+func cnameOwners(dnsName string, answer []dns.RR) map[string]bool {
+	owners := map[string]bool{dnsName: true}
+	for {
+		added := false
+		for _, rr := range answer {
+			cname, ok := rr.(*dns.CNAME)
+			if !ok {
+				continue
+			}
+			name := strings.ToLower(dns.Fqdn(cname.Hdr.Name))
+			if !owners[name] {
+				continue
+			}
+			target := strings.ToLower(dns.Fqdn(cname.Target))
+			if !owners[target] {
+				owners[target] = true
+				added = true
+			}
+		}
+		if !added {
+			return owners
+		}
+	}
+}
+
+// resolveCacheTTL reads the cache TTL override env var; invalid or empty
+// values fall back to defaultTTL. Called once per Resolver from NewResolver.
+func resolveCacheTTL() time.Duration {
+	if v := os.Getenv(envMgmtCacheTTL); v != "" {
+		if d, err := time.ParseDuration(v); err == nil && d > 0 {
+			return d
+		}
+	}
+	return defaultTTL
+}

client/internal/dns/mgmt/mgmt_refresh_test.go

@@ -0,0 +1,408 @@
+package mgmt
+
+import (
+	"context"
+	"errors"
+	"net"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/miekg/dns"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/netbirdio/netbird/client/internal/dns/test"
+	"github.com/netbirdio/netbird/shared/management/domain"
+)
+
+type fakeChain struct {
+	mu       sync.Mutex
+	calls    map[string]int
+	answers  map[string][]dns.RR
+	err      error
+	hasRoot  bool
+	onLookup func()
+}
+
+func newFakeChain() *fakeChain {
+	return &fakeChain{
+		calls:   map[string]int{},
+		answers: map[string][]dns.RR{},
+		hasRoot: true,
+	}
+}
+
+func (f *fakeChain) HasRootHandlerAtOrBelow(maxPriority int) bool {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	return f.hasRoot
+}
+
+func (f *fakeChain) ResolveInternal(ctx context.Context, msg *dns.Msg, maxPriority int) (*dns.Msg, error) {
+	f.mu.Lock()
+	q := msg.Question[0]
+	key := q.Name + "|" + dns.TypeToString[q.Qtype]
+	f.calls[key]++
+	answers := f.answers[key]
+	err := f.err
+	onLookup := f.onLookup
+	f.mu.Unlock()
+
+	if onLookup != nil {
+		onLookup()
+	}
+	if err != nil {
+		return nil, err
+	}
+	resp := &dns.Msg{}
+	resp.SetReply(msg)
+	resp.Answer = answers
+	return resp, nil
+}
+
+func (f *fakeChain) setAnswer(name string, qtype uint16, ip string) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	key := name + "|" + dns.TypeToString[qtype]
+	hdr := dns.RR_Header{Name: name, Rrtype: qtype, Class: dns.ClassINET, Ttl: 60}
+	switch qtype {
+	case dns.TypeA:
+		f.answers[key] = []dns.RR{&dns.A{Hdr: hdr, A: net.ParseIP(ip).To4()}}
+	case dns.TypeAAAA:
+		f.answers[key] = []dns.RR{&dns.AAAA{Hdr: hdr, AAAA: net.ParseIP(ip).To16()}}
+	}
+}
+
+func (f *fakeChain) callCount(name string, qtype uint16) int {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	return f.calls[name+"|"+dns.TypeToString[qtype]]
+}
+
+// waitFor polls the predicate until it returns true or the deadline passes.
+func waitFor(t *testing.T, d time.Duration, fn func() bool) {
+	t.Helper()
+	deadline := time.Now().Add(d)
+	for time.Now().Before(deadline) {
+		if fn() {
+			return
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+	t.Fatalf("condition not met within %s", d)
+}
+
+func queryA(t *testing.T, r *Resolver, name string) *dns.Msg {
+	t.Helper()
+	msg := new(dns.Msg)
+	msg.SetQuestion(name, dns.TypeA)
+	w := &test.MockResponseWriter{}
+	r.ServeDNS(w, msg)
+	return w.GetLastResponse()
+}
+
+func firstA(t *testing.T, resp *dns.Msg) string {
+	t.Helper()
+	require.NotNil(t, resp)
+	require.Greater(t, len(resp.Answer), 0, "expected at least one answer")
+	a, ok := resp.Answer[0].(*dns.A)
+	require.True(t, ok, "expected A record")
+	return a.A.String()
+}
+
+func TestResolver_CacheTTLGatesRefresh(t *testing.T) {
+	// Same cached entry age, different cacheTTL values: the shorter TTL must
+	// trigger a background refresh, the longer one must not. Proves that the
+	// per-Resolver cacheTTL field actually drives the stale decision.
+	cachedAt := time.Now().Add(-100 * time.Millisecond)
+
+	newRec := func() *cachedRecord {
+		return &cachedRecord{
+			records: []dns.RR{&dns.A{
+				Hdr: dns.RR_Header{Name: "mgmt.example.com.", Rrtype: dns.TypeA, Class: dns.ClassINET, Ttl: 60},
+				A:   net.ParseIP("10.0.0.1").To4(),
+			}},
+			cachedAt: cachedAt,
+		}
+	}
+	q := dns.Question{Name: "mgmt.example.com.", Qtype: dns.TypeA, Qclass: dns.ClassINET}
+
+	t.Run("short TTL treats entry as stale and refreshes", func(t *testing.T) {
+		r := NewResolver()
+		r.cacheTTL = 10 * time.Millisecond
+		chain := newFakeChain()
+		chain.setAnswer(q.Name, dns.TypeA, "10.0.0.2")
+		r.SetChainResolver(chain, 50)
+		r.records[q] = newRec()
+
+		resp := queryA(t, r, q.Name)
+		assert.Equal(t, "10.0.0.1", firstA(t, resp), "stale entry must be served while refresh runs")
+
+		waitFor(t, time.Second, func() bool {
+			return chain.callCount(q.Name, dns.TypeA) >= 1
+		})
+	})
+
+	t.Run("long TTL keeps entry fresh and skips refresh", func(t *testing.T) {
+		r := NewResolver()
+		r.cacheTTL = time.Hour
+		chain := newFakeChain()
+		chain.setAnswer(q.Name, dns.TypeA, "10.0.0.2")
+		r.SetChainResolver(chain, 50)
+		r.records[q] = newRec()
+
+		resp := queryA(t, r, q.Name)
+		assert.Equal(t, "10.0.0.1", firstA(t, resp))
+
+		time.Sleep(50 * time.Millisecond)
+		assert.Equal(t, 0, chain.callCount(q.Name, dns.TypeA), "fresh entry must not trigger refresh")
+	})
+}
+
+func TestResolver_ServeFresh_NoRefresh(t *testing.T) {
+	r := NewResolver()
+	chain := newFakeChain()
+	chain.setAnswer("mgmt.example.com.", dns.TypeA, "10.0.0.2")
+	r.SetChainResolver(chain, 50)
+
+	r.records[dns.Question{Name: "mgmt.example.com.", Qtype: dns.TypeA, Qclass: dns.ClassINET}] = &cachedRecord{
+		records: []dns.RR{&dns.A{
+			Hdr: dns.RR_Header{Name: "mgmt.example.com.", Rrtype: dns.TypeA, Class: dns.ClassINET, Ttl: 60},
+			A:   net.ParseIP("10.0.0.1").To4(),
+		}},
+		cachedAt: time.Now(), // fresh
+	}
+
+	resp := queryA(t, r, "mgmt.example.com.")
+	assert.Equal(t, "10.0.0.1", firstA(t, resp))
+
+	time.Sleep(20 * time.Millisecond)
+	assert.Equal(t, 0, chain.callCount("mgmt.example.com.", dns.TypeA), "fresh entry must not trigger refresh")
+}
+
+func TestResolver_StaleTriggersAsyncRefresh(t *testing.T) {
+	r := NewResolver()
+	chain := newFakeChain()
+	chain.setAnswer("mgmt.example.com.", dns.TypeA, "10.0.0.2")
+	r.SetChainResolver(chain, 50)
+
+	q := dns.Question{Name: "mgmt.example.com.", Qtype: dns.TypeA, Qclass: dns.ClassINET}
+	r.records[q] = &cachedRecord{
+		records: []dns.RR{&dns.A{
+			Hdr: dns.RR_Header{Name: q.Name, Rrtype: dns.TypeA, Class: dns.ClassINET, Ttl: 60},
+			A:   net.ParseIP("10.0.0.1").To4(),
+		}},
+		cachedAt: time.Now().Add(-2 * defaultTTL), // stale
+	}
+
+	// First query: serves stale immediately.
+	resp := queryA(t, r, "mgmt.example.com.")
+	assert.Equal(t, "10.0.0.1", firstA(t, resp), "stale entry must be served while refresh runs")
+
+	waitFor(t, time.Second, func() bool {
+		return chain.callCount("mgmt.example.com.", dns.TypeA) >= 1
+	})
+
+	// Next query should now return the refreshed IP.
+	waitFor(t, time.Second, func() bool {
+		resp := queryA(t, r, "mgmt.example.com.")
+		return resp != nil && len(resp.Answer) > 0 && firstA(t, resp) == "10.0.0.2"
+	})
+}
+
+func TestResolver_ConcurrentStaleHitsCollapseRefresh(t *testing.T) {
+	r := NewResolver()
+	chain := newFakeChain()
+	chain.setAnswer("mgmt.example.com.", dns.TypeA, "10.0.0.2")
+
+	var inflight atomic.Int32
+	var maxInflight atomic.Int32
+	chain.onLookup = func() {
+		cur := inflight.Add(1)
+		defer inflight.Add(-1)
+		for {
+			prev := maxInflight.Load()
+			if cur <= prev || maxInflight.CompareAndSwap(prev, cur) {
+				break
+			}
+		}
+		time.Sleep(50 * time.Millisecond) // hold inflight long enough to collide
+	}
+
+	r.SetChainResolver(chain, 50)
+
+	q := dns.Question{Name: "mgmt.example.com.", Qtype: dns.TypeA, Qclass: dns.ClassINET}
+	r.records[q] = &cachedRecord{
+		records: []dns.RR{&dns.A{
+			Hdr: dns.RR_Header{Name: q.Name, Rrtype: dns.TypeA, Class: dns.ClassINET, Ttl: 60},
+			A:   net.ParseIP("10.0.0.1").To4(),
+		}},
+		cachedAt: time.Now().Add(-2 * defaultTTL),
+	}
+
+	var wg sync.WaitGroup
+	for i := 0; i < 50; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			queryA(t, r, "mgmt.example.com.")
+		}()
+	}
+	wg.Wait()
+
+	waitFor(t, 2*time.Second, func() bool {
+		return inflight.Load() == 0
+	})
+
+	calls := chain.callCount("mgmt.example.com.", dns.TypeA)
+	assert.LessOrEqual(t, calls, 2, "singleflight must collapse concurrent refreshes (got %d)", calls)
+	assert.Equal(t, int32(1), maxInflight.Load(), "only one refresh should run concurrently")
+}
+
+func TestResolver_RefreshFailureArmsBackoff(t *testing.T) {
+	r := NewResolver()
+	chain := newFakeChain()
+	chain.err = errors.New("boom")
+	r.SetChainResolver(chain, 50)
+
+	q := dns.Question{Name: "mgmt.example.com.", Qtype: dns.TypeA, Qclass: dns.ClassINET}
+	r.records[q] = &cachedRecord{
+		records: []dns.RR{&dns.A{
+			Hdr: dns.RR_Header{Name: q.Name, Rrtype: dns.TypeA, Class: dns.ClassINET, Ttl: 60},
+			A:   net.ParseIP("10.0.0.1").To4(),
+		}},
+		cachedAt: time.Now().Add(-2 * defaultTTL),
+	}
+
+	// First stale hit triggers a refresh attempt that fails.
+	resp := queryA(t, r, "mgmt.example.com.")
+	assert.Equal(t, "10.0.0.1", firstA(t, resp), "stale entry served while refresh fails")
+
+	waitFor(t, time.Second, func() bool {
+		return chain.callCount("mgmt.example.com.", dns.TypeA) == 1
+	})
+	waitFor(t, time.Second, func() bool {
+		r.mutex.RLock()
+		defer r.mutex.RUnlock()
+		c, ok := r.records[q]
+		return ok && !c.lastFailedRefresh.IsZero()
+	})
+
+	// Subsequent stale hits within backoff window should not schedule more refreshes.
+	for i := 0; i < 10; i++ {
+		queryA(t, r, "mgmt.example.com.")
+	}
+	time.Sleep(50 * time.Millisecond)
+	assert.Equal(t, 1, chain.callCount("mgmt.example.com.", dns.TypeA), "backoff must suppress further refreshes")
+}
+
+func TestResolver_NoRootHandler_SkipsChain(t *testing.T) {
+	r := NewResolver()
+	chain := newFakeChain()
+	chain.hasRoot = false
+	chain.setAnswer("mgmt.example.com.", dns.TypeA, "10.0.0.2")
+	r.SetChainResolver(chain, 50)
+
+	// With hasRoot=false the chain must not be consulted. Use a short
+	// deadline so the OS fallback returns quickly without waiting on a
+	// real network call in CI.
+	ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond)
+	defer cancel()
+	_, _, _, _ = r.lookupBoth(ctx, domain.Domain("mgmt.example.com"), "mgmt.example.com.")
+
+	assert.Equal(t, 0, chain.callCount("mgmt.example.com.", dns.TypeA),
+		"chain must not be used when no root handler is registered at the bound priority")
+}
+
+func TestResolver_ServeDuringRefreshSetsLoopFlag(t *testing.T) {
+	// ServeDNS being invoked for a question while a refresh for that question
+	// is inflight indicates a resolver loop (OS resolver sent the recursive
+	// query back to us). The inflightRefresh.loopLoggedOnce flag must be set.
+	r := NewResolver()
+
+	q := dns.Question{Name: "mgmt.example.com.", Qtype: dns.TypeA, Qclass: dns.ClassINET}
+	r.records[q] = &cachedRecord{
+		records: []dns.RR{&dns.A{
+			Hdr: dns.RR_Header{Name: q.Name, Rrtype: dns.TypeA, Class: dns.ClassINET, Ttl: 60},
+			A:   net.ParseIP("10.0.0.1").To4(),
+		}},
+		cachedAt: time.Now(),
+	}
+
+	// Simulate an inflight refresh.
+	r.markRefreshing(q)
+	defer r.clearRefreshing(q)
+
+	resp := queryA(t, r, "mgmt.example.com.")
+	assert.Equal(t, "10.0.0.1", firstA(t, resp), "stale entry must still be served to avoid breaking external queries")
+
+	r.mutex.RLock()
+	inflight := r.refreshing[q]
+	r.mutex.RUnlock()
+	require.NotNil(t, inflight)
+	assert.True(t, inflight.Load(), "loop flag must be set once a ServeDNS during refresh was observed")
+}
+
+func TestResolver_LoopFlagOnlyTrippedOncePerRefresh(t *testing.T) {
+	r := NewResolver()
+
+	q := dns.Question{Name: "mgmt.example.com.", Qtype: dns.TypeA, Qclass: dns.ClassINET}
+	r.records[q] = &cachedRecord{
+		records: []dns.RR{&dns.A{
+			Hdr: dns.RR_Header{Name: q.Name, Rrtype: dns.TypeA, Class: dns.ClassINET, Ttl: 60},
+			A:   net.ParseIP("10.0.0.1").To4(),
+		}},
+		cachedAt: time.Now(),
+	}
+
+	r.markRefreshing(q)
+	defer r.clearRefreshing(q)
+
+	// Multiple ServeDNS calls during the same refresh must not re-set the flag
+	// (CompareAndSwap from false -> true returns true only on the first call).
+	for range 5 {
+		queryA(t, r, "mgmt.example.com.")
+	}
+
+	r.mutex.RLock()
+	inflight := r.refreshing[q]
+	r.mutex.RUnlock()
+	assert.True(t, inflight.Load())
+}
+
+func TestResolver_NoLoopFlagWhenNotRefreshing(t *testing.T) {
+	r := NewResolver()
+
+	q := dns.Question{Name: "mgmt.example.com.", Qtype: dns.TypeA, Qclass: dns.ClassINET}
+	r.records[q] = &cachedRecord{
+		records: []dns.RR{&dns.A{
+			Hdr: dns.RR_Header{Name: q.Name, Rrtype: dns.TypeA, Class: dns.ClassINET, Ttl: 60},
+			A:   net.ParseIP("10.0.0.1").To4(),
+		}},
+		cachedAt: time.Now(),
+	}
+
+	queryA(t, r, "mgmt.example.com.")
+
+	r.mutex.RLock()
+	_, ok := r.refreshing[q]
+	r.mutex.RUnlock()
+	assert.False(t, ok, "no refresh inflight means no loop tracking")
+}
+
+func TestResolver_AddDomain_UsesChainWhenRootRegistered(t *testing.T) {
+	r := NewResolver()
+	chain := newFakeChain()
+	chain.setAnswer("mgmt.example.com.", dns.TypeA, "10.0.0.2")
+	chain.setAnswer("mgmt.example.com.", dns.TypeAAAA, "fd00::2")
+	r.SetChainResolver(chain, 50)
+
+	require.NoError(t, r.AddDomain(context.Background(), domain.Domain("mgmt.example.com")))
+
+	resp := queryA(t, r, "mgmt.example.com.")
+	assert.Equal(t, "10.0.0.2", firstA(t, resp))
+	assert.Equal(t, 1, chain.callCount("mgmt.example.com.", dns.TypeA))
+	assert.Equal(t, 1, chain.callCount("mgmt.example.com.", dns.TypeAAAA))
+}

client/internal/dns/mgmt/mgmt_test.go

@@ -6,6 +6,7 @@ import (
 	"net/url"
 	"strings"
 	"testing"
+	"time"
 
 	"github.com/miekg/dns"
 	"github.com/stretchr/testify/assert"
@@ -23,6 +24,60 @@ func TestResolver_NewResolver(t *testing.T) {
 	assert.False(t, resolver.MatchSubdomains())
 }
 
+func TestResolveCacheTTL(t *testing.T) {
+	tests := []struct {
+		name  string
+		value string
+		want  time.Duration
+	}{
+		{"unset falls back to default", "", defaultTTL},
+		{"valid duration", "45s", 45 * time.Second},
+		{"valid minutes", "2m", 2 * time.Minute},
+		{"malformed falls back to default", "not-a-duration", defaultTTL},
+		{"zero falls back to default", "0s", defaultTTL},
+		{"negative falls back to default", "-5s", defaultTTL},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Setenv(envMgmtCacheTTL, tc.value)
+			got := resolveCacheTTL()
+			assert.Equal(t, tc.want, got, "parsed TTL should match")
+		})
+	}
+}
+
+func TestNewResolver_CacheTTLFromEnv(t *testing.T) {
+	t.Setenv(envMgmtCacheTTL, "7s")
+	r := NewResolver()
+	assert.Equal(t, 7*time.Second, r.cacheTTL, "NewResolver should evaluate cacheTTL once from env")
+}
+
+func TestResolver_ResponseTTL(t *testing.T) {
+	now := time.Now()
+	tests := []struct {
+		name     string
+		cacheTTL time.Duration
+		cachedAt time.Time
+		wantMin  uint32
+		wantMax  uint32
+	}{
+		{"fresh entry returns full TTL", 60 * time.Second, now, 59, 60},
+		{"half-aged entry returns half TTL", 60 * time.Second, now.Add(-30 * time.Second), 29, 31},
+		{"expired entry returns zero", 60 * time.Second, now.Add(-61 * time.Second), 0, 0},
+		{"exactly expired returns zero", 10 * time.Second, now.Add(-10 * time.Second), 0, 0},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			r := &Resolver{cacheTTL: tc.cacheTTL}
+			got := r.responseTTL(tc.cachedAt)
+			assert.GreaterOrEqual(t, got, tc.wantMin, "remaining TTL should be >= wantMin")
+			assert.LessOrEqual(t, got, tc.wantMax, "remaining TTL should be <= wantMax")
+		})
+	}
+}
+
 func TestResolver_ExtractDomainFromURL(t *testing.T) {
 	tests := []struct {
 		name        string

client/internal/dns/server.go

@@ -31,6 +31,28 @@ import (
 
 const envSkipDNSProbe = "NB_SKIP_DNS_PROBE"
 
+// subdomainMatchHandler is a thin wrapper used to register a handler under
+// a pool-root domain (e.g. a relay URL advertised by the mgmt) with
+// subdomain matching enabled. The underlying handler's own MatchSubdomains
+// is left untouched so that exact-match registrations keep their
+// semantics.
+type subdomainMatchHandler struct {
+	dns.Handler
+}
+
+// MatchSubdomains lets the handler chain route any instance subdomain
+// (e.g. streamline-de-fra1-0.relay.netbird.io) to the wrapped handler.
+func (subdomainMatchHandler) MatchSubdomains() bool { return true }
+
+// String returns a debug-friendly name; the chain uses fmt.Stringer for
+// its "registering handler X" logs.
+func (h subdomainMatchHandler) String() string {
+	if s, ok := h.Handler.(fmt.Stringer); ok {
+		return s.String() + "[subdomains]"
+	}
+	return "subdomainMatchHandler"
+}
+
 // ReadyListener is a notification mechanism what indicate the server is ready to handle host dns address changes
 type ReadyListener interface {
 	OnReady()
@@ -95,6 +117,11 @@ type DefaultServer struct {
 	batchMode          bool
 
 	mgmtCacheResolver *mgmt.Resolver
+	// mgmtPoolRoots tracks pool-root domains currently contributed to
+	// extraDomains by the mgmt cache, so the next UpdateServerConfig can
+	// decrement the old set before incrementing the new one without
+	// disturbing unrelated registerHandler callers.
+	mgmtPoolRoots map[domain.Domain]struct{}
 
 	// permanent related properties
 	permanent      bool
@@ -212,6 +239,7 @@ func newDefaultServer(
 	ctx, stop := context.WithCancel(ctx)
 
 	mgmtCacheResolver := mgmt.NewResolver()
+	mgmtCacheResolver.SetChainResolver(handlerChain, PriorityUpstream)
 
 	defaultServer := &DefaultServer{
 		ctx:               ctx,
@@ -228,6 +256,7 @@ func newDefaultServer(
 		hostsDNSHolder:    newHostsDNSHolder(),
 		hostManager:       &noopHostConfigurator{},
 		mgmtCacheResolver: mgmtCacheResolver,
+		mgmtPoolRoots:     make(map[domain.Domain]struct{}),
 		currentConfigHash: ^uint64(0), // Initialize to max uint64 to ensure first config is always applied
 	}
 
@@ -586,25 +615,92 @@ func (s *DefaultServer) UpdateServerConfig(domains dnsconfig.ServerDomains) erro
 	s.mux.Lock()
 	defer s.mux.Unlock()
 
-	if s.mgmtCacheResolver != nil {
-		removedDomains, err := s.mgmtCacheResolver.UpdateFromServerDomains(s.ctx, domains)
-		if err != nil {
-			return fmt.Errorf("update management cache resolver: %w", err)
-		}
-
-		if len(removedDomains) > 0 {
-			s.deregisterHandler(removedDomains.ToPunycodeList(), PriorityMgmtCache)
-		}
-
-		newDomains := s.mgmtCacheResolver.GetCachedDomains()
-		if len(newDomains) > 0 {
-			s.registerHandler(newDomains.ToPunycodeList(), s.mgmtCacheResolver, PriorityMgmtCache)
-		}
+	if s.mgmtCacheResolver == nil {
+		return nil
 	}
 
+	removedDomains, err := s.mgmtCacheResolver.UpdateFromServerDomains(s.ctx, domains)
+	if err != nil {
+		return fmt.Errorf("update management cache resolver: %w", err)
+	}
+
+	if len(removedDomains) > 0 {
+		s.deregisterHandler(removedDomains.ToPunycodeList(), PriorityMgmtCache)
+	}
+
+	poolRoots := s.mgmtCacheResolver.GetPoolRootDomains()
+	s.registerMgmtCacheHandlers(poolRoots)
+	s.reconcileMgmtPoolRoots(poolRoots)
+
+	if !s.batchMode {
+		s.applyHostConfig()
+	}
 	return nil
 }
 
+// registerMgmtCacheHandlers wires the mgmt cache resolver into the handler
+// chain for the current set of cached domains. Pool-root domains (advertised
+// by the mgmt as Relay URLs) go through a thin subdomain-matching wrapper so
+// a query like "streamline-de-fra1-0.relay.netbird.io" routes to the mgmt
+// cache resolver, which resolves it on demand through the bypass resolver
+// instead of falling through to the overlay-routed upstream handler.
+//
+// Canonicalize with toZone on both sides of the pool-root membership check so
+// the comparison is independent of each source's canonical form:
+// GetPoolRootDomains returns what the extractor stored; GetCachedDomains
+// strips the trailing dot from question names.
+func (s *DefaultServer) registerMgmtCacheHandlers(poolRoots domain.List) {
+	poolRootSet := make(map[domain.Domain]struct{}, len(poolRoots))
+	for _, d := range poolRoots {
+		poolRootSet[toZone(d)] = struct{}{}
+	}
+
+	if len(poolRoots) > 0 {
+		s.registerHandler(poolRoots.ToPunycodeList(), subdomainMatchHandler{Handler: s.mgmtCacheResolver}, PriorityMgmtCache)
+	}
+
+	var exactDomains domain.List
+	for _, d := range s.mgmtCacheResolver.GetCachedDomains() {
+		if _, isPool := poolRootSet[toZone(d)]; isPool {
+			continue
+		}
+		exactDomains = append(exactDomains, d)
+	}
+	if len(exactDomains) > 0 {
+		s.registerHandler(exactDomains.ToPunycodeList(), s.mgmtCacheResolver, PriorityMgmtCache)
+	}
+}
+
+// reconcileMgmtPoolRoots keeps extraDomains in sync with the current mgmt
+// pool-root set. These entries show up as *match* domains for the host DNS
+// manager (systemd-resolved, NetworkManager, etc.) so instance subdomain
+// queries like streamline-* are delegated to the wt0 link where the daemon's
+// DNS listener sits. Without this, systemd-resolved answers them from the
+// host's global upstream, skipping our handler chain entirely.
+//
+// Uses s.mgmtPoolRoots as a dedicated tracking map so increments/decrements
+// here don't collide with RegisterHandler's refcounting.
+func (s *DefaultServer) reconcileMgmtPoolRoots(poolRoots domain.List) {
+	newPoolRoots := make(map[domain.Domain]struct{}, len(poolRoots))
+	for _, d := range poolRoots {
+		zone := toZone(d)
+		newPoolRoots[zone] = struct{}{}
+		if _, already := s.mgmtPoolRoots[zone]; !already {
+			s.extraDomains[zone]++
+		}
+	}
+	for zone := range s.mgmtPoolRoots {
+		if _, keep := newPoolRoots[zone]; keep {
+			continue
+		}
+		s.extraDomains[zone]--
+		if s.extraDomains[zone] <= 0 {
+			delete(s.extraDomains, zone)
+		}
+	}
+	s.mgmtPoolRoots = newPoolRoots
+}
+
 func (s *DefaultServer) applyConfiguration(update nbdns.Config) error {
 	// is the service should be Disabled, we stop the listener or fake resolver
 	if update.ServiceEnable {
@@ -758,6 +854,9 @@ func (s *DefaultServer) registerFallback(config HostDNSConfig) {
 	originalNameservers := hostMgrWithNS.getOriginalNameservers()
 	if len(originalNameservers) == 0 {
 		s.deregisterHandler([]string{nbdns.RootZone}, PriorityFallback)
+		if s.mgmtCacheResolver != nil {
+			s.mgmtCacheResolver.SetBypassResolver(nil)
+		}
 		return
 	}
 
@@ -776,6 +875,7 @@ func (s *DefaultServer) registerFallback(config HostDNSConfig) {
 	}
 	handler.routeMatch = s.routeMatch
 
+	var bypassNameservers []netip.Addr
 	for _, ns := range originalNameservers {
 		if ns == config.ServerIP {
 			log.Debugf("skipping original nameserver %s as it is the same as the server IP %s", ns, config.ServerIP)
@@ -784,11 +884,22 @@ func (s *DefaultServer) registerFallback(config HostDNSConfig) {
 
 		addrPort := netip.AddrPortFrom(ns, DefaultPort)
 		handler.upstreamServers = append(handler.upstreamServers, addrPort)
+		bypassNameservers = append(bypassNameservers, ns)
 	}
 	handler.deactivate = func(error) { /* always active */ }
 	handler.reactivate = func() { /* always active */ }
 
 	s.registerHandler([]string{nbdns.RootZone}, handler, PriorityFallback)
+
+	// Wire a bypass resolver into the mgmt cache so its refresh path dials
+	// the original nameservers directly over a fwmarked socket, avoiding
+	// the ENOKEY deadlock that occurs when an exit-node default route is
+	// installed on the overlay before its peer has handshaked. Scoped to
+	// the mgmt cache only: ordinary user DNS still flows through the
+	// normal upstream path.
+	if s.mgmtCacheResolver != nil {
+		s.mgmtCacheResolver.SetBypassResolver(mgmt.NewBypassResolver(bypassNameservers))
+	}
 }
 
 func (s *DefaultServer) buildLocalHandlerUpdate(customZones []nbdns.CustomZone) ([]handlerWrapper, []nbdns.CustomZone, error) {

client/internal/engine.go

@@ -26,6 +26,7 @@ import (
 
 	nberrors "github.com/netbirdio/netbird/client/errors"
 	"github.com/netbirdio/netbird/client/firewall"
+	"github.com/netbirdio/netbird/client/firewall/firewalld"
 	firewallManager "github.com/netbirdio/netbird/client/firewall/manager"
 	"github.com/netbirdio/netbird/client/iface"
 	"github.com/netbirdio/netbird/client/iface/device"
@@ -140,6 +141,7 @@ type EngineConfig struct {
 	ProfileConfig *profilemanager.Config
 
 	LogPath string
+	TempDir string
 }
 
 // EngineServices holds the external service dependencies required by the Engine.
@@ -569,7 +571,7 @@ func (e *Engine) Start(netbirdConfig *mgmProto.NetbirdConfig, mgmtURL *url.URL)
 	e.connMgr.Start(e.ctx)
 
 	e.srWatcher = guard.NewSRWatcher(e.signal, e.relayManager, e.mobileDep.IFaceDiscover, iceCfg)
-	e.srWatcher.Start()
+	e.srWatcher.Start(peer.IsForceRelayed())
 
 	e.receiveSignalEvents()
 	e.receiveManagementEvents()
@@ -603,6 +605,8 @@ func (e *Engine) createFirewall() error {
 		return nil
 	}
 
+	firewalld.SetParentContext(e.ctx)
+
 	var err error
 	e.firewall, err = firewall.NewFirewall(e.wgInterface, e.stateManager, e.flowManager.GetLogger(), e.config.DisableServerRoutes, e.config.MTU)
 	if err != nil {
@@ -1095,6 +1099,7 @@ func (e *Engine) handleBundle(params *mgmProto.BundleParameters) (*mgmProto.JobR
 		StatusRecorder: e.statusRecorder,
 		SyncResponse:   syncResponse,
 		LogPath:        e.config.LogPath,
+		TempDir:        e.config.TempDir,
 		ClientMetrics:  e.clientMetrics,
 		RefreshStatus: func() {
 			e.RunHealthProbes(true)

client/internal/engine_test.go

@@ -55,6 +55,7 @@ import (
 	nbdns "github.com/netbirdio/netbird/dns"
 	"github.com/netbirdio/netbird/management/server"
 	"github.com/netbirdio/netbird/management/server/activity"
+	nbcache "github.com/netbirdio/netbird/management/server/cache"
 	"github.com/netbirdio/netbird/management/server/integrations/port_forwarding"
 	"github.com/netbirdio/netbird/management/server/permissions"
 	"github.com/netbirdio/netbird/management/server/settings"
@@ -1634,7 +1635,12 @@ func startManagement(t *testing.T, dataDir, testFile string) (*grpc.Server, stri
 	peersManager := peers.NewManager(store, permissionsManager)
 	jobManager := job.NewJobManager(nil, store, peersManager)
 
-	ia, _ := integrations.NewIntegratedValidator(context.Background(), peersManager, nil, eventStore)
+	cacheStore, err := nbcache.NewStore(context.Background(), 100*time.Millisecond, 300*time.Millisecond, 100)
+	if err != nil {
+		return nil, "", err
+	}
+
+	ia, _ := integrations.NewIntegratedValidator(context.Background(), peersManager, nil, eventStore, cacheStore)
 
 	metrics, err := telemetry.NewDefaultAppMetrics(context.Background())
 	require.NoError(t, err)
@@ -1656,7 +1662,7 @@ func startManagement(t *testing.T, dataDir, testFile string) (*grpc.Server, stri
 	updateManager := update_channel.NewPeersUpdateManager(metrics)
 	requestBuffer := server.NewAccountRequestBuffer(context.Background(), store)
 	networkMapController := controller.NewController(context.Background(), store, metrics, updateManager, requestBuffer, server.MockIntegratedValidator{}, settingsMockManager, "netbird.selfhosted", port_forwarding.NewControllerMock(), manager.NewEphemeralManager(store, peersManager), config)
-	accountManager, err := server.BuildManager(context.Background(), config, store, networkMapController, jobManager, nil, "", eventStore, nil, false, ia, metrics, port_forwarding.NewControllerMock(), settingsMockManager, permissionsManager, false)
+	accountManager, err := server.BuildManager(context.Background(), config, store, networkMapController, jobManager, nil, "", eventStore, nil, false, ia, metrics, port_forwarding.NewControllerMock(), settingsMockManager, permissionsManager, false, cacheStore)
 	if err != nil {
 		return nil, "", err
 	}

client/internal/mobile_dependency.go

@@ -22,4 +22,8 @@ type MobileDependency struct {
 	DnsManager     dns.IosDnsManager
 	FileDescriptor int32
 	StateFilePath  string
+
+	// TempDir is a writable directory for temporary files (e.g., debug bundle zip).
+	// On Android, this should be set to the app's cache directory.
+	TempDir string
 }

client/internal/netflow/conntrack/conntrack.go

@@ -7,7 +7,9 @@ import (
 	"fmt"
 	"net/netip"
 	"sync"
+	"time"
 
+	"github.com/cenkalti/backoff/v4"
 	"github.com/google/uuid"
 	log "github.com/sirupsen/logrus"
 	nfct "github.com/ti-mo/conntrack"
@@ -17,31 +19,64 @@ import (
 	nbnet "github.com/netbirdio/netbird/client/net"
 )
 
-const defaultChannelSize = 100
+const (
+	defaultChannelSize     = 100
+	reconnectInitInterval  = 5 * time.Second
+	reconnectMaxInterval   = 5 * time.Minute
+	reconnectRandomization = 0.5
+)
+
+// listener abstracts a netlink conntrack connection for testability.
+type listener interface {
+	Listen(evChan chan<- nfct.Event, numWorkers uint8, groups []netfilter.NetlinkGroup) (chan error, error)
+	Close() error
+}
 
 // ConnTrack manages kernel-based conntrack events
 type ConnTrack struct {
 	flowLogger nftypes.FlowLogger
 	iface      nftypes.IFaceMapper
 
-	conn *nfct.Conn
+	conn listener
 	mux  sync.Mutex
 
+	dial           func() (listener, error)
 	instanceID     uuid.UUID
 	started        bool
 	done           chan struct{}
 	sysctlModified bool
 }
 
+// DialFunc is a constructor for netlink conntrack connections.
+type DialFunc func() (listener, error)
+
+// Option configures a ConnTrack instance.
+type Option func(*ConnTrack)
+
+// WithDialer overrides the default netlink dialer, primarily for testing.
+func WithDialer(dial DialFunc) Option {
+	return func(c *ConnTrack) {
+		c.dial = dial
+	}
+}
+
+func defaultDial() (listener, error) {
+	return nfct.Dial(nil)
+}
+
 // New creates a new connection tracker that interfaces with the kernel's conntrack system
-func New(flowLogger nftypes.FlowLogger, iface nftypes.IFaceMapper) *ConnTrack {
-	return &ConnTrack{
+func New(flowLogger nftypes.FlowLogger, iface nftypes.IFaceMapper, opts ...Option) *ConnTrack {
+	ct := &ConnTrack{
 		flowLogger: flowLogger,
 		iface:      iface,
 		instanceID: uuid.New(),
-		started:    false,
+		dial:       defaultDial,
 		done:       make(chan struct{}, 1),
 	}
+	for _, opt := range opts {
+		opt(ct)
+	}
+	return ct
 }
 
 // Start begins tracking connections by listening for conntrack events. This method is idempotent.
@@ -59,8 +94,9 @@ func (c *ConnTrack) Start(enableCounters bool) error {
 		c.EnableAccounting()
 	}
 
-	conn, err := nfct.Dial(nil)
+	conn, err := c.dial()
 	if err != nil {
+		c.RestoreAccounting()
 		return fmt.Errorf("dial conntrack: %w", err)
 	}
 	c.conn = conn
@@ -76,9 +112,16 @@ func (c *ConnTrack) Start(enableCounters bool) error {
 			log.Errorf("Error closing conntrack connection: %v", err)
 		}
 		c.conn = nil
+		c.RestoreAccounting()
 		return fmt.Errorf("start conntrack listener: %w", err)
 	}
 
+	// Drain any stale stop signal from a previous cycle.
+	select {
+	case <-c.done:
+	default:
+	}
+
 	c.started = true
 
 	go c.receiverRoutine(events, errChan)
@@ -92,17 +135,98 @@ func (c *ConnTrack) receiverRoutine(events chan nfct.Event, errChan chan error)
 		case event := <-events:
 			c.handleEvent(event)
 		case err := <-errChan:
-			log.Errorf("Error from conntrack event listener: %v", err)
-			if err := c.conn.Close(); err != nil {
-				log.Errorf("Error closing conntrack connection: %v", err)
+			if events, errChan = c.handleListenerError(err); events == nil {
+				return
 			}
-			return
 		case <-c.done:
 			return
 		}
 	}
 }
 
+// handleListenerError closes the failed connection and attempts to reconnect.
+// Returns new channels on success, or nil if shutdown was requested.
+func (c *ConnTrack) handleListenerError(err error) (chan nfct.Event, chan error) {
+	log.Warnf("conntrack event listener failed: %v", err)
+	c.closeConn()
+	return c.reconnect()
+}
+
+func (c *ConnTrack) closeConn() {
+	c.mux.Lock()
+	defer c.mux.Unlock()
+
+	if c.conn != nil {
+		if err := c.conn.Close(); err != nil {
+			log.Debugf("close conntrack connection: %v", err)
+		}
+		c.conn = nil
+	}
+}
+
+// reconnect attempts to re-establish the conntrack netlink listener with exponential backoff.
+// Returns new channels on success, or nil if shutdown was requested.
+func (c *ConnTrack) reconnect() (chan nfct.Event, chan error) {
+	bo := &backoff.ExponentialBackOff{
+		InitialInterval:     reconnectInitInterval,
+		RandomizationFactor: reconnectRandomization,
+		Multiplier:          backoff.DefaultMultiplier,
+		MaxInterval:         reconnectMaxInterval,
+		MaxElapsedTime:      0, // retry indefinitely
+		Clock:               backoff.SystemClock,
+	}
+	bo.Reset()
+
+	for {
+		delay := bo.NextBackOff()
+		log.Infof("reconnecting conntrack listener in %s", delay)
+
+		select {
+		case <-c.done:
+			c.mux.Lock()
+			c.started = false
+			c.mux.Unlock()
+			return nil, nil
+		case <-time.After(delay):
+		}
+
+		conn, err := c.dial()
+		if err != nil {
+			log.Warnf("reconnect conntrack dial: %v", err)
+			continue
+		}
+
+		events := make(chan nfct.Event, defaultChannelSize)
+		errChan, err := conn.Listen(events, 1, []netfilter.NetlinkGroup{
+			netfilter.GroupCTNew,
+			netfilter.GroupCTDestroy,
+		})
+		if err != nil {
+			log.Warnf("reconnect conntrack listen: %v", err)
+			if closeErr := conn.Close(); closeErr != nil {
+				log.Debugf("close conntrack connection: %v", closeErr)
+			}
+			continue
+		}
+
+		c.mux.Lock()
+		if !c.started {
+			// Stop() ran while we were reconnecting.
+			c.mux.Unlock()
+			if closeErr := conn.Close(); closeErr != nil {
+				log.Debugf("close conntrack connection: %v", closeErr)
+			}
+			return nil, nil
+		}
+		c.conn = conn
+		c.mux.Unlock()
+
+		log.Infof("conntrack listener reconnected successfully")
+
+		return events, errChan
+	}
+}
+
 // Stop stops the connection tracking. This method is idempotent.
 func (c *ConnTrack) Stop() {
 	c.mux.Lock()
@@ -136,23 +260,27 @@ func (c *ConnTrack) Close() error {
 	c.mux.Lock()
 	defer c.mux.Unlock()
 
-	if c.started {
-		select {
-		case c.done <- struct{}{}:
-		default:
-		}
+	if !c.started {
+		return nil
 	}
 
+	select {
+	case c.done <- struct{}{}:
+	default:
+	}
+
+	c.started = false
+
+	var closeErr error
 	if c.conn != nil {
-		err := c.conn.Close()
+		closeErr = c.conn.Close()
 		c.conn = nil
-		c.started = false
+	}
 
-		c.RestoreAccounting()
+	c.RestoreAccounting()
 
-		if err != nil {
-			return fmt.Errorf("close conntrack: %w", err)
-		}
+	if closeErr != nil {
+		return fmt.Errorf("close conntrack: %w", closeErr)
 	}
 
 	return nil

client/internal/netflow/conntrack/conntrack_test.go

@@ -0,0 +1,224 @@
+//go:build linux && !android
+
+package conntrack
+
+import (
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	nfct "github.com/ti-mo/conntrack"
+	"github.com/ti-mo/netfilter"
+)
+
+type mockListener struct {
+	errChan  chan error
+	closed   atomic.Bool
+	closedCh chan struct{}
+}
+
+func newMockListener() *mockListener {
+	return &mockListener{
+		errChan:  make(chan error, 1),
+		closedCh: make(chan struct{}),
+	}
+}
+
+func (m *mockListener) Listen(evChan chan<- nfct.Event, _ uint8, _ []netfilter.NetlinkGroup) (chan error, error) {
+	return m.errChan, nil
+}
+
+func (m *mockListener) Close() error {
+	if m.closed.CompareAndSwap(false, true) {
+		close(m.closedCh)
+	}
+	return nil
+}
+
+func TestReconnectAfterError(t *testing.T) {
+	first := newMockListener()
+	second := newMockListener()
+	third := newMockListener()
+	listeners := []*mockListener{first, second, third}
+	callCount := atomic.Int32{}
+
+	ct := New(nil, nil, WithDialer(func() (listener, error) {
+		n := int(callCount.Add(1)) - 1
+		return listeners[n], nil
+	}))
+
+	err := ct.Start(false)
+	require.NoError(t, err)
+
+	// Inject an error on the first listener.
+	first.errChan <- assert.AnError
+
+	// Wait for reconnect to complete.
+	require.Eventually(t, func() bool {
+		return callCount.Load() >= 2
+	}, 15*time.Second, 100*time.Millisecond, "reconnect should dial a new connection")
+
+	// The first connection must have been closed.
+	select {
+	case <-first.closedCh:
+	case <-time.After(2 * time.Second):
+		t.Fatal("first connection was not closed")
+	}
+
+	// Verify the receiver is still running by injecting and handling a second error.
+	second.errChan <- assert.AnError
+
+	require.Eventually(t, func() bool {
+		return callCount.Load() >= 3
+	}, 15*time.Second, 100*time.Millisecond, "second reconnect should succeed")
+
+	ct.Stop()
+}
+
+func TestStopDuringReconnectBackoff(t *testing.T) {
+	mock := newMockListener()
+
+	ct := New(nil, nil, WithDialer(func() (listener, error) {
+		return mock, nil
+	}))
+
+	err := ct.Start(false)
+	require.NoError(t, err)
+
+	// Trigger an error so the receiver enters reconnect.
+	mock.errChan <- assert.AnError
+
+	// Wait for the error handler to close the old listener before calling Stop.
+	select {
+	case <-mock.closedCh:
+	case <-time.After(5 * time.Second):
+		t.Fatal("timed out waiting for reconnect to start")
+	}
+
+	// Stop while reconnecting.
+	ct.Stop()
+
+	ct.mux.Lock()
+	assert.False(t, ct.started, "started should be false after Stop")
+	assert.Nil(t, ct.conn, "conn should be nil after Stop")
+	ct.mux.Unlock()
+}
+
+func TestStopRaceWithReconnectDial(t *testing.T) {
+	first := newMockListener()
+	dialStarted := make(chan struct{})
+	dialProceed := make(chan struct{})
+	second := newMockListener()
+	callCount := atomic.Int32{}
+
+	ct := New(nil, nil, WithDialer(func() (listener, error) {
+		n := callCount.Add(1)
+		if n == 1 {
+			return first, nil
+		}
+		// Second dial: signal that we're in progress, wait for test to call Stop.
+		close(dialStarted)
+		<-dialProceed
+		return second, nil
+	}))
+
+	err := ct.Start(false)
+	require.NoError(t, err)
+
+	// Trigger error to enter reconnect.
+	first.errChan <- assert.AnError
+
+	// Wait for reconnect's second dial to begin.
+	select {
+	case <-dialStarted:
+	case <-time.After(15 * time.Second):
+		t.Fatal("timed out waiting for reconnect dial")
+	}
+
+	// Stop while dial is in progress (conn is nil at this point).
+	ct.Stop()
+
+	// Let the dial complete. reconnect should detect started==false and close the new conn.
+	close(dialProceed)
+
+	// The second connection should be closed (not leaked).
+	select {
+	case <-second.closedCh:
+	case <-time.After(2 * time.Second):
+		t.Fatal("second connection was leaked after Stop")
+	}
+
+	ct.mux.Lock()
+	assert.False(t, ct.started)
+	assert.Nil(t, ct.conn)
+	ct.mux.Unlock()
+}
+
+func TestCloseRaceWithReconnectDial(t *testing.T) {
+	first := newMockListener()
+	dialStarted := make(chan struct{})
+	dialProceed := make(chan struct{})
+	second := newMockListener()
+	callCount := atomic.Int32{}
+
+	ct := New(nil, nil, WithDialer(func() (listener, error) {
+		n := callCount.Add(1)
+		if n == 1 {
+			return first, nil
+		}
+		close(dialStarted)
+		<-dialProceed
+		return second, nil
+	}))
+
+	err := ct.Start(false)
+	require.NoError(t, err)
+
+	first.errChan <- assert.AnError
+
+	select {
+	case <-dialStarted:
+	case <-time.After(15 * time.Second):
+		t.Fatal("timed out waiting for reconnect dial")
+	}
+
+	// Close while dial is in progress (conn is nil).
+	require.NoError(t, ct.Close())
+
+	close(dialProceed)
+
+	// The second connection should be closed (not leaked).
+	select {
+	case <-second.closedCh:
+	case <-time.After(2 * time.Second):
+		t.Fatal("second connection was leaked after Close")
+	}
+
+	ct.mux.Lock()
+	assert.False(t, ct.started)
+	assert.Nil(t, ct.conn)
+	ct.mux.Unlock()
+}
+
+func TestStartIsIdempotent(t *testing.T) {
+	mock := newMockListener()
+	callCount := atomic.Int32{}
+
+	ct := New(nil, nil, WithDialer(func() (listener, error) {
+		callCount.Add(1)
+		return mock, nil
+	}))
+
+	err := ct.Start(false)
+	require.NoError(t, err)
+
+	// Second Start should be a no-op.
+	err = ct.Start(false)
+	require.NoError(t, err)
+
+	assert.Equal(t, int32(1), callCount.Load(), "dial should only be called once")
+
+	ct.Stop()
+}

client/internal/peer/conn.go

@@ -185,17 +185,20 @@ func (conn *Conn) Open(engineCtx context.Context) error {
 
 	conn.workerRelay = NewWorkerRelay(conn.ctx, conn.Log, isController(conn.config), conn.config, conn, conn.relayManager)
 
-	relayIsSupportedLocally := conn.workerRelay.RelayIsSupportedLocally()
-	workerICE, err := NewWorkerICE(conn.ctx, conn.Log, conn.config, conn, conn.signaler, conn.iFaceDiscover, conn.statusRecorder, relayIsSupportedLocally)
-	if err != nil {
-		return err
+	forceRelay := IsForceRelayed()
+	if !forceRelay {
+		relayIsSupportedLocally := conn.workerRelay.RelayIsSupportedLocally()
+		workerICE, err := NewWorkerICE(conn.ctx, conn.Log, conn.config, conn, conn.signaler, conn.iFaceDiscover, conn.statusRecorder, relayIsSupportedLocally)
+		if err != nil {
+			return err
+		}
+		conn.workerICE = workerICE
 	}
-	conn.workerICE = workerICE
 
 	conn.handshaker = NewHandshaker(conn.Log, conn.config, conn.signaler, conn.workerICE, conn.workerRelay, conn.metricsStages)
 
 	conn.handshaker.AddRelayListener(conn.workerRelay.OnNewOffer)
-	if !isForceRelayed() {
+	if !forceRelay {
 		conn.handshaker.AddICEListener(conn.workerICE.OnNewOffer)
 	}
 
@@ -251,7 +254,9 @@ func (conn *Conn) Close(signalToRemote bool) {
 		conn.wgWatcherCancel()
 	}
 	conn.workerRelay.CloseConn()
-	conn.workerICE.Close()
+	if conn.workerICE != nil {
+		conn.workerICE.Close()
+	}
 
 	if conn.wgProxyRelay != nil {
 		err := conn.wgProxyRelay.CloseConn()
@@ -294,7 +299,9 @@ func (conn *Conn) OnRemoteAnswer(answer OfferAnswer) {
 // OnRemoteCandidate Handles ICE connection Candidate provided by the remote peer.
 func (conn *Conn) OnRemoteCandidate(candidate ice.Candidate, haRoutes route.HAMap) {
 	conn.dumpState.RemoteCandidate()
-	conn.workerICE.OnRemoteCandidate(candidate, haRoutes)
+	if conn.workerICE != nil {
+		conn.workerICE.OnRemoteCandidate(candidate, haRoutes)
+	}
 }
 
 // SetOnConnected sets a handler function to be triggered by Conn when a new connection to a remote peer established
@@ -712,33 +719,35 @@ func (conn *Conn) evalStatus() ConnStatus {
 	return StatusConnecting
 }
 
-func (conn *Conn) isConnectedOnAllWay() (connected bool) {
-	// would be better to protect this with a mutex, but it could cause deadlock with Close function
-
+// isConnectedOnAllWay evaluates the overall connection status based on ICE and Relay transports.
+//
+// The result is a tri-state:
+//   - ConnStatusConnected:          all available transports are up
+//   - ConnStatusPartiallyConnected: relay is up but ICE is still pending/reconnecting
+//   - ConnStatusDisconnected:       no working transport
+func (conn *Conn) isConnectedOnAllWay() (status guard.ConnStatus) {
 	defer func() {
-		if !connected {
+		if status == guard.ConnStatusDisconnected {
 			conn.logTraceConnState()
 		}
 	}()
 
-	// For JS platform: only relay connection is supported
-	if runtime.GOOS == "js" {
-		return conn.statusRelay.Get() == worker.StatusConnected
+	iceWorkerCreated := conn.workerICE != nil
+
+	var iceInProgress bool
+	if iceWorkerCreated {
+		iceInProgress = conn.workerICE.InProgress()
 	}
 
-	// For non-JS platforms: check ICE connection status
-	if conn.statusICE.Get() == worker.StatusDisconnected && !conn.workerICE.InProgress() {
-		return false
-	}
-
-	// If relay is supported with peer, it must also be connected
-	if conn.workerRelay.IsRelayConnectionSupportedWithPeer() {
-		if conn.statusRelay.Get() == worker.StatusDisconnected {
-			return false
-		}
-	}
-
-	return true
+	return evalConnStatus(connStatusInputs{
+		forceRelay:          IsForceRelayed(),
+		peerUsesRelay:       conn.workerRelay.IsRelayConnectionSupportedWithPeer(),
+		relayConnected:      conn.statusRelay.Get() == worker.StatusConnected,
+		remoteSupportsICE:   conn.handshaker.RemoteICESupported(),
+		iceWorkerCreated:    iceWorkerCreated,
+		iceStatusConnecting: conn.statusICE.Get() != worker.StatusDisconnected,
+		iceInProgress:       iceInProgress,
+	})
 }
 
 func (conn *Conn) enableWgWatcherIfNeeded(enabledTime time.Time) {
@@ -926,3 +935,43 @@ func isController(config ConnConfig) bool {
 func isRosenpassEnabled(remoteRosenpassPubKey []byte) bool {
 	return remoteRosenpassPubKey != nil
 }
+
+func evalConnStatus(in connStatusInputs) guard.ConnStatus {
+	// "Relay up and needed" — the peer uses relay and the transport is connected.
+	relayUsedAndUp := in.peerUsesRelay && in.relayConnected
+
+	// Force-relay mode: ICE never runs. Relay is the only transport and must be up.
+	if in.forceRelay {
+		return boolToConnStatus(relayUsedAndUp)
+	}
+
+	// Remote peer doesn't support ICE, or we haven't created the worker yet:
+	// relay is the only possible transport.
+	if !in.remoteSupportsICE || !in.iceWorkerCreated {
+		return boolToConnStatus(relayUsedAndUp)
+	}
+
+	// ICE counts as "up" when the status is anything other than Disconnected, OR
+	// when a negotiation is currently in progress (so we don't spam offers while one is in flight).
+	iceUp := in.iceStatusConnecting || in.iceInProgress
+
+	// Relay side is acceptable if the peer doesn't rely on relay, or relay is connected.
+	relayOK := !in.peerUsesRelay || in.relayConnected
+
+	switch {
+	case iceUp && relayOK:
+		return guard.ConnStatusConnected
+	case relayUsedAndUp:
+		// Relay is up but ICE is down — partially connected.
+		return guard.ConnStatusPartiallyConnected
+	default:
+		return guard.ConnStatusDisconnected
+	}
+}
+
+func boolToConnStatus(connected bool) guard.ConnStatus {
+	if connected {
+		return guard.ConnStatusConnected
+	}
+	return guard.ConnStatusDisconnected
+}

client/internal/peer/conn_status.go

@@ -13,6 +13,20 @@ const (
 	StatusConnected
 )
 
+// connStatusInputs is the primitive-valued snapshot of the state that drives the
+// tri-state connection classification. Extracted so the decision logic can be unit-tested
+// without constructing full Worker/Handshaker objects.
+type connStatusInputs struct {
+	forceRelay          bool // NB_FORCE_RELAY or JS/WASM
+	peerUsesRelay       bool // remote peer advertises relay support AND local has relay
+	relayConnected      bool // statusRelay reports Connected (independent of whether peer uses relay)
+	remoteSupportsICE   bool // remote peer sent ICE credentials
+	iceWorkerCreated    bool // local WorkerICE exists (false in force-relay mode)
+	iceStatusConnecting bool // statusICE is anything other than Disconnected
+	iceInProgress       bool // a negotiation is currently in flight
+}
+
+
 // ConnStatus describe the status of a peer's connection
 type ConnStatus int32
 

client/internal/peer/conn_status_eval_test.go

@@ -0,0 +1,201 @@
+package peer
+
+import (
+	"testing"
+
+	"github.com/netbirdio/netbird/client/internal/peer/guard"
+)
+
+func TestEvalConnStatus_ForceRelay(t *testing.T) {
+	tests := []struct {
+		name string
+		in   connStatusInputs
+		want guard.ConnStatus
+	}{
+		{
+			name: "force relay, peer uses relay, relay up",
+			in: connStatusInputs{
+				forceRelay:     true,
+				peerUsesRelay:  true,
+				relayConnected: true,
+			},
+			want: guard.ConnStatusConnected,
+		},
+		{
+			name: "force relay, peer uses relay, relay down",
+			in: connStatusInputs{
+				forceRelay:     true,
+				peerUsesRelay:  true,
+				relayConnected: false,
+			},
+			want: guard.ConnStatusDisconnected,
+		},
+		{
+			name: "force relay, peer does NOT use relay - disconnected forever",
+			in: connStatusInputs{
+				forceRelay:     true,
+				peerUsesRelay:  false,
+				relayConnected: true,
+			},
+			want: guard.ConnStatusDisconnected,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := evalConnStatus(tc.in); got != tc.want {
+				t.Fatalf("evalConnStatus = %v, want %v", got, tc.want)
+			}
+		})
+	}
+}
+
+func TestEvalConnStatus_ICEUnavailable(t *testing.T) {
+	tests := []struct {
+		name string
+		in   connStatusInputs
+		want guard.ConnStatus
+	}{
+		{
+			name: "remote does not support ICE, peer uses relay, relay up",
+			in: connStatusInputs{
+				peerUsesRelay:     true,
+				relayConnected:    true,
+				remoteSupportsICE: false,
+				iceWorkerCreated:  true,
+			},
+			want: guard.ConnStatusConnected,
+		},
+		{
+			name: "remote does not support ICE, peer uses relay, relay down",
+			in: connStatusInputs{
+				peerUsesRelay:     true,
+				relayConnected:    false,
+				remoteSupportsICE: false,
+				iceWorkerCreated:  true,
+			},
+			want: guard.ConnStatusDisconnected,
+		},
+		{
+			name: "ICE worker not yet created, relay up",
+			in: connStatusInputs{
+				peerUsesRelay:     true,
+				relayConnected:    true,
+				remoteSupportsICE: true,
+				iceWorkerCreated:  false,
+			},
+			want: guard.ConnStatusConnected,
+		},
+		{
+			name: "remote does not support ICE, peer does not use relay",
+			in: connStatusInputs{
+				peerUsesRelay:     false,
+				relayConnected:    false,
+				remoteSupportsICE: false,
+				iceWorkerCreated:  true,
+			},
+			want: guard.ConnStatusDisconnected,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := evalConnStatus(tc.in); got != tc.want {
+				t.Fatalf("evalConnStatus = %v, want %v", got, tc.want)
+			}
+		})
+	}
+}
+
+func TestEvalConnStatus_FullyAvailable(t *testing.T) {
+	base := connStatusInputs{
+		remoteSupportsICE: true,
+		iceWorkerCreated:  true,
+	}
+
+	tests := []struct {
+		name    string
+		mutator func(*connStatusInputs)
+		want    guard.ConnStatus
+	}{
+		{
+			name: "ICE connected, relay connected, peer uses relay",
+			mutator: func(in *connStatusInputs) {
+				in.peerUsesRelay = true
+				in.relayConnected = true
+				in.iceStatusConnecting = true
+			},
+			want: guard.ConnStatusConnected,
+		},
+		{
+			name: "ICE connected, peer does NOT use relay",
+			mutator: func(in *connStatusInputs) {
+				in.peerUsesRelay = false
+				in.relayConnected = false
+				in.iceStatusConnecting = true
+			},
+			want: guard.ConnStatusConnected,
+		},
+		{
+			name: "ICE InProgress only, peer does NOT use relay",
+			mutator: func(in *connStatusInputs) {
+				in.peerUsesRelay = false
+				in.iceStatusConnecting = false
+				in.iceInProgress = true
+			},
+			want: guard.ConnStatusConnected,
+		},
+		{
+			name: "ICE down, relay up, peer uses relay -> partial",
+			mutator: func(in *connStatusInputs) {
+				in.peerUsesRelay = true
+				in.relayConnected = true
+				in.iceStatusConnecting = false
+				in.iceInProgress = false
+			},
+			want: guard.ConnStatusPartiallyConnected,
+		},
+		{
+			name: "ICE down, peer does NOT use relay -> disconnected",
+			mutator: func(in *connStatusInputs) {
+				in.peerUsesRelay = false
+				in.relayConnected = false
+				in.iceStatusConnecting = false
+				in.iceInProgress = false
+			},
+			want: guard.ConnStatusDisconnected,
+		},
+		{
+			name: "ICE up, peer uses relay but relay down -> partial (relay required, ICE ignored)",
+			mutator: func(in *connStatusInputs) {
+				in.peerUsesRelay = true
+				in.relayConnected = false
+				in.iceStatusConnecting = true
+			},
+			// relayOK = false (peer uses relay but it's down), iceUp = true
+			// first switch arm fails (relayOK false), relayUsedAndUp = false (relay down),
+			// falls into default: Disconnected.
+			want: guard.ConnStatusDisconnected,
+		},
+		{
+			name: "ICE down, relay up but peer does not use relay -> disconnected",
+			mutator: func(in *connStatusInputs) {
+				in.peerUsesRelay = false
+				in.relayConnected = true // not actually used since peer doesn't rely on it
+				in.iceStatusConnecting = false
+				in.iceInProgress = false
+			},
+			want: guard.ConnStatusDisconnected,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			in := base
+			tc.mutator(&in)
+			if got := evalConnStatus(in); got != tc.want {
+				t.Fatalf("evalConnStatus = %v, want %v (inputs: %+v)", got, tc.want, in)
+			}
+		})
+	}
+}

client/internal/peer/env.go

@@ -10,7 +10,7 @@ const (
 	EnvKeyNBForceRelay = "NB_FORCE_RELAY"
 )
 
-func isForceRelayed() bool {
+func IsForceRelayed() bool {
 	if runtime.GOOS == "js" {
 		return true
 	}

client/internal/peer/guard/guard.go

@@ -8,7 +8,19 @@ import (
 	log "github.com/sirupsen/logrus"
 )
 
-type isConnectedFunc func() bool
+// ConnStatus represents the connection state as seen by the guard.
+type ConnStatus int
+
+const (
+	// ConnStatusDisconnected means neither ICE nor Relay is connected.
+	ConnStatusDisconnected ConnStatus = iota
+	// ConnStatusPartiallyConnected means Relay is connected but ICE is not.
+	ConnStatusPartiallyConnected
+	// ConnStatusConnected means all required connections are established.
+	ConnStatusConnected
+)
+
+type connStatusFunc func() ConnStatus
 
 // Guard is responsible for the reconnection logic.
 // It will trigger to send an offer to the peer then has connection issues.
@@ -20,14 +32,14 @@ type isConnectedFunc func() bool
 // - ICE candidate changes
 type Guard struct {
 	log                     *log.Entry
-	isConnectedOnAllWay     isConnectedFunc
+	isConnectedOnAllWay     connStatusFunc
 	timeout                 time.Duration
 	srWatcher               *SRWatcher
 	relayedConnDisconnected chan struct{}
 	iCEConnDisconnected     chan struct{}
 }
 
-func NewGuard(log *log.Entry, isConnectedFn isConnectedFunc, timeout time.Duration, srWatcher *SRWatcher) *Guard {
+func NewGuard(log *log.Entry, isConnectedFn connStatusFunc, timeout time.Duration, srWatcher *SRWatcher) *Guard {
 	return &Guard{
 		log:                     log,
 		isConnectedOnAllWay:     isConnectedFn,
@@ -57,8 +69,17 @@ func (g *Guard) SetICEConnDisconnected() {
 	}
 }
 
-// reconnectLoopWithRetry periodically check the connection status.
-// Try to send offer while the P2P is not established or while the Relay is not connected if is it supported
+// reconnectLoopWithRetry periodically checks the connection status and sends offers to re-establish connectivity.
+//
+// Behavior depends on the connection state reported by isConnectedOnAllWay:
+//   - Connected: no action, the peer is fully reachable.
+//   - Disconnected (neither ICE nor Relay): retries aggressively with exponential backoff (800ms doubling
+//     up to timeout), never gives up. This ensures rapid recovery when the peer has no connectivity at all.
+//   - PartiallyConnected (Relay up, ICE not): retries up to 3 times with exponential backoff, then switches
+//     to one attempt per hour. This limits signaling traffic when relay already provides connectivity.
+//
+// External events (relay/ICE disconnect, signal/relay reconnect, candidate changes) reset the retry
+// counter and backoff ticker, giving ICE a fresh chance after network conditions change.
 func (g *Guard) reconnectLoopWithRetry(ctx context.Context, callback func()) {
 	srReconnectedChan := g.srWatcher.NewListener()
 	defer g.srWatcher.RemoveListener(srReconnectedChan)
@@ -68,36 +89,47 @@ func (g *Guard) reconnectLoopWithRetry(ctx context.Context, callback func()) {
 
 	tickerChannel := ticker.C
 
+	iceState := &iceRetryState{log: g.log}
+	defer iceState.reset()
+
 	for {
 		select {
-		case t := <-tickerChannel:
-			if t.IsZero() {
-				g.log.Infof("retry timed out, stop periodic offer sending")
-				// after backoff timeout the ticker.C will be closed. We need to a dummy channel to avoid loop
-				tickerChannel = make(<-chan time.Time)
-				continue
+		case <-tickerChannel:
+			switch g.isConnectedOnAllWay() {
+			case ConnStatusConnected:
+				// all good, nothing to do
+			case ConnStatusDisconnected:
+				callback()
+			case ConnStatusPartiallyConnected:
+				if iceState.shouldRetry() {
+					callback()
+				} else {
+					iceState.enterHourlyMode()
+					ticker.Stop()
+					tickerChannel = iceState.hourlyC()
+				}
 			}
 
-			if !g.isConnectedOnAllWay() {
-				callback()
-			}
 		case <-g.relayedConnDisconnected:
 			g.log.Debugf("Relay connection changed, reset reconnection ticker")
 			ticker.Stop()
-			ticker = g.prepareExponentTicker(ctx)
+			ticker = g.newReconnectTicker(ctx)
 			tickerChannel = ticker.C
+			iceState.reset()
 
 		case <-g.iCEConnDisconnected:
 			g.log.Debugf("ICE connection changed, reset reconnection ticker")
 			ticker.Stop()
-			ticker = g.prepareExponentTicker(ctx)
+			ticker = g.newReconnectTicker(ctx)
 			tickerChannel = ticker.C
+			iceState.reset()
 
 		case <-srReconnectedChan:
 			g.log.Debugf("has network changes, reset reconnection ticker")
 			ticker.Stop()
-			ticker = g.prepareExponentTicker(ctx)
+			ticker = g.newReconnectTicker(ctx)
 			tickerChannel = ticker.C
+			iceState.reset()
 
 		case <-ctx.Done():
 			g.log.Debugf("context is done, stop reconnect loop")
@@ -120,7 +152,7 @@ func (g *Guard) initialTicker(ctx context.Context) *backoff.Ticker {
 	return backoff.NewTicker(bo)
 }
 
-func (g *Guard) prepareExponentTicker(ctx context.Context) *backoff.Ticker {
+func (g *Guard) newReconnectTicker(ctx context.Context) *backoff.Ticker {
 	bo := backoff.WithContext(&backoff.ExponentialBackOff{
 		InitialInterval:     800 * time.Millisecond,
 		RandomizationFactor: 0.1,

client/internal/peer/guard/ice_retry_state.go

@@ -0,0 +1,61 @@
+package guard
+
+import (
+	"time"
+
+	log "github.com/sirupsen/logrus"
+)
+
+const (
+	// maxICERetries is the maximum number of ICE offer attempts when relay is connected
+	maxICERetries = 3
+	// iceRetryInterval is the periodic retry interval after ICE retries are exhausted
+	iceRetryInterval = 1 * time.Hour
+)
+
+// iceRetryState tracks the limited ICE retry attempts when relay is already connected.
+// After maxICERetries attempts it switches to a periodic hourly retry.
+type iceRetryState struct {
+	log     *log.Entry
+	retries int
+	hourly  *time.Ticker
+}
+
+func (s *iceRetryState) reset() {
+	s.retries = 0
+	if s.hourly != nil {
+		s.hourly.Stop()
+		s.hourly = nil
+	}
+}
+
+// shouldRetry reports whether the caller should send another ICE offer on this tick.
+// Returns false when the per-cycle retry budget is exhausted and the caller must switch
+// to the hourly ticker via enterHourlyMode + hourlyC.
+func (s *iceRetryState) shouldRetry() bool {
+	if s.hourly != nil {
+		s.log.Debugf("hourly ICE retry attempt")
+		return true
+	}
+
+	s.retries++
+	if s.retries <= maxICERetries {
+		s.log.Debugf("ICE retry attempt %d/%d", s.retries, maxICERetries)
+		return true
+	}
+
+	return false
+}
+
+// enterHourlyMode starts the hourly retry ticker. Must be called after shouldRetry returns false.
+func (s *iceRetryState) enterHourlyMode() {
+	s.log.Infof("ICE retries exhausted (%d/%d), switching to hourly retry", maxICERetries, maxICERetries)
+	s.hourly = time.NewTicker(iceRetryInterval)
+}
+
+func (s *iceRetryState) hourlyC() <-chan time.Time {
+	if s.hourly == nil {
+		return nil
+	}
+	return s.hourly.C
+}

client/internal/peer/guard/ice_retry_state_test.go

@@ -0,0 +1,103 @@
+package guard
+
+import (
+	"testing"
+
+	log "github.com/sirupsen/logrus"
+)
+
+func newTestRetryState() *iceRetryState {
+	return &iceRetryState{log: log.NewEntry(log.StandardLogger())}
+}
+
+func TestICERetryState_AllowsInitialBudget(t *testing.T) {
+	s := newTestRetryState()
+
+	for i := 1; i <= maxICERetries; i++ {
+		if !s.shouldRetry() {
+			t.Fatalf("shouldRetry returned false on attempt %d, want true (budget = %d)", i, maxICERetries)
+		}
+	}
+}
+
+func TestICERetryState_ExhaustsAfterBudget(t *testing.T) {
+	s := newTestRetryState()
+
+	for i := 0; i < maxICERetries; i++ {
+		_ = s.shouldRetry()
+	}
+
+	if s.shouldRetry() {
+		t.Fatalf("shouldRetry returned true after budget exhausted, want false")
+	}
+}
+
+func TestICERetryState_HourlyCNilBeforeEnterHourlyMode(t *testing.T) {
+	s := newTestRetryState()
+
+	if s.hourlyC() != nil {
+		t.Fatalf("hourlyC returned non-nil channel before enterHourlyMode")
+	}
+}
+
+func TestICERetryState_EnterHourlyModeArmsTicker(t *testing.T) {
+	s := newTestRetryState()
+	for i := 0; i < maxICERetries+1; i++ {
+		_ = s.shouldRetry()
+	}
+
+	s.enterHourlyMode()
+	defer s.reset()
+
+	if s.hourlyC() == nil {
+		t.Fatalf("hourlyC returned nil after enterHourlyMode")
+	}
+}
+
+func TestICERetryState_ShouldRetryTrueInHourlyMode(t *testing.T) {
+	s := newTestRetryState()
+	s.enterHourlyMode()
+	defer s.reset()
+
+	if !s.shouldRetry() {
+		t.Fatalf("shouldRetry returned false in hourly mode, want true")
+	}
+
+	// Subsequent calls also return true — we keep retrying on each hourly tick.
+	if !s.shouldRetry() {
+		t.Fatalf("second shouldRetry returned false in hourly mode, want true")
+	}
+}
+
+func TestICERetryState_ResetRestoresBudget(t *testing.T) {
+	s := newTestRetryState()
+	for i := 0; i < maxICERetries+1; i++ {
+		_ = s.shouldRetry()
+	}
+	s.enterHourlyMode()
+
+	s.reset()
+
+	if s.hourlyC() != nil {
+		t.Fatalf("hourlyC returned non-nil channel after reset")
+	}
+	if s.retries != 0 {
+		t.Fatalf("retries = %d after reset, want 0", s.retries)
+	}
+
+	for i := 1; i <= maxICERetries; i++ {
+		if !s.shouldRetry() {
+			t.Fatalf("shouldRetry returned false on attempt %d after reset, want true", i)
+		}
+	}
+}
+
+func TestICERetryState_ResetIsIdempotent(t *testing.T) {
+	s := newTestRetryState()
+	s.reset()
+	s.reset() // second call must not panic or re-stop a nil ticker
+
+	if s.hourlyC() != nil {
+		t.Fatalf("hourlyC non-nil after double reset")
+	}
+}

client/internal/peer/guard/sr_watcher.go

@@ -39,7 +39,7 @@ func NewSRWatcher(signalClient chNotifier, relayManager chNotifier, iFaceDiscove
 	return srw
 }
 
-func (w *SRWatcher) Start() {
+func (w *SRWatcher) Start(disableICEMonitor bool) {
 	w.mu.Lock()
 	defer w.mu.Unlock()
 
@@ -50,8 +50,10 @@ func (w *SRWatcher) Start() {
 	ctx, cancel := context.WithCancel(context.Background())
 	w.cancelIceMonitor = cancel
 
-	iceMonitor := NewICEMonitor(w.iFaceDiscover, w.iceConfig, GetICEMonitorPeriod())
-	go iceMonitor.Start(ctx, w.onICEChanged)
+	if !disableICEMonitor {
+		iceMonitor := NewICEMonitor(w.iFaceDiscover, w.iceConfig, GetICEMonitorPeriod())
+		go iceMonitor.Start(ctx, w.onICEChanged)
+	}
 	w.signalClient.SetOnReconnectedListener(w.onReconnected)
 	w.relayManager.SetOnReconnectedListener(w.onReconnected)
 

client/internal/peer/handshaker.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"errors"
 	"sync"
+	"sync/atomic"
 
 	log "github.com/sirupsen/logrus"
 
@@ -43,6 +44,10 @@ type OfferAnswer struct {
 	SessionID *ICESessionID
 }
 
+func (o *OfferAnswer) hasICECredentials() bool {
+	return o.IceCredentials.UFrag != "" && o.IceCredentials.Pwd != ""
+}
+
 type Handshaker struct {
 	mu            sync.Mutex
 	log           *log.Entry
@@ -59,6 +64,10 @@ type Handshaker struct {
 	relayListener *AsyncOfferListener
 	iceListener   func(remoteOfferAnswer *OfferAnswer)
 
+	// remoteICESupported tracks whether the remote peer includes ICE credentials in its offers/answers.
+	// When false, the local side skips ICE listener dispatch and suppresses ICE credentials in responses.
+	remoteICESupported atomic.Bool
+
 	// remoteOffersCh is a channel used to wait for remote credentials to proceed with the connection
 	remoteOffersCh chan OfferAnswer
 	// remoteAnswerCh is a channel used to wait for remote credentials answer (confirmation of our offer) to proceed with the connection
@@ -66,7 +75,7 @@ type Handshaker struct {
 }
 
 func NewHandshaker(log *log.Entry, config ConnConfig, signaler *Signaler, ice *WorkerICE, relay *WorkerRelay, metricsStages *MetricsStages) *Handshaker {
-	return &Handshaker{
+	h := &Handshaker{
 		log:            log,
 		config:         config,
 		signaler:       signaler,
@@ -76,6 +85,13 @@ func NewHandshaker(log *log.Entry, config ConnConfig, signaler *Signaler, ice *W
 		remoteOffersCh: make(chan OfferAnswer),
 		remoteAnswerCh: make(chan OfferAnswer),
 	}
+	// assume remote supports ICE until we learn otherwise from received offers
+	h.remoteICESupported.Store(ice != nil)
+	return h
+}
+
+func (h *Handshaker) RemoteICESupported() bool {
+	return h.remoteICESupported.Load()
 }
 
 func (h *Handshaker) AddRelayListener(offer func(remoteOfferAnswer *OfferAnswer)) {
@@ -90,18 +106,20 @@ func (h *Handshaker) Listen(ctx context.Context) {
 	for {
 		select {
 		case remoteOfferAnswer := <-h.remoteOffersCh:
-			h.log.Infof("received offer, running version %s, remote WireGuard listen port %d, session id: %s", remoteOfferAnswer.Version, remoteOfferAnswer.WgListenPort, remoteOfferAnswer.SessionIDString())
+			h.log.Infof("received offer, running version %s, remote WireGuard listen port %d, session id: %s, remote ICE supported: %t", remoteOfferAnswer.Version, remoteOfferAnswer.WgListenPort, remoteOfferAnswer.SessionIDString(), remoteOfferAnswer.hasICECredentials())
 
 			// Record signaling received for reconnection attempts
 			if h.metricsStages != nil {
 				h.metricsStages.RecordSignalingReceived()
 			}
 
+			h.updateRemoteICEState(&remoteOfferAnswer)
+
 			if h.relayListener != nil {
 				h.relayListener.Notify(&remoteOfferAnswer)
 			}
 
-			if h.iceListener != nil {
+			if h.iceListener != nil && h.RemoteICESupported() {
 				h.iceListener(&remoteOfferAnswer)
 			}
 
@@ -110,18 +128,20 @@ func (h *Handshaker) Listen(ctx context.Context) {
 				continue
 			}
 		case remoteOfferAnswer := <-h.remoteAnswerCh:
-			h.log.Infof("received answer, running version %s, remote WireGuard listen port %d, session id: %s", remoteOfferAnswer.Version, remoteOfferAnswer.WgListenPort, remoteOfferAnswer.SessionIDString())
+			h.log.Infof("received answer, running version %s, remote WireGuard listen port %d, session id: %s, remote ICE supported: %t", remoteOfferAnswer.Version, remoteOfferAnswer.WgListenPort, remoteOfferAnswer.SessionIDString(), remoteOfferAnswer.hasICECredentials())
 
 			// Record signaling received for reconnection attempts
 			if h.metricsStages != nil {
 				h.metricsStages.RecordSignalingReceived()
 			}
 
+			h.updateRemoteICEState(&remoteOfferAnswer)
+
 			if h.relayListener != nil {
 				h.relayListener.Notify(&remoteOfferAnswer)
 			}
 
-			if h.iceListener != nil {
+			if h.iceListener != nil && h.RemoteICESupported() {
 				h.iceListener(&remoteOfferAnswer)
 			}
 		case <-ctx.Done():
@@ -183,15 +203,18 @@ func (h *Handshaker) sendAnswer() error {
 }
 
 func (h *Handshaker) buildOfferAnswer() OfferAnswer {
-	uFrag, pwd := h.ice.GetLocalUserCredentials()
-	sid := h.ice.SessionID()
 	answer := OfferAnswer{
-		IceCredentials:  IceCredentials{uFrag, pwd},
 		WgListenPort:    h.config.LocalWgPort,
 		Version:         version.NetbirdVersion(),
 		RosenpassPubKey: h.config.RosenpassConfig.PubKey,
 		RosenpassAddr:   h.config.RosenpassConfig.Addr,
-		SessionID:       &sid,
+	}
+
+	if h.ice != nil && h.RemoteICESupported() {
+		uFrag, pwd := h.ice.GetLocalUserCredentials()
+		sid := h.ice.SessionID()
+		answer.IceCredentials = IceCredentials{uFrag, pwd}
+		answer.SessionID = &sid
 	}
 
 	if addr, err := h.relay.RelayInstanceAddress(); err == nil {
@@ -200,3 +223,18 @@ func (h *Handshaker) buildOfferAnswer() OfferAnswer {
 
 	return answer
 }
+
+func (h *Handshaker) updateRemoteICEState(offer *OfferAnswer) {
+	hasICE := offer.hasICECredentials()
+	prev := h.remoteICESupported.Swap(hasICE)
+	if prev != hasICE {
+		if hasICE {
+			h.log.Infof("remote peer started sending ICE credentials")
+		} else {
+			h.log.Infof("remote peer stopped sending ICE credentials")
+			if h.ice != nil {
+				h.ice.Close()
+			}
+		}
+	}
+}

client/internal/peer/signaler.go

@@ -46,9 +46,13 @@ func (s *Signaler) Ready() bool {
 
 // SignalOfferAnswer signals either an offer or an answer to remote peer
 func (s *Signaler) signalOfferAnswer(offerAnswer OfferAnswer, remoteKey string, bodyType sProto.Body_Type) error {
-	sessionIDBytes, err := offerAnswer.SessionID.Bytes()
-	if err != nil {
-		log.Warnf("failed to get session ID bytes: %v", err)
+	var sessionIDBytes []byte
+	if offerAnswer.SessionID != nil {
+		var err error
+		sessionIDBytes, err = offerAnswer.SessionID.Bytes()
+		if err != nil {
+			log.Warnf("failed to get session ID bytes: %v", err)
+		}
 	}
 	msg, err := signal.MarshalCredential(
 		s.wgPrivateKey,

client/internal/portforward/env.go

@@ -8,18 +8,27 @@ import (
 )
 
 const (
-	envDisableNATMapper = "NB_DISABLE_NAT_MAPPER"
+	envDisableNATMapper      = "NB_DISABLE_NAT_MAPPER"
+	envDisablePCPHealthCheck = "NB_DISABLE_PCP_HEALTH_CHECK"
 )
 
 func isDisabledByEnv() bool {
-	val := os.Getenv(envDisableNATMapper)
+	return parseBoolEnv(envDisableNATMapper)
+}
+
+func isHealthCheckDisabled() bool {
+	return parseBoolEnv(envDisablePCPHealthCheck)
+}
+
+func parseBoolEnv(key string) bool {
+	val := os.Getenv(key)
 	if val == "" {
 		return false
 	}
 
 	disabled, err := strconv.ParseBool(val)
 	if err != nil {
-		log.Warnf("failed to parse %s: %v", envDisableNATMapper, err)
+		log.Warnf("failed to parse %s: %v", key, err)
 		return false
 	}
 	return disabled

client/internal/portforward/manager.go

@@ -12,12 +12,15 @@ import (
 
 	"github.com/libp2p/go-nat"
 	log "github.com/sirupsen/logrus"
+
+	"github.com/netbirdio/netbird/client/internal/portforward/pcp"
 )
 
 const (
-	defaultMappingTTL  = 2 * time.Hour
-	discoveryTimeout   = 10 * time.Second
-	mappingDescription = "NetBird"
+	defaultMappingTTL   = 2 * time.Hour
+	healthCheckInterval = 1 * time.Minute
+	discoveryTimeout    = 10 * time.Second
+	mappingDescription  = "NetBird"
 )
 
 // upnpErrPermanentLeaseOnly matches UPnP error 725 in SOAP fault XML,
@@ -154,7 +157,7 @@ func (m *Manager) setup(ctx context.Context) (nat.NAT, *Mapping, error) {
 	discoverCtx, discoverCancel := context.WithTimeout(ctx, discoveryTimeout)
 	defer discoverCancel()
 
-	gateway, err := nat.DiscoverGateway(discoverCtx)
+	gateway, err := discoverGateway(discoverCtx)
 	if err != nil {
 		return nil, nil, fmt.Errorf("discover gateway: %w", err)
 	}
@@ -189,7 +192,6 @@ func (m *Manager) createMapping(ctx context.Context, gateway nat.NAT) (*Mapping,
 	externalIP, err := gateway.GetExternalAddress()
 	if err != nil {
 		log.Debugf("failed to get external address: %v", err)
-		// todo return with err?
 	}
 
 	mapping := &Mapping{
@@ -208,27 +210,87 @@ func (m *Manager) createMapping(ctx context.Context, gateway nat.NAT) (*Mapping,
 
 func (m *Manager) renewLoop(ctx context.Context, gateway nat.NAT, ttl time.Duration) {
 	if ttl == 0 {
-		// Permanent mappings don't expire, just wait for cancellation.
-		<-ctx.Done()
+		// Permanent mappings don't expire, just wait for cancellation
+		// but still run health checks for PCP gateways.
+		m.permanentLeaseLoop(ctx, gateway)
 		return
 	}
 
-	ticker := time.NewTicker(ttl / 2)
-	defer ticker.Stop()
+	renewTicker := time.NewTicker(ttl / 2)
+	healthTicker := time.NewTicker(healthCheckInterval)
+	defer renewTicker.Stop()
+	defer healthTicker.Stop()
 
 	for {
 		select {
 		case <-ctx.Done():
 			return
-		case <-ticker.C:
+		case <-renewTicker.C:
 			if err := m.renewMapping(ctx, gateway); err != nil {
 				log.Warnf("failed to renew port mapping: %v", err)
 				continue
 			}
+		case <-healthTicker.C:
+			if m.checkHealthAndRecreate(ctx, gateway) {
+				renewTicker.Reset(ttl / 2)
+			}
 		}
 	}
 }
 
+func (m *Manager) permanentLeaseLoop(ctx context.Context, gateway nat.NAT) {
+	healthTicker := time.NewTicker(healthCheckInterval)
+	defer healthTicker.Stop()
+
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-healthTicker.C:
+			m.checkHealthAndRecreate(ctx, gateway)
+		}
+	}
+}
+
+func (m *Manager) checkHealthAndRecreate(ctx context.Context, gateway nat.NAT) bool {
+	if isHealthCheckDisabled() {
+		return false
+	}
+
+	m.mappingLock.Lock()
+	hasMapping := m.mapping != nil
+	m.mappingLock.Unlock()
+
+	if !hasMapping {
+		return false
+	}
+
+	pcpNAT, ok := gateway.(*pcp.NAT)
+	if !ok {
+		return false
+	}
+
+	ctx, cancel := context.WithTimeout(ctx, 10*time.Second)
+	defer cancel()
+
+	epoch, serverRestarted, err := pcpNAT.CheckServerHealth(ctx)
+	if err != nil {
+		log.Debugf("PCP health check failed: %v", err)
+		return false
+	}
+
+	if serverRestarted {
+		log.Warnf("PCP server restart detected (epoch=%d), recreating port mapping", epoch)
+		if err := m.renewMapping(ctx, gateway); err != nil {
+			log.Errorf("failed to recreate port mapping after server restart: %v", err)
+			return false
+		}
+		return true
+	}
+
+	return false
+}
+
 func (m *Manager) renewMapping(ctx context.Context, gateway nat.NAT) error {
 	ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
 	defer cancel()

client/internal/portforward/pcp/client.go

@@ -0,0 +1,408 @@
+package pcp
+
+import (
+	"context"
+	"crypto/rand"
+	"errors"
+	"fmt"
+	"net"
+	"net/netip"
+	"sync"
+	"time"
+
+	log "github.com/sirupsen/logrus"
+)
+
+const (
+	defaultTimeout     = 3 * time.Second
+	responseBufferSize = 128
+
+	// RFC 6887 Section 8.1.1 retry timing
+	initialRetryDelay = 3 * time.Second
+	maxRetryDelay     = 1024 * time.Second
+	maxRetries        = 4 // 3s + 6s + 12s + 24s = 45s total worst case
+)
+
+// Client is a PCP protocol client.
+// All methods are safe for concurrent use.
+type Client struct {
+	gateway netip.Addr
+	timeout time.Duration
+
+	mu sync.Mutex
+	// localIP caches the resolved local IP address.
+	localIP netip.Addr
+	// lastEpoch is the last observed server epoch value.
+	lastEpoch uint32
+	// epochTime tracks when lastEpoch was received for state loss detection.
+	epochTime time.Time
+	// externalIP caches the external IP from the last successful MAP response.
+	externalIP netip.Addr
+	// epochStateLost is set when epoch indicates server restart.
+	epochStateLost bool
+}
+
+// NewClient creates a new PCP client for the gateway at the given IP.
+func NewClient(gateway net.IP) *Client {
+	addr, ok := netip.AddrFromSlice(gateway)
+	if !ok {
+		log.Debugf("invalid gateway IP: %v", gateway)
+	}
+	return &Client{
+		gateway: addr.Unmap(),
+		timeout: defaultTimeout,
+	}
+}
+
+// NewClientWithTimeout creates a new PCP client with a custom timeout.
+func NewClientWithTimeout(gateway net.IP, timeout time.Duration) *Client {
+	addr, ok := netip.AddrFromSlice(gateway)
+	if !ok {
+		log.Debugf("invalid gateway IP: %v", gateway)
+	}
+	return &Client{
+		gateway: addr.Unmap(),
+		timeout: timeout,
+	}
+}
+
+// SetLocalIP sets the local IP address to use in PCP requests.
+func (c *Client) SetLocalIP(ip net.IP) {
+	addr, ok := netip.AddrFromSlice(ip)
+	if !ok {
+		log.Debugf("invalid local IP: %v", ip)
+	}
+	c.mu.Lock()
+	c.localIP = addr.Unmap()
+	c.mu.Unlock()
+}
+
+// Gateway returns the gateway IP address.
+func (c *Client) Gateway() net.IP {
+	return c.gateway.AsSlice()
+}
+
+// Announce sends a PCP ANNOUNCE request to discover PCP support.
+// Returns the server's epoch time on success.
+func (c *Client) Announce(ctx context.Context) (epoch uint32, err error) {
+	localIP, err := c.getLocalIP()
+	if err != nil {
+		return 0, fmt.Errorf("get local IP: %w", err)
+	}
+
+	req := buildAnnounceRequest(localIP)
+	resp, err := c.sendRequest(ctx, req)
+	if err != nil {
+		return 0, fmt.Errorf("send announce: %w", err)
+	}
+
+	parsed, err := parseResponse(resp)
+	if err != nil {
+		return 0, fmt.Errorf("parse announce response: %w", err)
+	}
+
+	if parsed.ResultCode != ResultSuccess {
+		return 0, fmt.Errorf("PCP ANNOUNCE failed: %s", ResultCodeString(parsed.ResultCode))
+	}
+
+	c.mu.Lock()
+	if c.updateEpochLocked(parsed.Epoch) {
+		log.Warnf("PCP server epoch indicates state loss - mappings may need refresh")
+	}
+	c.mu.Unlock()
+	return parsed.Epoch, nil
+}
+
+// AddPortMapping requests a port mapping from the PCP server.
+func (c *Client) AddPortMapping(ctx context.Context, protocol string, internalPort int, lifetime time.Duration) (*MapResponse, error) {
+	return c.addPortMappingWithHint(ctx, protocol, internalPort, internalPort, netip.Addr{}, lifetime)
+}
+
+// AddPortMappingWithHint requests a port mapping with suggested external port and IP.
+// Use lifetime <= 0 to delete a mapping.
+func (c *Client) AddPortMappingWithHint(ctx context.Context, protocol string, internalPort, suggestedExtPort int, suggestedExtIP net.IP, lifetime time.Duration) (*MapResponse, error) {
+	var extIP netip.Addr
+	if suggestedExtIP != nil {
+		var ok bool
+		extIP, ok = netip.AddrFromSlice(suggestedExtIP)
+		if !ok {
+			log.Debugf("invalid suggested external IP: %v", suggestedExtIP)
+		}
+		extIP = extIP.Unmap()
+	}
+	return c.addPortMappingWithHint(ctx, protocol, internalPort, suggestedExtPort, extIP, lifetime)
+}
+
+func (c *Client) addPortMappingWithHint(ctx context.Context, protocol string, internalPort, suggestedExtPort int, suggestedExtIP netip.Addr, lifetime time.Duration) (*MapResponse, error) {
+	localIP, err := c.getLocalIP()
+	if err != nil {
+		return nil, fmt.Errorf("get local IP: %w", err)
+	}
+
+	proto, err := protocolNumber(protocol)
+	if err != nil {
+		return nil, fmt.Errorf("parse protocol: %w", err)
+	}
+
+	var nonce [12]byte
+	if _, err := rand.Read(nonce[:]); err != nil {
+		return nil, fmt.Errorf("generate nonce: %w", err)
+	}
+
+	// Convert lifetime to seconds. Lifetime 0 means delete, so only apply
+	// default for positive durations that round to 0 seconds.
+	var lifetimeSec uint32
+	if lifetime > 0 {
+		lifetimeSec = uint32(lifetime.Seconds())
+		if lifetimeSec == 0 {
+			lifetimeSec = DefaultLifetime
+		}
+	}
+
+	req := buildMapRequest(localIP, nonce, proto, uint16(internalPort), uint16(suggestedExtPort), suggestedExtIP, lifetimeSec)
+
+	resp, err := c.sendRequest(ctx, req)
+	if err != nil {
+		return nil, fmt.Errorf("send map request: %w", err)
+	}
+
+	mapResp, err := parseMapResponse(resp)
+	if err != nil {
+		return nil, fmt.Errorf("parse map response: %w", err)
+	}
+
+	if mapResp.Nonce != nonce {
+		return nil, fmt.Errorf("nonce mismatch in response")
+	}
+
+	if mapResp.Protocol != proto {
+		return nil, fmt.Errorf("protocol mismatch: requested %d, got %d", proto, mapResp.Protocol)
+	}
+	if mapResp.InternalPort != uint16(internalPort) {
+		return nil, fmt.Errorf("internal port mismatch: requested %d, got %d", internalPort, mapResp.InternalPort)
+	}
+
+	if mapResp.ResultCode != ResultSuccess {
+		return nil, &Error{
+			Code:    mapResp.ResultCode,
+			Message: ResultCodeString(mapResp.ResultCode),
+		}
+	}
+
+	c.mu.Lock()
+	if c.updateEpochLocked(mapResp.Epoch) {
+		log.Warnf("PCP server epoch indicates state loss - mappings may need refresh")
+	}
+	c.cacheExternalIPLocked(mapResp.ExternalIP)
+	c.mu.Unlock()
+	return mapResp, nil
+}
+
+// DeletePortMapping removes a port mapping by requesting zero lifetime.
+func (c *Client) DeletePortMapping(ctx context.Context, protocol string, internalPort int) error {
+	if _, err := c.addPortMappingWithHint(ctx, protocol, internalPort, 0, netip.Addr{}, 0); err != nil {
+		var pcpErr *Error
+		if errors.As(err, &pcpErr) && pcpErr.Code == ResultNotAuthorized {
+			return nil
+		}
+		return fmt.Errorf("delete mapping: %w", err)
+	}
+	return nil
+}
+
+// GetExternalAddress returns the external IP address.
+// First checks for a cached value from previous MAP responses.
+// If not cached, creates a short-lived mapping to discover the external IP.
+func (c *Client) GetExternalAddress(ctx context.Context) (net.IP, error) {
+	c.mu.Lock()
+	if c.externalIP.IsValid() {
+		ip := c.externalIP.AsSlice()
+		c.mu.Unlock()
+		return ip, nil
+	}
+	c.mu.Unlock()
+
+	// Use an ephemeral port in the dynamic range (49152-65535).
+	// Port 0 is not valid with UDP/TCP protocols per RFC 6887.
+	ephemeralPort := 49152 + int(uint16(time.Now().UnixNano()))%(65535-49152)
+
+	// Use minimal lifetime (1 second) for discovery.
+	resp, err := c.AddPortMapping(ctx, "udp", ephemeralPort, time.Second)
+	if err != nil {
+		return nil, fmt.Errorf("create temporary mapping: %w", err)
+	}
+
+	if err := c.DeletePortMapping(ctx, "udp", ephemeralPort); err != nil {
+		log.Debugf("cleanup temporary PCP mapping: %v", err)
+	}
+
+	return resp.ExternalIP.AsSlice(), nil
+}
+
+// LastEpoch returns the last observed server epoch value.
+// A decrease in epoch indicates the server may have restarted and mappings may be lost.
+func (c *Client) LastEpoch() uint32 {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	return c.lastEpoch
+}
+
+// EpochStateLost returns true if epoch state loss was detected and clears the flag.
+func (c *Client) EpochStateLost() bool {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	lost := c.epochStateLost
+	c.epochStateLost = false
+	return lost
+}
+
+// updateEpoch updates the epoch tracking and detects potential state loss.
+// Returns true if state loss was detected (server likely restarted).
+// Caller must hold c.mu.
+func (c *Client) updateEpochLocked(newEpoch uint32) bool {
+	now := time.Now()
+	stateLost := false
+
+	// RFC 6887 Section 8.5: Detect invalid epoch indicating server state loss.
+	// client_delta = time since last response
+	// server_delta = epoch change since last response
+	// Invalid if: client_delta+2 < server_delta - server_delta/16
+	//         OR: server_delta+2 < client_delta - client_delta/16
+	// The +2 handles quantization, /16 (6.25%) handles clock drift.
+	if !c.epochTime.IsZero() && c.lastEpoch > 0 {
+		clientDelta := uint32(now.Sub(c.epochTime).Seconds())
+		serverDelta := newEpoch - c.lastEpoch
+
+		// Check for epoch going backwards or jumping unexpectedly.
+		// Subtraction is safe: serverDelta/16 is always <= serverDelta.
+		if clientDelta+2 < serverDelta-(serverDelta/16) ||
+			serverDelta+2 < clientDelta-(clientDelta/16) {
+			stateLost = true
+			c.epochStateLost = true
+		}
+	}
+
+	c.lastEpoch = newEpoch
+	c.epochTime = now
+	return stateLost
+}
+
+// cacheExternalIP stores the external IP from a successful MAP response.
+// Caller must hold c.mu.
+func (c *Client) cacheExternalIPLocked(ip netip.Addr) {
+	if ip.IsValid() && !ip.IsUnspecified() {
+		c.externalIP = ip
+	}
+}
+
+// sendRequest sends a PCP request with retries per RFC 6887 Section 8.1.1.
+func (c *Client) sendRequest(ctx context.Context, req []byte) ([]byte, error) {
+	addr := &net.UDPAddr{IP: c.gateway.AsSlice(), Port: Port}
+
+	var lastErr error
+	delay := initialRetryDelay
+
+	for range maxRetries {
+		resp, err := c.sendOnce(ctx, addr, req)
+		if err == nil {
+			return resp, nil
+		}
+		lastErr = err
+
+		if ctx.Err() != nil {
+			return nil, ctx.Err()
+		}
+
+		// RFC 6887 Section 8.1.1: RT = (1 + RAND) * MIN(2 * RTprev, MRT)
+		// RAND is random between -0.1 and +0.1
+		select {
+		case <-ctx.Done():
+			return nil, ctx.Err()
+		case <-time.After(retryDelayWithJitter(delay)):
+		}
+		delay = min(delay*2, maxRetryDelay)
+	}
+
+	return nil, fmt.Errorf("PCP request failed after %d retries: %w", maxRetries, lastErr)
+}
+
+// retryDelayWithJitter applies RFC 6887 jitter: multiply by (1 + RAND) where RAND is [-0.1, +0.1].
+func retryDelayWithJitter(d time.Duration) time.Duration {
+	var b [1]byte
+	_, _ = rand.Read(b[:])
+	// Convert byte to range [-0.1, +0.1]: (b/255 * 0.2) - 0.1
+	jitter := (float64(b[0])/255.0)*0.2 - 0.1
+	return time.Duration(float64(d) * (1 + jitter))
+}
+
+func (c *Client) sendOnce(ctx context.Context, addr *net.UDPAddr, req []byte) ([]byte, error) {
+	// Use ListenUDP instead of DialUDP to validate response source address per RFC 6887 §8.3.
+	conn, err := net.ListenUDP("udp", nil)
+	if err != nil {
+		return nil, fmt.Errorf("listen: %w", err)
+	}
+	defer func() {
+		if err := conn.Close(); err != nil {
+			log.Debugf("close UDP connection: %v", err)
+		}
+	}()
+
+	timeout := c.timeout
+	if deadline, ok := ctx.Deadline(); ok {
+		if remaining := time.Until(deadline); remaining < timeout {
+			timeout = remaining
+		}
+	}
+
+	if err := conn.SetDeadline(time.Now().Add(timeout)); err != nil {
+		return nil, fmt.Errorf("set deadline: %w", err)
+	}
+
+	if _, err := conn.WriteToUDP(req, addr); err != nil {
+		return nil, fmt.Errorf("write: %w", err)
+	}
+
+	resp := make([]byte, responseBufferSize)
+	n, from, err := conn.ReadFromUDP(resp)
+	if err != nil {
+		return nil, fmt.Errorf("read: %w", err)
+	}
+
+	// RFC 6887 §8.3: Validate response came from expected PCP server.
+	if !from.IP.Equal(addr.IP) {
+		return nil, fmt.Errorf("response from unexpected source %s (expected %s)", from.IP, addr.IP)
+	}
+
+	return resp[:n], nil
+}
+
+func (c *Client) getLocalIP() (netip.Addr, error) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	if !c.localIP.IsValid() {
+		return netip.Addr{}, fmt.Errorf("local IP not set for gateway %s", c.gateway)
+	}
+	return c.localIP, nil
+}
+
+func protocolNumber(protocol string) (uint8, error) {
+	switch protocol {
+	case "udp", "UDP":
+		return ProtoUDP, nil
+	case "tcp", "TCP":
+		return ProtoTCP, nil
+	default:
+		return 0, fmt.Errorf("unsupported protocol: %s", protocol)
+	}
+}
+
+// Error represents a PCP error response.
+type Error struct {
+	Code    uint8
+	Message string
+}
+
+func (e *Error) Error() string {
+	return fmt.Sprintf("PCP error: %s (%d)", e.Message, e.Code)
+}

client/internal/portforward/pcp/client_test.go

@@ -0,0 +1,187 @@
+package pcp
+
+import (
+	"context"
+	"net"
+	"net/netip"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestAddrConversion(t *testing.T) {
+	tests := []struct {
+		name string
+		addr netip.Addr
+	}{
+		{"IPv4", netip.MustParseAddr("192.168.1.100")},
+		{"IPv4 loopback", netip.MustParseAddr("127.0.0.1")},
+		{"IPv6", netip.MustParseAddr("2001:db8::1")},
+		{"IPv6 loopback", netip.MustParseAddr("::1")},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			b16 := addrTo16(tt.addr)
+
+			recovered := addrFrom16(b16)
+			assert.Equal(t, tt.addr, recovered, "address should round-trip")
+		})
+	}
+}
+
+func TestBuildAnnounceRequest(t *testing.T) {
+	clientIP := netip.MustParseAddr("192.168.1.100")
+	req := buildAnnounceRequest(clientIP)
+
+	require.Len(t, req, headerSize)
+	assert.Equal(t, byte(Version), req[0], "version")
+	assert.Equal(t, byte(OpAnnounce), req[1], "opcode")
+
+	// Check client IP is properly encoded as IPv4-mapped IPv6
+	assert.Equal(t, byte(0xff), req[18], "IPv4-mapped prefix byte 10")
+	assert.Equal(t, byte(0xff), req[19], "IPv4-mapped prefix byte 11")
+	assert.Equal(t, byte(192), req[20], "IP octet 1")
+	assert.Equal(t, byte(168), req[21], "IP octet 2")
+	assert.Equal(t, byte(1), req[22], "IP octet 3")
+	assert.Equal(t, byte(100), req[23], "IP octet 4")
+}
+
+func TestBuildMapRequest(t *testing.T) {
+	clientIP := netip.MustParseAddr("192.168.1.100")
+	nonce := [12]byte{1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12}
+	req := buildMapRequest(clientIP, nonce, ProtoUDP, 51820, 51820, netip.Addr{}, 3600)
+
+	require.Len(t, req, mapRequestSize)
+	assert.Equal(t, byte(Version), req[0], "version")
+	assert.Equal(t, byte(OpMap), req[1], "opcode")
+
+	// Lifetime at bytes 4-7
+	assert.Equal(t, uint32(3600), (uint32(req[4])<<24)|(uint32(req[5])<<16)|(uint32(req[6])<<8)|uint32(req[7]), "lifetime")
+
+	// Nonce at bytes 24-35
+	assert.Equal(t, nonce[:], req[24:36], "nonce")
+
+	// Protocol at byte 36
+	assert.Equal(t, byte(ProtoUDP), req[36], "protocol")
+
+	// Internal port at bytes 40-41
+	assert.Equal(t, uint16(51820), (uint16(req[40])<<8)|uint16(req[41]), "internal port")
+
+	// External port at bytes 42-43
+	assert.Equal(t, uint16(51820), (uint16(req[42])<<8)|uint16(req[43]), "external port")
+}
+
+func TestParseResponse(t *testing.T) {
+	// Construct a valid ANNOUNCE response
+	resp := make([]byte, headerSize)
+	resp[0] = Version
+	resp[1] = OpAnnounce | OpReply
+	// Result code = 0 (success)
+	// Lifetime = 0
+	// Epoch = 12345
+	resp[8] = 0
+	resp[9] = 0
+	resp[10] = 0x30
+	resp[11] = 0x39
+
+	parsed, err := parseResponse(resp)
+	require.NoError(t, err)
+	assert.Equal(t, uint8(Version), parsed.Version)
+	assert.Equal(t, uint8(OpAnnounce|OpReply), parsed.Opcode)
+	assert.Equal(t, uint8(ResultSuccess), parsed.ResultCode)
+	assert.Equal(t, uint32(12345), parsed.Epoch)
+}
+
+func TestParseResponseErrors(t *testing.T) {
+	t.Run("too short", func(t *testing.T) {
+		_, err := parseResponse([]byte{1, 2, 3})
+		assert.Error(t, err)
+	})
+
+	t.Run("wrong version", func(t *testing.T) {
+		resp := make([]byte, headerSize)
+		resp[0] = 1 // Wrong version
+		resp[1] = OpReply
+		_, err := parseResponse(resp)
+		assert.Error(t, err)
+	})
+
+	t.Run("missing reply bit", func(t *testing.T) {
+		resp := make([]byte, headerSize)
+		resp[0] = Version
+		resp[1] = OpAnnounce // Missing OpReply bit
+		_, err := parseResponse(resp)
+		assert.Error(t, err)
+	})
+}
+
+func TestResultCodeString(t *testing.T) {
+	assert.Equal(t, "SUCCESS", ResultCodeString(ResultSuccess))
+	assert.Equal(t, "NOT_AUTHORIZED", ResultCodeString(ResultNotAuthorized))
+	assert.Equal(t, "ADDRESS_MISMATCH", ResultCodeString(ResultAddressMismatch))
+	assert.Contains(t, ResultCodeString(255), "UNKNOWN")
+}
+
+func TestProtocolNumber(t *testing.T) {
+	proto, err := protocolNumber("udp")
+	require.NoError(t, err)
+	assert.Equal(t, uint8(ProtoUDP), proto)
+
+	proto, err = protocolNumber("tcp")
+	require.NoError(t, err)
+	assert.Equal(t, uint8(ProtoTCP), proto)
+
+	proto, err = protocolNumber("UDP")
+	require.NoError(t, err)
+	assert.Equal(t, uint8(ProtoUDP), proto)
+
+	_, err = protocolNumber("icmp")
+	assert.Error(t, err)
+}
+
+func TestClientCreation(t *testing.T) {
+	gateway := netip.MustParseAddr("192.168.1.1").AsSlice()
+
+	client := NewClient(gateway)
+	assert.Equal(t, net.IP(gateway), client.Gateway())
+	assert.Equal(t, defaultTimeout, client.timeout)
+
+	clientWithTimeout := NewClientWithTimeout(gateway, 5*time.Second)
+	assert.Equal(t, 5*time.Second, clientWithTimeout.timeout)
+}
+
+func TestNATType(t *testing.T) {
+	n := NewNAT(netip.MustParseAddr("192.168.1.1").AsSlice(), netip.MustParseAddr("192.168.1.100").AsSlice())
+	assert.Equal(t, "PCP", n.Type())
+}
+
+// Integration test - skipped unless PCP_TEST_GATEWAY env is set
+func TestClientIntegration(t *testing.T) {
+	t.Skip("Integration test - run manually with PCP_TEST_GATEWAY=<gateway-ip>")
+
+	gateway := netip.MustParseAddr("10.0.1.1").AsSlice()   // Change to your test gateway
+	localIP := netip.MustParseAddr("10.0.1.100").AsSlice() // Change to your local IP
+
+	client := NewClient(gateway)
+	client.SetLocalIP(localIP)
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	// Test ANNOUNCE
+	epoch, err := client.Announce(ctx)
+	require.NoError(t, err)
+	t.Logf("Server epoch: %d", epoch)
+
+	// Test MAP
+	resp, err := client.AddPortMapping(ctx, "udp", 51820, 1*time.Hour)
+	require.NoError(t, err)
+	t.Logf("Mapping: internal=%d external=%d externalIP=%s",
+		resp.InternalPort, resp.ExternalPort, resp.ExternalIP)
+
+	// Cleanup
+	err = client.DeletePortMapping(ctx, "udp", 51820)
+	require.NoError(t, err)
+}

client/internal/portforward/pcp/nat.go

@@ -0,0 +1,209 @@
+package pcp
+
+import (
+	"context"
+	"fmt"
+	"net"
+	"net/netip"
+	"sync"
+	"time"
+
+	log "github.com/sirupsen/logrus"
+
+	"github.com/libp2p/go-nat"
+	"github.com/libp2p/go-netroute"
+)
+
+var _ nat.NAT = (*NAT)(nil)
+
+// NAT implements the go-nat NAT interface using PCP.
+// Supports dual-stack (IPv4 and IPv6) when available.
+// All methods are safe for concurrent use.
+//
+// TODO: IPv6 pinholes use the local IPv6 address. If the address changes
+// (e.g., due to SLAAC rotation or network change), the pinhole becomes stale
+// and needs to be recreated with the new address.
+type NAT struct {
+	client *Client
+
+	mu sync.RWMutex
+	// client6 is the IPv6 PCP client, nil if IPv6 is unavailable.
+	client6 *Client
+	// localIP6 caches the local IPv6 address used for PCP requests.
+	localIP6 netip.Addr
+}
+
+// NewNAT creates a new NAT instance backed by PCP.
+func NewNAT(gateway, localIP net.IP) *NAT {
+	client := NewClient(gateway)
+	client.SetLocalIP(localIP)
+	return &NAT{
+		client: client,
+	}
+}
+
+// Type returns "PCP" as the NAT type.
+func (n *NAT) Type() string {
+	return "PCP"
+}
+
+// GetDeviceAddress returns the gateway IP address.
+func (n *NAT) GetDeviceAddress() (net.IP, error) {
+	return n.client.Gateway(), nil
+}
+
+// GetExternalAddress returns the external IP address.
+func (n *NAT) GetExternalAddress() (net.IP, error) {
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	return n.client.GetExternalAddress(ctx)
+}
+
+// GetInternalAddress returns the local IP address used to communicate with the gateway.
+func (n *NAT) GetInternalAddress() (net.IP, error) {
+	addr, err := n.client.getLocalIP()
+	if err != nil {
+		return nil, err
+	}
+	return addr.AsSlice(), nil
+}
+
+// AddPortMapping creates a port mapping on both IPv4 and IPv6 (if available).
+func (n *NAT) AddPortMapping(ctx context.Context, protocol string, internalPort int, _ string, timeout time.Duration) (int, error) {
+	resp, err := n.client.AddPortMapping(ctx, protocol, internalPort, timeout)
+	if err != nil {
+		return 0, fmt.Errorf("add mapping: %w", err)
+	}
+
+	n.mu.RLock()
+	client6 := n.client6
+	localIP6 := n.localIP6
+	n.mu.RUnlock()
+
+	if client6 == nil {
+		return int(resp.ExternalPort), nil
+	}
+
+	if _, err := client6.AddPortMapping(ctx, protocol, internalPort, timeout); err != nil {
+		log.Warnf("IPv6 PCP mapping failed (continuing with IPv4): %v", err)
+		return int(resp.ExternalPort), nil
+	}
+
+	log.Infof("created IPv6 PCP pinhole: %s:%d", localIP6, internalPort)
+	return int(resp.ExternalPort), nil
+}
+
+// DeletePortMapping removes a port mapping from both IPv4 and IPv6.
+func (n *NAT) DeletePortMapping(ctx context.Context, protocol string, internalPort int) error {
+	err := n.client.DeletePortMapping(ctx, protocol, internalPort)
+
+	n.mu.RLock()
+	client6 := n.client6
+	n.mu.RUnlock()
+
+	if client6 != nil {
+		if err6 := client6.DeletePortMapping(ctx, protocol, internalPort); err6 != nil {
+			log.Warnf("IPv6 PCP delete mapping failed: %v", err6)
+		}
+	}
+
+	if err != nil {
+		return fmt.Errorf("delete mapping: %w", err)
+	}
+	return nil
+}
+
+// CheckServerHealth sends an ANNOUNCE to verify the server is still responsive.
+// Returns the current epoch and whether the server may have restarted (epoch state loss detected).
+func (n *NAT) CheckServerHealth(ctx context.Context) (epoch uint32, serverRestarted bool, err error) {
+	epoch, err = n.client.Announce(ctx)
+	if err != nil {
+		return 0, false, fmt.Errorf("announce: %w", err)
+	}
+	return epoch, n.client.EpochStateLost(), nil
+}
+
+// DiscoverPCP attempts to discover a PCP-capable gateway.
+// Returns a NAT interface if PCP is supported, or an error otherwise.
+// Discovers both IPv4 and IPv6 gateways when available.
+func DiscoverPCP(ctx context.Context) (nat.NAT, error) {
+	gateway, localIP, err := getDefaultGateway()
+	if err != nil {
+		return nil, fmt.Errorf("get default gateway: %w", err)
+	}
+
+	client := NewClient(gateway)
+	client.SetLocalIP(localIP)
+	if _, err := client.Announce(ctx); err != nil {
+		return nil, fmt.Errorf("PCP announce: %w", err)
+	}
+
+	result := &NAT{client: client}
+	discoverIPv6(ctx, result)
+
+	return result, nil
+}
+
+func discoverIPv6(ctx context.Context, result *NAT) {
+	gateway6, localIP6, err := getDefaultGateway6()
+	if err != nil {
+		log.Debugf("IPv6 gateway discovery failed: %v", err)
+		return
+	}
+
+	client6 := NewClient(gateway6)
+	client6.SetLocalIP(localIP6)
+	if _, err := client6.Announce(ctx); err != nil {
+		log.Debugf("PCP IPv6 announce failed: %v", err)
+		return
+	}
+
+	addr, ok := netip.AddrFromSlice(localIP6)
+	if !ok {
+		log.Debugf("invalid IPv6 local IP: %v", localIP6)
+		return
+	}
+	result.mu.Lock()
+	result.client6 = client6
+	result.localIP6 = addr
+	result.mu.Unlock()
+	log.Debugf("PCP IPv6 gateway discovered: %s (local: %s)", gateway6, localIP6)
+}
+
+// getDefaultGateway returns the default IPv4 gateway and local IP using the system routing table.
+func getDefaultGateway() (gateway net.IP, localIP net.IP, err error) {
+	router, err := netroute.New()
+	if err != nil {
+		return nil, nil, err
+	}
+
+	_, gateway, localIP, err = router.Route(net.IPv4zero)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	if gateway == nil {
+		return nil, nil, nat.ErrNoNATFound
+	}
+
+	return gateway, localIP, nil
+}
+
+// getDefaultGateway6 returns the default IPv6 gateway IP address using the system routing table.
+func getDefaultGateway6() (gateway net.IP, localIP net.IP, err error) {
+	router, err := netroute.New()
+	if err != nil {
+		return nil, nil, err
+	}
+
+	_, gateway, localIP, err = router.Route(net.IPv6zero)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	if gateway == nil {
+		return nil, nil, nat.ErrNoNATFound
+	}
+
+	return gateway, localIP, nil
+}

client/internal/portforward/pcp/protocol.go

@@ -0,0 +1,225 @@
+// Package pcp implements the Port Control Protocol (RFC 6887).
+//
+// # Implemented Features
+//
+//   - ANNOUNCE opcode: Discovers PCP server support
+//   - MAP opcode: Creates/deletes port mappings (IPv4 NAT) and firewall pinholes (IPv6)
+//   - Dual-stack: Simultaneous IPv4 and IPv6 support via separate clients
+//   - Nonce validation: Prevents response spoofing
+//   - Epoch tracking: Detects server restarts per Section 8.5
+//   - RFC-compliant retry timing: 3s initial, exponential backoff to 1024s max (Section 8.1.1)
+//
+// # Not Implemented
+//
+//   - PEER opcode: For outbound peer connections (not needed for inbound NAT traversal)
+//   - THIRD_PARTY option: For managing mappings on behalf of other devices
+//   - PREFER_FAILURE option: Requires exact external port or fail (IPv4 NAT only, not needed for IPv6 pinholing)
+//   - FILTER option: To restrict remote peer addresses
+//
+// These optional features are omitted because the primary use case is simple
+// port forwarding for WireGuard, which only requires MAP with default behavior.
+package pcp
+
+import (
+	"encoding/binary"
+	"fmt"
+	"net/netip"
+)
+
+const (
+	// Version is the PCP protocol version (RFC 6887).
+	Version = 2
+
+	// Port is the standard PCP server port.
+	Port = 5351
+
+	// DefaultLifetime is the default requested mapping lifetime in seconds.
+	DefaultLifetime = 7200 // 2 hours
+
+	// Header sizes
+	headerSize     = 24
+	mapPayloadSize = 36
+	mapRequestSize = headerSize + mapPayloadSize // 60 bytes
+)
+
+// Opcodes
+const (
+	OpAnnounce = 0
+	OpMap      = 1
+	OpPeer     = 2
+	OpReply    = 0x80 // OR'd with opcode in responses
+)
+
+// Protocol numbers for MAP requests
+const (
+	ProtoUDP = 17
+	ProtoTCP = 6
+)
+
+// Result codes (RFC 6887 Section 7.4)
+const (
+	ResultSuccess              = 0
+	ResultUnsuppVersion        = 1
+	ResultNotAuthorized        = 2
+	ResultMalformedRequest     = 3
+	ResultUnsuppOpcode         = 4
+	ResultUnsuppOption         = 5
+	ResultMalformedOption      = 6
+	ResultNetworkFailure       = 7
+	ResultNoResources          = 8
+	ResultUnsuppProtocol       = 9
+	ResultUserExQuota          = 10
+	ResultCannotProvideExt     = 11
+	ResultAddressMismatch      = 12
+	ResultExcessiveRemotePeers = 13
+)
+
+// ResultCodeString returns a human-readable string for a result code.
+func ResultCodeString(code uint8) string {
+	switch code {
+	case ResultSuccess:
+		return "SUCCESS"
+	case ResultUnsuppVersion:
+		return "UNSUPP_VERSION"
+	case ResultNotAuthorized:
+		return "NOT_AUTHORIZED"
+	case ResultMalformedRequest:
+		return "MALFORMED_REQUEST"
+	case ResultUnsuppOpcode:
+		return "UNSUPP_OPCODE"
+	case ResultUnsuppOption:
+		return "UNSUPP_OPTION"
+	case ResultMalformedOption:
+		return "MALFORMED_OPTION"
+	case ResultNetworkFailure:
+		return "NETWORK_FAILURE"
+	case ResultNoResources:
+		return "NO_RESOURCES"
+	case ResultUnsuppProtocol:
+		return "UNSUPP_PROTOCOL"
+	case ResultUserExQuota:
+		return "USER_EX_QUOTA"
+	case ResultCannotProvideExt:
+		return "CANNOT_PROVIDE_EXTERNAL"
+	case ResultAddressMismatch:
+		return "ADDRESS_MISMATCH"
+	case ResultExcessiveRemotePeers:
+		return "EXCESSIVE_REMOTE_PEERS"
+	default:
+		return fmt.Sprintf("UNKNOWN(%d)", code)
+	}
+}
+
+// Response represents a parsed PCP response header.
+type Response struct {
+	Version    uint8
+	Opcode     uint8
+	ResultCode uint8
+	Lifetime   uint32
+	Epoch      uint32
+}
+
+// MapResponse contains the full response to a MAP request.
+type MapResponse struct {
+	Response
+	Nonce        [12]byte
+	Protocol     uint8
+	InternalPort uint16
+	ExternalPort uint16
+	ExternalIP   netip.Addr
+}
+
+// addrTo16 converts an address to its 16-byte IPv4-mapped IPv6 representation.
+func addrTo16(addr netip.Addr) [16]byte {
+	if addr.Is4() {
+		return netip.AddrFrom4(addr.As4()).As16()
+	}
+	return addr.As16()
+}
+
+// addrFrom16 extracts an address from a 16-byte representation, unmapping IPv4.
+func addrFrom16(b [16]byte) netip.Addr {
+	return netip.AddrFrom16(b).Unmap()
+}
+
+// buildAnnounceRequest creates a PCP ANNOUNCE request packet.
+func buildAnnounceRequest(clientIP netip.Addr) []byte {
+	req := make([]byte, headerSize)
+	req[0] = Version
+	req[1] = OpAnnounce
+	mapped := addrTo16(clientIP)
+	copy(req[8:24], mapped[:])
+	return req
+}
+
+// buildMapRequest creates a PCP MAP request packet.
+func buildMapRequest(clientIP netip.Addr, nonce [12]byte, protocol uint8, internalPort, suggestedExtPort uint16, suggestedExtIP netip.Addr, lifetime uint32) []byte {
+	req := make([]byte, mapRequestSize)
+
+	// Header
+	req[0] = Version
+	req[1] = OpMap
+	binary.BigEndian.PutUint32(req[4:8], lifetime)
+	mapped := addrTo16(clientIP)
+	copy(req[8:24], mapped[:])
+
+	// MAP payload
+	copy(req[24:36], nonce[:])
+	req[36] = protocol
+	binary.BigEndian.PutUint16(req[40:42], internalPort)
+	binary.BigEndian.PutUint16(req[42:44], suggestedExtPort)
+	if suggestedExtIP.IsValid() {
+		extMapped := addrTo16(suggestedExtIP)
+		copy(req[44:60], extMapped[:])
+	}
+
+	return req
+}
+
+// parseResponse parses the common PCP response header.
+func parseResponse(data []byte) (*Response, error) {
+	if len(data) < headerSize {
+		return nil, fmt.Errorf("response too short: %d bytes", len(data))
+	}
+
+	resp := &Response{
+		Version:    data[0],
+		Opcode:     data[1],
+		ResultCode: data[3], // Byte 2 is reserved, byte 3 is result code (RFC 6887 §7.2)
+		Lifetime:   binary.BigEndian.Uint32(data[4:8]),
+		Epoch:      binary.BigEndian.Uint32(data[8:12]),
+	}
+
+	if resp.Version != Version {
+		return nil, fmt.Errorf("unsupported PCP version: %d", resp.Version)
+	}
+
+	if resp.Opcode&OpReply == 0 {
+		return nil, fmt.Errorf("response missing reply bit: opcode=0x%02x", resp.Opcode)
+	}
+
+	return resp, nil
+}
+
+// parseMapResponse parses a complete MAP response.
+func parseMapResponse(data []byte) (*MapResponse, error) {
+	if len(data) < mapRequestSize {
+		return nil, fmt.Errorf("MAP response too short: %d bytes", len(data))
+	}
+
+	resp, err := parseResponse(data)
+	if err != nil {
+		return nil, fmt.Errorf("parse header: %w", err)
+	}
+
+	mapResp := &MapResponse{
+		Response:     *resp,
+		Protocol:     data[36],
+		InternalPort: binary.BigEndian.Uint16(data[40:42]),
+		ExternalPort: binary.BigEndian.Uint16(data[42:44]),
+		ExternalIP:   addrFrom16([16]byte(data[44:60])),
+	}
+	copy(mapResp.Nonce[:], data[24:36])
+
+	return mapResp, nil
+}

client/internal/portforward/state.go

@@ -0,0 +1,63 @@
+//go:build !js
+
+package portforward
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/libp2p/go-nat"
+	log "github.com/sirupsen/logrus"
+
+	"github.com/netbirdio/netbird/client/internal/portforward/pcp"
+)
+
+// discoverGateway is the function used for NAT gateway discovery.
+// It can be replaced in tests to avoid real network operations.
+// Tries PCP first, then falls back to NAT-PMP/UPnP.
+var discoverGateway = defaultDiscoverGateway
+
+func defaultDiscoverGateway(ctx context.Context) (nat.NAT, error) {
+	pcpGateway, err := pcp.DiscoverPCP(ctx)
+	if err == nil {
+		return pcpGateway, nil
+	}
+	log.Debugf("PCP discovery failed: %v, trying NAT-PMP/UPnP", err)
+
+	return nat.DiscoverGateway(ctx)
+}
+
+// State is persisted only for crash recovery cleanup
+type State struct {
+	InternalPort uint16 `json:"internal_port,omitempty"`
+	Protocol     string `json:"protocol,omitempty"`
+}
+
+func (s *State) Name() string {
+	return "port_forward_state"
+}
+
+// Cleanup implements statemanager.CleanableState for crash recovery
+func (s *State) Cleanup() error {
+	if s.InternalPort == 0 {
+		return nil
+	}
+
+	log.Infof("cleaning up stale port mapping for port %d", s.InternalPort)
+
+	ctx, cancel := context.WithTimeout(context.Background(), discoveryTimeout)
+	defer cancel()
+
+	gateway, err := discoverGateway(ctx)
+	if err != nil {
+		// Discovery failure is not an error - gateway may not exist
+		log.Debugf("cleanup: no gateway found: %v", err)
+		return nil
+	}
+
+	if err := gateway.DeletePortMapping(ctx, s.Protocol, int(s.InternalPort)); err != nil {
+		return fmt.Errorf("delete port mapping: %w", err)
+	}
+
+	return nil
+}

client/internal/routemanager/manager.go

@@ -168,6 +168,7 @@ func (m *DefaultManager) setupAndroidRoutes(config ManagerConfig) {
 			NetworkType: route.IPv4Network,
 		}
 		cr = append(cr, fakeIPRoute)
+		m.notifier.SetFakeIPRoute(fakeIPRoute)
 	}
 
 	m.notifier.SetInitialClientRoutes(cr, routesForComparison)

client/internal/routemanager/notifier/notifier_android.go

@@ -16,6 +16,7 @@ import (
 type Notifier struct {
 	initialRoutes []*route.Route
 	currentRoutes []*route.Route
+	fakeIPRoute   *route.Route
 
 	listener    listener.NetworkChangeListener
 	listenerMux sync.Mutex
@@ -31,13 +32,17 @@ func (n *Notifier) SetListener(listener listener.NetworkChangeListener) {
 	n.listener = listener
 }
 
-// SetInitialClientRoutes stores the full initial route set (including fake IP blocks)
-// and a separate comparison set (without fake IP blocks) for diff detection.
+// SetInitialClientRoutes stores the initial route sets for TUN configuration.
 func (n *Notifier) SetInitialClientRoutes(initialRoutes []*route.Route, routesForComparison []*route.Route) {
 	n.initialRoutes = filterStatic(initialRoutes)
 	n.currentRoutes = filterStatic(routesForComparison)
 }
 
+// SetFakeIPRoute stores the fake IP route to be included in every TUN rebuild.
+func (n *Notifier) SetFakeIPRoute(r *route.Route) {
+	n.fakeIPRoute = r
+}
+
 func (n *Notifier) OnNewRoutes(idMap route.HAMap) {
 	var newRoutes []*route.Route
 	for _, routes := range idMap {
@@ -69,7 +74,9 @@ func (n *Notifier) notify() {
 	}
 
 	allRoutes := slices.Clone(n.currentRoutes)
-	allRoutes = append(allRoutes, n.extraInitialRoutes()...)
+	if n.fakeIPRoute != nil {
+		allRoutes = append(allRoutes, n.fakeIPRoute)
+	}
 
 	routeStrings := n.routesToStrings(allRoutes)
 	sort.Strings(routeStrings)
@@ -78,23 +85,6 @@ func (n *Notifier) notify() {
 	}(n.listener)
 }
 
-// extraInitialRoutes returns initialRoutes whose network prefix is absent
-// from currentRoutes (e.g. the fake IP block added at setup time).
-func (n *Notifier) extraInitialRoutes() []*route.Route {
-	currentNets := make(map[netip.Prefix]struct{}, len(n.currentRoutes))
-	for _, r := range n.currentRoutes {
-		currentNets[r.Network] = struct{}{}
-	}
-
-	var extra []*route.Route
-	for _, r := range n.initialRoutes {
-		if _, ok := currentNets[r.Network]; !ok {
-			extra = append(extra, r)
-		}
-	}
-	return extra
-}
-
 func filterStatic(routes []*route.Route) []*route.Route {
 	out := make([]*route.Route, 0, len(routes))
 	for _, r := range routes {

client/internal/routemanager/notifier/notifier_ios.go

@@ -34,6 +34,10 @@ func (n *Notifier) SetInitialClientRoutes([]*route.Route, []*route.Route) {
 	// iOS doesn't care about initial routes
 }
 
+func (n *Notifier) SetFakeIPRoute(*route.Route) {
+	// Not used on iOS
+}
+
 func (n *Notifier) OnNewRoutes(route.HAMap) {
 	// Not used on iOS
 }

client/internal/routemanager/notifier/notifier_other.go

@@ -23,6 +23,10 @@ func (n *Notifier) SetInitialClientRoutes([]*route.Route, []*route.Route) {
 	// Not used on non-mobile platforms
 }
 
+func (n *Notifier) SetFakeIPRoute(*route.Route) {
+	// Not used on non-mobile platforms
+}
+
 func (n *Notifier) OnNewRoutes(idMap route.HAMap) {
 	// Not used on non-mobile platforms
 }

client/internal/routemanager/systemops/systemops_bsd_other.go

@@ -0,0 +1,10 @@
+//go:build (dragonfly || freebsd || netbsd || openbsd) && !darwin
+
+package systemops
+
+// Non-darwin BSDs don't support the IP_BOUND_IF + scoped default model. They
+// always fall through to the ref-counter exclusion-route path; these stubs
+// exist only so systemops_unix.go compiles.
+func (r *SysOps) setupAdvancedRouting() error   { return nil }
+func (r *SysOps) cleanupAdvancedRouting() error { return nil }
+func (r *SysOps) flushPlatformExtras() error    { return nil }

client/internal/routemanager/systemops/systemops_darwin.go

@@ -0,0 +1,241 @@
+//go:build darwin && !ios
+
+package systemops
+
+import (
+	"errors"
+	"fmt"
+	"net/netip"
+	"os"
+	"time"
+
+	"github.com/hashicorp/go-multierror"
+	log "github.com/sirupsen/logrus"
+	"golang.org/x/net/route"
+	"golang.org/x/sys/unix"
+
+	nberrors "github.com/netbirdio/netbird/client/errors"
+	"github.com/netbirdio/netbird/client/internal/routemanager/vars"
+	nbnet "github.com/netbirdio/netbird/client/net"
+)
+
+// scopedRouteBudget bounds retries for the scoped default route. Installing or
+// deleting it matters enough that we're willing to spend longer waiting for the
+// kernel reply than for per-prefix exclusion routes.
+const scopedRouteBudget = 5 * time.Second
+
+// setupAdvancedRouting installs an RTF_IFSCOPE default route per address family
+// pinned to the current physical egress, so IP_BOUND_IF scoped lookups can
+// resolve gateway'd destinations while the VPN's split default owns the
+// unscoped table.
+//
+// Timing note: this runs during routeManager.Init, which happens before the
+// VPN interface is created and before any peer routes propagate. The initial
+// mgmt / signal / relay TCP dials always fire before this runs, so those
+// sockets miss the IP_BOUND_IF binding and rely on the kernel's normal route
+// lookup, which at that point correctly picks the physical default. Those
+// already-established TCP flows keep their originally-selected interface for
+// their lifetime on Darwin because the kernel caches the egress route
+// per-socket at connect time; adding the VPN's 0/1 + 128/1 split default
+// afterwards does not migrate them since the original en0 default stays in
+// the table. Any subsequent reconnect via nbnet.NewDialer picks up the
+// populated bound-iface cache and gets IP_BOUND_IF set cleanly.
+func (r *SysOps) setupAdvancedRouting() error {
+	// Drop any previously-cached egress interface before reinstalling. On a
+	// refresh, a family that no longer resolves would otherwise keep the stale
+	// binding, causing new sockets to scope to an interface without a matching
+	// scoped default.
+	nbnet.ClearBoundInterfaces()
+
+	if err := r.flushScopedDefaults(); err != nil {
+		log.Warnf("flush residual scoped defaults: %v", err)
+	}
+
+	var merr *multierror.Error
+	installed := 0
+
+	for _, unspec := range []netip.Addr{netip.IPv4Unspecified(), netip.IPv6Unspecified()} {
+		ok, err := r.installScopedDefaultFor(unspec)
+		if err != nil {
+			merr = multierror.Append(merr, err)
+			continue
+		}
+		if ok {
+			installed++
+		}
+	}
+
+	if installed == 0 && merr != nil {
+		return nberrors.FormatErrorOrNil(merr)
+	}
+	if merr != nil {
+		log.Warnf("advanced routing setup partially succeeded: %v", nberrors.FormatErrorOrNil(merr))
+	}
+	return nil
+}
+
+// installScopedDefaultFor resolves the physical default nexthop for the given
+// address family, installs a scoped default via it, and caches the iface for
+// subsequent IP_BOUND_IF / IPV6_BOUND_IF socket binds.
+func (r *SysOps) installScopedDefaultFor(unspec netip.Addr) (bool, error) {
+	nexthop, err := GetNextHop(unspec)
+	if err != nil {
+		if errors.Is(err, vars.ErrRouteNotFound) {
+			return false, nil
+		}
+		return false, fmt.Errorf("get default nexthop for %s: %w", unspec, err)
+	}
+	if nexthop.Intf == nil {
+		return false, fmt.Errorf("unusable default nexthop for %s (no interface)", unspec)
+	}
+
+	if err := r.addScopedDefault(unspec, nexthop); err != nil {
+		return false, fmt.Errorf("add scoped default on %s: %w", nexthop.Intf.Name, err)
+	}
+
+	af := unix.AF_INET
+	if unspec.Is6() {
+		af = unix.AF_INET6
+	}
+	nbnet.SetBoundInterface(af, nexthop.Intf)
+	via := "point-to-point"
+	if nexthop.IP.IsValid() {
+		via = nexthop.IP.String()
+	}
+	log.Infof("installed scoped default route via %s on %s for %s", via, nexthop.Intf.Name, afOf(unspec))
+	return true, nil
+}
+
+func (r *SysOps) cleanupAdvancedRouting() error {
+	nbnet.ClearBoundInterfaces()
+	return r.flushScopedDefaults()
+}
+
+// flushPlatformExtras runs darwin-specific residual cleanup hooked into the
+// generic FlushMarkedRoutes path, so a crashed daemon's scoped defaults get
+// removed on the next boot regardless of whether a profile is brought up.
+func (r *SysOps) flushPlatformExtras() error {
+	return r.flushScopedDefaults()
+}
+
+// flushScopedDefaults removes any scoped default routes tagged with routeProtoFlag.
+// Safe to call at startup to clear residual entries from a prior session.
+func (r *SysOps) flushScopedDefaults() error {
+	rib, err := retryFetchRIB()
+	if err != nil {
+		return fmt.Errorf("fetch routing table: %w", err)
+	}
+
+	msgs, err := route.ParseRIB(route.RIBTypeRoute, rib)
+	if err != nil {
+		return fmt.Errorf("parse routing table: %w", err)
+	}
+
+	var merr *multierror.Error
+	removed := 0
+
+	for _, msg := range msgs {
+		rtMsg, ok := msg.(*route.RouteMessage)
+		if !ok {
+			continue
+		}
+		if rtMsg.Flags&routeProtoFlag == 0 {
+			continue
+		}
+		if rtMsg.Flags&unix.RTF_IFSCOPE == 0 {
+			continue
+		}
+
+		info, err := MsgToRoute(rtMsg)
+		if err != nil {
+			log.Debugf("skip scoped flush: %v", err)
+			continue
+		}
+		if !info.Dst.IsValid() || info.Dst.Bits() != 0 {
+			continue
+		}
+
+		if err := r.deleteScopedRoute(rtMsg); err != nil {
+			merr = multierror.Append(merr, fmt.Errorf("delete scoped default %s on index %d: %w",
+				info.Dst, rtMsg.Index, err))
+			continue
+		}
+		removed++
+		log.Debugf("flushed residual scoped default %s on index %d", info.Dst, rtMsg.Index)
+	}
+
+	if removed > 0 {
+		log.Infof("flushed %d residual scoped default route(s)", removed)
+	}
+	return nberrors.FormatErrorOrNil(merr)
+}
+
+func (r *SysOps) addScopedDefault(unspec netip.Addr, nexthop Nexthop) error {
+	return r.scopedRouteSocket(unix.RTM_ADD, unspec, nexthop)
+}
+
+func (r *SysOps) deleteScopedRoute(rtMsg *route.RouteMessage) error {
+	// Preserve identifying flags from the stored route (including RTF_GATEWAY
+	// only if present); kernel-set bits like RTF_DONE don't belong on RTM_DELETE.
+	keep := unix.RTF_UP | unix.RTF_STATIC | unix.RTF_GATEWAY | unix.RTF_IFSCOPE | routeProtoFlag
+	del := &route.RouteMessage{
+		Type:    unix.RTM_DELETE,
+		Flags:   rtMsg.Flags & keep,
+		Version: unix.RTM_VERSION,
+		Seq:     r.getSeq(),
+		Index:   rtMsg.Index,
+		Addrs:   rtMsg.Addrs,
+	}
+	return r.writeRouteMessage(del, scopedRouteBudget)
+}
+
+func (r *SysOps) scopedRouteSocket(action int, unspec netip.Addr, nexthop Nexthop) error {
+	flags := unix.RTF_UP | unix.RTF_STATIC | unix.RTF_IFSCOPE | routeProtoFlag
+
+	msg := &route.RouteMessage{
+		Type:    action,
+		Flags:   flags,
+		Version: unix.RTM_VERSION,
+		ID:      uintptr(os.Getpid()),
+		Seq:     r.getSeq(),
+		Index:   nexthop.Intf.Index,
+	}
+
+	const numAddrs = unix.RTAX_NETMASK + 1
+	addrs := make([]route.Addr, numAddrs)
+
+	dst, err := addrToRouteAddr(unspec)
+	if err != nil {
+		return fmt.Errorf("build destination: %w", err)
+	}
+	mask, err := prefixToRouteNetmask(netip.PrefixFrom(unspec, 0))
+	if err != nil {
+		return fmt.Errorf("build netmask: %w", err)
+	}
+	addrs[unix.RTAX_DST] = dst
+	addrs[unix.RTAX_NETMASK] = mask
+
+	if nexthop.IP.IsValid() {
+		msg.Flags |= unix.RTF_GATEWAY
+		gw, err := addrToRouteAddr(nexthop.IP.Unmap())
+		if err != nil {
+			return fmt.Errorf("build gateway: %w", err)
+		}
+		addrs[unix.RTAX_GATEWAY] = gw
+	} else {
+		addrs[unix.RTAX_GATEWAY] = &route.LinkAddr{
+			Index: nexthop.Intf.Index,
+			Name:  nexthop.Intf.Name,
+		}
+	}
+	msg.Addrs = addrs
+
+	return r.writeRouteMessage(msg, scopedRouteBudget)
+}
+
+func afOf(a netip.Addr) string {
+	if a.Is4() {
+		return "IPv4"
+	}
+	return "IPv6"
+}

client/internal/routemanager/systemops/systemops_generic.go

@@ -21,6 +21,7 @@ import (
 	"github.com/netbirdio/netbird/client/internal/routemanager/util"
 	"github.com/netbirdio/netbird/client/internal/routemanager/vars"
 	"github.com/netbirdio/netbird/client/internal/statemanager"
+	nbnet "github.com/netbirdio/netbird/client/net"
 	"github.com/netbirdio/netbird/client/net/hooks"
 )
 
@@ -31,8 +32,6 @@ var splitDefaultv4_2 = netip.PrefixFrom(netip.AddrFrom4([4]byte{128}), 1)
 var splitDefaultv6_1 = netip.PrefixFrom(netip.IPv6Unspecified(), 1)
 var splitDefaultv6_2 = netip.PrefixFrom(netip.AddrFrom16([16]byte{0x80}), 1)
 
-var ErrRoutingIsSeparate = errors.New("routing is separate")
-
 func (r *SysOps) setupRefCounter(initAddresses []net.IP, stateManager *statemanager.Manager) error {
 	stateManager.RegisterState(&ShutdownState{})
 
@@ -397,12 +396,16 @@ func ipToAddr(ip net.IP, intf *net.Interface) (netip.Addr, error) {
 }
 
 // IsAddrRouted checks if the candidate address would route to the vpn, in which case it returns true and the matched prefix.
+// When advanced routing is active the WG socket is bound to the physical interface (fwmark on linux,
+// IP_UNICAST_IF on windows, IP_BOUND_IF on darwin) and bypasses the main routing table, so the check is skipped.
 func IsAddrRouted(addr netip.Addr, vpnRoutes []netip.Prefix) (bool, netip.Prefix) {
-	localRoutes, err := hasSeparateRouting()
+	if nbnet.AdvancedRouting() {
+		return false, netip.Prefix{}
+	}
+
+	localRoutes, err := GetRoutesFromTable()
 	if err != nil {
-		if !errors.Is(err, ErrRoutingIsSeparate) {
-			log.Errorf("Failed to get routes: %v", err)
-		}
+		log.Errorf("Failed to get routes: %v", err)
 		return false, netip.Prefix{}
 	}
 

client/internal/routemanager/systemops/systemops_js.go

@@ -22,10 +22,6 @@ func GetRoutesFromTable() ([]netip.Prefix, error) {
 	return []netip.Prefix{}, nil
 }
 
-func hasSeparateRouting() ([]netip.Prefix, error) {
-	return []netip.Prefix{}, nil
-}
-
 // GetDetailedRoutesFromTable returns empty routes for WASM.
 func GetDetailedRoutesFromTable() ([]DetailedRoute, error) {
 	return []DetailedRoute{}, nil

client/internal/routemanager/systemops/systemops_linux.go

@@ -894,13 +894,6 @@ func getAddressFamily(prefix netip.Prefix) int {
 	return netlink.FAMILY_V6
 }
 
-func hasSeparateRouting() ([]netip.Prefix, error) {
-	if !nbnet.AdvancedRouting() {
-		return GetRoutesFromTable()
-	}
-	return nil, ErrRoutingIsSeparate
-}
-
 func isOpErr(err error) bool {
 	// EAFTNOSUPPORT when ipv6 is disabled via sysctl, EOPNOTSUPP when disabled in boot options or otherwise not supported
 	if errors.Is(err, syscall.EAFNOSUPPORT) || errors.Is(err, syscall.EOPNOTSUPP) {

client/internal/routemanager/systemops/systemops_nonlinux.go

@@ -48,10 +48,6 @@ func EnableIPForwarding() error {
 	return nil
 }
 
-func hasSeparateRouting() ([]netip.Prefix, error) {
-	return GetRoutesFromTable()
-}
-
 // GetIPRules returns IP rules for debugging (not supported on non-Linux platforms)
 func GetIPRules() ([]IPRule, error) {
 	log.Infof("IP rules collection is not supported on %s", runtime.GOOS)

client/internal/routemanager/systemops/systemops_unix.go

@@ -25,6 +25,9 @@ import (
 
 const (
 	envRouteProtoFlag = "NB_ROUTE_PROTO_FLAG"
+
+	// routeBudget bounds retries for per-prefix exclusion route programming.
+	routeBudget = 1 * time.Second
 )
 
 var routeProtoFlag int
@@ -41,26 +44,42 @@ func init() {
 }
 
 func (r *SysOps) SetupRouting(initAddresses []net.IP, stateManager *statemanager.Manager, advancedRouting bool) error {
+	if advancedRouting {
+		return r.setupAdvancedRouting()
+	}
+
+	log.Infof("Using legacy routing setup with ref counters")
 	return r.setupRefCounter(initAddresses, stateManager)
 }
 
 func (r *SysOps) CleanupRouting(stateManager *statemanager.Manager, advancedRouting bool) error {
+	if advancedRouting {
+		return r.cleanupAdvancedRouting()
+	}
+
 	return r.cleanupRefCounter(stateManager)
 }
 
 // FlushMarkedRoutes removes single IP exclusion routes marked with the configured RTF_PROTO flag.
+// On darwin it also flushes residual RTF_IFSCOPE scoped default routes so a
+// crashed prior session can't leave crud in the table.
 func (r *SysOps) FlushMarkedRoutes() error {
+	var merr *multierror.Error
+
+	if err := r.flushPlatformExtras(); err != nil {
+		merr = multierror.Append(merr, fmt.Errorf("flush platform extras: %w", err))
+	}
+
 	rib, err := retryFetchRIB()
 	if err != nil {
-		return fmt.Errorf("fetch routing table: %w", err)
+		return nberrors.FormatErrorOrNil(multierror.Append(merr, fmt.Errorf("fetch routing table: %w", err)))
 	}
 
 	msgs, err := route.ParseRIB(route.RIBTypeRoute, rib)
 	if err != nil {
-		return fmt.Errorf("parse routing table: %w", err)
+		return nberrors.FormatErrorOrNil(multierror.Append(merr, fmt.Errorf("parse routing table: %w", err)))
 	}
 
-	var merr *multierror.Error
 	flushedCount := 0
 
 	for _, msg := range msgs {
@@ -117,12 +136,12 @@ func (r *SysOps) routeSocket(action int, prefix netip.Prefix, nexthop Nexthop) e
 		return fmt.Errorf("invalid prefix: %s", prefix)
 	}
 
-	expBackOff := backoff.NewExponentialBackOff()
-	expBackOff.InitialInterval = 50 * time.Millisecond
-	expBackOff.MaxInterval = 500 * time.Millisecond
-	expBackOff.MaxElapsedTime = 1 * time.Second
+	msg, err := r.buildRouteMessage(action, prefix, nexthop)
+	if err != nil {
+		return fmt.Errorf("build route message: %w", err)
+	}
 
-	if err := backoff.Retry(r.routeOp(action, prefix, nexthop), expBackOff); err != nil {
+	if err := r.writeRouteMessage(msg, routeBudget); err != nil {
 		a := "add"
 		if action == unix.RTM_DELETE {
 			a = "remove"
@@ -132,50 +151,91 @@ func (r *SysOps) routeSocket(action int, prefix netip.Prefix, nexthop Nexthop) e
 	return nil
 }
 
-func (r *SysOps) routeOp(action int, prefix netip.Prefix, nexthop Nexthop) func() error {
-	operation := func() error {
-		fd, err := unix.Socket(syscall.AF_ROUTE, syscall.SOCK_RAW, syscall.AF_UNSPEC)
-		if err != nil {
-			return fmt.Errorf("open routing socket: %w", err)
+// writeRouteMessage sends a route message over AF_ROUTE and waits for the
+// kernel's matching reply, retrying transient failures until budget elapses.
+// Callers do not need to manage sockets or seq numbers themselves.
+func (r *SysOps) writeRouteMessage(msg *route.RouteMessage, budget time.Duration) error {
+	expBackOff := backoff.NewExponentialBackOff()
+	expBackOff.InitialInterval = 50 * time.Millisecond
+	expBackOff.MaxInterval = 500 * time.Millisecond
+	expBackOff.MaxElapsedTime = budget
+
+	return backoff.Retry(func() error { return routeMessageRoundtrip(msg) }, expBackOff)
+}
+
+func routeMessageRoundtrip(msg *route.RouteMessage) error {
+	fd, err := unix.Socket(syscall.AF_ROUTE, syscall.SOCK_RAW, syscall.AF_UNSPEC)
+	if err != nil {
+		return fmt.Errorf("open routing socket: %w", err)
+	}
+	defer func() {
+		if err := unix.Close(fd); err != nil && !errors.Is(err, unix.EBADF) {
+			log.Warnf("close routing socket: %v", err)
 		}
-		defer func() {
-			if err := unix.Close(fd); err != nil && !errors.Is(err, unix.EBADF) {
-				log.Warnf("failed to close routing socket: %v", err)
+	}()
+
+	tv := unix.Timeval{Sec: 1}
+	if err := unix.SetsockoptTimeval(fd, unix.SOL_SOCKET, unix.SO_RCVTIMEO, &tv); err != nil {
+		return backoff.Permanent(fmt.Errorf("set recv timeout: %w", err))
+	}
+
+	// AF_ROUTE is a broadcast channel: every route socket on the host sees
+	// every RTM_* event. With concurrent route programming the default
+	// per-socket queue overflows and our own reply gets dropped.
+	if err := unix.SetsockoptInt(fd, unix.SOL_SOCKET, unix.SO_RCVBUF, 1<<20); err != nil {
+		log.Debugf("set SO_RCVBUF on route socket: %v", err)
+	}
+
+	bytes, err := msg.Marshal()
+	if err != nil {
+		return backoff.Permanent(fmt.Errorf("marshal: %w", err))
+	}
+
+	if _, err = unix.Write(fd, bytes); err != nil {
+		if errors.Is(err, unix.ENOBUFS) || errors.Is(err, unix.EAGAIN) {
+			return fmt.Errorf("write: %w", err)
+		}
+		return backoff.Permanent(fmt.Errorf("write: %w", err))
+	}
+	return readRouteResponse(fd, msg.Type, msg.Seq)
+}
+
+// readRouteResponse reads from the AF_ROUTE socket until it sees a reply
+// matching our write (same type, seq, and pid). AF_ROUTE SOCK_RAW is a
+// broadcast channel: interface up/down, third-party route changes and neighbor
+// discovery events can all land between our write and read, so we must filter.
+func readRouteResponse(fd, wantType, wantSeq int) error {
+	pid := int32(os.Getpid())
+	resp := make([]byte, 2048)
+	deadline := time.Now().Add(time.Second)
+	for {
+		if time.Now().After(deadline) {
+			// Transient: under concurrent pressure the kernel can drop our reply
+			// from the socket buffer. Let backoff.Retry re-send with a fresh seq.
+			return fmt.Errorf("read: timeout waiting for route reply type=%d seq=%d", wantType, wantSeq)
+		}
+		n, err := unix.Read(fd, resp)
+		if err != nil {
+			if errors.Is(err, unix.EAGAIN) || errors.Is(err, unix.EWOULDBLOCK) {
+				// SO_RCVTIMEO fired while waiting; loop to re-check the absolute deadline.
+				continue
 			}
-		}()
-
-		msg, err := r.buildRouteMessage(action, prefix, nexthop)
-		if err != nil {
-			return backoff.Permanent(fmt.Errorf("build route message: %w", err))
+			return backoff.Permanent(fmt.Errorf("read: %w", err))
 		}
-
-		msgBytes, err := msg.Marshal()
-		if err != nil {
-			return backoff.Permanent(fmt.Errorf("marshal route message: %w", err))
+		if n < int(unsafe.Sizeof(unix.RtMsghdr{})) {
+			continue
 		}
-
-		if _, err = unix.Write(fd, msgBytes); err != nil {
-			if errors.Is(err, unix.ENOBUFS) || errors.Is(err, unix.EAGAIN) {
-				return fmt.Errorf("write: %w", err)
-			}
-			return backoff.Permanent(fmt.Errorf("write: %w", err))
+		hdr := (*unix.RtMsghdr)(unsafe.Pointer(&resp[0]))
+		// Darwin reflects the sender's pid on replies; matching (Type, Seq, Pid)
+		// uniquely identifies our own reply among broadcast traffic.
+		if int(hdr.Type) != wantType || int(hdr.Seq) != wantSeq || hdr.Pid != pid {
+			continue
 		}
-
-		respBuf := make([]byte, 2048)
-		n, err := unix.Read(fd, respBuf)
-		if err != nil {
-			return backoff.Permanent(fmt.Errorf("read route response: %w", err))
+		if hdr.Errno != 0 {
+			return backoff.Permanent(fmt.Errorf("kernel: %w", syscall.Errno(hdr.Errno)))
 		}
-
-		if n > 0 {
-			if err := r.parseRouteResponse(respBuf[:n]); err != nil {
-				return backoff.Permanent(err)
-			}
-		}
-
 		return nil
 	}
-	return operation
 }
 
 func (r *SysOps) buildRouteMessage(action int, prefix netip.Prefix, nexthop Nexthop) (msg *route.RouteMessage, err error) {
@@ -183,6 +243,7 @@ func (r *SysOps) buildRouteMessage(action int, prefix netip.Prefix, nexthop Next
 		Type:    action,
 		Flags:   unix.RTF_UP | routeProtoFlag,
 		Version: unix.RTM_VERSION,
+		ID:      uintptr(os.Getpid()),
 		Seq:     r.getSeq(),
 	}
 
@@ -221,19 +282,6 @@ func (r *SysOps) buildRouteMessage(action int, prefix netip.Prefix, nexthop Next
 	return msg, nil
 }
 
-func (r *SysOps) parseRouteResponse(buf []byte) error {
-	if len(buf) < int(unsafe.Sizeof(unix.RtMsghdr{})) {
-		return nil
-	}
-
-	rtMsg := (*unix.RtMsghdr)(unsafe.Pointer(&buf[0]))
-	if rtMsg.Errno != 0 {
-		return fmt.Errorf("parse: %d", rtMsg.Errno)
-	}
-
-	return nil
-}
-
 // addrToRouteAddr converts a netip.Addr to the appropriate route.Addr (*route.Inet4Addr or *route.Inet6Addr).
 func addrToRouteAddr(addr netip.Addr) (route.Addr, error) {
 	if addr.Is4() {

client/net/dialer_init_darwin.go

@@ -0,0 +1,5 @@
+package net
+
+func (d *Dialer) init() {
+	d.Dialer.Control = applyBoundIfToSocket
+}

client/net/dialer_init_generic.go

@@ -1,4 +1,4 @@
-//go:build !linux && !windows
+//go:build !linux && !windows && !darwin
 
 package net
 

client/net/env_android.go

@@ -1,24 +0,0 @@
-//go:build android
-
-package net
-
-// Init initializes the network environment for Android
-func Init() {
-	// No initialization needed on Android
-}
-
-// AdvancedRouting reports whether routing loops can be avoided without using exclusion routes.
-// Always returns true on Android since we cannot handle routes dynamically.
-func AdvancedRouting() bool {
-	return true
-}
-
-// SetVPNInterfaceName is a no-op on Android
-func SetVPNInterfaceName(name string) {
-	// No-op on Android - not needed for Android VPN service
-}
-
-// GetVPNInterfaceName returns empty string on Android
-func GetVPNInterfaceName() string {
-	return ""
-}

client/net/env_bound_iface.go

@@ -1,4 +1,4 @@
-//go:build windows
+//go:build (darwin && !ios) || windows
 
 package net
 
@@ -24,17 +24,22 @@ func Init() {
 }
 
 func checkAdvancedRoutingSupport() bool {
-	var err error
-	var legacyRouting bool
+	legacyRouting := false
 	if val := os.Getenv(envUseLegacyRouting); val != "" {
-		legacyRouting, err = strconv.ParseBool(val)
+		parsed, err := strconv.ParseBool(val)
 		if err != nil {
-			log.Warnf("failed to parse %s: %v", envUseLegacyRouting, err)
+			log.Warnf("ignoring unparsable %s=%q: %v", envUseLegacyRouting, val, err)
+		} else {
+			legacyRouting = parsed
 		}
 	}
 
-	if legacyRouting || netstack.IsEnabled() {
-		log.Info("advanced routing has been requested to be disabled")
+	if legacyRouting {
+		log.Infof("advanced routing disabled: legacy routing requested via %s", envUseLegacyRouting)
+		return false
+	}
+	if netstack.IsEnabled() {
+		log.Info("advanced routing disabled: netstack mode is enabled")
 		return false
 	}
 

client/net/env_generic.go

@@ -1,4 +1,4 @@
-//go:build !linux && !windows && !android
+//go:build !linux && !windows && !darwin
 
 package net
 

client/net/env_mobile.go

@@ -0,0 +1,25 @@
+//go:build ios || android
+
+package net
+
+// Init initializes the network environment for mobile platforms.
+func Init() {
+	// no-op on mobile: routing scope is owned by the VPN extension.
+}
+
+// AdvancedRouting reports whether routing loops can be avoided without using exclusion routes.
+// Always returns true on mobile since routes cannot be handled dynamically and the VPN extension
+// owns the routing scope.
+func AdvancedRouting() bool {
+	return true
+}
+
+// SetVPNInterfaceName is a no-op on mobile.
+func SetVPNInterfaceName(string) {
+	// no-op on mobile: the VPN extension manages the interface.
+}
+
+// GetVPNInterfaceName returns an empty string on mobile.
+func GetVPNInterfaceName() string {
+	return ""
+}

client/net/listener_init_darwin.go

@@ -0,0 +1,5 @@
+package net
+
+func (l *ListenerConfig) init() {
+	l.ListenConfig.Control = applyBoundIfToSocket
+}

client/net/listener_init_generic.go

@@ -1,4 +1,4 @@
-//go:build !linux && !windows
+//go:build !linux && !windows && !darwin
 
 package net
 

client/net/net_darwin.go

@@ -0,0 +1,160 @@
+package net
+
+import (
+	"fmt"
+	"net"
+	"net/netip"
+	"strconv"
+	"strings"
+	"sync"
+	"syscall"
+
+	log "github.com/sirupsen/logrus"
+	"golang.org/x/sys/unix"
+)
+
+// On darwin IPV6_BOUND_IF also scopes v4-mapped egress from dual-stack
+// (IPV6_V6ONLY=0) AF_INET6 sockets, so a single setsockopt on "udp6"/"tcp6"
+// covers both families. Setting IP_BOUND_IF on an AF_INET6 socket returns
+// EINVAL regardless of V6ONLY because the IPPROTO_IP ctloutput path is
+// dispatched by socket domain (AF_INET only) not by inp_vflag.
+
+// boundIface holds the physical interface chosen at routing setup time. Sockets
+// created via nbnet.NewDialer / nbnet.NewListener bind to it via IP_BOUND_IF
+// (IPv4) or IPV6_BOUND_IF (IPv6 / dual-stack) so their scoped route lookup
+// hits the RTF_IFSCOPE default installed by the routemanager, rather than
+// following the VPN's split default.
+var (
+	boundIfaceMu sync.RWMutex
+	boundIface4  *net.Interface
+	boundIface6  *net.Interface
+)
+
+// SetBoundInterface records the egress interface for an address family. Called
+// by the routemanager after a scoped default route has been installed.
+// af must be unix.AF_INET or unix.AF_INET6; other values are ignored.
+// nil iface is rejected — use ClearBoundInterfaces to clear all slots.
+func SetBoundInterface(af int, iface *net.Interface) {
+	if iface == nil {
+		log.Warnf("SetBoundInterface: nil iface for AF %d, ignored", af)
+		return
+	}
+	boundIfaceMu.Lock()
+	defer boundIfaceMu.Unlock()
+	switch af {
+	case unix.AF_INET:
+		boundIface4 = iface
+	case unix.AF_INET6:
+		boundIface6 = iface
+	default:
+		log.Warnf("SetBoundInterface: unsupported address family %d", af)
+	}
+}
+
+// ClearBoundInterfaces resets the cached egress interfaces. Called by the
+// routemanager during cleanup.
+func ClearBoundInterfaces() {
+	boundIfaceMu.Lock()
+	defer boundIfaceMu.Unlock()
+	boundIface4 = nil
+	boundIface6 = nil
+}
+
+// boundInterfaceFor returns the cached egress interface for a socket's address
+// family, falling back to the other family if the preferred slot is empty.
+// The kernel stores both IP_BOUND_IF and IPV6_BOUND_IF in inp_boundifp, so
+// either setsockopt scopes the socket; preferring same-family still matters
+// when v4 and v6 defaults egress different NICs.
+func boundInterfaceFor(network, address string) *net.Interface {
+	if iface := zoneInterface(address); iface != nil {
+		return iface
+	}
+
+	boundIfaceMu.RLock()
+	defer boundIfaceMu.RUnlock()
+
+	primary, secondary := boundIface4, boundIface6
+	if isV6Network(network) {
+		primary, secondary = boundIface6, boundIface4
+	}
+	if primary != nil {
+		return primary
+	}
+	return secondary
+}
+
+func isV6Network(network string) bool {
+	return strings.HasSuffix(network, "6")
+}
+
+// zoneInterface extracts an explicit interface from an IPv6 link-local zone (e.g. fe80::1%en0).
+func zoneInterface(address string) *net.Interface {
+	if address == "" {
+		return nil
+	}
+	addr, err := netip.ParseAddrPort(address)
+	if err != nil {
+		a, err := netip.ParseAddr(address)
+		if err != nil {
+			return nil
+		}
+		addr = netip.AddrPortFrom(a, 0)
+	}
+	zone := addr.Addr().Zone()
+	if zone == "" {
+		return nil
+	}
+	if iface, err := net.InterfaceByName(zone); err == nil {
+		return iface
+	}
+	if idx, err := strconv.Atoi(zone); err == nil {
+		if iface, err := net.InterfaceByIndex(idx); err == nil {
+			return iface
+		}
+	}
+	return nil
+}
+
+func setIPv4BoundIf(fd uintptr, iface *net.Interface) error {
+	if err := unix.SetsockoptInt(int(fd), unix.IPPROTO_IP, unix.IP_BOUND_IF, iface.Index); err != nil {
+		return fmt.Errorf("set IP_BOUND_IF: %w (interface: %s, index: %d)", err, iface.Name, iface.Index)
+	}
+	return nil
+}
+
+func setIPv6BoundIf(fd uintptr, iface *net.Interface) error {
+	if err := unix.SetsockoptInt(int(fd), unix.IPPROTO_IPV6, unix.IPV6_BOUND_IF, iface.Index); err != nil {
+		return fmt.Errorf("set IPV6_BOUND_IF: %w (interface: %s, index: %d)", err, iface.Name, iface.Index)
+	}
+	return nil
+}
+
+// applyBoundIfToSocket binds the socket to the cached physical egress interface
+// so scoped route lookup avoids the VPN utun and egresses the underlay directly.
+func applyBoundIfToSocket(network, address string, c syscall.RawConn) error {
+	if !AdvancedRouting() {
+		return nil
+	}
+
+	iface := boundInterfaceFor(network, address)
+	if iface == nil {
+		log.Debugf("no bound iface cached for %s to %s, skipping BOUND_IF", network, address)
+		return nil
+	}
+
+	isV6 := isV6Network(network)
+	var controlErr error
+	if err := c.Control(func(fd uintptr) {
+		if isV6 {
+			controlErr = setIPv6BoundIf(fd, iface)
+		} else {
+			controlErr = setIPv4BoundIf(fd, iface)
+		}
+		if controlErr == nil {
+			log.Debugf("set BOUND_IF=%d on %s for %s to %s", iface.Index, iface.Name, network, address)
+		}
+	}); err != nil {
+		return fmt.Errorf("control: %w", err)
+	}
+	return controlErr
+}

client/proto/daemon.pb.go

@@ -4979,6 +4979,7 @@ type GetFeaturesResponse struct {
 	state                 protoimpl.MessageState `protogen:"open.v1"`
 	DisableProfiles       bool                   `protobuf:"varint,1,opt,name=disable_profiles,json=disableProfiles,proto3" json:"disable_profiles,omitempty"`
 	DisableUpdateSettings bool                   `protobuf:"varint,2,opt,name=disable_update_settings,json=disableUpdateSettings,proto3" json:"disable_update_settings,omitempty"`
+	DisableNetworks       bool                   `protobuf:"varint,3,opt,name=disable_networks,json=disableNetworks,proto3" json:"disable_networks,omitempty"`
 	unknownFields         protoimpl.UnknownFields
 	sizeCache             protoimpl.SizeCache
 }
@@ -5027,6 +5028,13 @@ func (x *GetFeaturesResponse) GetDisableUpdateSettings() bool {
 	return false
 }
 
+func (x *GetFeaturesResponse) GetDisableNetworks() bool {
+	if x != nil {
+		return x.DisableNetworks
+	}
+	return false
+}
+
 type TriggerUpdateRequest struct {
 	state         protoimpl.MessageState `protogen:"open.v1"`
 	unknownFields protoimpl.UnknownFields
@@ -6472,10 +6480,11 @@ const file_daemon_proto_rawDesc = "" +
 	"\f_profileNameB\v\n" +
 	"\t_username\"\x10\n" +
 	"\x0eLogoutResponse\"\x14\n" +
-	"\x12GetFeaturesRequest\"x\n" +
+	"\x12GetFeaturesRequest\"\xa3\x01\n" +
 	"\x13GetFeaturesResponse\x12)\n" +
 	"\x10disable_profiles\x18\x01 \x01(\bR\x0fdisableProfiles\x126\n" +
-	"\x17disable_update_settings\x18\x02 \x01(\bR\x15disableUpdateSettings\"\x16\n" +
+	"\x17disable_update_settings\x18\x02 \x01(\bR\x15disableUpdateSettings\x12)\n" +
+	"\x10disable_networks\x18\x03 \x01(\bR\x0fdisableNetworks\"\x16\n" +
 	"\x14TriggerUpdateRequest\"M\n" +
 	"\x15TriggerUpdateResponse\x12\x18\n" +
 	"\asuccess\x18\x01 \x01(\bR\asuccess\x12\x1a\n" +

client/proto/daemon.proto

@@ -727,6 +727,7 @@ message GetFeaturesRequest{}
 message GetFeaturesResponse{
   bool disable_profiles = 1;
   bool disable_update_settings = 2;
+  bool disable_networks = 3;
 }
 
 message TriggerUpdateRequest {}

client/server/network.go

@@ -9,6 +9,8 @@ import (
 	"strings"
 
 	"golang.org/x/exp/maps"
+	"google.golang.org/grpc/codes"
+	gstatus "google.golang.org/grpc/status"
 
 	"github.com/netbirdio/netbird/client/proto"
 	"github.com/netbirdio/netbird/route"
@@ -27,6 +29,10 @@ func (s *Server) ListNetworks(context.Context, *proto.ListNetworksRequest) (*pro
 	s.mutex.Lock()
 	defer s.mutex.Unlock()
 
+	if s.networksDisabled {
+		return nil, gstatus.Errorf(codes.Unavailable, errNetworksDisabled)
+	}
+
 	if s.connectClient == nil {
 		return nil, fmt.Errorf("not connected")
 	}
@@ -118,6 +124,10 @@ func (s *Server) SelectNetworks(_ context.Context, req *proto.SelectNetworksRequ
 	s.mutex.Lock()
 	defer s.mutex.Unlock()
 
+	if s.networksDisabled {
+		return nil, gstatus.Errorf(codes.Unavailable, errNetworksDisabled)
+	}
+
 	if s.connectClient == nil {
 		return nil, fmt.Errorf("not connected")
 	}
@@ -164,6 +174,10 @@ func (s *Server) DeselectNetworks(_ context.Context, req *proto.SelectNetworksRe
 	s.mutex.Lock()
 	defer s.mutex.Unlock()
 
+	if s.networksDisabled {
+		return nil, gstatus.Errorf(codes.Unavailable, errNetworksDisabled)
+	}
+
 	if s.connectClient == nil {
 		return nil, fmt.Errorf("not connected")
 	}

client/server/server.go

@@ -53,6 +53,7 @@ const (
 	errRestoreResidualState   = "failed to restore residual state: %v"
 	errProfilesDisabled       = "profiles are disabled, you cannot use this feature without profiles enabled"
 	errUpdateSettingsDisabled = "update settings are disabled, you cannot use this feature without update settings enabled"
+	errNetworksDisabled       = "network selection is disabled by the administrator"
 )
 
 var ErrServiceNotUp = errors.New("service is not up")
@@ -88,6 +89,7 @@ type Server struct {
 	profileManager         *profilemanager.ServiceManager
 	profilesDisabled       bool
 	updateSettingsDisabled bool
+	networksDisabled       bool
 
 	sleepHandler *sleephandler.SleepHandler
 
@@ -104,7 +106,7 @@ type oauthAuthFlow struct {
 }
 
 // New server instance constructor.
-func New(ctx context.Context, logFile string, configFile string, profilesDisabled bool, updateSettingsDisabled bool) *Server {
+func New(ctx context.Context, logFile string, configFile string, profilesDisabled bool, updateSettingsDisabled bool, networksDisabled bool) *Server {
 	s := &Server{
 		rootCtx:                ctx,
 		logFile:                logFile,
@@ -113,6 +115,7 @@ func New(ctx context.Context, logFile string, configFile string, profilesDisable
 		profileManager:         profilemanager.NewServiceManager(configFile),
 		profilesDisabled:       profilesDisabled,
 		updateSettingsDisabled: updateSettingsDisabled,
+		networksDisabled:       networksDisabled,
 		jwtCache:               newJWTCache(),
 	}
 	agent := &serverAgent{s}
@@ -1628,6 +1631,7 @@ func (s *Server) GetFeatures(ctx context.Context, msg *proto.GetFeaturesRequest)
 	features := &proto.GetFeaturesResponse{
 		DisableProfiles:       s.checkProfilesDisabled(),
 		DisableUpdateSettings: s.checkUpdateSettingsDisabled(),
+		DisableNetworks:       s.networksDisabled,
 	}
 
 	return features, nil

client/server/server_test.go

@@ -36,6 +36,7 @@ import (
 	daemonProto "github.com/netbirdio/netbird/client/proto"
 	"github.com/netbirdio/netbird/management/server"
 	"github.com/netbirdio/netbird/management/server/activity"
+	nbcache "github.com/netbirdio/netbird/management/server/cache"
 	"github.com/netbirdio/netbird/management/server/integrations/port_forwarding"
 	"github.com/netbirdio/netbird/management/server/permissions"
 	"github.com/netbirdio/netbird/management/server/settings"
@@ -103,7 +104,7 @@ func TestConnectWithRetryRuns(t *testing.T) {
 		t.Fatalf("failed to set active profile state: %v", err)
 	}
 
-	s := New(ctx, "debug", "", false, false)
+	s := New(ctx, "debug", "", false, false, false)
 
 	s.config = config
 
@@ -164,7 +165,7 @@ func TestServer_Up(t *testing.T) {
 		t.Fatalf("failed to set active profile state: %v", err)
 	}
 
-	s := New(ctx, "console", "", false, false)
+	s := New(ctx, "console", "", false, false, false)
 	err = s.Start()
 	require.NoError(t, err)
 
@@ -234,7 +235,7 @@ func TestServer_SubcribeEvents(t *testing.T) {
 		t.Fatalf("failed to set active profile state: %v", err)
 	}
 
-	s := New(ctx, "console", "", false, false)
+	s := New(ctx, "console", "", false, false, false)
 
 	err = s.Start()
 	require.NoError(t, err)
@@ -309,7 +310,12 @@ func startManagement(t *testing.T, signalAddr string, counter *int) (*grpc.Serve
 
 	jobManager := job.NewJobManager(nil, store, peersManager)
 
-	ia, _ := integrations.NewIntegratedValidator(context.Background(), peersManager, settingsManagerMock, eventStore)
+	cacheStore, err := nbcache.NewStore(context.Background(), 100*time.Millisecond, 300*time.Millisecond, 100)
+	if err != nil {
+		return nil, "", err
+	}
+
+	ia, _ := integrations.NewIntegratedValidator(context.Background(), peersManager, settingsManagerMock, eventStore, cacheStore)
 
 	metrics, err := telemetry.NewDefaultAppMetrics(context.Background())
 	require.NoError(t, err)
@@ -320,7 +326,7 @@ func startManagement(t *testing.T, signalAddr string, counter *int) (*grpc.Serve
 	requestBuffer := server.NewAccountRequestBuffer(context.Background(), store)
 	peersUpdateManager := update_channel.NewPeersUpdateManager(metrics)
 	networkMapController := controller.NewController(context.Background(), store, metrics, peersUpdateManager, requestBuffer, server.MockIntegratedValidator{}, settingsMockManager, "netbird.selfhosted", port_forwarding.NewControllerMock(), manager.NewEphemeralManager(store, peersManager), config)
-	accountManager, err := server.BuildManager(context.Background(), config, store, networkMapController, jobManager, nil, "", eventStore, nil, false, ia, metrics, port_forwarding.NewControllerMock(), settingsMockManager, permissionsManagerMock, false)
+	accountManager, err := server.BuildManager(context.Background(), config, store, networkMapController, jobManager, nil, "", eventStore, nil, false, ia, metrics, port_forwarding.NewControllerMock(), settingsMockManager, permissionsManagerMock, false, cacheStore)
 	if err != nil {
 		return nil, "", err
 	}

client/server/setconfig_test.go

@@ -53,7 +53,7 @@ func TestSetConfig_AllFieldsSaved(t *testing.T) {
 	require.NoError(t, err)
 
 	ctx := context.Background()
-	s := New(ctx, "console", "", false, false)
+	s := New(ctx, "console", "", false, false, false)
 
 	rosenpassEnabled := true
 	rosenpassPermissive := true

client/server/state.go

@@ -12,7 +12,6 @@ import (
 	"github.com/netbirdio/netbird/client/internal"
 	"github.com/netbirdio/netbird/client/internal/routemanager/systemops"
 	"github.com/netbirdio/netbird/client/internal/statemanager"
-	nbnet "github.com/netbirdio/netbird/client/net"
 	"github.com/netbirdio/netbird/client/proto"
 )
 
@@ -138,10 +137,8 @@ func restoreResidualState(ctx context.Context, statePath string) error {
 	}
 
 	// clean up any remaining routes independently of the state file
-	if !nbnet.AdvancedRouting() {
-		if err := systemops.New(nil, nil).FlushMarkedRoutes(); err != nil {
-			merr = multierror.Append(merr, fmt.Errorf("flush marked routes: %w", err))
-		}
+	if err := systemops.New(nil, nil).FlushMarkedRoutes(); err != nil {
+		merr = multierror.Append(merr, fmt.Errorf("flush marked routes: %w", err))
 	}
 
 	return nberrors.FormatErrorOrNil(merr)

client/ssh/config/manager.go

@@ -187,24 +187,23 @@ func (m *Manager) buildPeerConfig(allHostPatterns []string) (string, error) {
 		return "", fmt.Errorf("get NetBird executable path: %w", err)
 	}
 
-	hostLine := strings.Join(deduplicatedPatterns, " ")
-	config := fmt.Sprintf("Host %s\n", hostLine)
-	config += fmt.Sprintf("    Match exec \"%s ssh detect %%h %%p\"\n", execPath)
-	config += "        PreferredAuthentications password,publickey,keyboard-interactive\n"
-	config += "        PasswordAuthentication yes\n"
-	config += "        PubkeyAuthentication yes\n"
-	config += "        BatchMode no\n"
-	config += fmt.Sprintf("        ProxyCommand %s ssh proxy %%h %%p\n", execPath)
-	config += "        StrictHostKeyChecking no\n"
+	hostList := strings.Join(deduplicatedPatterns, ",")
+	config := fmt.Sprintf("Match host \"%s\" exec \"%s ssh detect %%h %%p\"\n", hostList, execPath)
+	config += "    PreferredAuthentications password,publickey,keyboard-interactive\n"
+	config += "    PasswordAuthentication yes\n"
+	config += "    PubkeyAuthentication yes\n"
+	config += "    BatchMode no\n"
+	config += fmt.Sprintf("    ProxyCommand %s ssh proxy %%h %%p\n", execPath)
+	config += "    StrictHostKeyChecking no\n"
 
 	if runtime.GOOS == "windows" {
-		config += "        UserKnownHostsFile NUL\n"
+		config += "    UserKnownHostsFile NUL\n"
 	} else {
-		config += "        UserKnownHostsFile /dev/null\n"
+		config += "    UserKnownHostsFile /dev/null\n"
 	}
 
-	config += "        CheckHostIP no\n"
-	config += "        LogLevel ERROR\n\n"
+	config += "    CheckHostIP no\n"
+	config += "    LogLevel ERROR\n\n"
 
 	return config, nil
 }

client/ssh/config/manager_test.go

@@ -116,6 +116,37 @@ func TestManager_PeerLimit(t *testing.T) {
 	assert.True(t, os.IsNotExist(err), "SSH config should not be created with too many peers")
 }
 
+func TestManager_MatchHostFormat(t *testing.T) {
+	tempDir, err := os.MkdirTemp("", "netbird-ssh-config-test")
+	require.NoError(t, err)
+	defer func() { assert.NoError(t, os.RemoveAll(tempDir)) }()
+
+	manager := &Manager{
+		sshConfigDir:  filepath.Join(tempDir, "ssh_config.d"),
+		sshConfigFile: "99-netbird.conf",
+	}
+
+	peers := []PeerSSHInfo{
+		{Hostname: "peer1", IP: "100.125.1.1", FQDN: "peer1.nb.internal"},
+		{Hostname: "peer2", IP: "100.125.1.2", FQDN: "peer2.nb.internal"},
+	}
+
+	err = manager.SetupSSHClientConfig(peers)
+	require.NoError(t, err)
+
+	configPath := filepath.Join(manager.sshConfigDir, manager.sshConfigFile)
+	content, err := os.ReadFile(configPath)
+	require.NoError(t, err)
+	configStr := string(content)
+
+	// Must use "Match host" with comma-separated patterns, not a bare "Host" directive.
+	// A bare "Host" followed by "Match exec" is incorrect per ssh_config(5): the Host block
+	// ends at the next Match keyword, making it a no-op and leaving the Match exec unscoped.
+	assert.NotContains(t, configStr, "\nHost ", "should not use bare Host directive")
+	assert.Contains(t, configStr, "Match host \"100.125.1.1,peer1.nb.internal,peer1,100.125.1.2,peer2.nb.internal,peer2\"",
+		"should use Match host with comma-separated patterns")
+}
+
 func TestManager_ForcedSSHConfig(t *testing.T) {
 	// Set force environment variable
 	t.Setenv(EnvForceSSHConfig, "true")

client/system/info.go

@@ -2,7 +2,6 @@ package system
 
 import (
 	"context"
-	"net"
 	"net/netip"
 	"strings"
 
@@ -145,59 +144,6 @@ func extractDeviceName(ctx context.Context, defaultName string) string {
 	return v
 }
 
-func networkAddresses() ([]NetworkAddress, error) {
-	interfaces, err := net.Interfaces()
-	if err != nil {
-		return nil, err
-	}
-
-	var netAddresses []NetworkAddress
-	for _, iface := range interfaces {
-		if iface.Flags&net.FlagUp == 0 {
-			continue
-		}
-		if iface.HardwareAddr.String() == "" {
-			continue
-		}
-		addrs, err := iface.Addrs()
-		if err != nil {
-			continue
-		}
-
-		for _, address := range addrs {
-			ipNet, ok := address.(*net.IPNet)
-			if !ok {
-				continue
-			}
-
-			if ipNet.IP.IsLoopback() {
-				continue
-			}
-
-			netAddr := NetworkAddress{
-				NetIP: netip.MustParsePrefix(ipNet.String()),
-				Mac:   iface.HardwareAddr.String(),
-			}
-
-			if isDuplicated(netAddresses, netAddr) {
-				continue
-			}
-
-			netAddresses = append(netAddresses, netAddr)
-		}
-	}
-	return netAddresses, nil
-}
-
-func isDuplicated(addresses []NetworkAddress, addr NetworkAddress) bool {
-	for _, duplicated := range addresses {
-		if duplicated.NetIP == addr.NetIP {
-			return true
-		}
-	}
-	return false
-}
-
 // GetInfoWithChecks retrieves and parses the system information with applied checks.
 func GetInfoWithChecks(ctx context.Context, checks []*proto.Checks) (*Info, error) {
 	log.Debugf("gathering system information with checks: %d", len(checks))

client/system/info_ios.go

@@ -2,12 +2,16 @@ package system
 
 import (
 	"context"
+	"net"
+	"net/netip"
 	"runtime"
 
+	log "github.com/sirupsen/logrus"
+
 	"github.com/netbirdio/netbird/version"
 )
 
-// UpdateStaticInfoAsync is a no-op on Android as there is no static info to update
+// UpdateStaticInfoAsync is a no-op on iOS as there is no static info to update
 func UpdateStaticInfoAsync() {
 	// do nothing
 }
@@ -15,11 +19,24 @@ func UpdateStaticInfoAsync() {
 // GetInfo retrieves and parses the system information
 func GetInfo(ctx context.Context) *Info {
 
-	// Convert fixed-size byte arrays to Go strings
 	sysName := extractOsName(ctx, "sysName")
 	swVersion := extractOsVersion(ctx, "swVersion")
 
-	gio := &Info{Kernel: sysName, OSVersion: swVersion, Platform: "unknown", OS: sysName, GoOS: runtime.GOOS, CPUs: runtime.NumCPU(), KernelVersion: swVersion}
+	addrs, err := networkAddresses()
+	if err != nil {
+		log.Warnf("failed to discover network addresses: %s", err)
+	}
+
+	gio := &Info{
+		Kernel:           sysName,
+		OSVersion:        swVersion,
+		Platform:         "unknown",
+		OS:               sysName,
+		GoOS:             runtime.GOOS,
+		CPUs:             runtime.NumCPU(),
+		KernelVersion:    swVersion,
+		NetworkAddresses: addrs,
+	}
 	gio.Hostname = extractDeviceName(ctx, "hostname")
 	gio.NetbirdVersion = version.NetbirdVersion()
 	gio.UIVersion = extractUserAgent(ctx)
@@ -27,6 +44,66 @@ func GetInfo(ctx context.Context) *Info {
 	return gio
 }
 
+// networkAddresses returns the list of network addresses on iOS.
+// On iOS, hardware (MAC) addresses are not available due to Apple's privacy
+// restrictions (iOS returns a fixed 02:00:00:00:00:00 placeholder), so we
+// leave Mac empty to match Android's behavior. We also skip the HardwareAddr
+// check that other platforms use and filter out link-local addresses as they
+// are not useful for posture checks.
+func networkAddresses() ([]NetworkAddress, error) {
+	interfaces, err := net.Interfaces()
+	if err != nil {
+		return nil, err
+	}
+
+	var netAddresses []NetworkAddress
+	for _, iface := range interfaces {
+		if iface.Flags&net.FlagUp == 0 {
+			continue
+		}
+		addrs, err := iface.Addrs()
+		if err != nil {
+			continue
+		}
+
+		for _, address := range addrs {
+			netAddr, ok := toNetworkAddress(address)
+			if !ok {
+				continue
+			}
+			if isDuplicated(netAddresses, netAddr) {
+				continue
+			}
+			netAddresses = append(netAddresses, netAddr)
+		}
+	}
+	return netAddresses, nil
+}
+
+func toNetworkAddress(address net.Addr) (NetworkAddress, bool) {
+	ipNet, ok := address.(*net.IPNet)
+	if !ok {
+		return NetworkAddress{}, false
+	}
+	if ipNet.IP.IsLoopback() || ipNet.IP.IsLinkLocalUnicast() || ipNet.IP.IsMulticast() {
+		return NetworkAddress{}, false
+	}
+	prefix, err := netip.ParsePrefix(ipNet.String())
+	if err != nil {
+		return NetworkAddress{}, false
+	}
+	return NetworkAddress{NetIP: prefix, Mac: ""}, true
+}
+
+func isDuplicated(addresses []NetworkAddress, addr NetworkAddress) bool {
+	for _, duplicated := range addresses {
+		if duplicated.NetIP == addr.NetIP {
+			return true
+		}
+	}
+	return false
+}
+
 // checkFileAndProcess checks if the file path exists and if a process is running at that path.
 func checkFileAndProcess(paths []string) ([]File, error) {
 	return []File{}, nil

client/system/network_addr.go

@@ -0,0 +1,66 @@
+//go:build !ios
+
+package system
+
+import (
+	"net"
+	"net/netip"
+)
+
+func networkAddresses() ([]NetworkAddress, error) {
+	interfaces, err := net.Interfaces()
+	if err != nil {
+		return nil, err
+	}
+
+	var netAddresses []NetworkAddress
+	for _, iface := range interfaces {
+		if iface.Flags&net.FlagUp == 0 {
+			continue
+		}
+		if iface.HardwareAddr.String() == "" {
+			continue
+		}
+		addrs, err := iface.Addrs()
+		if err != nil {
+			continue
+		}
+
+		mac := iface.HardwareAddr.String()
+		for _, address := range addrs {
+			netAddr, ok := toNetworkAddress(address, mac)
+			if !ok {
+				continue
+			}
+			if isDuplicated(netAddresses, netAddr) {
+				continue
+			}
+			netAddresses = append(netAddresses, netAddr)
+		}
+	}
+	return netAddresses, nil
+}
+
+func toNetworkAddress(address net.Addr, mac string) (NetworkAddress, bool) {
+	ipNet, ok := address.(*net.IPNet)
+	if !ok {
+		return NetworkAddress{}, false
+	}
+	if ipNet.IP.IsLoopback() {
+		return NetworkAddress{}, false
+	}
+	prefix, err := netip.ParsePrefix(ipNet.String())
+	if err != nil {
+		return NetworkAddress{}, false
+	}
+	return NetworkAddress{NetIP: prefix, Mac: mac}, true
+}
+
+func isDuplicated(addresses []NetworkAddress, addr NetworkAddress) bool {
+	for _, duplicated := range addresses {
+		if duplicated.NetIP == addr.NetIP {
+			return true
+		}
+	}
+	return false
+}