DAOS-3985 control: Add ControlInterface to server config (#17367)

By default, the control plane server binds to 0.0.0.0, which
means that it is listening to all addresses on all interfaces.
In some cases, the admin may prefer to specify a single interface
to be used for control plane traffic.

When control_iface is set in daos_server.yml, the server will
use the lowest IPv4 address on that interface as both the listen
address and the address recorded in the management database. If
the prometheus listener is configured, it will also use the same
address found for the control interface.

Signed-off-by: Michael MacDonald <[email protected]>

Author: mjmac

src/control/fault/code/codes.go

@@ -1,6 +1,6 @@
 //
 // (C) Copyright 2018-2024 Intel Corporation.
-// (C) Copyright 2025 Hewlett Packard Enterprise Development LP
+// (C) Copyright 2025-2026 Hewlett Packard Enterprise Development LP
 // (C) Copyright 2025 Google LLC
 //
 // SPDX-License-Identifier: BSD-2-Clause-Patent
@@ -205,6 +205,8 @@ const (
 	ServerConfigBdevExcludeClash
 	ServerConfigHugepagesDisabledWithNrSet
 	ServerConfigScmHugeEnabled
+	ServerConfigBadControlInterface
+	ServerConfigControlInterfaceMismatch
 )
 
 // SPDK library bindings codes

src/control/lib/telemetry/promexp/httpd.go

@@ -1,5 +1,6 @@
 //
 // (C) Copyright 2021-2024 Intel Corporation.
+// (C) Copyright 2026 Hewlett Packard Enterprise Development LP
 //
 // SPDX-License-Identifier: BSD-2-Clause-Patent
 //
@@ -29,9 +30,10 @@ type (
 
 	// ExporterConfig defines the configuration for the Prometheus exporter.
 	ExporterConfig struct {
-		Port     int
-		Title    string
-		Register RegMonFn
+		Port        int
+		BindAddress string // optional: IP address to bind to (default: 0.0.0.0)
+		Title       string
+		Register    RegMonFn
 	}
 )
 
@@ -60,7 +62,11 @@ func StartExporter(ctx context.Context, log logging.Logger, cfg *ExporterConfig)
 		return nil, errors.Wrap(err, "failed to register client monitor")
 	}
 
