Module layout 

What the supervisor and the guest stub agree on in the guest-stub restricted mode: fixed addresses, the mailbox format, and which memory each trapped syscall reads or writes, for the x86_64 and i386 ABIs of an x86_64 host and the aarch64 and 32-bit ARM ABIs of an aarch64 host.

Compiled into the supervisor and into every build of the no_std exec shim, so it uses core only, with syscall numbers written out: the supervisor needs its compat ABI’s table as well as its own.

Gates

One page at a fixed address holds two gates, GATE_NOTIFY_OFFSET apart. The filter lets a syscall made from the first (allow) through untouched and sends one made from the second (notify) to the supervisor, telling them apart by the instruction pointer the kernel reports, which is the address right after the syscall instruction. On x86_64 a gate is syscall; jmp *%r12 and on aarch64 svc #0; br x16, the caller putting its return address in a register the kernel preserves and that carries no argument, so the gate needs no stack; i386 uses all six free registers for arguments, so there a gate is int $0x80; ret, called, and on 32-bit ARM svc #0; bx lr, called.

Mailbox

A memfd of MAIL_SIZE bytes mapped at a fixed address in every guest process, a different one in 64-bit and 32-bit processes, and anywhere in the supervisor. The first page holds one u32 owner per slot, the thread id of the stub that claimed it or 0; the slots follow, SLOT_SIZE bytes each. A stub copies the memory a syscall reads into its slot, points the arguments there, makes the call from the notify gate, and copies what the call wrote back to the caller’s buffers. Path strings get PATH_AREA bytes each so the supervisor can replace one with a host path of any length before letting the call continue.

Enums

Len

Length of a buffer argument.

Produced

The part of an output buffer a successful call wrote.

Stage

How one argument is staged in the mailbox.

Constants

ALLOW_GATE

Gate whose syscalls the filter allows untouched.

ARM 🔒

Whether this build serves the ARM family (aarch64 and 32-bit ARM).

E2BIG 🔒

E2BIG.

EINVAL 🔒

EINVAL.

EXEC_TRUNCATED_ARG

Argument of a staged execve or execveat that is 1 when the argument and environment vectors did not fit in the slot and only argv[0] was staged.

GATE32

Address of the gate page in a 32-bit guest: below where mmap starts handing out memory top-down under the stack, above where executables, their heaps and Wine’s reserved ranges lie.

GATE64

Address of the gate page in a 64-bit guest. On x86_64, below the region mmap hands out top-down from near the stack and above where position-independent executables and their heaps are placed, and above 0x7000_ffff_ffff: the seccomp filter Proton’s Wine installs for some games traps every syscall made from there or lower as a Windows program’s. On aarch64 below where position-independent executables are placed even with 39-bit addresses (2/3 of 512 GiB), far from the mmap region.

GATE_ADDR

Address of the gate page in this build’s guests.

GATE_CODE

Machine code of each gate: syscall; jmp *%r12.

GATE_NOTIFY_OFFSET

Distance from the allow gate to the notify gate.

GROUPS_MAX

Most supplementary groups staged for setgroups.

HELLO

This build’s hello syscall.

HELLO32

getpid on i386 and 32-bit ARM, the 32-bit shim’s HELLO64.

HELLO64

getpid on the host’s 64-bit ABI (x86_64 39, aarch64 172). The exec shim makes it from the notify gate once it runs, with HELLO_MARK as its argument, telling the supervisor that the exec it planned has happened. A real syscall that every seccomp profile allows: a container runtime’s filter refuses unknown numbers, and its refusal outranks the notification.

HELLO_MARK

Argument 0 of the hello, small enough for a 32-bit register.

LOADER_NAME

Name of the loader in the alias directory, next to e: a copy of the trampoline whose ROLE_MARK ends in ROLE_LOADER. An exec of a dynamically linked program of the host’s own machine is re-targeted at it outside the guest-stub mode, and it loads the program and its interpreter in place, where the kernel would have put them.

MAIL32

Address of the mailbox in a 32-bit guest, one megabyte above its gates.

MAIL64

Address of the mailbox in a 64-bit guest, one megabyte above its gates.

MAIL_ADDR

Address of the mailbox in this build’s guests.

MAIL_SIZE

Size of the mailbox: the owner page and the slots.

NOTIFY_GATE

Gate whose syscalls the filter sends to the supervisor.

