[management,signal,proxy,relay,misc] Unify service configuration loading

Service entry points currently resolve defaults, files, environment variables, and flags differently, which makes precedence inconsistent and prevents some services from using config files. Introduce one Viper-backed loader and migrate Combined, Management, Relay, Signal, and Proxy while preserving compatibility aliases and Management template expansion.
2026-08-28 10:31:29 +02:00 · 2026-08-24 18:18:59 +02:00
parent f03853867b
commit c8cd6b4dca
27 changed files with 1296 additions and 339 deletions
--- a/proxy/cmd/proxy/cmd/config.go
+++ b/proxy/cmd/proxy/cmd/config.go
@@ -0,0 +1,47 @@
+package cmd
+
+import (
+	"github.com/spf13/cobra"
+	"golang.org/x/crypto/acme"
+
+	"github.com/netbirdio/netbird/proxy"
+	configloader "github.com/netbirdio/netbird/util/config"
+)
+
+type commandConfig struct {
+	proxy.Config `yaml:",squash"`
+
+	LogLevel            string  `yaml:"logLevel" env:"NB_PROXY_LOG_LEVEL" flag:"log-level"`
+	PreallocatedBuffers *uint32 `yaml:"preallocatedBuffers" env:"NB_PROXY_PREALLOCATED_BUFFERS"`
+	MaxBatchSize        *uint32 `yaml:"maxBatchSize" env:"NB_PROXY_MAX_BATCH_SIZE"`
+}
+
+func defaultConfig() *commandConfig {
+	return &commandConfig{
+		Config: proxy.Config{
+			ListenAddr:           ":443",
+			ManagementAddress:    DefaultManagementURL,
+			CertificateDirectory: "./certs",
+			CertificateFile:      "tls.crt",
+			CertificateKeyFile:   "tls.key",
+			ACMEChallengeAddress: ":80",
+			ACMEDirectory:        acme.LetsEncryptURL,
+			ACMEChallengeType:    "tls-alpn-01",
+			CertLockMethod:       "auto",
+			HealthAddr:           "localhost:8080",
+			ForwardedProto:       "auto",
+			SupportsCustomPorts:  true,
+			GeoDataDir:           "/var/lib/netbird/geolocation",
+		},
+		LogLevel: "info",
+	}
+}
+
+func loadConfig(cmd *cobra.Command, configPath string) (*commandConfig, error) {
+	return configloader.Load(configPath, defaultConfig(), configloader.Options{
+		TagName:      "yaml",
+		AllowMissing: configPath == "",
+		FlagSet:      cmd.Flags(),
+		Strict:       true,
+	})
+}
--- a/proxy/cmd/proxy/cmd/config_test.go
+++ b/proxy/cmd/proxy/cmd/config_test.go
@@ -0,0 +1,40 @@
+package cmd
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestLoadConfigPrecedence(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "proxy.yaml")
+	require.NoError(t, os.WriteFile(configPath, []byte(`
+domain: file.example.com
+trustedProxies: 192.0.2.0/24
+maxDialTimeout: 5s
+`), 0o600))
+	t.Setenv("NB_PROXY_TOKEN", "environment-token")
+	require.NoError(t, rootCmd.ParseFlags(nil))
+
+	domainFlag := rootCmd.Flags().Lookup("domain")
+	oldDomain := domainFlag.Value.String()
+	oldChanged := domainFlag.Changed
+	t.Cleanup(func() {
+		require.NoError(t, domainFlag.Value.Set(oldDomain))
+		domainFlag.Changed = oldChanged
+	})
+	require.NoError(t, domainFlag.Value.Set("flag.example.com"))
+	domainFlag.Changed = true
+
+	cfg, err := loadConfig(rootCmd, configPath)
+	require.NoError(t, err)
+	assert.Equal(t, "flag.example.com", cfg.ProxyURL, "Flags should override the configuration file")
+	assert.Equal(t, "environment-token", cfg.ProxyToken, "Environment should populate secrets")
+	assert.Equal(t, 5*time.Second, cfg.MaxDialTimeout, "Durations should be decoded from the file")
+	require.NotNil(t, cfg.TrustedProxies, "Trusted proxies should be decoded")
+	assert.False(t, cfg.TrustedProxies.Empty(), "Configured trusted proxies should not be empty")
+}
--- a/proxy/cmd/proxy/cmd/root.go
+++ b/proxy/cmd/proxy/cmd/root.go
@@ -15,22 +15,13 @@ import (

 	"github.com/netbirdio/netbird/shared/management/domain"

-	"github.com/netbirdio/netbird/client/embed"
 	"github.com/netbirdio/netbird/proxy"
-	nbacme "github.com/netbirdio/netbird/proxy/internal/acme"
-	"github.com/netbirdio/netbird/trustedproxy"
 	"github.com/netbirdio/netbird/util"
 )

