Use a 1:1 mapping of netbird client to netbird account

- Add debug endpoint for monitoring netbird clients - Add types package with AccountID type - Refactor netbird roundtrip to key clients by AccountID - Multiple domains can share the same client per account - Add status notifier for tunnel connection updates - Add OIDC flags to CLI - Add tests for netbird client management
2026-04-19 00:36:38 +00:00 · 2026-02-04 14:39:52 +08:00
parent 18cd0f1480
commit ca33849f31
20 changed files with 2270 additions and 182 deletions
--- a/proxy/cmd/proxy/cmd/debug.go
+++ b/proxy/cmd/proxy/cmd/debug.go
@@ -0,0 +1,166 @@
+package cmd
+
+import (
+	"fmt"
+	"strconv"
+
+	"github.com/spf13/cobra"
+
+	"github.com/netbirdio/netbird/proxy/internal/debug"
+)
+
+var (
+	debugAddr  string
+	jsonOutput bool
+
+	// status filters
+	statusFilterByIPs            []string
+	statusFilterByNames          []string
+	statusFilterByStatus         string
+	statusFilterByConnectionType string
+)
+
+var debugCmd = &cobra.Command{
+	Use:   "debug",
+	Short: "Debug commands for inspecting proxy state",
+	Long:  "Debug commands for inspecting the reverse proxy state via the debug HTTP endpoint.",
+}
+
+var debugHealthCmd = &cobra.Command{
+	Use:          "health",
+	Short:        "Show proxy health status",
+	RunE:         runDebugHealth,
+	SilenceUsage: true,
+}
+
+var debugClientsCmd = &cobra.Command{
+	Use:          "clients",
+	Aliases:      []string{"list"},
+	Short:        "List all connected clients",
+	RunE:         runDebugClients,
+	SilenceUsage: true,
+}
+
+var debugStatusCmd = &cobra.Command{
+	Use:          "status <account-id>",
+	Short:        "Show client status",
+	Args:         cobra.ExactArgs(1),
+	RunE:         runDebugStatus,
+	SilenceUsage: true,
+}
+
+var debugSyncCmd = &cobra.Command{
+	Use:          "sync-response <account-id>",
+	Short:        "Show client sync response",
+	Args:         cobra.ExactArgs(1),
+	RunE:         runDebugSync,
+	SilenceUsage: true,
+}
+
+var pingTimeout string
+
+var debugPingCmd = &cobra.Command{
+	Use:          "ping <account-id> <host> [port]",
+	Short:        "TCP ping through a client",
+	Long:         "Perform a TCP ping through a client's network to test connectivity.\nPort defaults to 80 if not specified.",
+	Args:         cobra.RangeArgs(2, 3),
+	RunE:         runDebugPing,
+	SilenceUsage: true,
+}
+
+var debugLogLevelCmd = &cobra.Command{
+	Use:          "loglevel <account-id> <level>",
+	Short:        "Set client log level",
+	Long:         "Set the log level for a client (trace, debug, info, warn, error).",
+	Args:         cobra.ExactArgs(2),
+	RunE:         runDebugLogLevel,
+	SilenceUsage: true,
+}
+
+var debugStartCmd = &cobra.Command{
+	Use:          "start <account-id>",
+	Short:        "Start a client",
+	Args:         cobra.ExactArgs(1),
+	RunE:         runDebugStart,
+	SilenceUsage: true,
+}
+
+var debugStopCmd = &cobra.Command{
+	Use:          "stop <account-id>",
+	Short:        "Stop a client",
+	Args:         cobra.ExactArgs(1),
+	RunE:         runDebugStop,
+	SilenceUsage: true,
+}
+
+func init() {
+	debugCmd.PersistentFlags().StringVar(&debugAddr, "addr", envStringOrDefault("NB_PROXY_DEBUG_ADDRESS", "localhost:8444"), "Debug endpoint address")
+	debugCmd.PersistentFlags().BoolVar(&jsonOutput, "json", false, "Output JSON instead of pretty format")
+
+	debugStatusCmd.Flags().StringSliceVar(&statusFilterByIPs, "filter-by-ips", nil, "Filter by peer IPs (comma-separated)")
+	debugStatusCmd.Flags().StringSliceVar(&statusFilterByNames, "filter-by-names", nil, "Filter by peer names (comma-separated)")
+	debugStatusCmd.Flags().StringVar(&statusFilterByStatus, "filter-by-status", "", "Filter by status (idle|connecting|connected)")
+	debugStatusCmd.Flags().StringVar(&statusFilterByConnectionType, "filter-by-connection-type", "", "Filter by connection type (P2P|Relayed)")
+
+	debugPingCmd.Flags().StringVar(&pingTimeout, "timeout", "", "Ping timeout (e.g., 10s)")
+
+	debugCmd.AddCommand(debugHealthCmd)
+	debugCmd.AddCommand(debugClientsCmd)
+	debugCmd.AddCommand(debugStatusCmd)
+	debugCmd.AddCommand(debugSyncCmd)
+	debugCmd.AddCommand(debugPingCmd)
+	debugCmd.AddCommand(debugLogLevelCmd)
+	debugCmd.AddCommand(debugStartCmd)
+	debugCmd.AddCommand(debugStopCmd)
+
+	rootCmd.AddCommand(debugCmd)
+}
+
+func getDebugClient(cmd *cobra.Command) *debug.Client {
+	return debug.NewClient(debugAddr, jsonOutput, cmd.OutOrStdout())
+}
+
+func runDebugHealth(cmd *cobra.Command, _ []string) error {
+	return getDebugClient(cmd).Health(cmd.Context())
+}
+
+func runDebugClients(cmd *cobra.Command, _ []string) error {
+	return getDebugClient(cmd).ListClients(cmd.Context())
+}
+
+func runDebugStatus(cmd *cobra.Command, args []string) error {
+	return getDebugClient(cmd).ClientStatus(cmd.Context(), args[0], debug.StatusFilters{
+		IPs:            statusFilterByIPs,
+		Names:          statusFilterByNames,
+		Status:         statusFilterByStatus,
+		ConnectionType: statusFilterByConnectionType,
+	})
+}
+
+func runDebugSync(cmd *cobra.Command, args []string) error {
+	return getDebugClient(cmd).ClientSyncResponse(cmd.Context(), args[0])
+}
+
+func runDebugPing(cmd *cobra.Command, args []string) error {
+	port := 80
+	if len(args) > 2 {
+		p, err := strconv.Atoi(args[2])
+		if err != nil {
+			return fmt.Errorf("invalid port: %w", err)
+		}
+		port = p
+	}
+	return getDebugClient(cmd).PingTCP(cmd.Context(), args[0], args[1], port, pingTimeout)
+}
+
+func runDebugLogLevel(cmd *cobra.Command, args []string) error {
+	return getDebugClient(cmd).SetLogLevel(cmd.Context(), args[0], args[1])
+}
+
+func runDebugStart(cmd *cobra.Command, args []string) error {
+	return getDebugClient(cmd).StartClient(cmd.Context(), args[0])
+}
+
+func runDebugStop(cmd *cobra.Command, args []string) error {
+	return getDebugClient(cmd).StopClient(cmd.Context(), args[0])
+}
--- a/proxy/cmd/proxy/cmd/root.go
+++ b/proxy/cmd/proxy/cmd/root.go
@@ -0,0 +1,137 @@
+package cmd
+
+import (
+	"context"
+	"os"
+	"strconv"
+	"strings"
+
+	log "github.com/sirupsen/logrus"
+	"github.com/spf13/cobra"
+	"golang.org/x/crypto/acme"
+
+	"github.com/netbirdio/netbird/proxy"
+	"github.com/netbirdio/netbird/util"
+)
+
+const DefaultManagementURL = "https://api.netbird.io:443"
+
+var (
+	Version   = "dev"
+	Commit    = "unknown"
+	BuildDate = "unknown"
+	GoVersion = "unknown"
+)
+
+var (
+	debugLogs         bool
+	mgmtAddr          string
+	addr              string
+	proxyURL          string
+	certDir           string
+	acmeCerts         bool
+	acmeAddr          string
+	acmeDir           string
+	debugEndpoint     bool
+	debugEndpointAddr string
+	oidcClientID      string
+	oidcClientSecret  string
+	oidcEndpoint      string
+	oidcScopes        string
+)
+
+var rootCmd = &cobra.Command{
+	Use:     "proxy",
+	Short:   "NetBird reverse proxy server",
+	Long:    "NetBird reverse proxy server for proxying traffic to NetBird networks.",
+	Version: Version,
+	RunE:    runServer,
+}
+
+func init() {
+	rootCmd.PersistentFlags().BoolVar(&debugLogs, "debug", envBoolOrDefault("NB_PROXY_DEBUG_LOGS", false), "Enable debug logs")
+	rootCmd.Flags().StringVar(&mgmtAddr, "mgmt", envStringOrDefault("NB_PROXY_MANAGEMENT_ADDRESS", DefaultManagementURL), "Management address to connect to")
+	rootCmd.Flags().StringVar(&addr, "addr", envStringOrDefault("NB_PROXY_ADDRESS", ":443"), "Reverse proxy address to listen on")
+	rootCmd.Flags().StringVar(&proxyURL, "url", envStringOrDefault("NB_PROXY_URL", ""), "The URL at which this proxy will be reached")
+	rootCmd.Flags().StringVar(&certDir, "cert-dir", envStringOrDefault("NB_PROXY_CERTIFICATE_DIRECTORY", "./certs"), "Directory to store certificates")
+	rootCmd.Flags().BoolVar(&acmeCerts, "acme-certs", envBoolOrDefault("NB_PROXY_ACME_CERTIFICATES", false), "Generate ACME certificates using HTTP-01 challenges")
+	rootCmd.Flags().StringVar(&acmeAddr, "acme-addr", envStringOrDefault("NB_PROXY_ACME_ADDRESS", ":80"), "HTTP address for ACME HTTP-01 challenges")
+	rootCmd.Flags().StringVar(&acmeDir, "acme-dir", envStringOrDefault("NB_PROXY_ACME_DIRECTORY", acme.LetsEncryptURL), "URL of ACME challenge directory")
+	rootCmd.Flags().BoolVar(&debugEndpoint, "debug-endpoint", envBoolOrDefault("NB_PROXY_DEBUG_ENDPOINT", false), "Enable debug HTTP endpoint")
+	rootCmd.Flags().StringVar(&debugEndpointAddr, "debug-endpoint-addr", envStringOrDefault("NB_PROXY_DEBUG_ENDPOINT_ADDRESS", "localhost:8444"), "Address for the debug HTTP endpoint")
+	rootCmd.Flags().StringVar(&oidcClientID, "oidc-id", envStringOrDefault("NB_PROXY_OIDC_CLIENT_ID", "netbird-proxy"), "The OAuth2 Client ID for OIDC User Authentication")
+	rootCmd.Flags().StringVar(&oidcClientSecret, "oidc-secret", envStringOrDefault("NB_PROXY_OIDC_CLIENT_SECRET", ""), "The OAuth2 Client Secret for OIDC User Authentication")
+	rootCmd.Flags().StringVar(&oidcEndpoint, "oidc-endpoint", envStringOrDefault("NB_PROXY_OIDC_ENDPOINT", ""), "The OIDC Endpoint for OIDC User Authentication")
+	rootCmd.Flags().StringVar(&oidcScopes, "oidc-scopes", envStringOrDefault("NB_PROXY_OIDC_SCOPES", "openid,profile,email"), "The OAuth2 scopes for OIDC User Authentication, comma separated")
+}
+
+// Execute runs the root command.
+func Execute() {
+	if err := rootCmd.Execute(); err != nil {
+		os.Exit(1)
+	}
+}
+
+// SetVersionInfo sets version information for the CLI.
+func SetVersionInfo(version, commit, buildDate, goVersion string) {
+	Version = version
+	Commit = commit
+	BuildDate = buildDate
+	GoVersion = goVersion
+	rootCmd.Version = version
+	rootCmd.SetVersionTemplate("Version: {{.Version}}, Commit: " + Commit + ", BuildDate: " + BuildDate + ", Go: " + GoVersion + "\n")
+}
+
+func runServer(cmd *cobra.Command, args []string) error {
+	level := "error"
+	if debugLogs {
+		level = "debug"
+	}
+	logger := log.New()
+
+	_ = util.InitLogger(logger, level, util.LogConsole)
+
+	log.Infof("configured log level: %s", level)
+
+	srv := proxy.Server{
+		Logger:                   logger,
+		Version:                  Version,
+		ManagementAddress:        mgmtAddr,
+		ProxyURL:                 proxyURL,
+		CertificateDirectory:     certDir,
+		GenerateACMECertificates: acmeCerts,
+		ACMEChallengeAddress:     acmeAddr,
+		ACMEDirectory:            acmeDir,
+		DebugEndpointEnabled:     debugEndpoint,
+		DebugEndpointAddress:     debugEndpointAddr,
+		OIDCClientId:             oidcClientID,
+		OIDCClientSecret:         oidcClientSecret,
+		OIDCEndpoint:             oidcEndpoint,
+		OIDCScopes:               strings.Split(oidcScopes, ","),
+	}
+
+	if err := srv.ListenAndServe(context.TODO(), addr); err != nil {
+		log.Fatal(err)
+	}
+	return nil
+}
+
+func envBoolOrDefault(key string, def bool) bool {
+	v, exists := os.LookupEnv(key)
+	if !exists {
+		return def
+	}
+	parsed, err := strconv.ParseBool(v)
+	if err != nil {
+		return def
+	}
+	return parsed
+}
+
+func envStringOrDefault(key string, def string) string {
+	v, exists := os.LookupEnv(key)
+	if !exists {
+		return def
+	}
+	return v
+}
--- a/proxy/cmd/proxy/main.go
+++ b/proxy/cmd/proxy/main.go
@@ -1,22 +1,11 @@
 package main

 import (
-	"context"
-	"flag"
-	"fmt"
-	"os"
 	"runtime"
-	"strings"

-	"github.com/netbirdio/netbird/util"
-	log "github.com/sirupsen/logrus"
-	"golang.org/x/crypto/acme"
-
-	"github.com/netbirdio/netbird/proxy"
+	"github.com/netbirdio/netbird/proxy/cmd/proxy/cmd"
 )

