feat(monitors): expose a configurable control socket for each monitor by Anamika1608 · Pull Request #850 · urunc-dev/urunc

Anamika1608 · 2026-07-28T11:46:23Z

Description

Expose each monitor's control socket in the normal (config-file / CLI) boot flow, so the runtime can talk to the VMM after the guest starts (graceful shutdown now, snapshots later). Each monitor still boots exactly as before — this only keeps its control socket open and reachable:

Firecracker: launches with --api-sock while keeping --config-file, so the guest still boots from the config file and the socket stays open (drops only --no-api).
QEMU: adds -qmp unix:<path>,server,nowait alongside the disabled human monitor.
Cloud Hypervisor: adds --api-socket path=<path>.

The socket path is configurable via a socket_path monitor field, shared across all monitors through a common ResolveSocketPath helper, defaulting to a per-container /tmp/<id>.sock. After changeRoot, urunc creates the socket path's directory inside the monitor rootfs so a custom path works; it fails only if the location is invalid (a file already exists on the path).

Related issues

Related to LFx Mentorship (CNCF - urunc: Improve lifecycle management of sandbox monitors) #756

How was this tested?

go build ./..., go test ./pkg/... ./internal/..., gofmt, make lint, and cspell pass; the QEMU BuildExecCmd tests cover the new -qmp argument (Ubuntu 24.04 aarch64 VM, KVM).
Live, through real containerd + nerdctl: Firecracker boots from its config file with the socket reachable (state Running) for both the default and a custom socket_path; QEMU (chttp-qemu-linux-aarch64) boots, the guest serves HTTP 200, launches with -qmp unix:/tmp/qemu.sock,server,nowait, and the QMP socket answers query-status with running.
Cloud Hypervisor is unit-tested only: no aarch64 Cloud Hypervisor image is published in the registry, so its socket could not be exercised live.

LLM usage

claude code (opus 4.8) for the understanding of codebase, approach decisions and reviews

Checklist

I have read the contribution guide.
The linter passes locally (make lint).
The e2e tests of at least one tool pass locally (make test_ctr, make test_nerdctl, make test_docker, make test_crictl).
If LLMs were used: I have read the llm policy.

netlify · 2026-07-28T11:46:29Z

✅ Deploy Preview for urunc ready!

Name	Link
🔨 Latest commit	`295a902`
🔍 Latest deploy log	https://app.netlify.com/projects/urunc/deploys/6a71a24dd937a20008424cf5
😎 Deploy Preview	https://deploy-preview-850--urunc.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

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: - 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 in server mode, configured not to wait for a client before booting, alongside the disabled human monitor. - Cloud Hypervisor exposes its REST API socket (--api-socket). The socket location is configurable through a new socket_path option under a monitor's configuration, wired through MonitorConfig, ExecArgs and the state.json annotation passthrough, with a per-container default of /tmp/<id>.sock behind a DefaultSocketDir constant and a shared resolveSocketPath helper. After changeRoot, urunc creates the socket path's directory inside the monitor rootfs, so any custom path works; it fails only if the location is invalid, such as a file already existing at one of the path's components. Extend the QEMU BuildExecCmd tests to cover the new argument and document the socket_path option. Signed-off-by: Anamika Aggarwal <anamikaagg18@gmail.com>

cmainas

Hello @Anamika1608 ,

thank you for the PR. I have added some comments in the code. Also, some generic comments:

There is still the case where an admin configures the urunc to run the monitors without any socket. This might be for security reasons or because they do not require it. Therefore, if the socket path is not in the configuration, then there should be no socket (no default value).
We need to cleanup the socket path, because in case of a container restart (e.g. pod) the monitor might fail to use the same path.

Remove the default /tmp/<id>.sock socket path. A monitor now gets a control socket only when socket_path is set in config; with no socket_path it launches with no control socket, exactly like upstream. Firecracker restores --no-api in that case. Signed-off-by: Anamika Aggarwal <anamikaagg18@gmail.com>

Move the control socket directory creation from between changeRoot and setupUser to right after setupUser, so it runs as the monitor's user and a non-root monitor can create and use it. Also remove a stale socket left at the same path by a previous instance before the monitor binds, so a restart reusing the same socket_path does not fail to bind. Signed-off-by: Anamika Aggarwal <anamikaagg18@gmail.com>

Signed-off-by: Anamika Aggarwal <anamikaagg18@gmail.com>

The QEMU QMP flag string "server,nowait" trips cspell in qemu.go and qemu_test.go. Signed-off-by: Anamika Aggarwal <anamikaagg18@gmail.com>

Anamika1608 · 2026-08-04T08:27:49Z

can you take a look at the new commits i have pushed, done all three changes as you said. @cmainas

cmainas

Hello @Anamika1608 ,

thank you for the updates. I have added some more comments. One thing that we need to have in mind is that the socket path can be anywhere, but it should still be in an accessible places for any user and more importantly do not collide with any other file.

