Add Linux user namespace support for runner spawning

Spawn the propolis-runner inside a CLONE_NEWUSER namespace so it gains
CAP_SETUID/CAP_SETGID within the namespace. This allows libkrun's
virtiofs passthrough to call set_creds() without requiring host-level
capabilities, fixing EPERM errors when host GID != guest GID.

- Add WithUserNamespaceUID(uid, gid) backend option
- Add UserNamespaceConfig type and applyUserNamespace() (Linux/no-op)
- Add preflight check for kernel.unprivileged_userns_clone sysctl
- Add EPERM hint in SpawnProcess suggesting sysctl check

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: JAORMX

hypervisor/libkrun/backend.go

@@ -45,14 +45,32 @@ func WithFirmware(src extract.Source) Option { return func(b *Backend) { b.firmw
 // Ignored when Sources are directory-based.
 func WithCacheDir(dir string) Option { return func(b *Backend) { b.cacheDir = dir } }
 
+// WithUserNamespaceUID configures the runner to spawn inside a Linux user
+// namespace (CLONE_NEWUSER) with a single UID/GID mapping. The child
+// process gains CAP_SETUID and CAP_SETGID within the namespace, which
+// allows libkrun's virtiofs passthrough to call set_creds() without
+// requiring host-level capabilities.
+//
+// uid and gid specify the namespace-side IDs that map to the host
+// process's real UID/GID. For example, if the guest expects UID 1000
+// and the host runs as UID 1000, pass uid=1000, gid=1000.
+//
+// On non-Linux platforms, this option is accepted but has no effect.
+func WithUserNamespaceUID(uid, gid uint32) Option {
+	return func(b *Backend) {
+		b.userNamespace = &runner.UserNamespaceConfig{UID: uid, GID: gid}
+	}
+}
+
 // Backend implements hypervisor.Backend using libkrun.
 type Backend struct {
-	runnerPath string
-	libDir     string
-	spawner    runner.Spawner
-	runtime    extract.Source
-	firmware   extract.Source
-	cacheDir   string
+	runnerPath    string
+	libDir        string
+	spawner       runner.Spawner
+	runtime       extract.Source
+	firmware      extract.Source
+	cacheDir      string
+	userNamespace *runner.UserNamespaceConfig
 }
 
 // NewBackend creates a libkrun backend with the given options.
@@ -131,17 +149,18 @@ func (b *Backend) Start(ctx context.Context, cfg hypervisor.VMConfig) (hyperviso
 	}
 
 	runCfg := runner.Config{
-		RootPath:     cfg.RootFSPath,
-		NumVCPUs:     cfg.NumVCPUs,
-		RAMMiB:       cfg.RAMMiB,
-		NetSocket:    netSocket,
-		PortForwards: toRunnerPortForwards(cfg.PortForwards),
-		VirtioFS:     toRunnerVirtioFS(cfg.FilesystemMounts),
-		ConsoleLog:   cfg.ConsoleLogPath,
-		LogLevel:     cfg.LogLevel,
-		LibDir:       libDir,
-		RunnerPath:   runnerPath,
-		VMLogPath:    filepath.Join(cfg.DataDir, "vm.log"),
+		RootPath:      cfg.RootFSPath,
+		NumVCPUs:      cfg.NumVCPUs,
+		RAMMiB:        cfg.RAMMiB,
+		NetSocket:     netSocket,
+		PortForwards:  toRunnerPortForwards(cfg.PortForwards),
+		VirtioFS:      toRunnerVirtioFS(cfg.FilesystemMounts),
+		ConsoleLog:    cfg.ConsoleLogPath,
+		LogLevel:      cfg.LogLevel,
+		LibDir:        libDir,
+		RunnerPath:    runnerPath,
+		VMLogPath:     filepath.Join(cfg.DataDir, "vm.log"),
+		UserNamespace: b.userNamespace,
 	}
 
 	spawner := b.spawner

hypervisor/libkrun/backend_test.go

@@ -448,5 +448,62 @@ func TestBackend_Start_DefaultUnchanged(t *testing.T) {
 	assert.Equal(t, "/my/lib", spawner.captured.LibDir)
 }
 
+func TestBackend_Options_UserNamespaceUID(t *testing.T) {
+	t.Parallel()
+
+	b := NewBackend(WithUserNamespaceUID(1000, 1000))
+
+	require.NotNil(t, b.userNamespace)
+	assert.Equal(t, uint32(1000), b.userNamespace.UID)
+	assert.Equal(t, uint32(1000), b.userNamespace.GID)
+}
+
+func TestBackend_Start_WithUserNamespaceUID(t *testing.T) {
+	t.Parallel()
+
+	proc := &mockProcessHandle{pid: 77, alive: true}
+	spawner := &captureSpawner{proc: proc}
+
+	b := NewBackend(
+		WithUserNamespaceUID(1000, 1000),
+		WithSpawner(spawner),
+	)
+
+	cfg := hypervisor.VMConfig{
+		RootFSPath: t.TempDir(),
+		DataDir:    t.TempDir(),
+	}
+
+	handle, err := b.Start(context.Background(), cfg)
+	require.NoError(t, err)
+	require.NotNil(t, handle)
+
+	// Verify the user namespace config was threaded through.
+	require.NotNil(t, spawner.captured.UserNamespace)
+	assert.Equal(t, uint32(1000), spawner.captured.UserNamespace.UID)
+	assert.Equal(t, uint32(1000), spawner.captured.UserNamespace.GID)
+}
+
+func TestBackend_Start_WithoutUserNamespace(t *testing.T) {
+	t.Parallel()
+
+	proc := &mockProcessHandle{pid: 78, alive: true}
+	spawner := &captureSpawner{proc: proc}
+
+	b := NewBackend(WithSpawner(spawner))
+
+	cfg := hypervisor.VMConfig{
+		RootFSPath: t.TempDir(),
+		DataDir:    t.TempDir(),
+	}
+
+	handle, err := b.Start(context.Background(), cfg)
+	require.NoError(t, err)
+	require.NotNil(t, handle)
+
+	// UserNamespace should be nil when not configured.
+	assert.Nil(t, spawner.captured.UserNamespace)
+}
+
 // Verify mockSource implements extract.Source.
 var _ extract.Source = (*mockSource)(nil)

preflight/userns_linux.go

@@ -0,0 +1,71 @@
+// SPDX-FileCopyrightText: Copyright 2026 Stacklok, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+//go:build linux
+
+package preflight
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"strings"
+)
+
+const usernsCloneSysctl = "/proc/sys/kernel/unprivileged_userns_clone"
+
+// usernsChecker holds injectable dependencies for user namespace verification.
+type usernsChecker struct {
+	getuid   func() int
+	readFile func(string) ([]byte, error)
+}
+
+func newUsernsChecker() *usernsChecker {
+	return &usernsChecker{
+		getuid:   os.Getuid,
+		readFile: os.ReadFile,
+	}
+}
+
+// check verifies that unprivileged user namespaces are available. Root
+// can always create user namespaces, so the check only applies to
+// non-root users. On kernels that don't expose the sysctl (e.g.
+// Fedora 30+, most modern distros), the check passes — CLONE_NEWUSER
+// is always available.
+func (c *usernsChecker) check(_ context.Context) error {
+	// Root can always create user namespaces.
+	if c.getuid() == 0 {
+		return nil
+	}
+
+	data, err := c.readFile(usernsCloneSysctl)
+	if err != nil {
+		if os.IsNotExist(err) {
+			// Sysctl doesn't exist — unprivileged userns is always enabled.
+			return nil
+		}
+		return fmt.Errorf("cannot read %s: %w", usernsCloneSysctl, err)
+	}
+
+	val := strings.TrimSpace(string(data))
+	if val == "0" {
+		return fmt.Errorf("unprivileged user namespaces are disabled (kernel.unprivileged_userns_clone=0); " +
+			"the runner requires CLONE_NEWUSER for virtiofs UID/GID mapping; " +
+			"enable with: sudo sysctl -w kernel.unprivileged_userns_clone=1")
+	}
+
+	return nil
+}
+
+// UserNamespaceCheck returns a preflight Check that verifies unprivileged
+// user namespaces are available. This check should only be registered when
+// user namespace spawning is configured.
+func UserNamespaceCheck() Check {
+	c := newUsernsChecker()
+	return Check{
+		Name:        "userns",
+		Description: "Verify unprivileged user namespaces are available",
+		Run:         c.check,
+		Required:    true,
+	}
+}

preflight/userns_linux_test.go

@@ -0,0 +1,100 @@
+// SPDX-FileCopyrightText: Copyright 2026 Stacklok, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+//go:build linux
+
+package preflight
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestUsernsCheck_Root(t *testing.T) {
+	t.Parallel()
+
+	c := &usernsChecker{
+		getuid: func() int { return 0 },
+		readFile: func(_ string) ([]byte, error) {
+			t.Fatal("readFile should not be called for root")
+			return nil, nil
+		},
+	}
+
+	err := c.check(context.Background())
+	assert.NoError(t, err)
+}
+
+func TestUsernsCheck_SysctlNotExist(t *testing.T) {
+	t.Parallel()
+
+	c := &usernsChecker{
+		getuid: func() int { return 1000 },
+		readFile: func(_ string) ([]byte, error) {
+			return nil, os.ErrNotExist
+		},
+	}
+
+	// If the sysctl doesn't exist, unprivileged userns is always enabled.
+	err := c.check(context.Background())
+	assert.NoError(t, err)
+}
+
+func TestUsernsCheck_Enabled(t *testing.T) {
+	t.Parallel()
+
+	c := &usernsChecker{
+		getuid: func() int { return 1000 },
+		readFile: func(_ string) ([]byte, error) {
+			return []byte("1\n"), nil
+		},
+	}
+
+	err := c.check(context.Background())
+	assert.NoError(t, err)
+}
+
+func TestUsernsCheck_Disabled(t *testing.T) {
+	t.Parallel()
+
+	c := &usernsChecker{
+		getuid: func() int { return 1000 },
+		readFile: func(_ string) ([]byte, error) {
+			return []byte("0\n"), nil
+		},
+	}
+
+	err := c.check(context.Background())
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "unprivileged user namespaces are disabled")
+	assert.Contains(t, err.Error(), "kernel.unprivileged_userns_clone=1")
+}
+
+func TestUsernsCheck_ReadError(t *testing.T) {
+	t.Parallel()
+
+	c := &usernsChecker{
+		getuid: func() int { return 1000 },
+		readFile: func(_ string) ([]byte, error) {
+			return nil, fmt.Errorf("permission denied")
+		},
+	}
+
+	err := c.check(context.Background())
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "cannot read")
+}
+
+func TestUserNamespaceCheck_ReturnsCheck(t *testing.T) {
+	t.Parallel()
+
+	check := UserNamespaceCheck()
+	assert.Equal(t, "userns", check.Name)
+	assert.True(t, check.Required)
+	assert.NotNil(t, check.Run)
+}

