feat(monitors): expose a configurable control socket for each monitor

Expose each monitor's control socket in the normal boot flow, so the
runtime can keep talking to the VMM after the guest starts. Every
monitor boots exactly as before; the only change is that its control
socket stays open and reachable. The socket is opt-in: it exists only
when socket_path is set in the monitor's configuration, so an admin can
run a monitor with no socket at all.

- Firecracker launches with --api-sock instead of --no-api, keeping
  --config-file so the guest still boots from the config file.
- QEMU exposes a QMP Unix socket (server=on,wait=off) alongside the
  disabled human monitor.
- Cloud Hypervisor exposes its REST API socket (--api-socket).

The socket_path option is wired through MonitorConfig, ExecArgs and the
state.json annotation passthrough. Each monitor declares whether it
exposes a control socket via a new SupportsControlSocket method on the
VMM interface, so a new monitor cannot be added without deciding this.

After setupUser, urunc creates the socket path's directory (0700) inside
the monitor rootfs, so the monitor's user owns it and a non-root monitor
can bind there. This runs in both the exec and the libcontainer monitor
paths. It fails only if the location is invalid, such as a file already
existing at one of the path's components.

A stop calls kill with SIGTERM and never runs delete, so the socket is
removed on a lethal signal after the monitor has been signalled, resolved
through the monitor rootfs with SecureJoin and only when it is an actual
socket. Delete needs no explicit removal: the monitor rootfs is removed
as a whole.

Add unit tests for the new arguments on all three monitors and for
SupportsControlSocket, and document the socket_path option.

PR: #850
Signed-off-by: Anamika Aggarwal <anamikaagg18@gmail.com>
Reviewed-by: Charalampos Mainas <cmainas@nubificus.co.uk>
Approved-by: Charalampos Mainas <cmainas@nubificus.co.uk>

Author: Anamika1608

docs/configuration.md

@@ -167,11 +167,34 @@ Each monitor subsection supports the following options:
 | `path` | string | (empty) | Optional custom path to the monitor binary. If not specified, urunc will search for the binary in PATH |
 | `data_path` | string | (empty) | Optional custom path for the monitor's data file directory |
 | `vhost` | boolean | `false` | Optional: enable `vhost-net` for the monitor's network device, to improve network performance. Currently only honored by the `qemu` monitor |
+| `socket_path` | string | (empty) | Optional path for the monitor's control socket. If not set, the monitor runs without a control socket |
 
 Since Qemu is the only currently supported monitor which requires extra data to
 boot a VM, `urunc` will first check `/usr/local/share` and then `/usr/share` for
 Qemu's data files.
 
+The `socket_path` option applies to the monitors that expose a control socket:
+Firecracker (its API socket), Qemu (a QMP socket) and Cloud Hypervisor (its REST
+API socket). It has no effect on the other monitors. The control socket is
+opt-in: it exists only when `socket_path` is set. If it is not set, the
+monitor runs with no control socket at all; an operator can leave it unset if
+they do not need the socket, or to keep a smaller attack surface.
+
+When it is set, the monitor creates the socket inside its own (pivoted) rootfs.
+`urunc` creates the directory of `socket_path` inside that rootfs after it drops
+privileges to the monitor's user, so the path is subject to two constraints:
+
+- Its parent directory must be one the monitor's user can create and write. A
+  directory that only `root` can write does not work for a non-root monitor.
+- It must not sit over an existing file or directory. `urunc` creates the
+  directory of `socket_path`; that fails cleanly if a file already exists at one
+  of the directories in the path. The monitor then binds the socket at
+  `socket_path`; that fails if a file already exists at `socket_path` itself.
+
+`urunc` removes the socket when the container is stopped (on a terminating
+signal) and when it is deleted, so a restart that reuses the same `socket_path`
+does not find a stale socket.
+
 **Example:**
 
 ```toml
@@ -186,6 +209,7 @@ vhost = false
 default_memory_mb = 512
 default_vcpus = 2
 path = "/opt/firecracker/firecracker"
+socket_path = "/run/urunc/fc.sock"
 ```
 
 ### Extra binaries Configuration

pkg/unikontainers/hypervisors/cloud_hypervisor.go

@@ -49,6 +49,12 @@ func (ch *CloudHypervisor) UsesKVM() bool {
 	return true
 }
 