OPEN_HOW 🔒

A struct open_how whose size is argument 3.

OPEN_HOW_MAX

Largest struct open_how staged.

P0 🔒

One path in argument 0.

P0P1 🔒

Paths in arguments 0 and 1.

P0P2 🔒

Paths in arguments 0 and 2.

P1 🔒

One path in argument 1.

P1P3 🔒

Paths in arguments 1 and 3.

PAGE

Size of a page.

PATH_AREA

Room given to each staged path string, terminating NUL included, so the supervisor can write any host path over it.

ROLE_EXEC

Role of the trampoline as built: carry out a record.

ROLE_LOADER

Role of the copy installed as LOADER_NAME: load the program its arguments name.

ROLE_MARK

Bytes the trampoline carries once in its file, the last of them naming the role of that copy: ROLE_EXEC as built, ROLE_LOADER in the copy the supervisor installs as LOADER_NAME.

SHIM32_NAME

Name of the 32-bit trampoline in the alias directory, next to e.

SIGNAL_CALLS32

rt_sigaction and rt_sigprocmask of the host’s 32-bit compat ABI.

SIGNAL_CALLS64

rt_sigaction and rt_sigprocmask of the host’s 64-bit ABI, which the stub handles and the filter traps although the supervisor serves neither.

SLOTS

Number of slots, the most trapped syscalls in flight at once across every guest process; a stub that finds none free waits for one.

SLOT_SIZE

Size of one slot.

SOCKADDR 🔒

A socket address whose length is argument 2.

SOCKADDR_MAX

Largest socket address, sizeof(struct sockaddr_storage).

SOCKETCALL_I386

i386 socketcall, whose bind and connect the filter traps.

SYSCALL_LEN

Length of the syscall instruction (syscall, int $0x80; svc #0 on ARM), by which the instruction pointer the kernel reports for a gate’s syscall lies past it.

TAG

SECCOMP_RET_DATA of the filter’s traps, reported in si_errno, which tells the stub’s traps from those of a filter the program installed.

XATTR_MAX

Largest extended attribute value, XATTR_SIZE_MAX.

XATTR_VALUE 🔒

An extended attribute value whose size is argument 3.

Statics

SHIM32_PATH

The path e takes to SHIM32_NAME, see padded_path.

SHIM_PATH

The path every exec in the guest-stub mode takes to e, see padded_path.

Functions

groups_in 🔒

A group list of argument 0 entries of size bytes.

groups_out 🔒

A group list output of argument 0 entries of size bytes.

input 🔒

A fixed-size input that always fits.

output 🔒

A fixed-size output, written whole on success.

padded_path

A trampoline’s path relative to the alias directory, . and slashes before its name filling a PATH_AREA, for execve.

ret_bytes 🔒

An output holding as many bytes as the call returned, sized by an argument.

slot_addr

Address of slot i.

staging

The staging of this build’s ABI.

staging_aarch64

The memory an aarch64 syscall uses, as (argument index, staging) pairs.

staging_arm

The memory a 32-bit ARM (EABI) syscall uses, as (argument index, staging) pairs.

staging_i386

The memory an i386 syscall uses, as (argument index, staging) pairs.

staging_x86_64

The memory an x86_64 syscall uses, as (argument index, staging) pairs.

trapped32

Whether the filter traps syscall nr of the host’s 32-bit compat ABI.

trapped64

Whether the filter traps syscall nr of the host’s 64-bit ABI.

trapped_aarch64

Whether the filter traps aarch64 syscall nr into the stub rather than notifying the supervisor directly: it has memory to stage, or the stub handles it (execve, execveat, rt_sigaction, rt_sigprocmask).

trapped_arm

Whether the filter traps 32-bit ARM syscall nr into the stub rather than notifying the supervisor directly: it has memory to stage, or the stub handles it (execve, execveat, rt_sigaction, rt_sigprocmask).

trapped_i386

Whether the filter traps i386 syscall nr into the stub rather than notifying the supervisor directly: it has memory to stage, or the stub handles it (execve, execveat, rt_sigaction, rt_sigprocmask). socketcall is trapped by its call number, apart from this list.

trapped_x86_64

Whether the filter traps x86_64 syscall nr into the stub rather than notifying the supervisor directly: it has memory to stage, or the stub handles it (execve, execveat, rt_sigaction, rt_sigprocmask).