-const DefaultManagementURL = "https://api.netbird.io:443"
-
 var (
 	// Version is the application version (set via ldflags during build)
 	Version = "dev"
@@ -31,78 +20,7 @@ var (
 	GoVersion = runtime.Version()
 )

-func envBoolOrDefault(key string, def bool) bool {
-	v, exists := os.LookupEnv(key)
-	if !exists {
-		return def
-	}
-	return v == strings.ToLower("true")
-}
-
-func envStringOrDefault(key string, def string) string {
-	v, exists := os.LookupEnv(key)
-	if !exists {
-		return def
-	}
-	return v
-}
-
 func main() {
-	var (
-		version, debug                               bool
-		mgmtAddr, addr, url, certDir                 string
-		acmeCerts                                    bool
-		acmeAddr, acmeDir                            string
-		oidcId, oidcSecret, oidcEndpoint, oidcScopes string
-	)
-
-	flag.BoolVar(&version, "v", false, "Print version and exit")
-	flag.BoolVar(&debug, "debug", envBoolOrDefault("NB_PROXY_DEBUG_LOGS", false), "Enable debug logs")
-	flag.StringVar(&mgmtAddr, "mgmt", envStringOrDefault("NB_PROXY_MANAGEMENT_ADDRESS", DefaultManagementURL), "Management address to connect to.")
-	flag.StringVar(&addr, "addr", envStringOrDefault("NB_PROXY_ADDRESS", ":443"), "Reverse proxy address to listen on.")
-	flag.StringVar(&url, "url", envStringOrDefault("NB_PROXY_URL", "proxy.netbird.io"), "The URL at which this proxy will be reached, where CNAME records for proxied endpoints will be directed.")
-	flag.StringVar(&certDir, "cert-dir", envStringOrDefault("NB_PROXY_CERTIFICATE_DIRECTORY", "./certs"), "Directory to store ")
-	flag.BoolVar(&acmeCerts, "acme-certs", envBoolOrDefault("NB_PROXY_ACME_CERTIFICATES", false), "Generate ACME certificates using HTTP-01 challenges.")
-	flag.StringVar(&acmeAddr, "acme-addr", envStringOrDefault("NB_PROXY_ACME_ADDRESS", ":80"), "HTTP address to listen on, used for ACME HTTP-01 certificate generation.")
-	flag.StringVar(&acmeDir, "acme-dir", envStringOrDefault("NB_PROXY_ACME_DIRECTORY", acme.LetsEncryptURL), "URL of ACME challenge directory.")
-	flag.StringVar(&oidcId, "oidc-id", envStringOrDefault("NB_PROXY_OIDC_CLIENT_ID", "netbird-proxy"), "The OAuth2 Client ID for OIDC User Authentication")
-	flag.StringVar(&oidcSecret, "oidc-secret", envStringOrDefault("NB_PROXY_OIDC_CLIENT_SECRET", ""), "The OAuth2 Client Secret for OIDC User Authentication")
-	flag.StringVar(&oidcEndpoint, "oidc-endpoint", envStringOrDefault("NB_PROXY_OIDC_ENDPOINT", ""), "The OIDC Endpoint for OIDC User Authentication")
-	flag.StringVar(&oidcScopes, "oidc-scopes", envStringOrDefault("NB_PROXY_OIDC_SCOPES", "openid,profile,email"), "The OAuth2 scopes for OIDC User Authentication, comma separated")
-	flag.Parse()
-
-	if version {
-		fmt.Printf("Version: %s, Commit: %s, BuildDate: %s, Go: %s", Version, Commit, BuildDate, GoVersion)
-		os.Exit(0)
-	}
-
-	// Configure logrus.
-	level := "error"
-	if debug {
-		level = "debug"
-	}
-	logger := log.New()
-
-	_ = util.InitLogger(logger, level, util.LogConsole)
-
-	log.Infof("configured log level: %s", level)
-
-	srv := proxy.Server{
-		Logger:                   logger,
-		Version:                  Version,
-		ManagementAddress:        mgmtAddr,
-		ProxyURL:                 url,
-		CertificateDirectory:     certDir,
-		GenerateACMECertificates: acmeCerts,
-		ACMEChallengeAddress:     acmeAddr,
-		ACMEDirectory:            acmeDir,
-		OIDCClientId:             oidcId,
-		OIDCClientSecret:         oidcSecret,
-		OIDCEndpoint:             oidcEndpoint,
-		OIDCScopes:               strings.Split(oidcScopes, ","),
-	}
-
-	if err := srv.ListenAndServe(context.TODO(), addr); err != nil {
-		log.Fatal(err)
-	}
+	cmd.SetVersionInfo(Version, Commit, BuildDate, GoVersion)
+	cmd.Execute()
 }