preflight/userns_other.go

@@ -0,0 +1,19 @@
+// SPDX-FileCopyrightText: Copyright 2026 Stacklok, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+//go:build !linux
+
+package preflight
+
+import "context"
+
+// UserNamespaceCheck returns a no-op preflight check on non-Linux platforms.
+// User namespaces are a Linux-specific feature.
+func UserNamespaceCheck() Check {
+	return Check{
+		Name:        "userns",
+		Description: "Verify unprivileged user namespaces are available (Linux only)",
+		Run:         func(_ context.Context) error { return nil },
+		Required:    false,
+	}
+}

runner/config.go

@@ -44,6 +44,11 @@ type Config struct {
 	// VMLogPath is the path to the file where runner stdout/stderr is written.
 	// Not serialized to JSON; used by Spawn to redirect output.
 	VMLogPath string `json:"-"`
+	// UserNamespace configures a Linux user namespace for the runner subprocess.
+	// When non-nil, the runner is spawned inside CLONE_NEWUSER so that
+	// libkrun's virtiofs passthrough can call set_creds() without host caps.
+	// Not serialized to JSON; applied by SpawnProcess before exec.
+	UserNamespace *UserNamespaceConfig `json:"-"`
 }
 
 // VirtioFSMount exposes a host directory to the guest via virtio-fs.