+// SupportsControlSocket reports that Cloud Hypervisor exposes a control socket
+// (its REST API socket).
+func (ch *CloudHypervisor) SupportsControlSocket() bool {
+	return true
+}
+
 // SupportsSharedfs returns true as Cloud Hypervisor supports virtiofs
 func (ch *CloudHypervisor) SupportsSharedfs(fsType string) bool {
 	switch fsType {
@@ -70,6 +76,12 @@ func (ch *CloudHypervisor) BuildExecCmd(args types.ExecArgs, ukernel types.Unike
 	// Start building the command
 	exArgs := []string{ch.binaryPath}
 
+	// Expose the REST API socket only when socket_path is set, so the runtime
+	// can talk to Cloud Hypervisor after boot.
+	if args.SocketPath != "" {
+		exArgs = append(exArgs, "--api-socket", "path="+args.SocketPath)
+	}
+
 	// Memory configuration
 	if args.Sharedfs.Type == "virtiofs" {
 		memArg := "size=" + chMem + "M,shared=on"

pkg/unikontainers/hypervisors/cloud_hypervisor_test.go

@@ -0,0 +1,78 @@
+// Copyright (c) 2023-2026, Nubificus LTD
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package hypervisors
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/urunc-dev/urunc/pkg/unikontainers/types"
+)
+
+const testCHBinary = "/usr/bin/cloud-hypervisor"
+
+// TestCloudHypervisorBuildExecCmdSocket verifies Cloud Hypervisor emits
+// --api-socket only when socket_path is set.
+func TestCloudHypervisorBuildExecCmdSocket(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name           string
+		args           types.ExecArgs
+		mustContain    []string
+		mustNotContain []string
+	}{
+		{
+			name: "configured SocketPath renders --api-socket on that path",
+			args: types.ExecArgs{
+				UnikernelPath: testKernelPath,
+				Command:       testCommand,
+				SocketPath:    "/run/urunc/ch.sock",
+			},
+			mustContain: []string{"--api-socket path=/run/urunc/ch.sock"},
+		},
+		{
+			name: "unset SocketPath omits --api-socket",
+			args: types.ExecArgs{
+				UnikernelPath: testKernelPath,
+				Command:       testCommand,
+				ContainerID:   "abc123",
+			},
+			mustNotContain: []string{"--api-socket"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			ch := &CloudHypervisor{binary: CloudHypervisorBinary, binaryPath: testCHBinary}
+			out, err := ch.BuildExecCmd(tt.args, &fakeUnikernel{})
+			assert.NoError(t, err)
+			assert.NotEmpty(t, out)
+
+			assert.Equal(t, testCHBinary, out[0], "binary path must be the first element")
+			joined := strings.Join(out, " ")
+
+			for _, want := range tt.mustContain {
+				assert.Contains(t, joined, want, "expected %q to be present", want)
+			}
+			for _, notWant := range tt.mustNotContain {
+				assert.NotContains(t, joined, notWant, "expected %q to be absent", notWant)
+			}
+		})
+	}
+}

pkg/unikontainers/hypervisors/firecracker.go

@@ -99,6 +99,12 @@ func (fc *Firecracker) SupportsSharedfs(_ string) bool {
 	return false
 }
 
+// SupportsControlSocket reports that Firecracker exposes a control socket (its API
+// socket).
+func (fc *Firecracker) SupportsControlSocket() bool {
+	return true
+}
+
 func (fc *Firecracker) Path() string {
 	return fc.binaryPath
 }
@@ -111,7 +117,15 @@ func (fc *Firecracker) BuildExecCmd(args types.ExecArgs, ukernel types.Unikernel
 	// functions in the unikernel interface do not integrate well with FC's
 	// json configuration.
 	JSONConfigFile := filepath.Join("/tmp/", FCJsonFilename)
-	exArgs := []string{fc.Path(), "--no-api", "--config-file", JSONConfigFile}
+	exArgs := []string{fc.Path()}
+	// Enable the API socket when a socket_path is configured, otherwise keep the
+	// upstream --no-api. Either way the guest boots from the config file.
+	if args.SocketPath != "" {
+		exArgs = append(exArgs, "--api-sock", args.SocketPath)
+	} else {
+		exArgs = append(exArgs, "--no-api")
+	}
+	exArgs = append(exArgs, "--config-file", JSONConfigFile)
 	if !args.Seccomp {
 		exArgs = append(exArgs, "--no-seccomp")
 	}

pkg/unikontainers/hypervisors/firecracker_test.go

@@ -0,0 +1,80 @@
+// Copyright (c) 2023-2026, Nubificus LTD
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package hypervisors
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/urunc-dev/urunc/pkg/unikontainers/types"
+)
+
+const testFCBinary = "/usr/bin/firecracker"
+
+// TestFirecrackerBuildExecCmdSocket verifies Firecracker enables --api-sock
+// only when socket_path is set, and restores --no-api otherwise.
+func TestFirecrackerBuildExecCmdSocket(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name           string
+		args           types.ExecArgs
+		mustContain    []string
+		mustNotContain []string
+	}{
+		{
+			name: "configured SocketPath renders --api-sock and keeps --config-file",
+			args: types.ExecArgs{
+				UnikernelPath: testKernelPath,
+				Command:       testCommand,
+				SocketPath:    "/run/urunc/fc.sock",
+			},
+			mustContain:    []string{"--api-sock /run/urunc/fc.sock", "--config-file"},
+			mustNotContain: []string{"--no-api"},
+		},
+		{
+			name: "unset SocketPath restores --no-api and omits --api-sock",
+			args: types.ExecArgs{
+				UnikernelPath: testKernelPath,
+				Command:       testCommand,
+				ContainerID:   "abc123",
+			},
+			mustContain:    []string{"--no-api", "--config-file"},
+			mustNotContain: []string{"--api-sock"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			fc := &Firecracker{binary: FirecrackerBinary, binaryPath: testFCBinary}
+			out, err := fc.BuildExecCmd(tt.args, &fakeUnikernel{})
+			assert.NoError(t, err)
+			assert.NotEmpty(t, out)
+
+			assert.Equal(t, testFCBinary, out[0], "binary path must be the first element")
+			joined := strings.Join(out, " ")
+
+			for _, want := range tt.mustContain {
+				assert.Contains(t, joined, want, "expected %q to be present", want)
+			}
+			for _, notWant := range tt.mustNotContain {
+				assert.NotContains(t, joined, notWant, "expected %q to be absent", notWant)
+			}
+		})
+	}
+}

pkg/unikontainers/hypervisors/hedge.go

@@ -51,6 +51,11 @@ func (h *Hedge) SupportsSharedfs(_ string) bool {
 	return false
 }
 
+// SupportsControlSocket reports that Hedge exposes no control socket.
+func (h *Hedge) SupportsControlSocket() bool {
+	return false
+}
+
 func (h *Hedge) Path() string {
 	return ""
 }

pkg/unikontainers/hypervisors/hvt.go

@@ -140,6 +140,11 @@ func (h *HVT) SupportsSharedfs(_ string) bool {
 	return false
 }
 
+// SupportsControlSocket reports that HVT exposes no control socket.
+func (h *HVT) SupportsControlSocket() bool {
+	return false
+}
+
 // Path returns the path to the hvt binary.
 func (h *HVT) Path() string {
 	return h.binaryPath

pkg/unikontainers/hypervisors/hyperlight.go

@@ -46,6 +46,11 @@ func (h *Hyperlight) SupportsSharedfs(_ string) bool {
 	return false
 }
 
+// SupportsControlSocket reports that Hyperlight exposes no control socket.
+func (h *Hyperlight) SupportsControlSocket() bool {
+	return false
+}
+
 // Path returns the path to the hyperlight binary.
 func (h *Hyperlight) Path() string {
 	return h.binaryPath

pkg/unikontainers/hypervisors/qemu.go

@@ -56,6 +56,11 @@ func (q *Qemu) SupportsSharedfs(_ string) bool {
 	return true
 }
 
+// SupportsControlSocket reports that QEMU exposes a control socket (QMP).
+func (q *Qemu) SupportsControlSocket() bool {
+	return true
+}
+
 func (q *Qemu) Path() string {
 	return q.binaryPath
 }
@@ -73,6 +78,11 @@ func (q *Qemu) BuildExecCmd(args types.ExecArgs, ukernel types.Unikernel) ([]str
 		"-serial", "stdio",
 		"-monitor", "null",
 	}
+	// Expose the QMP socket only when socket_path is set. server=on,wait=off lets
+	// QEMU boot without waiting for a client.
+	if args.SocketPath != "" {
+		exArgs = append(exArgs, "-qmp", "unix:"+args.SocketPath+",server=on,wait=off")
+	}
 
 	if args.VCPUs > 0 {
 		exArgs = append(exArgs, "-smp", strconv.FormatUint(uint64(args.VCPUs), 10))

pkg/unikontainers/hypervisors/qemu_test.go

@@ -95,8 +95,29 @@ func TestQemuBuildExecCmd(t *testing.T) {
 				"vhost-user-fs-pci",
 				"virtio-blk-pci",
 				"vhost-vsock-pci",
+				"-qmp",
 			},
 		},
+		{
+			name: "configured SocketPath renders -qmp on that path",
+			args: types.ExecArgs{
+				UnikernelPath: testKernelPath,
+				Command:       testCommand,
+				SocketPath:    "/run/urunc/q.sock",
+			},
+			unikernel:   &fakeUnikernel{},
+			mustContain: []string{"-qmp unix:/run/urunc/q.sock,server=on,wait=off"},
+		},
+		{
+			name: "unset SocketPath omits -qmp",
+			args: types.ExecArgs{
+				UnikernelPath: testKernelPath,
+				Command:       testCommand,
+				ContainerID:   "abc123",
+			},
+			unikernel:      &fakeUnikernel{},
+			mustNotContain: []string{"-qmp"},
+		},
 		{
 			name: "custom MemSizeB renders -m in MB",
 			args: types.ExecArgs{