-const (
-	// envPreallocatedBuffers caps the per-tunnel buffer pool. Zero (unset)
-	// keeps the upstream uncapped default.
-	envPreallocatedBuffers = "NB_PROXY_PREALLOCATED_BUFFERS"
-	// envMaxBatchSize overrides the per-tunnel batch size, which controls
-	// how many buffers each receive/TUN worker eagerly allocates. Zero
-	// (unset) keeps the platform default.
-	envMaxBatchSize = "NB_PROXY_MAX_BATCH_SIZE"
-)
+// envPreallocatedBuffers caps the per-tunnel buffer pool. Zero (unset)
+// keeps the upstream uncapped default.
+const envPreallocatedBuffers = "NB_PROXY_PREALLOCATED_BUFFERS"

 const DefaultManagementURL = "https://api.netbird.io:443"

@@ -79,6 +70,7 @@ var (
 	geoDataDir            string
 	crowdsecAPIURL        string
 	crowdsecAPIKey        string
+	configPath            string
 )

 var rootCmd = &cobra.Command{
@@ -91,6 +83,7 @@ var rootCmd = &cobra.Command{
 }

 func init() {
+	rootCmd.Flags().StringVar(&configPath, "config", "", "path to configuration file")
 	rootCmd.PersistentFlags().StringVar(&logLevel, "log-level", envStringOrDefault("NB_PROXY_LOG_LEVEL", "info"), "Log level: panic, fatal, error, warn, info, debug, trace")
 	rootCmd.PersistentFlags().BoolVar(&debugLogs, "debug", envBoolOrDefault("NB_PROXY_DEBUG_LOGS", false), "Enable debug logs")
 	_ = rootCmd.PersistentFlags().MarkDeprecated("debug", "use --log-level instead")
@@ -145,118 +138,68 @@ func SetVersionInfo(version, commit, buildDate, goVersion string) {
 }

 func runServer(cmd *cobra.Command, args []string) error {
-	proxyToken := os.Getenv(envProxyToken)
-	if proxyToken == "" {
-		return fmt.Errorf("proxy token is required: set %s environment variable", envProxyToken)
+	cfg, err := loadConfig(cmd, configPath)
+	if err != nil {
+		return fmt.Errorf("load config: %w", err)
+	}
+	if cfg.ProxyToken == "" {
+		return fmt.Errorf("proxy token is required: set proxyToken or %s", envProxyToken)
 	}

-	level := logLevel
-	if debugLogs {
+	level := cfg.LogLevel
+	if debugLogs && (!cmd.Flags().Changed("log-level") || cmd.Flags().Changed("debug")) {
 		level = "debug"
 	}
 	logger := log.New()
-
 	_ = util.InitLogger(logger, level, util.LogConsole)
-
 	logger.Infof("configured log level: %s", level)

-	var wgPool, wgBatch uint64
-	var perf embed.Performance
-	if raw := os.Getenv(envPreallocatedBuffers); raw != "" {
-		n, err := strconv.ParseUint(raw, 10, 32)
-		if err != nil {
-			return fmt.Errorf("invalid %s %q: %w", envPreallocatedBuffers, raw, err)
-		}
-		wgPool = n
-		v := uint32(n)
-		perf.PreallocatedBuffersPerPool = &v
-		logger.Infof("tunnel preallocated buffers per pool: %d", n)
-	}
-	if raw := os.Getenv(envMaxBatchSize); raw != "" {
-		n, err := strconv.ParseUint(raw, 10, 32)
-		if err != nil {
-			return fmt.Errorf("invalid %s %q: %w", envMaxBatchSize, raw, err)
-		}
-		wgBatch = n
-		v := uint32(n)
-		perf.MaxBatchSize = &v
-		logger.Infof("tunnel max batch size override: %d", n)
-	}
-	if wgPool > 0 {
-		// Each bind recv goroutine (IPv4 + IPv6 + ICE relay) plus
-		// RoutineReadFromTUN eagerly reserves `batch` message buffers for
-		// the lifetime of the Device. A pool cap below that floor blocks
-		// the receive pipeline at startup.
-		batch := wgBatch
-		if batch == 0 {
-			batch = 128
-		}
-		const recvGoroutines = 4
-		floor := batch * recvGoroutines
-		if wgPool < floor {
-			logger.Warnf("%s=%d is below the eager-allocation floor (~%d for batch=%d); startup may deadlock",
-				envPreallocatedBuffers, wgPool, floor, batch)
-		}
-	}
+	proxyConfig := cfg.Config
+	proxyConfig.Logger = logger
+	proxyConfig.Version = Version
+	applyPerformanceConfig(&proxyConfig, cfg, logger)

-	switch forwardedProto {
+	switch proxyConfig.ForwardedProto {
 	case "auto", "http", "https":
 	default:
-		return fmt.Errorf("invalid --forwarded-proto value %q: must be auto, http, or https", forwardedProto)
+		return fmt.Errorf("invalid --forwarded-proto value %q: must be auto, http, or https", proxyConfig.ForwardedProto)
 	}

-	_, err := domain.ValidateDomains([]string{proxyDomain})
-	if err != nil {
-		return fmt.Errorf("invalid domain value %q: %w", proxyDomain, err)
-	}
-
-	parsedTrustedProxies, err := trustedproxy.Parse(trustedProxies)
-	if err != nil {
-		return fmt.Errorf("invalid --trusted-proxies: %w", err)
+	if _, err := domain.ValidateDomains([]string{proxyConfig.ProxyURL}); err != nil {
+		return fmt.Errorf("invalid domain value %q: %w", proxyConfig.ProxyURL, err)
 	}

 	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGTERM, syscall.SIGINT)
 	defer stop()

-	srv := proxy.New(ctx, proxy.Config{
-		ListenAddr:               addr,
-		Logger:                   logger,
-		Version:                  Version,
-		ManagementAddress:        mgmtAddr,
-		ProxyURL:                 proxyDomain,
-		ProxyToken:               proxyToken,
-		CertificateDirectory:     certDir,
-		CertificateFile:          certFile,
-		CertificateKeyFile:       certKeyFile,
-		GenerateACMECertificates: acmeCerts,
-		ACMEChallengeAddress:     acmeAddr,
-		ACMEDirectory:            acmeDir,
-		ACMEEABKID:               acmeEABKID,
-		ACMEEABHMACKey:           acmeEABHMACKey,
-		ACMEChallengeType:        acmeChallengeType,
-		DebugEndpointEnabled:     debugEndpoint,
-		DebugEndpointAddress:     debugEndpointAddr,
-		HealthAddr:               healthAddr,
-		ForwardedProto:           forwardedProto,
-		TrustedProxies:           parsedTrustedProxies,
-		CertLockMethod:           nbacme.CertLockMethod(certLockMethod),
-		WildcardCertDir:          wildcardCertDir,
-		WireguardPort:            wgPort,
-		Performance:              perf,
-		ProxyProtocol:            proxyProtocol,
-		PreSharedKey:             preSharedKey,
-		SupportsCustomPorts:      supportsCustomPorts,
-		RequireSubdomain:         requireSubdomain,
-		Private:                  private,
-		MaxDialTimeout:           maxDialTimeout,
-		MaxSessionIdleTimeout:    maxSessionIdleTimeout,
-		MappingBatchWatchdog:     envDurationOrDefault("NB_PROXY_MAPPING_BATCH_WATCHDOG", 0),
-		GeoDataDir:               geoDataDir,
-		CrowdSecAPIURL:           crowdsecAPIURL,
-		CrowdSecAPIKey:           crowdsecAPIKey,
-	})
+	srv := proxy.New(ctx, proxyConfig)
+	return srv.ListenAndServe(ctx, proxyConfig.ListenAddr)
+}

-	return srv.ListenAndServe(ctx, addr)
+func applyPerformanceConfig(proxyConfig *proxy.Config, cfg *commandConfig, logger *log.Logger) {
+	if cfg.PreallocatedBuffers != nil {
+		proxyConfig.Performance.PreallocatedBuffersPerPool = cfg.PreallocatedBuffers
+		logger.Infof("tunnel preallocated buffers per pool: %d", *cfg.PreallocatedBuffers)
+	}
+	if cfg.MaxBatchSize != nil {
+		proxyConfig.Performance.MaxBatchSize = cfg.MaxBatchSize
+		logger.Infof("tunnel max batch size override: %d", *cfg.MaxBatchSize)
+	}
+	if cfg.PreallocatedBuffers == nil || *cfg.PreallocatedBuffers == 0 {
+		return
+	}
+
+	batch := uint64(128)
+	if cfg.MaxBatchSize != nil && *cfg.MaxBatchSize > 0 {
+		batch = uint64(*cfg.MaxBatchSize)
+	}
+	const recvGoroutines = 4
+	floor := batch * recvGoroutines
+	pool := uint64(*cfg.PreallocatedBuffers)
+	if pool < floor {
+		logger.Warnf("%s=%d is below the eager-allocation floor (~%d for batch=%d); startup may deadlock",
+			envPreallocatedBuffers, pool, floor, batch)
+	}
 }

 func envBoolOrDefault(key string, def bool) bool {
--- a/proxy/lifecycle.go
+++ b/proxy/lifecycle.go
@@ -20,112 +20,112 @@ import (
 // adding fields here must not change the zero-value behaviour of Server.
 type Config struct {
 	// ListenAddr is the TCP address the main listener binds. Required.
-	ListenAddr string
+	ListenAddr string `yaml:"listenAddress" env:"NB_PROXY_ADDRESS" flag:"addr"`
 	// ID identifies this proxy instance to management. Empty values are
 	// replaced with a timestamped default at Server.Start time (see
 	// initDefaults), not in New.
-	ID string
+	ID string `yaml:"id" env:"NB_PROXY_ID"`
 	// Logger is the logrus logger used everywhere. Empty values fall
 	// back to log.StandardLogger() at Server.Start time (see
 	// initDefaults), not in New.
-	Logger *log.Logger
+	Logger *log.Logger `yaml:"-" env:"-" flag:"-"`
 	// Version is the build version string reported to management. Empty
 	// values are replaced with "dev" at Server.Start time (see
 	// initDefaults), not in New.
-	Version string
+	Version string `yaml:"-" env:"-" flag:"-"`
 	// ProxyURL is the public address operators use to reach this proxy.
-	ProxyURL string
+	ProxyURL string `yaml:"domain" env:"NB_PROXY_DOMAIN" flag:"domain"`
 	// ManagementAddress is the gRPC URL of the management server.
-	ManagementAddress string
+	ManagementAddress string `yaml:"managementAddress" env:"NB_PROXY_MANAGEMENT_ADDRESS" flag:"mgmt"`
 	// ProxyToken authenticates this proxy with the management server.
-	ProxyToken string
+	ProxyToken string `yaml:"proxyToken" env:"NB_PROXY_TOKEN"`

 	// CertificateDirectory is the directory holding TLS certificate
 	// material (static or ACME-provisioned).
-	CertificateDirectory string
+	CertificateDirectory string `yaml:"certificateDirectory" env:"NB_PROXY_CERTIFICATE_DIRECTORY" flag:"cert-dir"`
 	// CertificateFile is the certificate filename within
 	// CertificateDirectory.
-	CertificateFile string
+	CertificateFile string `yaml:"certificateFile" env:"NB_PROXY_CERTIFICATE_FILE" flag:"cert-file"`
 	// CertificateKeyFile is the private key filename within
 	// CertificateDirectory.
-	CertificateKeyFile string
+	CertificateKeyFile string `yaml:"certificateKeyFile" env:"NB_PROXY_CERTIFICATE_KEY_FILE" flag:"cert-key-file"`
 	// GenerateACMECertificates toggles ACME certificate provisioning.
-	GenerateACMECertificates bool
+	GenerateACMECertificates bool `yaml:"generateACMECertificates" env:"NB_PROXY_ACME_CERTIFICATES" flag:"acme-certs"`
 	// ACMEChallengeAddress is the listen address for HTTP-01 challenges.
-	ACMEChallengeAddress string
+	ACMEChallengeAddress string `yaml:"acmeChallengeAddress" env:"NB_PROXY_ACME_ADDRESS" flag:"acme-addr"`
 	// ACMEDirectory is the ACME directory URL (Let's Encrypt by default).
-	ACMEDirectory string
+	ACMEDirectory string `yaml:"acmeDirectory" env:"NB_PROXY_ACME_DIRECTORY" flag:"acme-dir"`
 	// ACMEEABKID is the External Account Binding Key ID for CAs that
 	// require EAB (e.g. ZeroSSL).
-	ACMEEABKID string
+	ACMEEABKID string `yaml:"acmeEABKID" env:"NB_PROXY_ACME_EAB_KID" flag:"acme-eab-kid"`
 	// ACMEEABHMACKey is the External Account Binding HMAC key for CAs
 	// that require EAB.
-	ACMEEABHMACKey string
+	ACMEEABHMACKey string `yaml:"acmeEABHMACKey" env:"NB_PROXY_ACME_EAB_HMAC_KEY" flag:"acme-eab-hmac-key"`
 	// ACMEChallengeType is the ACME challenge type ("tls-alpn-01" or
 	// "http-01"). Empty defaults to "tls-alpn-01".
-	ACMEChallengeType string
+	ACMEChallengeType string `yaml:"acmeChallengeType" env:"NB_PROXY_ACME_CHALLENGE_TYPE" flag:"acme-challenge-type"`
 	// CertLockMethod controls how ACME certificate locks are coordinated
 	// across replicas.
-	CertLockMethod acme.CertLockMethod
+	CertLockMethod acme.CertLockMethod `yaml:"certLockMethod" env:"NB_PROXY_CERT_LOCK_METHOD" flag:"cert-lock-method"`
 	// WildcardCertDir is an optional directory containing static wildcard
 	// certificates that override ACME for matching domains.
-	WildcardCertDir string
+	WildcardCertDir string `yaml:"wildcardCertDir" env:"NB_PROXY_WILDCARD_CERT_DIR" flag:"wildcard-cert-dir"`

 	// DebugEndpointEnabled toggles the debug HTTP endpoint.
-	DebugEndpointEnabled bool
+	DebugEndpointEnabled bool `yaml:"debugEndpointEnabled" env:"NB_PROXY_DEBUG_ENDPOINT" flag:"debug-endpoint"`
 	// DebugEndpointAddress is the bind address for the debug endpoint.
-	DebugEndpointAddress string
+	DebugEndpointAddress string `yaml:"debugEndpointAddress" env:"NB_PROXY_DEBUG_ENDPOINT_ADDRESS" flag:"debug-endpoint-addr"`
 	// HealthAddr is the bind address for the health probe and metrics
 	// surface. Empty disables the health probe entirely (library callers
 	// can attach their own).
-	HealthAddr string
+	HealthAddr string `yaml:"healthAddress" env:"NB_PROXY_HEALTH_ADDRESS" flag:"health-addr"`

 	// ForwardedProto overrides the X-Forwarded-Proto value sent to
 	// backends. Valid values: "auto", "http", "https".
-	ForwardedProto string
+	ForwardedProto string `yaml:"forwardedProto" env:"NB_PROXY_FORWARDED_PROTO" flag:"forwarded-proto"`
 	// TrustedProxies is the set of trusted upstream proxies that may set
 	// forwarding headers.
-	TrustedProxies *trustedproxy.List
+	TrustedProxies *trustedproxy.List `yaml:"trustedProxies" env:"NB_PROXY_TRUSTED_PROXIES" flag:"trusted-proxies"`
 	// WireguardPort is the UDP port for the embedded NetBird tunnel.
 	// Zero asks the OS for a random port.
-	WireguardPort uint16
+	WireguardPort uint16 `yaml:"wireguardPort" env:"NB_PROXY_WG_PORT" flag:"wg-port"`
 	// ProxyProtocol enables PROXY protocol (v1/v2) on TCP listeners.
-	ProxyProtocol bool
+	ProxyProtocol bool `yaml:"proxyProtocol" env:"NB_PROXY_PROXY_PROTOCOL" flag:"proxy-protocol"`
 	// PreSharedKey is the WireGuard pre-shared key used between the
 	// proxy's embedded clients and peers.
-	PreSharedKey string
+	PreSharedKey string `yaml:"preSharedKey" env:"NB_PROXY_PRESHARED_KEY" flag:"preshared-key"`
 	// Performance configures the tunnel pool/batch sizes for every
 	// embedded client this proxy creates. Zero values fall back to
 	// upstream defaults.
-	Performance embed.Performance
+	Performance embed.Performance `yaml:"performance" env:"-" flag:"-"`

 	// SupportsCustomPorts indicates whether the proxy can bind arbitrary
 	// ports for TCP/UDP/TLS services.
-	SupportsCustomPorts bool
+	SupportsCustomPorts bool `yaml:"supportsCustomPorts" env:"NB_PROXY_SUPPORTS_CUSTOM_PORTS" flag:"supports-custom-ports"`
 	// RequireSubdomain forces accounts to use a subdomain in front of
 	// the proxy's cluster domain.
-	RequireSubdomain bool
+	RequireSubdomain bool `yaml:"requireSubdomain" env:"NB_PROXY_REQUIRE_SUBDOMAIN" flag:"require-subdomain"`
 	// Private flags this proxy as embedded in a netbird client and
 	// serving exclusively over the WireGuard tunnel. Also enables
 	// per-account inbound listeners on each embedded client's netstack.
-	Private bool
+	Private bool `yaml:"private" env:"NB_PROXY_PRIVATE" flag:"private"`

 	// MaxDialTimeout caps the per-service backend dial timeout.
-	MaxDialTimeout time.Duration
+	MaxDialTimeout time.Duration `yaml:"maxDialTimeout" env:"NB_PROXY_MAX_DIAL_TIMEOUT" flag:"max-dial-timeout"`
 	// MaxSessionIdleTimeout caps the per-service session idle timeout.
-	MaxSessionIdleTimeout time.Duration
+	MaxSessionIdleTimeout time.Duration `yaml:"maxSessionIdleTimeout" env:"NB_PROXY_MAX_SESSION_IDLE_TIMEOUT" flag:"max-session-idle-timeout"`
 	// MappingBatchWatchdog bounds how long a single mapping batch may spend
 	// being applied before the receive loop reconnects to resync. Zero falls
 	// back to the internal default.
-	MappingBatchWatchdog time.Duration
+	MappingBatchWatchdog time.Duration `yaml:"mappingBatchWatchdog" env:"NB_PROXY_MAPPING_BATCH_WATCHDOG"`

 	// GeoDataDir is the directory containing GeoLite2 MMDB files.
-	GeoDataDir string
+	GeoDataDir string `yaml:"geoDataDir" env:"NB_PROXY_GEO_DATA_DIR" flag:"geo-data-dir"`
 	// CrowdSecAPIURL is the CrowdSec LAPI URL. Empty disables CrowdSec.
-	CrowdSecAPIURL string
+	CrowdSecAPIURL string `yaml:"crowdSecAPIURL" env:"NB_PROXY_CROWDSEC_API_URL" flag:"crowdsec-api-url"`
 	// CrowdSecAPIKey is the CrowdSec bouncer API key. Empty disables
 	// CrowdSec.
-	CrowdSecAPIKey string
+	CrowdSecAPIKey string `yaml:"crowdSecAPIKey" env:"NB_PROXY_CROWDSEC_API_KEY" flag:"crowdsec-api-key"`
 }

 // New builds a Server from cfg without performing any I/O. No goroutines