Module launch 

Starting the first tracee and wiring supervisor, listener and tracer.

The child installs the seccomp filter and hands the listener back over a socketpair, then waits for one byte. The parent seizes it with ptrace, starts the notification pool and sends the byte, so the child’s first traced syscall already has a tracer and no SIGSTOP handshake is needed.

Where the ptrace syscall is filtered out (a hardened container profile), or when PROOT_NO_PTRACE is set, there is no tracer: the filter sends the trace tier to the listener as well, the child’s kernel working directory is pinned to the alias directory holding the exec shim, and the handlers in syscall::direct do the rest. The process table is then lazy and a reaper thread watches pidfds for exits.

Where the kernel’s ptrace access check refuses the supervisor even towards its own child (Yama’s ptrace_scope of 2), the first tracee enters a user namespace of its own before installing the filter; see access. Where that is refused too, the guest-stub restricted mode (see guest_stub) traps the served syscalls into a stub inside each guest, and the first tracee execs the trampoline that arms it, with a plan the supervisor wrote before letting it go.

Statics

environ 🔒 ^⚠

Traits

FromBytesHack 🔒

Byte-slice to OsStr helper kept local to avoid a trait import at call sites.

Functions

become_subreaper 🔒

Makes the supervisor the parent of every orphan among its descendants.

exit_like_bwrap_without_namespaces 🔒

Exits the way bubblewrap exits when it cannot create its namespaces.

guest_stub_choice 🔒

When the guest-stub restricted mode may be used, from PROOT_GUEST_STUB: as the fallback where nothing else reaches the guest’s memory (unset, or any other value), anywhere (force), or never (0).

no_ptrace_forced 🔒

Whether PROOT_NO_PTRACE forces the mode without a ptrace tier (any value but 0).

plan_first_trapped 🔒

Plans the first tracee’s exec in the guest-stub restricted mode: its command, argument vector and environment as the child will exec them.

recv_fd 🔒

Receives a descriptor sent by send_fd.

report_status 🔒

Writes one status line to each of bubblewrap’s --info-fd/--json-status-fd descriptors.

resolve_command_in_path 🔒

Resolves a bare command name through PATH, as seen from inside the guest.

run

Runs the configured command under supervision and returns its exit code.

send_fd 🔒

Sends a descriptor over a unix socket with SCM_RIGHTS. Allocation free.

wait_root 🔒

Waits for the first tracee and returns the exit code to report, reaping every other child along the way.