client: add optional daemon JSON socket gateway

Add positive-only service flags to enable the daemon HTTP/JSON grpc-gateway socket and persist its service configuration. Support unix and tcp listener addresses while keeping the gateway disabled by default and preserving live Unix sockets during stale cleanup.

Add gateway/socket coverage and a Docker smoke test script for validating Status over TCP and Unix JSON sockets.

client/cmd/service.go

@@ -26,10 +26,10 @@ var serviceCmd = &cobra.Command{
 const defaultJSONSocket = "unix:///var/run/netbird-http.sock"
 
 var (
-	serviceName        string
-	serviceEnvVars     []string
-	jsonSocket         string
-	jsonSocketDisabled bool
+	serviceName      string
+	serviceEnvVars   []string
+	jsonSocket       string
+	enableJSONSocket bool
 )
 
 type program struct {
@@ -53,8 +53,8 @@ func init() {
 	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(&captureEnabled, "enable-capture", false, "Enables packet capture via 'netbird debug capture'. To persist, use: netbird service install --enable-capture")
 	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")
-	serviceCmd.PersistentFlags().StringVar(&jsonSocket, "json-socket", defaultJSONSocket, "HTTP/JSON API socket address served by grpc-gateway [unix|tcp]://[path|host:port]. To persist, use: netbird service install --json-socket")
-	serviceCmd.PersistentFlags().BoolVar(&jsonSocketDisabled, "disable-json-socket", false, "Disables the HTTP/JSON API socket. To persist, use: netbird service install --disable-json-socket")
+	serviceCmd.PersistentFlags().BoolVar(&enableJSONSocket, "enable-json-socket", false, "Enables the HTTP/JSON API socket served by grpc-gateway. To persist, use: netbird service install --enable-json-socket")
+	serviceCmd.PersistentFlags().StringVar(&jsonSocket, "json-socket", defaultJSONSocket, "HTTP/JSON API socket address [unix|tcp]://[path|host:port]. Requires --enable-json-socket to serve. To persist, use: netbird service install --enable-json-socket --json-socket")
 
 	rootCmd.PersistentFlags().StringVarP(&serviceName, "service", "s", defaultServiceName, "Netbird system service name")
 	serviceEnvDesc := `Sets extra environment variables for the service. ` +

client/cmd/service_controller.go

@@ -19,10 +19,21 @@ import (
 	"github.com/netbirdio/netbird/util"
 )
 
+func validateJSONSocketFlags() error {
+	if serviceCmd.PersistentFlags().Changed("json-socket") && !enableJSONSocket {
+		return fmt.Errorf("--json-socket requires --enable-json-socket to configure the daemon JSON gateway")
+	}
+	return nil
+}
+
 func (p *program) Start(svc service.Service) error {
 	// Start should not block. Do the actual work async.
 	log.Info("starting NetBird service") //nolint
 
+	if err := validateJSONSocketFlags(); err != nil {
+		return err
+	}
+
 	// Collect static system and platform information
 	system.UpdateStaticInfoAsync()
 
@@ -35,7 +46,7 @@ func (p *program) Start(svc service.Service) error {
 	}
 
 	var jsonListener *socketListener
-	if !jsonSocketDisabled {
+	if enableJSONSocket {
 		jsonListener, err = listenOnAddress(jsonSocket)
 		if err != nil {
 			_ = daemonListener.Close()
@@ -171,6 +182,9 @@ var runCmd = &cobra.Command{
 		if err != nil {
 			return err
 		}
+		if err := validateJSONSocketFlags(); err != nil {
+			return err
+		}
 
 		return s.Run()
 	},
@@ -185,6 +199,9 @@ var startCmd = &cobra.Command{
 		if err != nil {
 			return err
 		}
+		if err := validateJSONSocketFlags(); err != nil {
+			return err
+		}
 
 		if err := s.Start(); err != nil {
 			return fmt.Errorf("start service: %w", err)
@@ -221,6 +238,9 @@ var restartCmd = &cobra.Command{
 		if err != nil {
 			return err
 		}
+		if err := validateJSONSocketFlags(); err != nil {
+			return err
+		}
 
 		if err := s.Restart(); err != nil {
 			return fmt.Errorf("restart service: %w", err)

client/cmd/service_installer.go

@@ -67,9 +67,8 @@ func buildServiceArguments() []string {
 		args = append(args, "--disable-networks")
 	}
 
-	args = append(args, "--json-socket", jsonSocket)
-	if jsonSocketDisabled {
-		args = append(args, "--disable-json-socket")
+	if enableJSONSocket {
+		args = append(args, "--enable-json-socket", "--json-socket", jsonSocket)
 	}
 
 	return args
@@ -111,6 +110,10 @@ func configurePlatformSpecificSettings(svcConfig *service.Config) error {
 
 // Create fully configured service config for install/reconfigure
 func createServiceConfigForInstall() (*service.Config, error) {
+	if err := validateJSONSocketFlags(); err != nil {
+		return nil, err
+	}
+
 	svcConfig, err := newSVCConfig()
 	if err != nil {
 		return nil, fmt.Errorf("create service config: %w", err)

client/cmd/service_json_socket_test.go

@@ -0,0 +1,176 @@
+//go:build !ios && !android
+
+package cmd
+
+import (
+	"net"
+	"os"
+	"path/filepath"
+	"runtime"
+	"testing"
+
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func preserveJSONSocketTestState(t *testing.T) {
+	t.Helper()
+
+	origJSONSocket := jsonSocket
+	origEnableJSONSocket := enableJSONSocket
+	origChanged := map[string]bool{}
+	serviceCmd.PersistentFlags().VisitAll(func(flag *pflag.Flag) {
+		origChanged[flag.Name] = flag.Changed
+	})
+
+	t.Cleanup(func() {
+		jsonSocket = origJSONSocket
+		enableJSONSocket = origEnableJSONSocket
+		serviceCmd.PersistentFlags().VisitAll(func(flag *pflag.Flag) {
+			flag.Changed = origChanged[flag.Name]
+		})
+	})
+}
+
+func TestJSONSocketFlagsArePositiveEnableOnly(t *testing.T) {
+	assert.NotNil(t, serviceCmd.PersistentFlags().Lookup("enable-json-socket"))
+	assert.NotNil(t, serviceCmd.PersistentFlags().Lookup("json-socket"))
+	assert.Nil(t, serviceCmd.PersistentFlags().Lookup("disable-json-socket"))
+	assert.Equal(t, "false", serviceCmd.PersistentFlags().Lookup("enable-json-socket").DefValue)
+}
+
+func TestBuildServiceArgumentsDefaultDisablesJSONSocket(t *testing.T) {
+	preserveJSONSocketTestState(t)
+
+	enableJSONSocket = false
+	jsonSocket = "tcp://127.0.0.1:8080"
+
+	args := buildServiceArguments()
+
+	assert.NotContains(t, args, "--enable-json-socket")
+	assert.NotContains(t, args, "--json-socket")
+}
+
+func TestBuildServiceArgumentsIncludesJSONSocketWhenEnabled(t *testing.T) {
+	preserveJSONSocketTestState(t)
+
+	enableJSONSocket = true
+	jsonSocket = "tcp://127.0.0.1:8080"
+
+	args := buildServiceArguments()
+
+	enableIndex := indexOfArg(args, "--enable-json-socket")
+	jsonIndex := indexOfArg(args, "--json-socket")
+	require.NotEqual(t, -1, enableIndex)
+	require.NotEqual(t, -1, jsonIndex)
+	require.Less(t, enableIndex, jsonIndex)
+	require.Less(t, jsonIndex+1, len(args))
+	assert.Equal(t, "tcp://127.0.0.1:8080", args[jsonIndex+1])
+}
+
+func TestJSONSocketWithoutEnableValidation(t *testing.T) {
+	preserveJSONSocketTestState(t)
+
+	enableJSONSocket = false
+	require.NoError(t, serviceCmd.PersistentFlags().Set("json-socket", "tcp://127.0.0.1:8080"))
+
+	err := validateJSONSocketFlags()
+
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "--enable-json-socket")
+}
+
+func TestJSONSocketWithEnableValidation(t *testing.T) {
+	preserveJSONSocketTestState(t)
+
+	require.NoError(t, serviceCmd.PersistentFlags().Set("enable-json-socket", "true"))
+	require.NoError(t, serviceCmd.PersistentFlags().Set("json-socket", "tcp://127.0.0.1:8080"))
+
+	assert.NoError(t, validateJSONSocketFlags())
+}
+
+func TestJSONSocketServiceParamsPersistEnableAndAddress(t *testing.T) {
+	preserveJSONSocketTestState(t)
+	serviceCmd.PersistentFlags().VisitAll(func(flag *pflag.Flag) {
+		flag.Changed = false
+	})
+
+	enableJSONSocket = true
+	jsonSocket = "tcp://127.0.0.1:8080"
+
+	params := currentServiceParams()
+	require.True(t, params.EnableJSONSocket)
+	require.Equal(t, "tcp://127.0.0.1:8080", params.JSONSocket)
+
+	enableJSONSocket = false
+	jsonSocket = defaultJSONSocket
+	applyServiceParams(testServiceEnvCommand(), params)
+
+	assert.True(t, enableJSONSocket)
+	assert.Equal(t, "tcp://127.0.0.1:8080", jsonSocket)
+}
+
+func TestRemoveStaleUnixSocketDoesNotRemoveRegularFile(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "netbird-http.sock")
+	require.NoError(t, os.WriteFile(path, []byte("not a socket"), 0600))
+
+	removeStaleUnixSocket(path)
+
+	data, err := os.ReadFile(path)
+	require.NoError(t, err)
+	assert.Equal(t, []byte("not a socket"), data)
+}
+
+func TestRemoveStaleUnixSocketRemovesSocket(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("unix sockets are not available on Windows")
+	}
+
+	path := filepath.Join(t.TempDir(), "netbird-http.sock")
+	addr := &net.UnixAddr{Name: path, Net: "unix"}
+	listener, err := net.ListenUnix("unix", addr)
+	require.NoError(t, err)
+	listener.SetUnlinkOnClose(false)
+	require.NoError(t, listener.Close())
+
+	_, err = os.Lstat(path)
+	require.NoError(t, err, "test setup must leave a stale Unix socket path")
+
+	removeStaleUnixSocket(path)
+
+	_, err = os.Lstat(path)
+	assert.True(t, os.IsNotExist(err), "expected stale Unix socket to be removed, got %v", err)
+}
+
+func TestRemoveStaleUnixSocketDoesNotRemoveLiveSocket(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("unix sockets are not available on Windows")
+	}
+
+	path := filepath.Join(t.TempDir(), "netbird-http.sock")
+	listener, err := net.Listen("unix", path)
+	require.NoError(t, err)
+	defer listener.Close()
+
+	removeStaleUnixSocket(path)
+
+	_, err = os.Lstat(path)
+	assert.NoError(t, err, "expected live Unix socket to be preserved")
+}
+
+func testServiceEnvCommand() *cobra.Command {
+	cmd := &cobra.Command{}
+	cmd.Flags().StringSlice("service-env", nil, "")
+	return cmd
+}
+
+func indexOfArg(args []string, arg string) int {
+	for i, candidate := range args {
+		if candidate == arg {
+			return i
+		}
+	}
+	return -1
+}

client/cmd/service_params.go

@@ -31,7 +31,7 @@ type serviceParams struct {
 	DisableUpdateSettings bool              `json:"disable_update_settings,omitempty"`
 	EnableCapture         bool              `json:"enable_capture,omitempty"`
 	DisableNetworks       bool              `json:"disable_networks,omitempty"`
-	DisableJSONSocket     bool              `json:"disable_json_socket,omitempty"`
+	EnableJSONSocket      bool              `json:"enable_json_socket,omitempty"`
 	ServiceEnvVars        map[string]string `json:"service_env_vars,omitempty"`
 }
 
@@ -85,7 +85,7 @@ func currentServiceParams() *serviceParams {
 		DisableUpdateSettings: updateSettingsDisabled,
 		EnableCapture:         captureEnabled,
 		DisableNetworks:       networksDisabled,
-		DisableJSONSocket:     jsonSocketDisabled,
+		EnableJSONSocket:      enableJSONSocket,
 	}
 
 	if len(serviceEnvVars) > 0 {
@@ -127,18 +127,12 @@ func applyServiceParams(cmd *cobra.Command, params *serviceParams) {
 		daemonAddr = params.DaemonAddr
 	}
 
-	jsonSocketChanged := serviceCmd.PersistentFlags().Changed("json-socket")
-	if !jsonSocketChanged && params.JSONSocket != "" {
+	if !serviceCmd.PersistentFlags().Changed("json-socket") && params.JSONSocket != "" {
 		jsonSocket = params.JSONSocket
 	}
 
-	if !serviceCmd.PersistentFlags().Changed("disable-json-socket") {
-		jsonSocketDisabled = params.DisableJSONSocket
-		// Passing --json-socket should re-enable the JSON gateway unless
-		// --disable-json-socket was explicitly provided too.
-		if jsonSocketChanged {
-			jsonSocketDisabled = false
-		}
+	if !serviceCmd.PersistentFlags().Changed("enable-json-socket") {
+		enableJSONSocket = params.EnableJSONSocket
 	}
 
 	// For optional fields where empty means "use default", always apply so

client/cmd/service_params_test.go

@@ -41,6 +41,8 @@ func TestSaveAndLoadServiceParams(t *testing.T) {
 	params := &serviceParams{
 		LogLevel:              "debug",
 		DaemonAddr:            "unix:///var/run/netbird.sock",
+		JSONSocket:            "tcp://127.0.0.1:8080",
+		EnableJSONSocket:      true,
 		ManagementURL:         "https://my.server.com",
 		ConfigPath:            "/etc/netbird/config.json",
 		LogFiles:              []string{"/var/log/netbird/client.log", "console"},
@@ -63,6 +65,8 @@ func TestSaveAndLoadServiceParams(t *testing.T) {
 
 	assert.Equal(t, params.LogLevel, loaded.LogLevel)
 	assert.Equal(t, params.DaemonAddr, loaded.DaemonAddr)
+	assert.Equal(t, params.JSONSocket, loaded.JSONSocket)
+	assert.Equal(t, params.EnableJSONSocket, loaded.EnableJSONSocket)
 	assert.Equal(t, params.ManagementURL, loaded.ManagementURL)
 	assert.Equal(t, params.ConfigPath, loaded.ConfigPath)
 	assert.Equal(t, params.LogFiles, loaded.LogFiles)
@@ -101,6 +105,8 @@ func TestLoadServiceParams_InvalidJSON(t *testing.T) {
 func TestCurrentServiceParams(t *testing.T) {
 	origLogLevel := logLevel
 	origDaemonAddr := daemonAddr
+	origJSONSocket := jsonSocket
+	origEnableJSONSocket := enableJSONSocket
 	origManagementURL := managementURL
 	origConfigPath := configPath
 	origLogFiles := logFiles
@@ -110,6 +116,8 @@ func TestCurrentServiceParams(t *testing.T) {
 	t.Cleanup(func() {
 		logLevel = origLogLevel
 		daemonAddr = origDaemonAddr
+		jsonSocket = origJSONSocket
+		enableJSONSocket = origEnableJSONSocket
 		managementURL = origManagementURL
 		configPath = origConfigPath
 		logFiles = origLogFiles
@@ -120,6 +128,8 @@ func TestCurrentServiceParams(t *testing.T) {
 
 	logLevel = "trace"
 	daemonAddr = "tcp://127.0.0.1:9999"
+	jsonSocket = "tcp://127.0.0.1:8080"
+	enableJSONSocket = true
 	managementURL = "https://mgmt.example.com"
 	configPath = "/tmp/test-config.json"
 	logFiles = []string{"/tmp/test.log"}
@@ -131,6 +141,8 @@ func TestCurrentServiceParams(t *testing.T) {
 
 	assert.Equal(t, "trace", params.LogLevel)
 	assert.Equal(t, "tcp://127.0.0.1:9999", params.DaemonAddr)
+	assert.Equal(t, "tcp://127.0.0.1:8080", params.JSONSocket)
+	assert.True(t, params.EnableJSONSocket)
 	assert.Equal(t, "https://mgmt.example.com", params.ManagementURL)
 	assert.Equal(t, "/tmp/test-config.json", params.ConfigPath)
 	assert.Equal(t, []string{"/tmp/test.log"}, params.LogFiles)
@@ -142,6 +154,8 @@ func TestCurrentServiceParams(t *testing.T) {
 func TestApplyServiceParams_OnlyUnchangedFlags(t *testing.T) {
 	origLogLevel := logLevel
 	origDaemonAddr := daemonAddr
+	origJSONSocket := jsonSocket
+	origEnableJSONSocket := enableJSONSocket
 	origManagementURL := managementURL
 	origConfigPath := configPath
 	origLogFiles := logFiles
@@ -151,6 +165,8 @@ func TestApplyServiceParams_OnlyUnchangedFlags(t *testing.T) {
 	t.Cleanup(func() {
 		logLevel = origLogLevel
 		daemonAddr = origDaemonAddr
+		jsonSocket = origJSONSocket
+		enableJSONSocket = origEnableJSONSocket
 		managementURL = origManagementURL
 		configPath = origConfigPath
 		logFiles = origLogFiles
@@ -162,6 +178,8 @@ func TestApplyServiceParams_OnlyUnchangedFlags(t *testing.T) {
 	// Reset all flags to defaults.
 	logLevel = "info"
 	daemonAddr = "unix:///var/run/netbird.sock"
+	jsonSocket = defaultJSONSocket
+	enableJSONSocket = false
 	managementURL = ""
 	configPath = "/etc/netbird/config.json"
 	logFiles = []string{"/var/log/netbird/client.log"}
@@ -184,6 +202,8 @@ func TestApplyServiceParams_OnlyUnchangedFlags(t *testing.T) {
 	saved := &serviceParams{
 		LogLevel:              "debug",
 		DaemonAddr:            "tcp://127.0.0.1:5555",
+		JSONSocket:            "tcp://127.0.0.1:8080",
+		EnableJSONSocket:      true,
 		ManagementURL:         "https://saved.example.com",
 		ConfigPath:            "/saved/config.json",
 		LogFiles:              []string{"/saved/client.log"},
@@ -201,6 +221,8 @@ func TestApplyServiceParams_OnlyUnchangedFlags(t *testing.T) {
 
 	// All other fields were not Changed, so they should use saved values.
 	assert.Equal(t, "tcp://127.0.0.1:5555", daemonAddr)
+	assert.Equal(t, "tcp://127.0.0.1:8080", jsonSocket)
+	assert.True(t, enableJSONSocket)
 	assert.Equal(t, "https://saved.example.com", managementURL)
 	assert.Equal(t, "/saved/config.json", configPath)
 	assert.Equal(t, []string{"/saved/client.log"}, logFiles)
@@ -212,14 +234,17 @@ func TestApplyServiceParams_OnlyUnchangedFlags(t *testing.T) {
 func TestApplyServiceParams_BooleanRevertToFalse(t *testing.T) {
 	origProfilesDisabled := profilesDisabled
 	origUpdateSettingsDisabled := updateSettingsDisabled
+	origEnableJSONSocket := enableJSONSocket
 	t.Cleanup(func() {
 		profilesDisabled = origProfilesDisabled
 		updateSettingsDisabled = origUpdateSettingsDisabled
+		enableJSONSocket = origEnableJSONSocket
 	})
 
 	// Simulate current state where booleans are true (e.g. set by previous install).
 	profilesDisabled = true
 	updateSettingsDisabled = true
+	enableJSONSocket = true
 
 	// Reset Changed state so flags appear unset.
 	serviceCmd.PersistentFlags().VisitAll(func(f *pflag.Flag) {
@@ -238,6 +263,7 @@ func TestApplyServiceParams_BooleanRevertToFalse(t *testing.T) {
 
 	assert.False(t, profilesDisabled, "saved false should override current true")
 	assert.False(t, updateSettingsDisabled, "saved false should override current true")
+	assert.False(t, enableJSONSocket, "saved false should override current true")
 }
 
 func TestApplyServiceParams_ClearManagementURL(t *testing.T) {
@@ -538,7 +564,7 @@ func fieldToGlobalVar(field string) string {
 		"DisableUpdateSettings": "updateSettingsDisabled",
 		"EnableCapture":         "captureEnabled",
 		"DisableNetworks":       "networksDisabled",
-		"DisableJSONSocket":     "jsonSocketDisabled",
+		"EnableJSONSocket":      "enableJSONSocket",
 		"ServiceEnvVars":        "serviceEnvVars",
 	}
 	if v, ok := m[field]; ok {

client/cmd/service_socket.go

@@ -3,10 +3,13 @@
 package cmd
 
 import (
+	"errors"
 	"fmt"
 	"net"
 	"os"
 	"strings"
+	"syscall"
+	"time"
 
 	log "github.com/sirupsen/logrus"
 )
@@ -50,17 +53,42 @@ func parseListenAddress(addr string) (string, string, error) {
 }
 
 func removeStaleUnixSocket(path string) {
-	stat, err := os.Stat(path)
-	if err == nil && !stat.IsDir() {
-		if err := os.Remove(path); err != nil {
-			log.Debugf("remove socket file: %v", err)
+	stat, err := os.Lstat(path)
+	if err != nil {
+		if !os.IsNotExist(err) {
+			log.Debugf("stat socket file: %v", err)
 		}
 		return
 	}
 
-	if err != nil && !os.IsNotExist(err) {
-		log.Debugf("stat socket file: %v", err)
+	if stat.Mode()&os.ModeSocket == 0 {
+		return
 	}
+
+	if !isStaleUnixSocket(path) {
+		return
+	}
+
+	if err := os.Remove(path); err != nil {
+		log.Debugf("remove socket file: %v", err)
+	}
+}
+
+func isStaleUnixSocket(path string) bool {
+	conn, err := net.DialTimeout("unix", path, 100*time.Millisecond)
+	if err == nil {
+		if closeErr := conn.Close(); closeErr != nil {
+			log.Debugf("close unix socket probe: %v", closeErr)
+		}
+		return false
+	}
+
+	if os.IsNotExist(err) || os.IsPermission(err) || os.IsTimeout(err) {
+		log.Debugf("not removing unix socket %s after probe error: %v", path, err)
+		return false
+	}
+
+	return errors.Is(err, syscall.ECONNREFUSED)
 }
 
 func removeStaleUnixSocketForAddress(addr string) {