cmainas · 2026-08-05T12:17:29Z

+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 a custom `socket_path` there for you, so the path


nit: remove "for you", the documentation should use third person only.

Also, the path can not be really anywhere. It should be in a directory that is accessible from all users (because we create it after user setup) and it should not be over existing files/directories.

cmainas · 2026-08-05T12:21:01Z

+	//     (--api-sock <path>) so the control socket stays open for use after
+	//     the guest has started.
+	//   - With no socket_path, launch with --no-api (upstream default) so no
+	//     control socket is exposed.


nit: comment too verbose without any benefit and in the wrong place. It should be before the if else

cmainas · 2026-08-05T12:45:37Z


+// UsesControlSocket reports whether a monitor exposes a control socket whose
+// path (socket_path) urunc must make reachable before the monitor launches.
+func UsesControlSocket(vmmType VmmType) bool {


We should replace this with a specific call to each VMM interface implementation. If we add a new monitor in the future, we will definitely forget to update this. As an example check #850

cmainas · 2026-08-05T12:50:21Z

+		}
+		// Remove a stale socket left by a previous instance (e.g. a restart
+		// reusing the same socket_path) so the monitor can bind it again.
+		if err = os.Remove(vmmArgs.SocketPath); err != nil && !os.IsNotExist(err) {


The removal of the socket should not take place here, but in delete.

cmainas · 2026-08-05T12:54:10Z

+	// can bind its socket there.
+	if hypervisors.UsesControlSocket(hypervisors.VmmType(vmmType)) && vmmArgs.SocketPath != "" {
+		sockDir := filepath.Dir(vmmArgs.SocketPath)
+		if err = os.MkdirAll(sockDir, 0o755); err != nil {


We can be stricter here and use 0o700

Anamika1608 force-pushed the config-socket-all-monitors branch from 48afaad to 3e02d31 Compare July 28, 2026 12:02

Anamika1608 mentioned this pull request Jul 31, 2026

feat(monitors): graceful shutdown over the control socket. #869

Draft

4 tasks

cmainas added the ok-to-test label Aug 3, 2026

cmainas requested changes Aug 3, 2026

View reviewed changes

Comment thread pkg/unikontainers/unikontainers.go Outdated

Anamika1608 added 5 commits August 4, 2026 13:04

docs(configuration): socket_path is opt-in with no default

841e2e0

Signed-off-by: Anamika Aggarwal <anamikaagg18@gmail.com>

docs(monitors): fix stale socket_path field comments

863c322

Signed-off-by: Anamika Aggarwal <anamikaagg18@gmail.com>

chore(lint): add nowait to the cspell dictionary

295a902

The QEMU QMP flag string "server,nowait" trips cspell in qemu.go and qemu_test.go. Signed-off-by: Anamika Aggarwal <anamikaagg18@gmail.com>

Anamika1608 requested a review from cmainas August 4, 2026 08:27

cmainas reviewed Aug 5, 2026

View reviewed changes

Navigation Menu

Uh oh!

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

feat(monitors): expose a configurable control socket for each monitor#850
Anamika1608 wants to merge 6 commits into
urunc-dev:mainfrom
Anamika1608:config-socket-all-monitors

Anamika1608 commented Jul 28, 2026 •

edited

Loading

Uh oh!

netlify Bot commented Jul 28, 2026 •

edited

Loading

Uh oh!

cmainas left a comment

Uh oh!

Uh oh!

Anamika1608 commented Aug 4, 2026 •

edited

Loading

Uh oh!

cmainas left a comment

Uh oh!

cmainas Aug 5, 2026

Uh oh!

cmainas Aug 5, 2026

Uh oh!

cmainas Aug 5, 2026

Uh oh!

cmainas Aug 5, 2026

Uh oh!

cmainas Aug 5, 2026

Uh oh!

cmainas Aug 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

Anamika1608 commented Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Related issues

How was this tested?

LLM usage

Checklist

Uh oh!

netlify Bot commented Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for urunc ready!

Uh oh!

cmainas left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Anamika1608 commented Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cmainas left a comment

Choose a reason for hiding this comment

Uh oh!

cmainas Aug 5, 2026

Choose a reason for hiding this comment

Uh oh!

cmainas Aug 5, 2026

Choose a reason for hiding this comment

Uh oh!

cmainas Aug 5, 2026

Choose a reason for hiding this comment

Uh oh!

cmainas Aug 5, 2026

Choose a reason for hiding this comment

Uh oh!

cmainas Aug 5, 2026

Choose a reason for hiding this comment

Uh oh!

cmainas Aug 5, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Anamika1608 commented Jul 28, 2026 •

edited

Loading

netlify Bot commented Jul 28, 2026 •

edited

Loading

Anamika1608 commented Aug 4, 2026 •

edited

Loading