runner/spawn.go

@@ -116,6 +116,7 @@ func SpawnProcess(ctx context.Context, cfg Config) (*Process, error) {
 	cmd.SysProcAttr = &syscall.SysProcAttr{
 		Setsid: true, // Create new session (detach from terminal)
 	}
+	applyUserNamespace(cmd, cfg.UserNamespace)
 
 	// Set library search path for bundled libraries if available.
 	if cfg.LibDir != "" {
@@ -135,6 +136,10 @@ func SpawnProcess(ctx context.Context, cfg Config) (*Process, error) {
 	}
 
 	if err := cmd.Start(); err != nil {
+		if cfg.UserNamespace != nil && isPermissionError(err) {
+			return nil, fmt.Errorf("start runner process: %w; user namespaces may be disabled — "+
+				"check that kernel.unprivileged_userns_clone=1 (sysctl kernel.unprivileged_userns_clone)", err)
+		}
 		return nil, fmt.Errorf("start runner process: %w", err)
 	}
 
@@ -282,3 +287,10 @@ func libPathEnvVar() string {
 func isNoSuchProcess(err error) bool {
 	return errors.Is(err, syscall.ESRCH)
 }
+
+// isPermissionError returns true if the error indicates a permission denial
+// (EPERM or EINVAL, the latter being returned by some kernels when
+// CLONE_NEWUSER is disabled).
+func isPermissionError(err error) bool {
+	return errors.Is(err, syscall.EPERM) || errors.Is(err, syscall.EINVAL)
+}

runner/userns.go

@@ -0,0 +1,21 @@
+// SPDX-FileCopyrightText: Copyright 2026 Stacklok, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+package runner
+
+// UserNamespaceConfig configures a Linux user namespace for the runner
+// subprocess. When set, the runner is spawned inside a CLONE_NEWUSER
+// namespace so that it gains CAP_SETUID/CAP_SETGID within the namespace.
+// This allows libkrun's virtiofs passthrough to call set_creds() without
+// requiring host-level capabilities.
+//
+// The UID and GID fields specify the single mapping from container
+// namespace IDs to the host process's real UID/GID. For example, if the
+// guest expects UID 1000 and the host process runs as UID 1000, set
+// UID=1000 and GID=1000 to create the mapping 1000→1000.
+type UserNamespaceConfig struct {
+	// UID is the user ID inside the namespace that maps to the host UID.
+	UID uint32
+	// GID is the group ID inside the namespace that maps to the host GID.
+	GID uint32
+}