Module notify 

Handlers for syscalls answered through seccomp user notification.

Each handler reads its path arguments out of the tracee, translates them into the guest filesystem view, performs the real syscall in the supervisor, and answers with a value, an error, or an injected descriptor. The kernel never sees an untranslated guest path for the syscalls routed here.

The syscall is made on what the walk resolved, not on a host path string the kernel would walk again: the *at form relative to the pinned parent directory with O_NOFOLLOW/AT_SYMLINK_NOFOLLOW, since the walk already followed a final symlink when asked to. A symlink found at that point was swapped in by the guest after the walk; the handler then walks again, a few times, so the link is resolved inside the guest namespace, and gives up with ELOOP. Syscalls without a dirfd form act on the object’s /proc/self/fd/<n>, which the kernel resolves to the open inode.

Every notification is answered exactly once. After tracee memory has been read and before anything irreversible happens, the notification id is re-validated; a stale id (the tracee died or was interrupted by a signal) is dropped silently.

Structs

Req 🔒

One notification plus the shared state needed to serve it.

Enums

Outcome 🔒

How a handler wants the notification answered.

Constants

DROPPED 🔒

Sentinel errno meaning “the notification is stale, do not answer”.

IN_DONT_FOLLOW 🔒

IN_DONT_FOLLOW for inotify_add_watch(2).

RETRIES 🔒

Walks of one call after a swapped-in symlink was found where the walk had followed none, before the call fails with ELOOP.

SYS_FCHMODAT2_HOST 🔒

fchmodat2(2) is 452 on every architecture; the libc crate lacks it for aarch64.

WRITE_INTENT 🔒

open(2) flags that imply the caller intends to modify the file.

XATTR_MAX 🔒

Largest extended attribute value or list we shuttle through.

Functions

cstr 🔒

Builds a C string from path bytes.

dispatch 🔒

Routes a syscall number to its handler.

do_access 🔒

access/faccessat/faccessat2.

do_chmod 🔒

chmod/fchmodat/fchmodat2, on the object’s /proc/self/fd link.

do_chown 🔒

chown/lchown/fchownat.

do_fchown 🔒

fchown under -0: through the descriptor’s /proc link; a refusal is forgiven.

do_getcwd 🔒

getcwd: the tracee’s cwd as a guest path, NUL-terminated.

do_getgroups 🔒

getgroups(size, list) under -0: the recorded list, or the kernel’s when none was set.

do_getxattr 🔒

getxattr/lgetxattr.

do_identity 🔒

The identity syscalls under -0, over the process’s virtual crate::procs::Ids.

do_inotify_add_watch 🔒

inotify_add_watch.

do_link 🔒

link/linkat. An empty old path with AT_EMPTY_PATH links the tracee’s descriptor via its /proc entry. The walk followed the old side when asked to, so the kernel is never asked to follow it again.

do_listxattr 🔒

listxattr/llistxattr.

do_mkdir 🔒

mkdir/mkdirat.

do_mknod 🔒

mknod/mknodat.

do_open 🔒

open/creat/openat: open in the supervisor and inject the descriptor.

do_openat2 🔒

openat2: like openat with a struct open_how.

do_prctl 🔒

prctl(PR_SET_DUMPABLE) and PR_GET_DUMPABLE.

do_readlink 🔒

readlink/readlinkat: raw target, except /proc magic links are detranslated.

do_removexattr 🔒

removexattr/lremovexattr.

do_rename 🔒

rename/renameat/renameat2. A mount point of the view is busy, as a mount point is.

do_setgroups 🔒

setgroups(size, list) under -0: recorded for getgroups, never applied.

do_setxattr 🔒

setxattr/lsetxattr.

do_stat 🔒

stat/lstat/newfstatat: fill the host’s struct stat in the tracee (144 bytes on x86_64, 128 on aarch64), converted for i386 callers.

do_statfs 🔒

statfs: fill a 120-byte struct statfs in the tracee.

do_statx 🔒

statx: fill a 256-byte struct statx in the tracee.

do_symlink 🔒

symlink/symlinkat: the target is stored verbatim, only the link path is translated.

do_truncate 🔒

truncate, on the object’s /proc/self/fd link.

do_uname 🔒

uname: the host’s answer with release and/or nodename replaced.

do_unlink 🔒

unlink/unlinkat/rmdir. A mount point of the view is busy, as a mount point is.

do_utime 🔒

utime: struct utimbuf (two seconds fields) to timespecs.

do_utimensat 🔒

utimensat. A NULL path targets the descriptor itself and is passed through.

do_utimes 🔒

utimes/futimesat: struct timeval[2] to timespecs.

fake_ids_for_status 🔒

Under -0, the virtual identity to show in a /proc/<pid>/status being opened.

fake_owner 🔒

Under -0, files owned by the supervisor’s own ids belong to root.

fake_proc_cmdline 🔒

Serves /proc/<pid>/cmdline as the process was started, without the loader the exec was retargeted at.

fake_proc_file 🔒

Serves an opened /proc/<pid>/status or cmdline from a rewritten copy.

fake_proc_status 🔒

Serves /proc/<pid>/status with our own pid hidden from TracerPid and, under -0, root in the Uid/Gid lines.

follow 🔒

Deref policy derived from AT_SYMLINK_NOFOLLOW.

forgive_as_root 🔒

Under -0, an ownership or device-node refusal reads as success, like PRoot’s fake_id0.

handle

Serves one notification. Always answers exactly once, unless the notification turned out to be stale.

host_utimensat 🔒

Runs utimensat(2) on a resolved path with an optional timespec pair.

is_fifo 🔒

Whether the resolved object is a FIFO; opening one may block the supervisor.

lexical_clean 🔒

Lexically cleans an absolute path (no symlink resolution).

nofollow_flag 🔒

The AT_SYMLINK_NOFOLLOW bit to pass for an act on a resolved path.

nofollow_open_flag 🔒

O_NOFOLLOW when the host open must not follow a final symlink.

proc_magic_link 🔒

Classifies a guest path as a /proc/<pid>/... magic link.

read_all 🔒

Reads all of an open descriptor without taking ownership of it.

readlink_by_path 🔒

The target of the link path names, or dirfd was opened on for an empty path, read by its path.

readonly_memfd 🔒

A read-only descriptor on a memfd holding content.

retrying 🔒

Runs a handler again while it reports a swapped-in symlink (RETRY).

rewrite_proc_self 🔒

Replaces a leading /proc/self or /proc/thread-self with the tracee’s pid.

targets_fd 🔒

Whether a path argument is empty with AT_EMPTY_PATH, i.e. targets the fd itself.

timespecs_from_tracee 🔒

Reads a struct timespec[2] from the tracee, widening 32-bit fields for i386 utimensat.

timevals_to_timespecs 🔒

Reads a struct timeval[2] from the tracee and converts it to 64-bit timespecs.

xattr_target 🔒

The path an extended-attribute syscall acts on.