-	listenAddress := fmt.Sprintf("0.0.0.0:%d", cfg.Port)
+	bindAddr := cfg.BindAddress
+	if bindAddr == "" {
+		bindAddr = "0.0.0.0"
+	}
+	listenAddress := fmt.Sprintf("%s:%d", bindAddr, cfg.Port)
 
 	srv := http.Server{Addr: listenAddress}
 	http.Handle("/metrics", promhttp.HandlerFor(

src/control/server/config/faults.go

@@ -1,6 +1,6 @@
 //
 // (C) Copyright 2020-2024 Intel Corporation.
-// (C) Copyright 2025 Hewlett Packard Enterprise Development LP
+// (C) Copyright 2025-2026 Hewlett Packard Enterprise Development LP
 //
 // SPDX-License-Identifier: BSD-2-Clause-Patent
 //
@@ -283,6 +283,25 @@ func FaultConfigEngineNUMAImbalance(nodeMap map[int]int) *fault.Fault {
 	)
 }
 
+// FaultConfigBadControlInterface creates a fault for an invalid control plane network interface.
+func FaultConfigBadControlInterface(iface string, err error) *fault.Fault {
+	return serverConfigFault(
+		code.ServerConfigBadControlInterface,
+		fmt.Sprintf("control_iface %q is invalid: %s", iface, err),
+		"update the 'control_iface' parameter with a valid network interface and restart",
+	)
+}
+
+// FaultConfigControlInterfaceMismatch creates a fault when the control interface address
+// doesn't match the configured MS replica address.
+func FaultConfigControlInterfaceMismatch(ifaceAddr, replicaAddr string) *fault.Fault {
+	return serverConfigFault(
+		code.ServerConfigControlInterfaceMismatch,
+		fmt.Sprintf("control_iface address %s doesn't match configured MS replica address %s", ifaceAddr, replicaAddr),
+		"ensure 'control_iface' specifies an interface with an address matching this server's entry in 'mgmt_svc_replicas'",
+	)
+}
+
 func serverConfigFault(code code.Code, desc, res string) *fault.Fault {
 	return &fault.Fault{
 		Domain:      "serverconfig",

src/control/server/config/server.go

@@ -1,6 +1,6 @@
 //
 // (C) Copyright 2020-2024 Intel Corporation.
-// (C) Copyright 2025 Hewlett Packard Enterprise Development LP
+// (C) Copyright 2025-2026 Hewlett Packard Enterprise Development LP
 //
 // SPDX-License-Identifier: BSD-2-Clause-Patent
 //
@@ -58,6 +58,7 @@ type deprecatedParams struct {
 type Server struct {
 	// control-specific
 	ControlPort        int                       `yaml:"port"`
+	ControlInterface   string                    `yaml:"control_iface,omitempty"`
 	TransportConfig    *security.TransportConfig `yaml:"transport_config"`
 	Engines            []*engine.Config          `yaml:"engines"`
 	BdevExclude        []string                  `yaml:"bdev_exclude,omitempty"`
@@ -231,6 +232,12 @@ func (cfg *Server) WithControlPort(port int) *Server {
 	return cfg
 }
 
+// WithControlInterface sets the network interface for the control plane listener.
+func (cfg *Server) WithControlInterface(iface string) *Server {
+	cfg.ControlInterface = iface
+	return cfg
+}
+
 // WithTransportConfig sets the gRPC transport configuration.
 func (cfg *Server) WithTransportConfig(cfgTransport *security.TransportConfig) *Server {
 	cfg.TransportConfig = cfgTransport

src/control/server/config/server_test.go

@@ -240,6 +240,7 @@ func TestServerConfig_Constructed(t *testing.T) {
 	// possible to construct an identical configuration with the helpers.
 	constructed := DefaultServer().
 		WithControlPort(10001).
+		WithControlInterface("eth0").
 		WithControlMetadata(storage.ControlMetadata{
 			Path:       "/home/daos_server/control_meta",
 			DevicePath: "/dev/sdb1",

src/control/server/server.go

@@ -1,6 +1,6 @@
 //
 // (C) Copyright 2018-2024 Intel Corporation.
-// (C) Copyright 2025 Hewlett Packard Enterprise Development LP
+// (C) Copyright 2025-2026 Hewlett Packard Enterprise Development LP
 //
 // SPDX-License-Identifier: BSD-2-Clause-Patent
 //
@@ -308,21 +308,37 @@ func (srv *server) setCoreDumpFilter() error {
 func (srv *server) initNetwork() error {
 	defer srv.logDuration(track("time to init network"))
 
-	ctlAddr, err := getControlAddr(ctlAddrParams{
+	params := ctlAddrParams{
 		port:           srv.cfg.ControlPort,
 		replicaAddrSrc: srv.sysdb,
 		lookupHost:     net.LookupIP,
-	})
+	}
+
+	// If a control interface is configured, look it up and pass it to getControlAddr.
+	// Also track whether we should bind to a specific IP (only when control_iface is set).
+	bindToCtlAddr := false
+	if srv.cfg.ControlInterface != "" {
+		iface, err := net.InterfaceByName(srv.cfg.ControlInterface)
+		if err != nil {
+			return config.FaultConfigBadControlInterface(srv.cfg.ControlInterface, err)
+		}
+		params.ctlIface = iface
+		bindToCtlAddr = true
+		srv.log.Debugf("using control interface %s for listener", srv.cfg.ControlInterface)
+	}
+
+	ctlAddr, err := getControlAddr(params)
 	if err != nil {
 		return err
 	}
 
-	listener, err := createListener(ctlAddr, net.Listen)
+	listener, err := createListener(ctlAddr, net.Listen, bindToCtlAddr)
 	if err != nil {
 		return err
 	}
 	srv.ctlAddr = ctlAddr
 	srv.listener = listener
+	srv.log.Debugf("control plane listener bound to %s", ctlAddr)
 
 	return nil
 }

src/control/server/server_utils.go

@@ -1,6 +1,6 @@
 //
 // (C) Copyright 2021-2024 Intel Corporation.
-// (C) Copyright 2025 Hewlett Packard Enterprise Development LP
+// (C) Copyright 2025-2026 Hewlett Packard Enterprise Development LP
 //
 // SPDX-License-Identifier: BSD-2-Clause-Patent
 //
@@ -150,11 +150,30 @@ type ctlAddrParams struct {
 	port           int
 	replicaAddrSrc replicaAddrGetter
 	lookupHost     ipLookupFn
+	ctlIface       netInterface // optional: if set, use this interface for bind address
 }
 
 func getControlAddr(params ctlAddrParams) (*net.TCPAddr, error) {
-	ipStr := "0.0.0.0"
+	// If a control interface is configured, use its first IPv4 address.
+	if params.ctlIface != nil {
+		ip, err := getFirstIPv4Addr(params.ctlIface)
+		if err != nil {
+			return nil, errors.Wrap(err, "getting control interface address")
+		}
+
+		// If this node is a replica, verify the control interface address matches
+		// the configured replica address. A mismatch would break raft connectivity.
+		if repAddr, err := params.replicaAddrSrc.ReplicaAddr(); err == nil {
+			if !repAddr.IP.Equal(ip) {
+				return nil, config.FaultConfigControlInterfaceMismatch(ip.String(), repAddr.IP.String())
+			}
+		}
 
+		return &net.TCPAddr{IP: ip, Port: params.port}, nil
+	}
+
+	// Fall back to legacy behavior: use replica address if available, otherwise 0.0.0.0.
+	ipStr := "0.0.0.0"
 	if repAddr, err := params.replicaAddrSrc.ReplicaAddr(); err == nil {
 		ipStr = repAddr.IP.String()
 	}
@@ -167,11 +186,17 @@ func getControlAddr(params ctlAddrParams) (*net.TCPAddr, error) {
 	return ctlAddr, nil
 }
 
-func createListener(ctlAddr *net.TCPAddr, listen netListenFn) (net.Listener, error) {
+func createListener(ctlAddr *net.TCPAddr, listen netListenFn, bindToCtlAddr bool) (net.Listener, error) {
 	// Create and start listener on management network.
-	lis, err := listen("tcp4", fmt.Sprintf("0.0.0.0:%d", ctlAddr.Port))
+	// Only bind to ctlAddr.IP if explicitly requested (i.e., control_iface is set),
+	// otherwise bind to all interfaces (0.0.0.0) for backwards compatibility.
+	bindAddr := fmt.Sprintf("0.0.0.0:%d", ctlAddr.Port)
+	if bindToCtlAddr {
+		bindAddr = ctlAddr.String()
+	}
+	lis, err := listen("tcp4", bindAddr)
 	if err != nil {
-		return nil, errors.Wrap(err, "unable to listen on management interface")
+		return nil, errors.Wrapf(err, "unable to listen on %s", bindAddr)
 	}
 
 	return lis, nil
@@ -730,9 +755,12 @@ func registerTelemetryCallbacks(ctx context.Context, srv *server) {
 		return
 	}
 
+	// Use the same bind address as the control plane listener.
+	bindAddr := srv.ctlAddr.IP.String()
+
 	srv.OnEnginesStarted(func(ctxIn context.Context) error {
 		srv.log.Debug("starting Prometheus exporter")
-		cleanup, err := startPrometheusExporter(ctxIn, srv.log, telemPort, srv.harness.Instances())
+		cleanup, err := startPrometheusExporter(ctxIn, srv.log, telemPort, bindAddr, srv.harness.Instances())
 		if err != nil {
 			return err
 		}
@@ -875,6 +903,35 @@ type netInterface interface {
 	Addrs() ([]net.Addr, error)
 }
 
+// getFirstIPv4Addr returns the first (lowest) IPv4 address from the interface.
+// If multiple IPv4 addresses exist, the lowest one is returned for determinism.
+func getFirstIPv4Addr(iface netInterface) (net.IP, error) {
+	addrs, err := iface.Addrs()
+	if err != nil {
+		return nil, errors.Wrap(err, "failed to get interface addresses")
+	}
+
+	var ipv4s []net.IP
+	for _, a := range addrs {
+		if ipNet, ok := a.(*net.IPNet); ok && ipNet.IP != nil {
+			if v4 := ipNet.IP.To4(); v4 != nil {
+				ipv4s = append(ipv4s, v4)
+			}
+		}
+	}
+
+	if len(ipv4s) == 0 {
+		return nil, errors.New("no IPv4 addresses on interface")
+	}
+
+	// Sort for deterministic selection (lowest address first).
+	sort.Slice(ipv4s, func(i, j int) bool {
+		return bytes.Compare(ipv4s[i], ipv4s[j]) < 0
+	})
+
+	return ipv4s[0], nil
+}
+
 func getSrxSetting(cfg *config.Server) (int32, error) {
 	if len(cfg.Engines) == 0 {
 		return -1, nil