Enable override_stat xattr on Linux

The Linux kernel restricts user.* xattrs to regular files and
directories, so symlinks and special files are silently skipped.
Once libkrun's Linux virtiofs passthrough reads these xattrs,
guest file ownership will be correct without CAP_CHOWN.

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

Author: JAORMX

docs/SECURITY.md

@@ -397,10 +397,19 @@ sudo setcap cap_chown+ep /path/to/your-binary
 capsh --addamb=cap_chown -- -c '/path/to/your-binary'
 ```
 
-On macOS, this problem is solved differently: propolis sets the
-`user.containers.override_stat` extended attribute on extracted files so that
-libkrun's virtiofs FUSE server reports correct ownership to the guest. See
-the `internal/xattr` package for details.
+### override_stat xattr (macOS and Linux)
+
+propolis also sets the `user.containers.override_stat` extended attribute on
+extracted files so that libkrun's virtiofs server reports correct ownership to
+the guest. This is the same mechanism that podman uses on macOS.
+
+On Linux, the xattr is set on regular files and directories. The kernel
+restricts `user.*` xattrs on symlinks and special files, so those are silently
+skipped. Once libkrun's Linux virtiofs passthrough adds support for reading
+these xattrs (the same support already exists on macOS), file ownership in the
+guest will be correct without requiring `CAP_CHOWN`.
+
+See the `internal/xattr` package for details.
 
 ## File Permissions
 

internal/xattr/doc.go

@@ -2,19 +2,24 @@
 // SPDX-License-Identifier: Apache-2.0
 
 // Package xattr sets libkrun's user.containers.override_stat extended
-// attribute on macOS so that the virtiofs FUSE server reports correct
+// attribute on macOS and Linux so that the virtiofs server reports correct
 // guest-visible ownership and permissions for rootfs files.
 //
-// When propolis extracts an OCI image on macOS, the host user (typically
-// uid 501) ends up owning all files because non-root cannot chown.
-// libkrun's FUSE server performs access checks against these host-side
-// attributes, causing permission denied errors for guest processes
-// running as UIDs that don't exist on the host (e.g. uid 1000).
+// When propolis extracts an OCI image, the host user ends up owning all
+// files because non-root cannot chown. libkrun's virtiofs server
+// performs access checks against these host-side attributes, causing
+// permission denied errors for guest processes running as UIDs that
+// don't exist on the host (e.g. uid 1000).
 //
-// Setting this xattr on each file tells the FUSE server to override
+// Setting this xattr on each file tells the virtiofs server to override
 // the reported stat values, making the guest see the correct ownership
 // from the original OCI image. This is the same mechanism that podman
 // uses on macOS.
 //
-// On non-darwin platforms these functions are no-ops.
+// On Linux, the kernel restricts user.* xattrs to regular files and
+// directories — symlinks and special files are silently skipped. This
+// is acceptable because applications check the target's ownership, not
+// the symlink itself.
+//
+// On platforms other than macOS and Linux these functions are no-ops.
 package xattr

internal/xattr/mode.go

@@ -0,0 +1,45 @@
+// SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+package xattr
+
+import "os"
+
+const overrideKey = "user.containers.override_stat"
+
+// goFileModeToPosix converts a Go os.FileMode to a POSIX st_mode value
+// including file type bits.
+func goFileModeToPosix(m os.FileMode) uint32 {
+	mode := uint32(m.Perm())
+
+	if m&os.ModeSetuid != 0 {
+		mode |= 0o4000
+	}
+	if m&os.ModeSetgid != 0 {
+		mode |= 0o2000
+	}
+	if m&os.ModeSticky != 0 {
+		mode |= 0o1000
+	}
+
+	switch {
+	case m.IsDir():
+		mode |= 0o040000 // S_IFDIR
+	case m&os.ModeSymlink != 0:
+		mode |= 0o120000 // S_IFLNK
+	case m&os.ModeNamedPipe != 0:
+		mode |= 0o010000 // S_IFIFO
+	case m&os.ModeSocket != 0:
+		mode |= 0o140000 // S_IFSOCK
+	case m&os.ModeDevice != 0:
+		if m&os.ModeCharDevice != 0 {
+			mode |= 0o020000 // S_IFCHR
+		} else {
+			mode |= 0o060000 // S_IFBLK
+		}
+	default:
+		mode |= 0o100000 // S_IFREG
+	}
+
+	return mode
+}

internal/xattr/mode_test.go

@@ -0,0 +1,39 @@
+// SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+package xattr
+
+import (
+	"os"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestGoFileModeToPosix(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name string
+		mode os.FileMode
+		want uint32
+	}{
+		{"regular 644", 0o644, 0o100644},
+		{"regular 755", 0o755, 0o100755},
+		{"regular 600", 0o600, 0o100600},
+		{"dir 755", os.ModeDir | 0o755, 0o040755},
+		{"dir 700", os.ModeDir | 0o700, 0o040700},
+		{"symlink", os.ModeSymlink | 0o777, 0o120777},
+		{"setuid", os.ModeSetuid | 0o755, 0o104755},
+		{"setgid", os.ModeSetgid | 0o755, 0o102755},
+		{"sticky", os.ModeSticky | 0o755, 0o101755},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			got := goFileModeToPosix(tt.mode)
+			assert.Equal(t, tt.want, got)
+		})
+	}
+}

internal/xattr/override_darwin.go

@@ -13,8 +13,6 @@ import (
 	"golang.org/x/sys/unix"
 )
 
-const overrideKey = "user.containers.override_stat"
-
 // SetOverrideStat sets the user.containers.override_stat xattr on path
 // so that libkrun's virtiofs FUSE server reports the given uid, gid,
 // and mode to the guest instead of the real APFS values.
@@ -51,40 +49,3 @@ func CopyOverrideStat(src, dst string) {
 		slog.Debug("copy override_stat xattr failed", "dst", dst, "err", err)
 	}
 }
-
-// goFileModeToPosix converts a Go os.FileMode to a POSIX st_mode value
-// including file type bits.
-func goFileModeToPosix(m os.FileMode) uint32 {
-	mode := uint32(m.Perm())
-
-	if m&os.ModeSetuid != 0 {
-		mode |= 0o4000
-	}
-	if m&os.ModeSetgid != 0 {
-		mode |= 0o2000
-	}
-	if m&os.ModeSticky != 0 {
-		mode |= 0o1000
-	}
-
-	switch {
-	case m.IsDir():
-		mode |= 0o040000 // S_IFDIR
-	case m&os.ModeSymlink != 0:
-		mode |= 0o120000 // S_IFLNK
-	case m&os.ModeNamedPipe != 0:
-		mode |= 0o010000 // S_IFIFO
-	case m&os.ModeSocket != 0:
-		mode |= 0o140000 // S_IFSOCK
-	case m&os.ModeDevice != 0:
-		if m&os.ModeCharDevice != 0 {
-			mode |= 0o020000 // S_IFCHR
-		} else {
-			mode |= 0o060000 // S_IFBLK
-		}
-	default:
-		mode |= 0o100000 // S_IFREG
-	}
-
-	return mode
-}

internal/xattr/override_darwin_test.go

@@ -117,34 +117,6 @@ func TestCopyOverrideStat_NoXattr(t *testing.T) {
 	assert.Error(t, err)
 }
 
-func TestGoFileModeToPosix(t *testing.T) {
-	t.Parallel()
-
-	tests := []struct {
-		name string
-		mode os.FileMode
-		want uint32
-	}{
-		{"regular 644", 0o644, 0o100644},
-		{"regular 755", 0o755, 0o100755},
-		{"regular 600", 0o600, 0o100600},
-		{"dir 755", os.ModeDir | 0o755, 0o040755},
-		{"dir 700", os.ModeDir | 0o700, 0o040700},
-		{"symlink", os.ModeSymlink | 0o777, 0o120777},
-		{"setuid", os.ModeSetuid | 0o755, 0o104755},
-		{"setgid", os.ModeSetgid | 0o755, 0o102755},
-		{"sticky", os.ModeSticky | 0o755, 0o101755},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			t.Parallel()
-			got := goFileModeToPosix(tt.mode)
-			assert.Equal(t, tt.want, got)
-		})
-	}
-}
-
 func readXattr(t *testing.T, path string) string {
 	t.Helper()
 	buf := make([]byte, 256)

internal/xattr/override_linux.go

@@ -0,0 +1,61 @@
+// SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+//go:build linux
+
+package xattr
+
+import (
+	"fmt"
+	"log/slog"
+	"os"
+
+	"golang.org/x/sys/unix"
+)
+
+// SetOverrideStat sets the user.containers.override_stat xattr on path
+// so that libkrun's virtiofs server reports the given uid, gid,
+// and mode to the guest instead of the real host values.
+// Errors are logged at debug level and silently ignored.
+//
+// On Linux the kernel restricts user.* xattrs to regular files and
+// directories (fs/xattr.c:xattr_permission). Symlinks, named pipes,
+// sockets, and device nodes are silently skipped.
+func SetOverrideStat(path string, uid, gid int, mode os.FileMode) {
+	// The Linux kernel refuses user.* xattrs on anything other than
+	// regular files and directories. Skip early to avoid EPERM.
+	if mode&(os.ModeSymlink|os.ModeNamedPipe|os.ModeSocket|os.ModeDevice) != 0 {
+		return
+	}
+
+	unixMode := goFileModeToPosix(mode)
+	val := fmt.Sprintf("%d:%d:0%o", uid, gid, unixMode)
+	if err := unix.Lsetxattr(path, overrideKey, []byte(val), 0); err != nil {
+		slog.Debug("setxattr override_stat failed", "path", path, "err", err)
+	}
+}
+
+// SetOverrideStatFromPath sets the override_stat xattr by reading the
+// file's current mode via Lstat. Useful when you know the intended
+// uid/gid but the mode comes from the existing file on disk.
+func SetOverrideStatFromPath(path string, uid, gid int) {
+	info, err := os.Lstat(path)
+	if err != nil {
+		slog.Debug("lstat for override_stat failed", "path", path, "err", err)
+		return
+	}
+	SetOverrideStat(path, uid, gid, info.Mode())
+}
+
+// CopyOverrideStat copies the user.containers.override_stat xattr from
+// src to dst. No-op if src has no such xattr. Errors are silently ignored.
+func CopyOverrideStat(src, dst string) {
+	buf := make([]byte, 256)
+	n, err := unix.Lgetxattr(src, overrideKey, buf)
+	if err != nil || n == 0 {
+		return
+	}
+	if err := unix.Lsetxattr(dst, overrideKey, buf[:n], 0); err != nil {
+		slog.Debug("copy override_stat xattr failed", "dst", dst, "err", err)
+	}
+}