Developing for Peios

Most questions about why the Peios kernel did something — why an access was denied, why an event never reached userspace, why a registry lookup stalled — are answered from inside the kernel, before any userspace tool can see the state involved. Peios makes that interior observable through the same tracing infrastructure the rest of the Linux kernel uses: static tracepoints.

The PKM security subsystems each expose a tracepoint system:

• kacs: — the access-control decisions. Every instrumented KACS hook records its verdict (allow/deny), the object it acted on (inode number and superblock magic — never a pathname), and a reason code naming the exact return path it took. This is where "why was this denied?" is answered.
• kmes: — the health of the event substrate: ring-buffer drops, capacity swaps, rate-limit throttling, backpressure. These trace the machinery, not the security events KMES ships to userspace (those are the event stream).
• lcs: — the registry source device: request/response round-trips, timeouts, transaction state transitions, source mark-downs.

Because these are ordinary kernel tracepoints, everything the kernel's tracing stack can do applies unchanged: enable individual events or whole subsystems, attach ftrace filters and triggers, sample with perf, or attach eBPF programs. They cost nothing when disabled (a patched-out branch) and record structured fields rather than formatted text, so you filter on ret, reason, or an inode number directly.

The Kernel tracepoints page covers how to enable them — at runtime through tracefs, or from the very first moments of boot through the kernel command line — and how to read what they emit.

PKM exposes its security subsystems through three tracepoint systems — kacs:, kmes:, and lcs: — registered with the standard Linux tracing infrastructure. This page shows how to turn them on and read them.

Discovering the events #

Every event and its fields are self-describing through tracefs. The live catalog is authoritative — prefer it over any static list:

# every PKM tracepoint
ls /sys/kernel/tracing/events/kacs /sys/kernel/tracing/events/kmes /sys/kernel/tracing/events/lcs

# the fields (and their symbolic decodings) of one event
cat /sys/kernel/tracing/events/kacs/kacs_file_access/format

The numeric reason, op, and state codes carried by these events are a stable, append-only diagnostic ABI defined in <pkm/trace.h>; the format file maps them back to their symbolic names for you.

Enabling at runtime #

Enable a whole subsystem, or a single event:

cd /sys/kernel/tracing

echo 1 > events/kacs/enable                 # all KACS access-decision events
echo 1 > events/kacs/kacs_file_access/enable # just one

cat trace                                    # read what has accumulated
echo 1 > tracing_on                          # (on by default)

Because the fields are structured, you filter in the kernel rather than grepping text. To see only denials:

echo 'ret != 0' > events/kacs/kacs_file_access/filter

To watch a single inode, or one reason:

echo 'ino == 1234' > events/kacs/kacs_file_access/filter
echo 'reason == 3' > events/kacs/kacs_sd_cache_lookup/filter   # 3 == miss-needs-synth

perf and eBPF attach to the same tracepoints by name — e.g. perf record -e kacs:kacs_file_access, or a tracepoint:kacs:kacs_file_access probe from bpftrace.

Enabling at boot #

The most common reason to reach for these is a decision that happens before userspace exists — the access checks that fire as the root filesystem mounts. tracefs is not available that early, so enable the events on the kernel command line and route them to the console with tp_printk:

trace_event=kacs:*,kmes:*,lcs:* tp_printk

trace_event= enables the listed events as the tracing subsystem initialises — which happens before the PKM LSM itself initialises, and well before the first access check — so no early decision is missed. tp_printk prints each enabled tracepoint to the kernel log, giving you a complete decision transcript on the console with no userspace involved. Narrow the selection (trace_event=kacs:kacs_file_access) to cut the volume.

Reading a KACS access decision #

A kacs: access-decision event answers "what did KACS decide about this object, and why?". The key fields:

• verdict — allow or deny, derived from ret (0 is allow; a negative errno is a denial). Filter on ret for machine use.
• reason — the specific return path taken, as a symbolic name (e.g. decision, unmanaged, no-token, pip-context). The same object can be denied for very different reasons; this names which one.
• ino / sb_magic — the inode number and the filesystem's superblock magic, identifying the object without disclosing its path.
• mount_policy — the resolved mount policy for the object's filesystem, which frequently explains a denial on an unmanaged or synthesis-only mount.
• access — the desired-access mask being checked.

For a worked example of tracing a specific denial end to end, see Debugging a denial.

From a PKM checkout, build/test-kunit.sh boots an already-built kernel in QEMU and checks its serial log. Supply either a kernel build tree or its bzImage. The kernel must include KUnit and the PKM test suites; enable CONFIG_PROVE_LOCKING when investigating lock ordering.

build/test-kunit.sh /path/to/bzImage

The runner requires successful emulator exit, clean power-down, and complete top-level KTAP results. An unfiltered run must also contain PKM's smoke marker and a passing PKM suite summary. A timeout, failed assertion, kernel warning, panic, or diagnostic that disables lock checking fails the run even when the individual test cases report success. Read the retained serial log for the cause: passing assertions alone do not establish that lock checking stayed active.

Selecting tests #

PKM_KUNIT_FILTER passes a KUnit suite/test glob to the kernel. For example:

PKM_KUNIT_FILTER='pkm_kunit_file.*' build/test-kunit.sh /path/to/bzImage

A filtered run may omit the global smoke test or select an upstream single-case suite without an aggregate summary. It must still emit selected case results, complete its top-level KTAP plan, and power down cleanly. Selecting no cases is a failure. Kernel diagnostic checks remain enabled for filtered runs.

Logs and emulator settings #

The script does not build, sign, install, or publish a kernel. Its result applies to the image and selected tests that were actually run; native integration suites and hardware qualification are separate checks.

Use this reference when implementing a launcher, supervisor, threading library, or other code that creates and controls processes. For inspecting or stopping a running program, start with Task Manager and Process lifecycle.

• Process creation: fork, vfork, clone/clone3, sharing flags, exec, posix_spawn, and pidfds.
• Process lifecycle: termination, exit-status encoding, the wait family, and subreaper adoption.
• Thread operations: TIDs, thread-exit notification, and thread-local storage.

These calls also interact with Peios security. See Token lifecycle for identity inheritance, the process security descriptor for process rights, and the two-check rule for cross-process access.

This is the detailed counterpart to Creating processes. That page explains the ideas; this one gives the exact contract — what each call does, what a new process inherits, and what each clone sharing flag controls.

fork #

fork() creates a new process by duplicating the caller. The child is a near-identical copy that runs independently from the point of the call.

The child inherits:

• a private copy of the parent's memory, made lazily (copy-on-write), so the duplication is cheap and changes on either side stay invisible to the other
• copies of the parent's open file descriptors — each refers to the same open file description, so file offset, status flags, and signal-driven-I/O settings are shared between parent and child
• open directory streams and open message-queue descriptors
• open-file-description locks (flock, OFD locks) through those shared descriptors
• the parent's signal dispositions (the handler set for each signal)
• the file-creation mask (umask), the current directory, and the root directory
• resource limits and the timer-slack value
• the parent's identity — it begins acting on the same token (see Token lifecycle)
• the parent's mitigations and protection, carried on its PSB

The child does not inherit:

• the parent's PID — it receives a new PID and a new Process GUID
• memory locks (mlock, mlockall)
• memory regions marked MADV_DONTFORK (absent in the child) or MADV_WIPEONFORK (present but zeroed)
• process resource usage and CPU-time counters — reset to zero
• pending signals — the child's set starts empty
• semaphore adjustments (semadj)
• process-associated record locks (POSIX fcntl locks — distinct from the OFD and flock locks above, which are shared through the inherited descriptors)
• timers (setitimer, alarm, timer_create)
• outstanding asynchronous I/O
• directory-change notifications (dnotify)
• the PR_SET_PDEATHSIG parent-death-signal setting (reset)
• I/O-port access permissions (ioperm)

The child's termination signal — what its parent is notified with when it ends — is SIGCHLD.

The child is created with a single thread — the one that called fork(). If the parent had other threads, they do not exist in the child.

vfork #

vfork() is a lightweight variant of fork() for the one case where the child will immediately replace itself with another program. It differs in two ways:

• the caller is suspended from the call until the child either execs or exits;
• the child runs in the parent's memory — no copy is made — until that point.

Because the two share memory and the parent is frozen, the child must do almost nothing first. The contract: the child must not return from the function that called vfork(), must not modify any variable other than the one holding the return value, and must not call any other function before a successful exec or _exit. Doing otherwise is undefined behaviour.

vfork is an optimisation for the create-then-replace pattern. Ordinary code should use posix_spawn (below) rather than reach for it directly.

clone and clone3 #

clone() is the general creation call. fork and thread creation are both clone with particular flag sets; clone exposes the choice directly. The caller gives a set of flags controlling what the new task shares with the creator, a stack for the new task, and locations for thread-ID and thread-local-storage bookkeeping.

clone3() is the modern form, taking a structure instead of positional arguments so it can grow new fields over time without changing the call:

The structure is size-versioned: the caller passes the size it knows, the kernel reads up to the size it knows, and any unknown trailing fields must be zero. This is how new fields are added without breaking existing programs.

Requesting a specific thread ID (set_tid) is a privileged operation — it exists for checkpoint-and-restore tools that must recreate a process with its original ID. The privilege required follows the capability model.

clone sharing flags #

Each flag makes the new task share something with its creator instead of getting its own copy. The flags that build threads and control creation:

A thread is CLONE_VM | CLONE_FS | CLONE_FILES | CLONE_SIGHAND | CLONE_THREAD (plus TLS and thread-ID bookkeeping) — everything shared, same process. A fork is the opposite end, with almost nothing shared.

Being in one thread group has consequences beyond shared memory. Every thread returns the same PID from getpid (the thread-group ID), and signal actions are process-wide — an unhandled fatal signal delivered to any thread ends them all — though each thread keeps its own signal mask. A thread that ends does not notify the thread that created it and cannot be collected with a wait call; only once every thread in the group has ended is the process's parent sent SIGCHLD. The new thread shares the creator's parent, and CLONE_THREAD requires CLONE_SIGHAND (and hence CLONE_VM).

Two further flag groups select separation rather than sharing, each documented where it belongs:

• The CLONE_NEW* flags create namespaces — separate views of system resources (mounts, process IDs, networking, and more). Only CLONE_NEWNS is available to an ordinary process: a private mount table is an object its creator owns, described in the Peios Kernel TRM (§3.13). Every other namespace type needs SeTcbPrivilege, which is what CAP_SYS_ADMIN means on Peios.
• CLONE_INTO_CGROUP places the new process into a resource group at creation, covered under resource management.

CLONE_DETACHED is a historical flag with no effect and is ignored.

The exec family #

An exec replaces the program running in the current process with a different one. The process keeps its PID, its Process GUID, and its identity — only the program changes (see Token lifecycle for the identity detail).

What survives an exec #

A successful exec keeps the process itself but replaces the program it runs. Preserved across the call:

• the PID, the parent PID, and the Process GUID
• the process's identity (its token), its process group and session, and its controlling terminal
• open file descriptors — except those marked close-on-exec, which are closed
• the current directory, root directory, file-creation mask, and resource limits
• pending signals, and the dispositions of signals that were ignored or left at their default

Reset or discarded:

• all memory — the program's mappings, stack, heap, and data are replaced; memory locks are dropped and MADV_* region markings are gone
• every thread except the one calling exec — the new program starts single-threaded
• handlers for caught signals — reset to the default; the alternate signal stack is dropped
• attached System V shared memory, POSIX shared-memory mappings, open POSIX message-queue descriptors and named semaphores, and in-process synchronisation objects (mutexes, condition variables)
• POSIX timers, outstanding asynchronous I/O, open directory streams, and registered exit handlers
• the floating-point environment, and the process name (set to the new program)

What an exec does to a process's identity when the program file is marked to run as another principal is not the Linux set-user-ID model — Peios handles that through the token, covered in setuid and uid0.

Whether a program is allowed to run at all is a separate, execution-policy question — covered under binary signing — not part of these calls.

posix_spawn #

posix_spawn() is the standard library function for the create-then-replace pattern: it makes a new process and runs a named program in it with a single call, with controls for arranging the child's file descriptors and a few attributes first. It is built on the calls above and is the recommended way to launch a program, in preference to assembling fork/vfork and exec by hand.

Process handles (the pidfd family) #

A pidfd is a file descriptor referring to one specific process — the reliable handle introduced in Creating processes. CLONE_PIDFD hands one back at creation; a few calls work with them afterwards:

pidfd_getfd reaches into another process, so it is not something any process may do to any other: it is gated by the right to act on the target, governed by that process's security descriptor.

See also #

• Creating processes — the conceptual counterpart to this page.
• Process lifecycle reference — ending a process and collecting its result.
• Thread operations reference — per-thread calls: TIDs, exit notification, TLS.

This is the detailed counterpart to Process lifecycle. That page explains how a process ends and is cleaned up; this one gives the exact calls — how a process terminates, what its exit status encodes, and how a parent collects it.

Ending a process #

A process can end itself in a few ways, differing in how much tidying happens first:

Returning from the program's entry point is equivalent to calling exit() with the returned value.

At the lowest level the raw _exit system call ends only the calling thread; the library _exit and ordinary termination route through exit_group so the whole process ends. Ending one thread while the rest of the process keeps running is the unusual case.

A process can also be ended from outside, by a signal rather than by a call of its own — covered under signals. Either way, it leaves an exit status behind.

The exit status #

When a process ends it leaves a small exit status for its parent to read. It records one of two outcomes:

• Ended on its own — carries an exit code: the low 8 bits of the value passed to exit/_exit (so 0–255, with 0 conventionally meaning success).
• Ended by a signal — carries the number of the signal that ended it, plus a flag for whether the process produced a core dump.

The status is a packed value, read not directly but through a set of macros:

Collecting the result #

A parent collects a finished child's status — and in doing so clears the zombie — with one of the wait calls. They differ in which child they target and how much they report:

waitpid's target is chosen by a single number: a positive value waits for that exact PID; -1 for any child; 0 for any child in the caller's own process group; and a value below -1 for any child in the process group whose ID is its absolute value.

Two further options matter for threads and other clone-created children, which may not notify their parent with SIGCHLD the way an ordinary child does: __WCLONE waits only for such clone children, and __WALL waits for every child regardless of type.

Orphan adoption and subreapers #

PID 1 is the catch-all, but a process can arrange to catch orphans within its own subtree. By marking itself a subreaper (with prctl(PR_SET_CHILD_SUBREAPER)), a process becomes the one that adopts any orphan descended from it — its grandchildren and below — instead of letting them reparent all the way up to PID 1. Service managers and container managers use this to keep responsibility for everything they launched: when something deep in their subtree loses its immediate parent, it reparents to the manager, which still learns when it finally ends.

See also #

• Process lifecycle — the conceptual counterpart to this page.
• Process creation reference — fork, clone, exec, and the pidfd calls.

This is the thread-level companion to the process and thread model — the operations that act on an individual thread rather than on the process as a whole.

Thread IDs #

Every thread has its own thread ID (TID), returned by gettid. Within a multi-threaded process all threads share one PID — the value getpid returns, which is really the thread-group ID (TGID) — but each thread's TID is unique. In a single-threaded process the TID, PID, and TGID are all the same number.

The TID is how the system targets one specific thread rather than the whole process: sending a signal to a single thread, setting one thread's CPU affinity, or addressing it under /proc. It names a thread the way a PID names a process — and, like a PID, it is a reference, not an identity. What a thread is acting as is its token, never its TID.

The TID is also distinct from the opaque handle a threading library returns when it creates a thread; that is a library-level identifier, not the kernel's TID.

Thread-exit notification #

A thread can have the kernel notify waiters when it exits — the mechanism threading libraries build thread join on. set_tid_address sets a clear-tid address for the calling thread (and returns its TID). When that thread later terminates, if it shares memory with other threads, the kernel writes 0 to the integer at that address and wakes one thread waiting on it (a single futex wake).

A thread waiting for another to finish blocks on that address; the kernel clears it and wakes the waiter at the exact moment the other thread ends. This is the same machinery as the CLONE_CHILD_CLEARTID flag in process creation — that flag arranges the clear-tid address at thread creation, where set_tid_address sets it afterwards.

Thread-local storage #

Thread-local storage (TLS) gives each thread its own private copy of a variable — a value that is per-thread rather than shared across the process, even though the threads share the same memory. The per-thread data lives in an ordinary block of memory; what makes it per-thread is a register pointing at this thread's block, so the same code reaches a different copy depending on which thread is running.

The kernel's part is maintaining that per-thread pointer. It is set when the thread is created (the CLONE_SETTLS flag carries the address) and, on x86-64, a running thread can change it through arch_prctl with ARCH_SET_FS (the older set_thread_area serves the same purpose on 32-bit). Everything above that — how thread-local variables are laid out and reached in code — is handled by the compiler and the threading library.

See also #

• The process and thread model — the conceptual counterpart to this page.
• Process creation reference — the clone flags that create threads and arrange TLS and clear-tid addresses.

The registry stores a value's type and bytes, but never its meaning — it does not know that a queue depth must be at least 16, or what changing it costs. That knowledge ships with the software that owns the key, as documentation regman reads. From the operator's side this is the registry manual; from yours, the package author's, it is a file you write and install.

This page is how you write one. The package that owns a set of registry keys is the package that documents them — the only arrangement that stays correct as packages come and go.

Put cross-references to another package's keys in your own page's body, rather than adding a second record for the same key. An exact record is a provider claim, so a redirect record makes a lookup report two providers. For example, netd's Machine\System\Network page points readers to Machine\System\Network\Dns, whose record belongs to resolvd.

Where the documentation lives #

regman reads a drop-in directory, /usr/share/regman/. Each *.regman file in it is one provider, and the provider's name is the file's stem:

/usr/share/regman/
    kmes.regman          # provider: kmes
    exampled.regman      # provider: exampled

A package documents its whole registry surface in one file. There is no central index to register with and no install-time hook: dropping the file in is the whole act, and removing it on uninstall is the whole undo. A missing directory simply means nothing is documented — not an error.

You ship the fragment the same way you ship any other file. Have your build target install it, then map it into the payload from the package file's [files] table:

[files]
"main:share/regman/exampled.regman" = "usr/share/regman/exampled.regman"

If the fragment is hand-written rather than generated — which it usually is — keep it beside the recipe and take it from there, no build target involved:

[files]
"@recipe:exampled.regman" = "usr/share/regman/exampled.regman"

See Packages for ref resolution, and Multi-package recipes if one recipe produces a family of packages that each document their own keys.

The shape of a fragment #

A fragment is a sequence of records, each documenting one key or one value. A record is a fence line, a small header, a blank line, then a Markdown body:

--- machine\system\exampled maxqueuedepth
canonical: Machine\System\Exampled MaxQueueDepth
type: REG_DWORD
default: 1024
valid: 16–65536
applies: restart

Maximum number of jobs held in the spool queue before new submissions
are rejected with EAGAIN.

Raising this lets the queue absorb larger bursts at the cost of memory.
The queue is preallocated, so the change takes effect at the next service
restart rather than live.

Fragments are UTF-8 text. LF and CRLF line endings are accepted, including both in one file. regman fmt preserves each fence's existing line ending and leaves headers, body text and any preamble unchanged; it only replaces the fence's anchor. Indexed and unindexed lookups read the same records.

Four parts, in order:

• The fence line — --- (three dashes, one space) followed by the anchor: the case-folded, lowercased lookup token regman matches against. You do not write this by hand; regman fmt bakes it from canonical (see The fmt/lint workflow, below).
• The header — key: value lines, one per line, until the first blank line. Keys are case-insensitive; values are trimmed. Unknown keys are ignored, so a typo'd field is silently dropped rather than rejected — watch for it.
• A blank line — this is what ends the header and starts the body. A record with no blank line has no body.
• The body — Markdown, rendered when the page is shown.

Key docs and value docs #

There is no kind: field. A record is a value doc if it carries any of type, default, valid, or applies; otherwise it is a key doc. That is the whole distinction — a key doc is just a record that omits all four.

A key doc introduces a subtree. Its body explains the shared semantics once (validation philosophy, security intent, how the subsystem reads the keys), and regman <key> renders that body followed by an auto-generated index of the values beneath it:

--- machine\system\exampled
canonical: Machine\System\Exampled

The Exampled spooler reads its tuning parameters from the values under
this key. Compiled-in defaults apply until LCS is available; after that
Exampled reads, validates, and applies each value, then watches the
subtree for later changes.

A value doc documents one knob. The four value fields are what fill in its card:

canonical is the only field any record must have — a record without it is dropped and flagged. The four value fields are not individually enforced, but each one you omit is a blank on the card, and applies in particular is the field operators reach for most. Treat a value doc as incomplete until it carries all four.

Documenting a family of keys #

Plenty of configuration isn't at a fixed path. A service definition lives at Machine\System\Services\<name>, an interface's record at Machine\System\Network\Interfaces\<ifid>, a principal's policy at Machine\Generic\Authn\Policy\<SID>. There is one thing to explain and an open set of paths to explain it at, and the operator asking will name a real one — sshd, not <name>.

Write the varying component in angle brackets and regman treats it as a wildcard matching exactly one path component:

--- machine\system\services\<name> imagepath
canonical: Machine\System\Services\<name> ImagePath
type: REG_SZ
default: (required)
valid: a non-empty absolute path
applies: restart

Absolute path to the service binary.

regman 'Machine\System\Services\sshd' ImagePath now answers with that card, and regman 'Machine\System\Services\sshd' renders the family's key doc with its whole Values index. The heading still shows the canonical — the reader can see they've been handed the generic page, which is the honest thing to show.

Four things worth knowing:

• One component, never a path tail. \X\<Y>\Z answers for \X\B\Z and not for \X\B\C\Z. A wildcard also never spans the space between a key path and a value name, so it cannot swallow a value it wasn't meant to cover.
• The name inside is for the reader. <name>, <ifid> and <x> behave identically; pick the one that documents itself.
• A concrete record wins. If some package documents Machine\System\Services\sshd ImagePath outright, that page answers instead of the generic one — the same most-specific-match rule as a port reservation selector. Key docs and value docs are resolved separately, so a service that ships its own key doc still gets the generic Values index beneath it.
• There is no escape for a literal <…>. LCS permits < and > in a key name, so a key genuinely spelled <Y> can't be told apart from a wildcard. In practice nobody names a key that, and the notation was already how these docs wrote a varying component by hand.

Use a wildcard for a family whose members share their whole meaning, which is the usual case. Where one member genuinely differs — a specific service's own knob, a particular principal's privileges — document that one concretely and let specificity do the rest.

When the family is a tree #

Some families nest. A PNP rule's subkeys are exceptions, twelve deep at most; a netd profile's subkeys are derived profiles. The vocabulary doesn't change with depth — an exception is a rule, with the same values meaning the same things — so there is still one page to write, but no fixed number of <…> components reaches every member of it.

Put ... immediately inside the closing bracket and that component spans separators, matching one path component or many:

--- machine\system\network\rules\<layer>\<rule...> actions
canonical: Machine\System\Network\Rules\<Layer>\<rule...> Actions
type: REG_MULTI_SZ
default: (absent or empty — NULL, the rule abstains)
valid: one action expression per element
applies: live — at the next generation

What the rule does when it matches.

That answers for Rules\Packet\ssh Actions and for Rules\Packet\ssh\from-lan\not-vpn Actions alike. Note that <Layer> in the same anchor is still one component: the spanning form applies to the bracket it is written in, not to the record.

The rules that matter:

• It still won't cross the space. <name...> spans \ and nothing else, so a key-path wildcard can never eat the value name after it.
• It still needs at least one component. Rules\<Layer>\<rule...> does not answer for Rules\Packet, which has its own page.
• Narrower beats broader. Concrete beats <name>, and <name> beats <name...>. A page written for the top of a tree and a page written for the whole tree can coexist; the narrower one answers where it applies, and no "documented by 2 packages" warning appears.

Reach for it only where the subtree really is a tree. A flat family — Services\<name>, Policy\<SID> — wants the plain form, which says something truer about the shape of the keys.

A wildcard in the value name #

Nothing restricts a wildcard to the key path. PNP documents rule conditions this way: a condition's value name is <Fact>.<Operator>, so each fact gets one record with the operator left open — Rules\<Layer>\<rule...> DstPort.<op>, whose card covers Equal, GreaterThan, LessThan and Present at once.

There is one trap, and it is worth knowing before you reach for this:

Where one fact's name is a prefix of another's, write that one out per operator (Local.Equal, Local.Present) instead of wildcarding it. The rest of the family is unaffected.

The other limit follows from the space rule: a value name that contains a space can't be reached by a wildcard at all. If the thing you are documenting has an optional-whitespace syntax, say so on the card and recommend the spelling that resolves.

The body's first line is the summary #

There is no summary: field. The first non-empty line of the body is taken as the one-sentence summary — it is what shows next to the value name in a key doc's index and in regman -k search results. So write the body like a good commit message or docstring: lead with one self-contained sentence, then elaborate in the paragraphs below.

The body is Markdown: **bold**, *emphasis*, `code`, headings, and bullet lists render; prose is wrapped to the terminal width. On a non-tty (piped) it renders plain, honouring NO_COLOR. Emphasis carries no styling of its own — the markers simply come off — because italic is not dependable across terminals and bold already covers making something stand out.

A delimiter only counts as markup when its closer is present, so a lone * or backtick stays in the text where you put it rather than disappearing. * and ** also need no whitespace just inside either end, which is what keeps a matched pair that was never markup — 2 * 3 * 4, or *.conf and *.h — from being read as one.

A complete fragment #

/usr/share/regman/exampled.regman, one key doc plus one value doc, as a package would ship it:

--- machine\system\exampled
canonical: Machine\System\Exampled

The Exampled spooler reads its tuning parameters from the values under
this key. Compiled-in defaults apply until LCS is available.

Security is on this key, not per value: every value inherits this key's
Security Descriptor.

--- machine\system\exampled maxqueuedepth
canonical: Machine\System\Exampled MaxQueueDepth
type: REG_DWORD
default: 1024
valid: 16–65536
applies: restart

Maximum number of jobs held in the spool queue before new submissions
are rejected with EAGAIN.

Raising this lets the queue absorb larger bursts at the cost of memory.
The queue is preallocated, so the change takes effect at the next service
restart rather than live.

That renders, for regman 'Machine\System\Exampled' MaxQueueDepth, as:

Machine\System\Exampled MaxQueueDepth                 documented by exampled

  Type     REG_DWORD
  Default  1024
  Valid    16–65536
  Applies  restart

Maximum number of jobs held in the spool queue before new submissions
are rejected with EAGAIN.

Raising this lets the queue absorb larger bursts at the cost of memory.
The queue is preallocated, so the change takes effect at the next service
restart rather than live.

— and the bare regman 'Machine\System\Exampled' renders the key body plus the index:

Machine\System\Exampled                               documented by exampled

The Exampled spooler reads its tuning parameters from the values under
this key. Compiled-in defaults apply until LCS is available.

Security is on this key, not per value: every value inherits this key's
Security Descriptor.

Values
  MaxQueueDepth  Maximum number of jobs held in the spool queue before n…

The fmt/lint workflow #

You write canonical with whatever casing reads best. The fence anchor — the folded, lowercased token the scanner matches — is derived from it, because the registry compares keys case-insensitively (Unicode Simple Case Folding) while a filesystem does not. Keeping the two in sync by hand is exactly the kind of error a tool should own, so two commands own it:

regman fmt  exampled.regman    # bake the folded anchor onto every fence line
regman lint exampled.regman    # verify structure and anchors

The workflow is:

1. Write each record with its canonical and body. Open the record with a fence line — you can put any placeholder after the dashes, e.g. --- x; regman fmt overwrites it.
2. Run regman fmt. It rewrites every fence to --- <fold(canonical)> and prints <file>: anchors updated if anything changed. It is idempotent — a second run is a no-op. A record missing canonical is skipped and reported.
3. Run regman lint. It reports any record with no canonical: and any fence anchor that disagrees with its canonical (anchor for ...: fence has X, expected Y — run regman fmt). A clean fragment prints nothing and exits 0.

Wire regman lint into your build or CI so a malformed fragment fails the build rather than shipping silently broken.

Preview before you ship #

regman honours REGMAN_DIR, so you can point it at your working directory and see exactly what an operator will see, without installing anything:

REGMAN_DIR=. regman Machine\\System\\Exampled MaxQueueDepth
REGMAN_DIR=. regman Machine\\System\\Exampled
REGMAN_DIR=. regman -k queue

Rules the tools won't catch #

regman lint checks structure and anchors. These conventions it does not enforce — they are on you:

• Never start a body line with --- (three dashes, a space, then text). Any such line is a fence — it will be read as the start of a new record and silently split your page in two. A bare --- on its own line (a Markdown thematic break) is fine; it's the --- text form that bites. If you need a horizontal rule, use *** or ___.
• Keep applies to the vocabulary live / restart / reboot. A short parenthetical is fine (live (ring-buffer swap)); a freeform sentence defeats the at-a-glance purpose of the field.
• Lead the body with one summary sentence (above) — an empty or buried first line leaves a blank in the key index and in -k results.
• Don't invent fields. Unknown header keys are ignored, so defualt: or applies-to: vanish without warning. There is deliberately no access:/SD field (the deployed Security Descriptor is live state a shipped file can't know — say access intent in prose if it matters) and no since: field (the package version already records provenance).

Two documenters, one key #

If two installed packages document the same (key, value), regman does not pick a winner — it shows both records under a documented by N packages: banner, flagging the overlap as the anomaly it is. That's a safety net, not a feature: a key should have exactly one documenting package, the one that owns it. If you find yourself documenting another package's keys, that's usually a sign the ownership is wrong.

Keeping lookups fast #

Lookup is correct with no index at all — regman scans the corpus directly, and at realistic sizes that's a few milliseconds. An optional index (regman index, kept warm by a supervised regman index --watch) just skips the scan; it can be absent or stale without ever producing a wrong answer. None of this is your concern as a fragment author, with one exception worth knowing: package installs must replace a fragment by atomic rename rather than truncate-and-rewrite, so a lookup never sees a half-written file. peipkg already does this, so simply shipping the file the normal way is correct.

See also #

• The registry manual — the operator's view of regman: reading a knob-card, the -k search, and the intent-not-state boundary.
• Configuration, not storage — why the registry holds values without their meaning, the idea a .regman page exists to serve.
• Packages and the recipe format reference — installing the fragment as part of your package.

An event record carries a type name and a MessagePack payload, but never its meaning — it does not say that outcome.reason is only present on failure, or which of two masks a field holds. That knowledge ships with the software that writes the event, as documentation evman reads. From the operator's side this is the event manual; from yours, the package author's, it is a file you write and install.

This page is how you write one. It assumes you have already designed your events — their types, fields and tiers — as Naming and shaping your events describes. The normative rules are PGSS §6.10; this page applies them.

Where the documentation lives #

evman reads a drop-in directory, /usr/share/evman/. Each *.evman file in it is one fragment, named for the component that ships it:

/usr/share/evman/
    kernel.evman                # the platform fragment: the shared field vocabulary
    kacs.evman
    org.example.backup.evman    # yours

A package ships one fragment per component, describing every event type that component writes and every field it defines. There is no central index to register with and no install-time hook: dropping the file in is the whole act, and removing it on uninstall is the whole undo.

Ship it the way you ship any other file. A hand-written fragment kept beside the recipe maps straight into the payload from the package file's [files] table:

[files]
"@recipe:org.example.backup.evman" = "usr/share/evman/org.example.backup.evman"

See Packages for ref resolution.

The shape of a fragment #

A fragment is a sequence of records. Each begins with an anchor line — three hyphens, a space, the record kind, a space and the name — then header lines, a blank line, and prose:

--- field object.org.example.backup.snapshot.id
type: bin.guid

The snapshot an event concerns, by the GUID the backup tool assigned it.

There are three kinds of record:

The prose's first sentence is the summary evman shows in its indexes and -k results, so make it a complete sentence that stands on its own. Inline markup is **bold** and `code` only. The full key tables, including the rarely needed asserted and carried, are in §6.10.

Event records list their fields #

After an event's prose come the fields it carries, one per line, each saying when it is present:

field: object.file.path                       required
field: object.file.size                       when outcome.success == true
field: outcome.reason                         when outcome.success == false
  values: disk-full | source-unreadable | cancelled
  closed: false
  Why the snapshot was not written.

• Presence is required, optional, or when and a condition on another field the event carries.
• An indented paragraph after a field: line is a gloss: what the field means in this event. Use it wherever the general definition is broader than what this event puts there. A gloss may narrow a definition and must not contradict it.
• Indented values: and closed: lines declare the values of a field whose definition leaves them to each event. outcome.reason is the common case: every event has its own reasons.
• include: <group> carries every field of a group at once.

Define your own fields; reference everyone else's #

This is the rule that matters most, and the one a new author most often gets wrong.

A --- field record defines a field. A field: line on an event carries it. You carry any field defined anywhere — subject.token.sid, object.file.path, outcome.success are all defined in the platform fragment, and your events reference them freely. You define a field only when no existing one has the meaning you need, and then only beneath your own package name, under the role it describes:

--- field object.org.example.backup.snapshot.id

Two fragments defining the same path is an error, and so is redefining a standard field "to be safe": one value with two names is a value a security descriptor can deny under one and leak under the other. Before defining anything, look for it:

evman object.file          # what is defined under object.file?
evman -k snapshot          # does anything already mean this?

If you find a field every package like yours would want and nobody defines, that is a gap in the shared vocabulary worth reporting rather than working around.

Enumerations declare their values #

A field whose type is str.enum or uint.enum lists its values and says whether the list is closed:

--- field object.org.example.backup.snapshot.kind
type: str.enum
values: full | incremental | differential
closed: true

Which kind of snapshot was taken. ...

• A str.enum value is a kebab-case string. A uint.enum value is a number and the name it renders as: 0 None | 512 Protected.
• closed: true promises that no value is added without a new version of the field. Consumers rely on it, so only claim it when the set is genuinely complete; otherwise say false, and consumers will cope with a value they have not seen.
• Take the values from your code, not from memory. Nothing checks that the list matches what your program writes.

A complete fragment #

--- field object.org.example.backup.snapshot.id
type: bin.guid

The snapshot an event concerns, by the GUID the backup tool assigned it.
Stable for the life of the snapshot, so it joins a snapshot's creation to
its later verification and deletion.

--- event org.example.backup.snapshot.created
tier: standard

A snapshot was written, or an attempt to write one failed.

field: object.kind                            required
  Always `file`.
field: object.file.path                       required
  The snapshot archive.
field: object.file.size                       when outcome.success == true
field: object.org.example.backup.snapshot.id  required
field: operation.duration                     required
field: outcome.success                        required
field: outcome.reason                         when outcome.success == false
  values: disk-full | source-unreadable | cancelled
  closed: false
  Why the snapshot was not written.
field: outcome.errno                          optional

Only object.org.example.backup.snapshot.id is defined here. Every other field is the platform's, and the event references it.

The lint workflow #

evman lint /usr/share/evman/*.evman org.example.backup.evman

Lint your fragment together with the installed ones. The rules that matter most — every referenced field is defined somewhere, no path is defined twice, no path is both a value and a map — can only be checked across the whole catalogue, and your fragment references fields defined in others. evman lint checks every rule of §6.10, prints each finding as file:line: rule N: message, and exits non-zero if there is any. A clean catalogue prints nothing.

Wire it into your build so a broken fragment fails the build rather than shipping.

Preview before you ship #

evman honours EVMAN_DIR, so you can see exactly what an operator will see without installing anything. Copy the installed fragments and yours into one directory and point it there:

mkdir -p /tmp/evman && cp /usr/share/evman/*.evman org.example.backup.evman /tmp/evman/
EVMAN_DIR=/tmp/evman evman org.example.backup.snapshot.created
EVMAN_DIR=/tmp/evman evman object.org.example.backup

Rules the tools won't catch #

evman lint checks structure, names, definitions and references. These it does not check, and they are on you:

• That a value list is right. Lint checks that an enumeration has values, not that they are the ones your program writes.
• That a condition is true. when outcome.success == false is checked for naming a field the event carries, not for matching when your program actually writes the field.
• That the gloss agrees with the definition. A gloss may narrow a field's meaning, never change it. If you find yourself writing a gloss that redefines a field, you want a different field.
• That the tier is honest. essential is for events that are extremely important and rare, or already governed by their own configuration; it cannot be switched off. Packages submitted to the Peios package repository are checked for it by hand.
• Never start a prose line with --- and a word. It is an anchor: it starts a new record and silently splits yours in two.

See also #

• evman — the operator's view: reading an event card, a field card, and the -k search.
• Naming and shaping your events — designing the events this page documents.
• The Catalogue — the normative format and rules.
• Writing regman pages — the same job for your registry keys.

Peios ships no pip. A Python project becomes a package the same way a C project does: a pekit recipe builds it, the files land under /usr, and peipkg installs and verifies them like any other payload. This page is what that recipe does and why, so that a package you write fits the ones already in the pool.

Where the files go #

The interpreter has one directory for installed Python code — its site-packages, inside the triplet directory:

/usr/lib/x86_64-linux-peios/python3.14/site-packages/

There is no separate pure-Python location and no dist-packages. Ask the interpreter for the path rather than writing it out; sysconfig.get_path("platlib") and sysconfig.get_path("purelib") both return it on Peios.

Two things follow from the path. It is versioned, so a package built for Python 3.14 is not visible to 3.15, and every Python package declares that in its dependencies (see The interpreter pin). And it sits inside the triplet directory, so a Python package is architecture = "x86_64" even when it contains no compiled code.

The system interpreter is the org.python.python3 package. Its standard library and shared runtime are in org.python.python3-libs; headers and embedding metadata are in org.python.python3-devel; and the static embedding library is in org.python.python3-static. Applications that only run Python do not need the development or static packages.

Libraries and applications #

Everything in site-packages is importable by every Python program on the system, which makes installing there an interface decision, not a filing one. Peios draws the line by what the software is for:

An application's modules are private: nothing else can import mesonbuild, so its internals never become an accidental API, and two applications cannot disagree about which version of a dependency site-packages may hold. The application's launcher is the one program that knows the address — it prepends the private directory to sys.path before importing. Site-packages stays on the path, so a private application uses shared libraries normally; privacy governs only whether its own modules are offered outward.

Some projects are both — docutils is a library that also ships rst2man. Classify by what other packages need from it: if anything imports it, it is a library, and its tools ride along in the same package.

Building without pip #

A recipe replaces pip with three steps that pip would otherwise do behind the scenes.

Build the wheel by calling the project's PEP 517 backend directly. The backend is named in the project's pyproject.toml; the pool packages Flit Core and Setuptools, and each is a build dependency of the recipe, not of the resulting package:

python3 -c 'import sys, flit_core.buildapi as b; b.build_wheel(sys.argv[1])' "$PEKIT_OUT/wheel"

Run it from the project's source tree. Some backends write into that tree (setuptools leaves build/ and *.egg-info behind); build from a copy when they do, so the fetched source stays pristine. Set PYTHONDONTWRITEBYTECODE=1 for the same reason.

Install the wheel by extracting it — a wheel is a zip archive of exactly the files that belong in site-packages:

python3 -c 'import sys, zipfile; zipfile.ZipFile(sys.argv[1]).extractall(sys.argv[2])' \
  "$PEKIT_OUT"/wheel/*.whl "$PEKIT_OUT$SITE"

Keep the .dist-info directory: importlib.metadata reads it at run time, and its entry_points.txt is the input to the next step.

Generate the launchers. A project declares its commands under [project.scripts]; the wheel records them in entry_points.txt under [console_scripts], one name = module:function per line. Each becomes a five-line script in /usr/bin:

#!/bin/python3
import sys
from docutils.core import rst2man
if __name__ == '__main__':
    sys.exit(rst2man())

The interpreter is /bin/python3, not /usr/bin/python3: /bin is the runtime view every program is reached through, and a payload never names /usr directly. A private application's launcher carries one more line before the import — sys.path.insert(0, '/lib/x86_64-linux-peios/meson') — again through the view.

Modules can carry a #! line of their own for running them directly: a #!/usr/bin/env python3 or #!/usr/bin/python3 at the top of an installed file. Rewrite it to #!/bin/python3 as well, and do it before compiling the bytecode. A checked-hash .pyc records the hash of its source, so editing the file afterwards leaves the bytecode stale, and Python recompiles it on every import.

Bytecode #

The recipe compiles bytecode and ships it in the package:

python3 -m compileall -q --invalidation-mode checked-hash -s "$PEKIT_OUT" -p / "$PEKIT_OUT$SITE"

Python's default is to write __pycache__ at first import, and Debian's is to write it at install time. Neither is acceptable on Peios: /usr is verified against the package manifest and is never written after install, so a .pyc that is not in the manifest is either a verification failure or a file that can never be written. Shipping the bytecode also removes the cost — every start-up would otherwise recompile.

checked-hash matters. A timestamp-validated .pyc embeds the source file's modification time and goes stale silently; a checked-hash one embeds a hash of the source and is re-validated against it on import. That makes the file reproducible, and it means an operator who shadows a .py through /lcl gets the shadowed source rather than the package's stale bytecode. -s and -p rewrite the path recorded in each .pyc from the staging directory to the installed one, so tracebacks name /usr/lib/....

The interpreter pin #

Every Python package depends on the interpreter's feature version:

[dependencies]
python3 = ">= 3.14, < 3.15"

Bytecode carries a per-version magic number, extension modules carry the interpreter's ABI tag in their file names, and site-packages itself is a versioned path — so nothing in the package survives a minor-version bump. The pin makes that a resolver fact: peipkg will not move the interpreter until rebuilt packages exist. An interpreter bump on Peios is a rebuild of every Python package, which is one pekit sweep.

The Python recipe follows upstream maintenance releases automatically within the current feature line. Its soft floor is Python 3.14 and its upper bound is 3.15: a 3.14 bug-fix release can be locked and rebuilt unattended, while 3.15 deliberately waits for the coordinated package sweep required by the ABI and path change.

The interpreter ships PEP 668's EXTERNALLY-MANAGED marker in its standard library. Nothing on the system reads it — there is no pip — but a pip an operator installs for their own use will find it and refuse to write into /usr, pointing at a virtual environment or /lcl instead. The interpreter also omits ensurepip and its bundled wheel. Create an environment with python3 -m venv --without-pip; install packaged Python software through peipkg.

A recipe, end to end #

The Docutils recipe in the pool is the reference for a library with console scripts: it builds through flit_core, runs the upstream test suite against a copy of the tree, extracts the wheel, generates eleven launchers from entry_points.txt, and compiles the bytecode. Meson is the reference for a private application, and Flit Core for the smallest possible case — a backend that builds itself.

See also #

• Install destinations — the permitted top-level paths, including why /usr/lib/python3.X is not one of them.
• Package files — the manifest keys a recipe's package definition may carry.
• Recipe anatomy — the pekit recipe this page's steps live in.

Qualifying Python build backends #

Flit Core and Setuptools bootstrap themselves with the system interpreter and install-wheel. Their build.main targets remain independent of the Python test ecosystem; their package gates add a separate build.vendor target and offline tests.

The catalogue installer and staged-module checks share the distribution path /usr/lib/x86_64-linux-peios/python<major>.<minor>/site-packages, using the executing interpreter's major/minor version. The interpreter must also report that exact path through sysconfig.

Test-only Python tools are resolved during the explicit acquisition stage, in a native root. Pip runs from its own current wheel, which the acquisition step downloads and checks against the digest PyPI publishes for it, so the root needs only the Peios Python. The selected backend version constrains the candidate tool wheel automatically; other requirements follow the upstream test requirements and current compatible releases. Only portable Python wheels are accepted. The acquisition output retains every wheel, a requirements file and test-tools.json with their hashes. These inputs enter the corresponding-source bundle under acquisition/vendor. This is a per-job resolved record, not a manually maintained version list.

The test worker verifies the complete recorded wheel inventory before creating a private virtualenv. Pip is bootstrapped from its recorded wheel and installs only recorded local files into that virtualenv. Dependency consistency is checked there. Pip and the test ecosystem are not added to the build backend's runtime package or to the system interpreter. Nested virtualenv tests can clear PYTHONPATH and still find their tools. The worker has no external network; local file:// package-index fixtures and recorded wheel files remain usable.

The gates run all Flit Core tests and Setuptools's offline functional suite. Setuptools tests explicitly marked uses_network are excluded: these include its live-PyPI project integration matrix. Release-upload tooling and performance instrumentation are outside this functional package gate. Upstream platform/version skips and expected failures remain visible in JUnit results; a dependency import failure or failed assertion fails qualification.

One recorded adjustment applies only to disposable Setuptools test inputs: the unused coverage-plugin warning category is removed from the copied pytest configuration when coverage instrumentation is not enabled. Other warning errors remain enforced.

Peios's runtime Python deliberately omits CPython's regression tests. Setuptools therefore declares the Python source package as a native test dependency. When test.support is absent, the gate copies its helpers into the private virtualenv from the source matching the interpreter's exact major, minor and micro version. Older source-package archives are checked against their source-lock hash before extraction; prepared source trees are also supported. A version mismatch fails the gate. No test modules are added to the runtime package.

Each backend's installed-payload checks import from the staging directory and exercise wheel, metadata and source-archive hooks. The smoke wheel's complete RECORD is checked against its files, then the wheel is installed into a fresh directory and its module is imported in a separate interpreter with an explicit staged search path. Metadata, vendored code, licenses and checked-hash bytecode are also checked.

For a selected release candidate, run pekit test --version VERSION from its recipe directory, then package and lint it. Only build:vendor has network access; compilation and tests remain offline. Normal release discovery continues to follow upstream automatically.

MSIP keeps what a page contains apart from how it is drawn. A daemon sends a turn of typed elements; a surface draws them however it draws that type. That split is what lets one surface serve every daemon and one daemon be driven by any surface, including a script.

It also means a daemon cannot lay a page out. What it can do is say what a page is for, and let the surface decide what that looks like. PGSS §3.7 gives a turn a class and §3.8 gives an element one — "presentation hints", which the specification is careful to say promise nothing. This page is the vocabulary the stock terminal surface (msip-tui, the renderer behind install-tui and oobe-tui) actually honours, so that a hint you send lands somewhere.

A class a surface does not know is ignored, by design. Sending one costs nothing and breaks nothing; it just does not draw anything either.

Turn classes #

One class per turn is the expectation; the surface reads each independently, so nothing stops you sending two, but nothing today means anything by the combination.

Element state the surface reads #

These are defined by the element types appendix rather than being surface conventions, but what the surface makes of them is worth knowing when you write a page.

What it does whether you hint or not #

Some of the surface's behaviour is not a hint you can send but a fact to design pages around.

Disabled elements take focus. Tab reaches them, and while one is focused the footer shows its help. This is how the surface treats a thing you show greyed out: as something the person is meant to see and ask about, not something to hide. So an element you disable should carry a help that says why — "no keymaps are packaged yet", "domain membership needs a directory source" — because that sentence is what the person will read.

Focus opens on the first element that can be answered. A page that starts with two disabled fields opens on the first enabled one, or the primary action.

A field's note line is reserved. An element with help or an error always has a line under it, so focus moving does not move the page. Help is shown there while the element is focused; an error is shown there always.

A table drops columns from the right when it has no room for them all, as the appendix asks. Put the column a person must see first.

Leaving is the surface's sentence, not yours. Esc opens a question whose wording comes from the surface binary, because what leaving means — an installation carrying on without you, a machine left without an account — is a fact about the program, not the page.

A script sees none of this. msip-drive prints elements and answers them from its arguments; every hint above is invisible to it, which is the point of hints. A page has to work with none of them honoured.

Use this exercise to understand how msip-drive answers an installerd conversation. It simulates an installation against an invented disk. For an actual installation, use Installing to disk.

1. Prepare a private, disposable lab #

Use a disposable lab instance with the matching installerd and msip-drive binaries and an account allowed to use its lab socket. Create a new private directory, restrict access using the lab system's access controls, and verify that protection before starting. In each terminal, set LAB to that directory's absolute path. The examples do not create or protect the directory for you. Keep any saved output there and use only synthetic, nonsensitive data.

These are daemon startup effects, including warning-only socket security. Dry-run does not partition, format, or copy to the target disk; it is not a side-effect-free or fully isolated mode.

Save this JSON as inventory.json in that directory:

{"disks":[{"device":"/dev/msip-lab-only","model":"Synthetic MSIP lab disk","size":8589934592}],"controllers":[]}

The device is deliberately invented, not a real target to substitute later. Omitted fields have schema defaults. Always supply the inventory: without it, dry-run still probes this machine's block devices and controllers. With it, the executor uses the supplied synthetic inventory.

2. Start only the lab daemon #

In the first terminal, with LAB set and verified:

installerd --dry-run --socket "${LAB:?Set LAB to the new private directory}/installerd.sock" \
  --inventory "$LAB/inventory.json"

Before starting a client, check that daemon output explicitly says installerd (dry run) listening on followed by the exact private socket path. Stop if the mode, path, or security checks are wrong. Leave the daemon running; do not connect any other surface to it. Use a fresh directory and daemon for each attempt rather than reusing an uncertain conversation.

3. Drive the synthetic conversation #

In the second terminal, with LAB set to the same verified directory:

msip-drive --socket "${LAB:?Set LAB to the new private directory}/installerd.sock" --kind install \
  --set disk.target=/dev/msip-lab-only \
  --press act.install --press nav.next --press act.begin --press act.reboot

The last action is intentional: successful job execution produces a finish page, not an ended conversation. The dry-run executor's restart returns success without rebooting the machine. Do not remove --dry-run or aim this sequence at a real service.

The expected sequence below is inferred from the flow and client, not captured test output:

1. bound: reports a conversation ID and attached=false.
2. Turns advance through mode, disk.choose, confirm, install.progress, and install.done. The client waits on the progress turn.
3. act.reboot produces == end: Complete Restarting the machine. and the client exits with status 0 for that completed conversation.

install.done means the executor reported job success. End Complete means the restart request was accepted or simulated; neither proves a restart or successful disk boot. A real restart request is accepted when svctl shutdown reboot returns success. In this lab, no disk installation or reboot takes place. Simulated percentages do not verify partitioning, copying, image integrity, cleanup, or bootability.

If it stalls or reconnects #

Do not blindly replay the command. The client's Start implicitly joins the daemon's one live, in-memory conversation and replays its current turn. It has no conversation-ID guard and can consume a queued action immediately; checking printed attached=true is not a barrier before an action runs. If that appears in this fresh-lab exercise, stop the attempt and investigate the unexpected state. The new private daemon and exclusive socket are the precondition, not a check performed by the client.

Disconnecting the client does not cancel the daemon's job. A daemon restart loses the in-memory conversation; a failed or completed conversation is also cleared, so a later Start opens a new one. This is not durable recovery. See job lifetime and disconnect and Start handling.

The driver consumes actions only on NewTurn, not same-turn Updated events. A rescan or rejected input/reboot can therefore leave it waiting indefinitely, even with more presses queued. It has no built-in timeout. An external watchdog that stops the client neither cancels the job nor undoes changes. A client with no presses is not a persistent observer: it exits with status 1 when an actionable turn arrives. These limits follow from the client loop and same-turn rejection/patch handling.

Keep the evidence in scope #

• Protect inventory, console output, and logs. Do not add credentials or first-boot account setup to this exercise. --set values are command-line arguments; only daemon-marked secret elements are masked in the client trace. The client also prints only the last three stored log lines per update, so its output is not a unique, exhaustive audit journal. See trace handling and log rendering.
• The checked-in VM queue-inspection script omits act.reboot and logs, rather than asserts, the client's exit status. At this revision, a successful job reaches the actionable done turn with no presses left, so the client exits 1. That script is not proof of a completed headless conversation; do not copy its real-device or mounting commands here.
• When finished, stop only the dedicated lab daemon. A real unattended-install guide still needs runtime validation of the shipped binaries, failure and reconnect handling, and independent checks of the installed disk and boot.

A feature is how a package does more than put files in place: define a service, change a setting, make something its files rely on. Reach for one only when the package can't do without it. A feature's scripts run as whoever turns it on, with that person's authority and no more, and each one is code an Administrator has to trust.

Its directory #

A feature is a directory your package installs under /usr/libexec/features/<name>/, read at /libexec/features/<name>/. Its name is letters, digits, -, _ and .. In it, any of:

Ship only the scripts that have something to do. A step with no script just records the new state. Other files may sit beside them for the scripts to use.

What a script is given #

Each script is run directly, so it needs a #! line and to be executable. It runs:

• as whoever asked, with their token: feat adds no authority;
• in the feature's directory, so it can name the files beside it;
• with FEAT_NAME, FEAT_DIR and FEAT_PHASE (install, enable, disable or uninstall) set, beside the rest of the caller's environment;
• with the caller's standard output and error, or, under a program such as Feature Manager, with its output read line by line and shown, and its standard input empty.

A script that exits with anything but 0 has failed: the feature is left interrupted, and the person is shown what the script said.

The rules a script keeps #

• Be safe to run again. Asking again after an interruption reruns the script from the start, whatever it had done. Set values rather than add to them; treat "already there" and "already gone" as done.
• Be safe to run first. An interrupted uninstall can be followed by an install, and an interrupted turn-on by a turn-off, so a script can't assume the step before it finished.
• Say what you did, briefly. Each line is shown to the person, under Feature Manager as the change runs. Start lines with the feature's name.
• Fail with words. Write why to standard error before exiting non-zero. It is what the person sees.
• Ask nothing. There may be no terminal, and standard input may be empty.
• Undo what you do. uninstall.sh takes away everything install.sh made; disable.sh reverses enable.sh.

feature.toml #

title = "Dynamic Boot"
description = """
Keeps this machine's boot image up to date. Two services, mkirf-watch and
mkuki-watch, make it again whenever the kernel, the initramfs or the kernel
command line changes, so a change to any of them is used at the next boot
without making the boot image by hand.

Turning it on or off takes effect at the next boot."""

Both are optional, and members feat doesn't know are ignored. A feature.toml that can't be read doesn't hide the feature: it is listed, with the problem said beside it.

Packaging it #

Map the files into place in your package's [files]:

[files]
"src/feature.toml" = "usr/libexec/features/dynamic-boot/feature.toml"
"src/install.sh"   = "usr/libexec/features/dynamic-boot/install.sh"
"src/enable.sh"    = "usr/libexec/features/dynamic-boot/enable.sh"
"src/disable.sh"   = "usr/libexec/features/dynamic-boot/disable.sh"
"src/uninstall.sh" = "usr/libexec/features/dynamic-boot/uninstall.sh"

and depend on dev.peios.peiosutils, which ships feat, and on whatever the scripts run. Installing the package runs none of them: the feature waits, not installed, until someone turns it on.

A feature's package is named for it, feat-<name>, as Peios's own dev.peios.feat-dynamic-boot is: a whole example.

A boot hook is a shell script that runs inside the initramfs, before the real root is mounted — during the initramfs stage. Hooks are how Peios keeps prelude deployment-agnostic: every part of early boot that depends on this particular machine is a hook, and prelude runs the hooks without knowing what any of them do.

The work hooks do is the work of getting to the real root: loading the storage driver that makes the system's disk visible; unlocking an encrypted container; assembling an LVM volume group or a RAID array; and, finally, mounting the real root filesystem onto /mnt/rootfs. None of that is the same on two arbitrary machines, so none of it is built into prelude — it is all hooks. prelude supplies the fixed skeleton of the boot; hooks supply everything that varies.

Where hooks live #

Hooks live in two directories, which mirror the layout's vendor/operator split everywhere else:

Every regular file directly in either directory is a hook, and prelude runs all of them. Neither is searched recursively — a subdirectory is not a hook — and the file extension does not matter. A hook is recognised by being a file in one of those directories, and it is run according to its #! shebang line, the same way any script is run.

A file name identifies a hook. The same name in both directories is one hook with two candidate bodies, not two hooks: the operator's copy wins and the packaged one is skipped, so a shipped hook can be replaced without deleting a package's payload. The build says which file lost, because a hook silently replaced by another is exactly the kind of thing that should not be quiet.

An older hooks/ directory at the initramfs root is still read, and every hook found there produces a build warning naming where it should move. That is deliberate: a hook in a directory nobody scans is not an error — it simply is not there, and the boot fails much later with nothing mounted — so the move cannot be a flag day. The warning going quiet is what says the migration is done. Choose a shebang whose interpreter exists in the initramfs when the hook runs. The examples below use #!/usr/bin/sh; this is not a universal requirement. The reviewed disk-root hook uses #!/bin/sh. Verify the interpreter and required tools in the image you build.

How hooks get there #

There are two ways a hook reaches the directory, and they are identical as far as prelude is concerned:

• From a package. A package can supply a hook under /usr/libexec/prelude/hooks.d/, together with the tools it needs. Verify the selected image actually includes both; the encryption examples below do not establish that a particular encryption package is available.
• By hand. An administrator can write a hook and place it in /lcl/libexec/prelude/hooks.d/ directly. A site with an unusual storage arrangement, or a one-off need, does not have to build a package — a script in the directory is a hook.

Either way, the next time the initramfs is built the new hook is picked up. (See The initramfs stage for the build.)

The ordering problem #

Hooks have an order, and the order matters. A hook that mounts the root cannot run before the hook that loads the disk's storage driver; a hook that unlocks an encrypted volume cannot run before that volume's driver is loaded. Run them in the wrong order and the boot fails.

The obvious approach — number the files, 10-modules, 20-crypto, 30-mount, and run them in numeric order — is the approach Peios deliberately does not take. Numeric prefixes work right up until two packages, written by people who never spoke to each other, both pick 20. Then every package author has to know the whole number line, and the "order" is a fiction held together by convention. This is the historical sysvinit problem, and it does not scale.

Instead, a hook declares what it needs and what it offers, in terms of named capabilities, and the order is computed from those declarations. The hook that mounts the root says "I require crypto-unlocked"; the hook that unlocks encryption says "I provide crypto-unlocked"; the order follows. No hook needs to know any other hook's name or position — only the capabilities. Packages that never met each other compose correctly because they agree on capability names, not on numbers.

The metadata block #

A hook declares its capabilities in a metadata block at the top of the script: a fenced comment block, every line of it a comment, so the block is invisible to the shell when the script actually runs.

#!/usr/bin/sh
# /// hook
# contributes = ["rootfs-ready"]
# ///

# ... the hook's actual work follows ...
cryptsetup open /dev/sda2 root

The rules of the block are small and exact:

• It opens with a line that is exactly # /// hook and closes with a line that is exactly # ///.
• Every line in between is a comment line — # followed by content, or a bare #. This is what keeps the block inert: the shell sees only comments.
• The content of those lines, with the # stripped, is up to four keys:
  • provides — capabilities this hook satisfies on its own. Several hooks may provide the same capability, and any one of them suffices; they are alternatives.
  • contributes — capabilities this hook is one part of. Every contributor must complete before the capability counts as satisfied.
  • requires — capabilities that must already be satisfied before this hook runs. If nothing supplies one, the build fails.
  • after — capabilities to be ordered after if anything supplies them. If nothing does, the hook simply runs; this is not an error.
• Each key's value is a list of capability names in double quotes — provides = ["a", "b"]. An empty list is allowed, and a trailing comma is allowed.

Why there are four keys and not two #

The four are two ways to supply a capability crossed with two ways to consume one, and each pair exists to say something the other cannot.

contributes is how a hook runs before something. A hook is otherwise ordered only by what it consumes — so "run before the root is mounted" would require the root-mounting hooks to name your hook, which they cannot, because they were packaged before it existed. Declaring yourself part of a capability inverts the relationship: everything that consumes it now waits for you. Without this, the only way to be early is to win the file-name tie-break, which is the numeric-prefix problem wearing a disguise.

after is how a shared vocabulary survives a small image. A requires on a capability nothing supplies is a build error — deliberately, since it catches an initramfs that cannot possibly boot. But that makes any standard capability name dangerous: a hook mentioning network-up would break every image that has no networking. after expresses "if this happens at all, it happens before me", which is what most ordering against an optional milestone actually means.

provides and contributes differ in what "satisfied" means. With alternatives, one supplier doing the job is enough — for example, two hardware-specific implementations of the same discovery step in a custom image. With contributors, the capability is not satisfied until every one of them has completed — three hooks each unlocking a layer of an encrypted stack, say. A capability must be one or the other; declaring it both ways is a build error, because there would be no answer to whether it is satisfied yet.

The format is a small, deliberate subset of TOML: enough to declare four optional lists of names, and no more. It is checked strictly when the initramfs is built — an unknown key, a list that is not well-formed, a block that is opened and never closed, two blocks in one file — each of these is a build error, not a quiet misread. A typo in a hook's metadata is caught at build time, with a message naming the hook and the line.

The metadata lives inside the hook script, not in a separate file, so a hook is a single self-contained thing: copy the script and its ordering travels with it.

The capability vocabulary #

Capabilities are just names, and a hook can in principle name its own. But the milestones every initramfs passes through are a small fixed vocabulary, so that hooks from unrelated packages line up against the same reference points:

The vocabulary is deliberately short. Names for things Peios does not yet do — device settling, volume assembly — are not reserved in advance: a capability that nothing supplies and nothing consumes is a name with no meaning behind it, and inventing one early only fixes a shape before we know it. Driver loading, which Peios does do, has no capability of its own for the same reason: the coldplug hook simply contributes to rootfs-ready, which is what it means for the root-mount hooks, and nothing has yet needed to order against it more precisely than that.

Once every hook has finished, prelude chroots into /mnt/rootfs. There is no "last point at which a hook can run" capability, because that is already every hook's guarantee.

initramfs-ready is the one capability with a rule #

A hook that must run before all the others cannot say so by ordinary means — it would need every other hook to name it, including hooks written by people who have never heard of it, whose forgetting would not fail the build but would quietly run their hook in an initramfs with no /bin.

So initramfs-ready carries one extra rule:

Every hook that does not supply initramfs-ready is implicitly ordered after it.

The exemption is derived, not declared — you are exempt exactly when you are part of the capability. There is no cycle to construct and nothing for a hook author to remember. A hook assembling the initramfs's own topology simply declares contributes = ["initramfs-ready"] and lands before everything.

Three things fall out of the existing rules rather than needing special cases. An initramfs with no contributors leaves the capability unsupplied, and an after on an unsupplied capability is vacuous — so a minimal initramfs just runs, with nothing to configure. A hook carrying no metadata block does not gain the edge, because it already runs after every declaring hook; adding it would have pulled the escape hatch into the DAG. And a hook that already waits on initramfs-ready, by requires as readily as by after, keeps the declaration it wrote: the implicit edge would order it no differently.

mkirf materialises these edges into the sequence as ordinary after entries, rather than leaving prelude to know the rule. That keeps one implementation instead of two that have to agree, and makes the sequence file explain itself — in a rescue shell you can read why a hook ran where it did, instead of needing a rule that appears nowhere in the image. Each stanza names a dependency once: a hook that declared requires = ["initramfs-ready"] shows that line and no after beside it, because the two keys mean different things at boot — requires waits for the capability to be achieved, after only for it to be settled.

More than one hook may supply the same capability #

Nothing limits a capability to a single supplier, and rootfs-ready is where that matters: getting a root filesystem ready is several jobs. A hook that unlocks an encrypted container, a hook that assembles a volume group, and a hook that performs the mount each contributes = ["rootfs-ready"], and the capability is not achieved until all of them have finished. None of them needs to know the others exist.

A capability does not have to be a hard, machine-specific thing. What matters for ordering is the declaration, not how much work the hook does to honour it. An encryption hook on a machine with no encrypted volumes has nothing to unlock and declines (exit 69) — which, for a capability it contributes to, completes its part: "nothing needed doing here" is a way of being done. The capability is still achieved, and everything waiting on it proceeds.

How the order is resolved #

When the initramfs is built, mkirf reads every hook's metadata and computes the running order:

• A hook that consumes a capability (by requires or by after) runs after every hook that supplies it (by provides or by contributes). That single rule is the whole of the ordering.
• Hooks with no ordering relationship between them run in a stable, predictable order — by file name — so the resolved sequence is the same every time the initramfs is built.

Note that ordering does not distinguish alternatives from contributors, nor hard requirements from soft ones: all four keys produce the same "supplier first" edge. What they change is validity — whether an unsupplied capability is an error — and what a capability being "satisfied" will mean to prelude at boot.

Three situations are build errors. They stop the build, and no initramfs is produced:

• A cycle — hook A consumes something B supplies, and B consumes something A supplies. There is no order that satisfies both; the build reports the hooks caught in the cycle.
• An unsatisfied requirement — a hook requires a capability that nothing installed supplies. Rather than build an initramfs that is guaranteed to fail at boot, mkirf reports the missing capability. An after on an unsupplied capability is explicitly fine.
• A capability that is both provided and contributed to — one hook calls it an alternative, another calls itself a part of it. The two answers to "is it satisfied?" contradict each other, so mkirf names both sides and stops rather than picking one.

This is the payoff of declared capabilities: an impossible or incomplete hook set is a build error on a running system, with a readable message, never a boot that hangs with no explanation.

The resolved order is recorded inside the initramfs image, at /system/prelude/hooks.seq.<n>, and prelude reads it at boot. An operator does not write or edit those files — they are generated. The hook directories are the source of truth; the order is derived from what they contain.

The <n> is the format version, and mkirf writes every version it can express faithfully, prelude reading the newest it understands. That is not ceremony: mkirf ships in peiosutils and prelude in its own package, so an image can pair a newer writer with an older reader, and separate files are what let one image satisfy both. A sequence newer than prelude understands is a warning when a usable one sits beside it, and a boot failure when it is the only one present. The warning arrives on the console tagged [ WARN ], naming both the sequence it passed over and the one it fell back on, and it is one of the lines peios.quiet=2 does not remove: the boot is not running the manifest the image considers authoritative, and that is the sort of thing you need to know from a quiet production boot that afterwards behaves oddly.

prelude checks the manifest it is given rather than trusting the build that wrote it — the two ship in separately versioned packages, so an image can pair a writer and a reader that were never tested together. A stanza key before any hook, an unknown key, a hook line with no path, a marker that disagrees with the file name, and a requires naming a capability nothing in that sequence provides or contributes to all refuse the boot, naming the hook and what was wrong with it. The last of those is the same refusal mkirf gives at build time, in the same words. An after on an unsupplied capability stays fine at boot exactly as it is at build time.

A missing sequence is always an error, never "no hooks to run" — mkirf writes one for every image, including an empty one for an image with no hooks at all. Were an absent file read as "nothing to do", a manifest that failed to generate would become a boot that silently ran no hooks, mounted no root, and reported the failure a long way from its cause.

Hooks with no metadata #

A hook is allowed to carry no metadata block at all. It is still a valid hook — it simply has no declared capabilities, and therefore no ordering constraints. Such a hook runs after all the hooks that do have constraints, in file-name order.

The build emits a warning for a hook with no block — because a hook that merely forgot its metadata looks identical to one that genuinely has none, and the warning makes the difference visible. A hook that is deliberately unconstrained can carry an empty block — a # /// hook line immediately followed by # /// — to say so on purpose, which suppresses the warning.

How prelude runs a hook #

At boot, prelude runs the hooks one at a time, each to completion before the next begins, scheduling from their declarations — repeated passes over the sequence, running whatever is ready, retrying anything that deferred once something else has progressed. Each hook runs as a separate process with a minimal environment — PATH=/usr/bin and TERM=linux — so the initramfs's shell and utilities (dash, peiosutils, and any tools a feature package added) are found without depending on a not-yet-mounted root-level view.

A hook reports what happened through its exit code, and there are four things it can say:

The two middle codes are borrowed from sysexits.h (EX_UNAVAILABLE, EX_TEMPFAIL) rather than invented, for a practical reason: 1 and 2 are what any failing command returns and 126, 127 and 128+n are the shell's own, so a small dedicated range is the only place a deliberate signal cannot be mistaken for an accident. A hook killed by a signal is always a failure, whatever code it might have produced. So is one that is stopped by a job-control signal: prelude reports it as stopped, kills it, and ends the boot. Nothing in the initramfs can resume a stopped hook — there is no job control, no shell and no other process to send it SIGCONT — so waiting for it would be waiting forever.

Declining is not the same as succeeding #

A hook that is not the right one for this machine declines (69) rather than exiting 0. The difference matters because provides means alternatives: a capability with several providers is achieved as soon as one of them is satisfied, and a provider that exits 0 is claiming to be that one.

A hardware-specific provider can use this to stand aside when the machine has no device it understands. If every provider declines, the capability is never achieved and prelude stops with a message naming it.

Live boot and disk boot deliberately do not use runtime decline as their selector. Their initramfs packages conflict, and the installer replaces the live package with the disk package before rebuilding the image. The root-mount hook that is present therefore owns the job: disk-boot treats a missing root= as a broken image, while live-boot treats a missing medium as a failure. This moves an impossible two-flavour image to package-resolution time and preserves the actual cause when a selected flavour is misconfigured.

For contributes the sense is reversed: since every contributor must complete, a contributor that declines has completed — "nothing needed doing here" is a way of being done.

Deferring is a promise that nothing happened #

Deferred (75) means the hook's inputs are not ready yet. prelude runs hooks in repeated passes, retrying deferred ones once something else has progressed, and stops with a diagnosis if a whole pass completes nothing while work remains.

The contract that makes this safe is that a deferring hook has done nothing. Re-running it is free in a way that re-running a failed hook could never be — a failure may have left a half-assembled array, an opened device, or a burnt unlock attempt behind it. So:

• Defer before you act, never after. Check whether you can do the job; if not, exit 75 immediately. Do not defer partway through.
• Failure is still failure. If the work was attempted and went wrong, exit non-zero. Deferring a genuine error turns one clear failure into a stall reported as "nothing left to wait for".

This is what lets layered arrangements compose without absolute ordering: three hooks each contributing to an encrypted stack can be written without knowing which layer comes first, because the ones whose devices do not exist yet simply defer and are retried.

A few more consequences for anyone writing a hook:

• Check, and exit non-zero on failure. A hook that mounts the root must exit non-zero if the mount failed. A hook that fails silently turns into prelude's generic "nothing mounted the root" failure later — which is harder to diagnose than the hook reporting its own error at the point it happened.
• Hooks run as SYSTEM. Everything in the initramfs runs on the SYSTEM token (see Bootstrap tokens), so a hook has full authority. There is no identity model to work within inside the initramfs — that begins on the real root.

Reporting to the console #

The exit code is what prelude reads. What a person reads is whatever the hook writes to its own stdout and stderr, which go straight to the console: prelude runs each hook with a bare fork and execve and no pipe, so it never sees a hook's output and cannot label, align or colour it. That is deliberate — it keeps a PID 1 free of a pump it would otherwise have to drain — but it does mean the only place a hook's lines can be shaped is inside the hook.

So that every hook does not invent its own shape, prelude ships a helper. Source it and report through it:

. /usr/libexec/prelude/hook-log.sh
hook_log_init stratafs-base

log      "mounting $target"     # progress, no outcome yet
log_ok   "mounted $target"      # it worked
log_skip "$target not present"  # deliberately not done
log_warn "$target was already mounted"   # wrong, but the boot continues
log_fail "mount $target failed"          # it did not work

which produces lines that line up with prelude's own and with peinit's later:

[      ] stratafs-base: mounting /bin
[  OK  ] stratafs-base: mounted /bin
[ SKIP ] stratafs-base: /opt not present
[ WARN ] stratafs-base: /bin was already mounted
[FAILED] stratafs-base: mount /bin failed

Three rules worth stating:

• Pass your own name to hook_log_init, not prelude and not the file name. These lines are yours, and attributing them to prelude is how a hook's failure gets read as prelude's.
• Match the verb to the tag. log_ok claims the thing is done, so it reads "mounted", never "mounting". A hook that announces its intention and then reports the outcome writes two lines, not one ambiguous one.
• The helper is prelude-hook-abi level 3. Declare prelude-hook-abi = ">= 3" in the package. Sourcing a file that is not there aborts the hook under set -e, so this is a hard requirement rather than a preference.

log_warn and log_fail write to stderr; the rest write to stdout. Both reach the console. Colour is decided the same way prelude and peinit decide it — on unless the kernel command line says TERM=dumb — so a hook never has to think about it.

Writing a hook #

These examples illustrate hook metadata and exit handling, not a ready-to-use encrypted-root configuration. They assume the named devices, interpreter, tools and suitable mount/access policy are supplied by your image. Adapt and test them in an appropriate development image before using them for boot; the literal device names are examples.

A minimal example that mounts an ext4 root from a known partition:

#!/usr/bin/sh
# /// hook
# contributes = ["rootfs-ready"]
# ///

# The device may not exist yet — another hook may still have to unlock or
# assemble it. Defer rather than fail: exit 75 promises we changed nothing,
# so prelude can retry us once something else has made progress.
[ -b /dev/mapper/root ] || exit 75

mount -t ext4 /dev/mapper/root /mnt/rootfs || exit 1

What this declares: it is one part of rootfs-ready, so anything waiting on a usable root filesystem is ordered after it. It does not name the hooks it depends on, because it does not know them.

A hook that unlocks the container it mounts, to pair with it:

#!/usr/bin/sh
# /// hook
# contributes = ["rootfs-ready"]
# ///

# Nothing encrypted on this machine — decline, which completes our part of
# the conjunction without claiming to have unlocked anything.
[ -e /dev/sda2 ] || exit 69

cryptsetup open /dev/sda2 root || exit 1

Installed together, these two compose without either one naming the other, and without an ordering declaration between them at all. If the mount hook runs first it finds no device and defers; the unlock hook then runs; the mount hook is retried and succeeds. Add a volume-assembly hook later — also just contributes = ["rootfs-ready"] — and it slots in the same way, because each hook knows only whether it can act yet.

That is the model: hooks are composed by capability, ordering is declared only where it is genuinely known, and the rest is settled at boot by hooks that can say "not yet".

What hooks are not #

A few clarifications:

• Hooks do not run on the real root. They run inside the initramfs, before the handoff. Work that belongs to the running system — starting services, applying mount and access policy — is peinit's job, not a hook's.
• A boot hook is not a service. "Hook" here means specifically an initramfs hook. The initramfs stage ends when prelude execs the real init; everything after that — services, supervision, restart policy — is peinit's domain and works nothing like a hook.
• The generated order file is not edited by hand. It is the build's record of the resolved order. The hooks/ directory is the source; the order is computed from it, every time the image is built.
• File names are not the ordering mechanism. A file name identifies a hook, and is the tie-break between hooks that have no capability relationship. Renaming a hook does not change where it runs relative to a hook it shares a capability with — the provides/requires declarations do that.

Where to go next #

For the stage that runs the hooks, read The initramfs stage.

For the build that validates hooks and resolves their order, read mkirf.

For what takes over once a hook has mounted the real root, read peinit at PID 1.

Implementation scope #

The metadata and ordering behavior is described by mkirf's hook implementation, and the runtime outcomes by prelude's scheduler. The console helpers come from hook-log.sh. These pinned sources do not verify that a particular released image supplies the tools or storage configuration used in an illustrative hook.

The Peios SDK is how your own software talks to Peios.

Peios exposes its security world — identities, tokens, access checks, file security, the registry, and the audit/event stream — through a kernel interface built out of raw syscalls, ioctls, and packed byte buffers in the MS-DTYP wire formats. That interface is precise, but it is not something you want to hand-assemble from C. The SDK is the layer that lifts it into ordinary functions you can call: build a SID, open a token, run an access check, read a registry value, emit an event.

It is a C ABI, not a C-only library. The shipping product is a set of hand-written C headers and a shared object with a frozen application binary interface. Anything that can call C — Go via cgo, Rust via bindgen, Python via ctypes, Zig, C++ — can link it and get the same surface. The library happens to be implemented in Rust, but that is invisible across the boundary: callers see peios_* functions, <peios/*.h> headers, and errno.

Who it's for #

You want the SDK if you are building software that runs on Peios and needs to participate in its security model — a service that checks whether a caller may perform an action, a tool that reads or writes security descriptors, an agent that emits audit events, or anything that reads and writes the registry.

You do not need it to simply run on Peios. Ordinary POSIX programs run under Peios's Linux-compatibility surface without ever linking libpeios. The SDK is for programs that want to reach past POSIX and speak KACS, LCS, and KMES directly. If you are administering a running system rather than writing code against it, the Peios operator documentation is the place to start.

The three surfaces #

Peios's kernel boundary has three subsystems, and the SDK mirrors them one-to-one. Everything in the SDK belongs to one of these:

The umbrella header <peios.h> pulls in all of them; you can also include the individual concept headers for a tighter compile surface.

libpeios, librsi, and the substrate #

The SDK is two libraries on a shared foundation, each with its own role:

• libpeios — the userspace C-ABI library for KACS, LCS, and KMES. It is the registry client and the whole of the access-control and event surface, and it is what the bulk of this documentation describes. Link -lpeios, include <peios.h>.
• librsi — the library for implementing a registry source (a storage backend): the provider counterpart to libpeios's registry client. Where libpeios reads and writes the registry, librsi is what a program uses to be the thing that holds the data and answers the kernel. Link -lrsi, include <rsi.h>. See Registry sources.
• peios-cabi — the internal C-ABI substrate both libraries are built on (the allocator wiring, the errno slot, the syscall/ioctl wrappers, the getxattr-style buffer helpers). You never link it directly; it is shared plumbing, documented here only so the conventions it sets make sense.

So the registry has two sides in this SDK: the client side in libpeios (open keys, read/write values) and the source side in librsi (back the keys and values, serve the kernel's requests). Most programs are clients; you reach for librsi only when you are providing storage.

Because the two libraries share one substrate, one error model, and one audience, they share one doc set. Learn the conventions once and they hold across both.

What this documentation promises #

This is user-facing documentation, not a specification. The authoritative byte-level contracts live in the PCSA specifications — PCDS for the core data structures, PGSS, PSPK and PSPU for the interfaces — and in the <pkm/*.h> kernel headers; where a detail is normative, this documentation points you at the specification that owns it. Where a detail is about this implementation rather than the contract, it points at the Peios Kernel manual instead. What you get here is the working knowledge to use the library well: what every function does, what it returns, how memory and errors flow, and how the pieces fit together — with enough coverage that you should not need to open the library's source to answer a question. When you find a gap, that is a documentation bug worth reporting.

Where to go next #

• Installing and linking — the packages, the headers, and how to build against the library.
• Library conventions — the error model, the memory rules, and the buffer protocol that every function in the SDK follows. Read this once; it saves you re-learning it per module.
• Your first program — a small, complete program you can compile and run.

libpeios ships as a small set of packages, split the same way a C library conventionally is: a lean runtime package that programs depend on, and a development package that carries the headers and the linker symlink. You install the runtime everywhere the library is used and the development package only where you compile.

The packages #

Installing dev.peios.libpeios-devel pulls in the matching dev.peios.libpeios runtime and kernel-headers automatically — the development package pins the exact runtime version whose ABI its headers describe, so the headers you compile against and the shared object you load cannot disagree.

Obtaining the SDK #

On a Peios system, the development package comes from the package repository the system is configured with:

peipkg install dev.peios.libpeios-devel

The packages are built, signed and published into the Peios repository, but that repository is not yet hosted at a public address. Until it is, the source is the route for anyone outside the project. All of it is public:

The library builds themselves need nothing beyond a Rust toolchain: they pin the kernel ABI through their Cargo dependencies. Compiling a C program against the resulting headers needs the <pkm/*.h> kernel UAPI headers described below.

The headers #

Everything lives under <peios/…>, with one umbrella:

#include <peios.h>          /* the whole API */

or, for a tighter compile surface, just the concept headers you use:

#include <peios/security.h> /* SIDs, security descriptors, ACLs */
#include <peios/token.h>    /* tokens */
#include <peios/access.h>   /* access checks */
#include <peios/file.h>     /* file security */
#include <peios/process.h>  /* process security */
#include <peios/registry.h> /* the LCS registry */
#include <peios/msgpack.h>  /* msgpack framing */
#include <peios/event.h>    /* the KMES event stream */

The headers are hand-written and are the real API — they carry the prose docs and the layout notes that a generated header can't. (Internally they are checked against the library's Rust surface by a cbindgen-based verifier, so they cannot silently drift from what the shared object actually exports. You do not interact with that machinery; it just means the header you read is the contract you get.)

The <pkm/*.h> dependency #

The Peios headers do not re-invent the kernel's wire constants — they use them directly. So <peios/security.h> includes <pkm/sid.h> and <pkm/sd.h>, and the other headers pull in their matching <pkm/*.h> UAPI headers for the KACS_*, LCS_*, and KMES_* constants and the #[repr(C)] argument structs. Those PKM kernel UAPI headers must be on your include path when you compile. They ship with the Peios kernel headers; on a normal Peios development install they are already where the toolchain looks. If a build fails with fatal error: pkm/sid.h: No such file or directory, that is what is missing — add the kernel UAPI include directory to your compiler's search path.

Compiling and linking #

With pkg-config (recommended) #

The development package installs a peios.pc descriptor, so pkg-config knows the include and library flags:

cc myprog.c $(pkg-config --cflags --libs peios) -o myprog

pkg-config --cflags peios expands to the include flags and --libs peios to -lpeios plus the library directory. This is the form to prefer — it stays correct across install prefixes and multiarch library directories.

By hand #

If you are not using pkg-config, link against -lpeios directly:

cc myprog.c -lpeios -o myprog

Add -I / -L flags if your headers and library live outside the compiler's default search paths.

Statically #

Install dev.peios.libpeios-static and point the linker at the archive:

cc myprog.c -o myprog /usr/lib/x86_64-linux-peios/libpeios.a

The static archive is also what the library's own integration tests link against, so it is a fully supported way to build. Static linking folds the library into your binary — you then do not need the libpeios runtime package on the target, though you still need whatever C runtime your program uses.

Linking from other languages #

Because libpeios is a C ABI, any language with a C FFI can call it. The shape is always the same: point the FFI at the libpeios.so.0 shared object (or the static archive), declare the peios_* functions with their C signatures, and follow the library conventions for buffers and errors exactly as a C caller would.

• Rust — use the maintained bindings: the safe peios crate (or the raw peios-sys), covered in Using the SDK from Rust. You don't need to hand-roll bindgen. (The library is Rust internally, but the crates still bind it strictly as a C library through the stable ABI — the supported entry point.)
• Go — cgo against <peios.h> with #cgo pkg-config: peios.
• Python — ctypes or cffi against libpeios.so.0.
• C++ — include the headers directly; they are wrapped in extern "C" and compile as C++.

The one rule that matters across every language: the errno-based error model and the caller-buffer / two-call buffer protocol are part of the contract, not a C convenience. Read Library conventions before you wrap the API in another language's idioms.

librsi — the registry-source library #

Everything above describes libpeios. If you are writing a registry source, you link the sibling library librsi instead (or as well). It is built on the same peios-cabi substrate and follows the identical library conventions — raw fds, the int/ssize_t error model, the borrow discipline.

The packages #

librsi takes the same split as libpeios:

peipkg install dev.peios.librsi-devel

The <rsi/*.h> headers include <pkm/lcs.h>, so the same UAPI-header requirement described above applies. To build from source instead, cargo build --release in a clone of https://github.com/peios/librsi produces librsi.so and librsi.a, with the headers in include/.

Headers and linking #

Include the umbrella or the individual concept headers:

#include <rsi.h>            /* the whole librsi API */
/* or: */
#include <rsi/source.h>    /* registration */
#include <rsi/request.h>   /* decoding requests */
#include <rsi/response.h>  /* building responses */

and compile with pkg-config (the descriptor's module name is rsi):

cc mysource.c $(pkg-config --cflags --libs rsi) -o mysource

or link -lrsi directly, or against librsi.a for a static build — exactly the three forms shown for libpeios above. The two libraries are independent: a program can be a client (libpeios), a source (librsi), or both, linking each as needed.

This is a complete program you can compile and run. It does not touch the kernel — it works entirely with the security-descriptor vocabulary from <peios/security.h>, which makes it a safe first outing: no privileges, no live tokens, just the conventions from Library conventions put to work.

The task: take a security descriptor written in SDDL text, turn it into wire bytes, read its owner, and print that owner's SID in string form. Along the way you exercise the two-call buffer protocol twice, parse with a zero-copy view, and handle errors the libpeios way.

The program #

#include <peios/security.h>

#include <errno.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

int main(void)
{
    /* An SDDL descriptor: owner and group are Administrators (BA), with a
       DACL granting them full access (FA). */
    const char *sddl = "O:BAG:BAD:(A;;FA;;;BA)";

    /* 1. Parse the SDDL text into self-relative SD wire bytes.
          First call probes for the size (cap == 0), then we retrieve. */
    ssize_t need = peios_sddl_parse_sd(NULL, 0, sddl);
    if (need < 0) {
        fprintf(stderr, "parse probe failed: %s\n", strerror(errno));
        return 1;
    }

    unsigned char *sd = malloc((size_t)need);
    if (!sd)
        return 1;

    ssize_t sd_len = peios_sddl_parse_sd(sd, (size_t)need, sddl);
    if (sd_len < 0) {
        fprintf(stderr, "parse failed: %s\n", strerror(errno));
        free(sd);
        return 1;
    }
    printf("security descriptor: %zd bytes\n", sd_len);

    /* 2. Parse the SD into a zero-copy view. The view borrows `sd` — it
          must stay alive and unmodified until we are done reading. */
    peios_sd_view view;
    if (peios_sd_parse(sd, (size_t)sd_len, &view) != 0) {
        fprintf(stderr, "sd parse failed: %s\n", strerror(errno));
        free(sd);
        return 1;
    }

    /* 3. Pull out the owner SID. On success `owner` points INTO `sd`. */
    const void *owner;
    size_t owner_len;
    if (peios_sd_view_owner(&view, &owner, &owner_len) != 0) {
        printf("no owner set\n");
        free(sd);
        return 0;
    }

    /* 4. Format the owner SID as its "S-1-…" string. The byte form of a
          SID is bounded, but its string form is variable, so we probe.
          A string length excludes the NUL, so allocate len + 1. */
    ssize_t slen = peios_sid_format(owner, owner_len, NULL, 0);
    if (slen < 0) {
        fprintf(stderr, "sid format probe failed: %s\n", strerror(errno));
        free(sd);
        return 1;
    }

    char *str = malloc((size_t)slen + 1);
    if (!str) {
        free(sd);
        return 1;
    }
    if (peios_sid_format(owner, owner_len, str, (size_t)slen + 1) < 0) {
        fprintf(stderr, "sid format failed: %s\n", strerror(errno));
        free(str);
        free(sd);
        return 1;
    }

    printf("owner: %s\n", str);

    /* 5. Only now free `sd` — every pointer the view gave us pointed into
          it, so it had to outlive the last read. */
    free(str);
    free(sd);
    return 0;
}

Building and running #

cc first.c $(pkg-config --cflags --libs peios) -o first
./first

Expected output:

security descriptor: 44 bytes
owner: S-1-5-32-544

S-1-5-32-544 is the well-known SID for the local Administrators group — which is exactly the BA you wrote in the SDDL string. (The byte count may differ across versions; the owner will not.)

What just happened #

Every convention from the previous page showed up here:

• The two-call protocol, twice. peios_sddl_parse_sd and peios_sid_format were each called first with a NULL/0 buffer to learn the size, then again to fill a right-sized allocation. Neither could ever truncate: a too-small buffer would have returned -1 with ERANGE, not a partial result.
• A string length excludes the NUL. That is why the SID string buffer was slen + 1.
• A zero-copy view borrowed our buffer. owner pointed into sd, so sd had to stay alive and unmodified until after the final peios_sid_format. Freeing it earlier would have left owner dangling — the one mistake this pattern invites, and the reason step 5 frees last.
• Errors came back through the return value and errno. Every call was checked; strerror(errno) explained any failure. No exceptions, no out-of-band error channel.

A shortcut worth knowing #

Not every buffer needs a probe. Some results have a known ceiling, and the library gives you a constant so you can use a fixed stack buffer and skip the first call entirely. A SID is the classic case — it is never larger than PEIOS_SID_MAX_BYTES:

unsigned char sid[PEIOS_SID_MAX_BYTES];
ssize_t n = peios_sid_well_known(sid, sizeof sid, PEIOS_WKS_ADMINISTRATORS);
/* n > 0: `sid` holds S-1-5-32-544 in wire form, no malloc, no probe. */

Use the probe when a length is genuinely unbounded (strings, whole descriptors, ACLs); use the fixed-size shortcut when the module documents a ceiling for the thing you are building.

Where to go next #

You now have the mechanics. From here, pick the subsystem you need:

• Access control (KACS) — the security vocabulary you just used, plus tokens, access checks, file security, and process security.
• The registry (LCS) — reading and writing Peios's configuration store.
• Events (KMES) — emitting and consuming the audit/event stream.

The SDK is a C ABI, so it is reachable from any language with a C FFI — but Rust gets first-class, maintained bindings rather than hand-rolled extern blocks. If you are writing Rust on Peios, use them. This page is the on-ramp: what the crates are, how to wire them into a build, and where the docs live. It is deliberately not an API reference — that job belongs to the crate's rustdoc, which is generated from the code and so never drifts from it.

The two crates #

peios-rs is two crates, layered:

Both bind libpeios strictly as a C library through its stable ABI — they never depend on libpeios's internal Rust crates. The C ABI is the only supported entry point, and binding through it means the crates exercise the exact surface every other consumer uses.

The safe crate's modules mirror the libpeios concept headers one-for-one — security, token, access, file, process, event, msgpack, registry — so everything you learn about the C surface maps straight across.

Where the docs live #

Two places, and the split is deliberate:

• The API reference is the crate's rustdoc. Every public item in peios is documented (the crate is built with #![warn(missing_docs)], so this is enforced), with a crate-level overview, per-module docs, and the error model. Build and browse it locally with:

  Copy

  cargo doc -p peios --open
  

  This is the reference precisely because it is generated from the code — it can never fall out of sync with the actual method signatures and types the way hand-written prose would.

• The concepts live in these docs. The what and why — what a token is, how the two-call protocol works, how an access check reaches a verdict, the RSI source model — are identical whether you call from C or Rust, and they are documented once, here. The safe crate mirrors the concept headers, so each learn section maps to a module:

  Rust module	Concepts in
  security, token, access, file, process	Access control
  registry	The registry
  event, msgpack	Events

  Read the concept page for the model, then the rustdoc for the exact Rust API.

Adding the dependency #

Add the peios crate to your Cargo.toml:

[dependencies]
peios = { git = "https://github.com/peios/peios-rs" }

(or a path/registry dependency, however you consume Peios crates). The features:

A first taste #

The safe crate turns the C conventions into ordinary Rust. Compare this with the C first program — no size probes, no manual close, errors as Result:

use peios::token::{Token, TokenAccess};

fn main() -> peios::Result<()> {
    // Open my own token; the handle closes on drop.
    let me = Token::open_self(false, TokenAccess::QUERY)?;

    let sid = me.user()?;          // owned Sid, not a caller buffer + length
    let il  = me.integrity()?;     // typed IntegrityLevel, not a raw u32
    println!("running as {sid} at integrity {il:?}");

    Ok(())
}

The idiomatic wins show up most in the fiddly places. Impersonation, for instance, is an RAII guard — identity reverts when the guard drops, so it is exception-safe by construction rather than needing a manual revert in every cleanup path:

use std::os::fd::BorrowedFd;

fn serve(conn: BorrowedFd<'_>) -> peios::Result<()> {
    let caller = Token::open_peer(conn)?;
    let _guard = caller.impersonate_scoped()?;   // now acting as the caller
    do_work_as_caller()?;                        // any early return still reverts
    Ok(())
    // `_guard` drops here (or on the `?` above) → identity reverts automatically
}

Success-side status values — a file's opened-vs-created disposition, a key's created-new-vs-opened — come back alongside the handle, not as errors; genuine failures are the Err(Error) side, where Error wraps the errno the C ABI set.

Linking: dynamic vs static #

This is the one Rust-specific wrinkle worth understanding, because the static path has a sharp edge.

• Dynamic (default) links libpeios.so — the production model, and the path a normal std Rust program must use.
• Static (--features static) links libpeios.a. That archive is a Rust staticlib: it bakes in its own copy of the Rust runtime (the panic = "abort" handler, the global-allocator shim, the alloc-error handler). Linking it into a consumer that also carries that runtime — i.e. any Rust binary that links std — collides on those symbols (rust_begin_unwind, __rust_alloc_error_handler, …). So the static path is for C consumers and no_std Rust binaries that supply no conflicting runtime. A std Rust consumer — including cargo test — must use the dynamic path.

Keep that rule in mind and static linking is a non-issue: reach for it only from no_std, and use the default dynamic link everywhere else.

Finding libpeios at build time #

peios-sys's build script resolves the library and headers in this order:

1. Environment override — set all three:
   • PEIOS_LIB_DIR — the directory containing libpeios.{so,a}
   • PEIOS_INCLUDE — the directory containing <peios.h>
   • PKM_UAPI — the directory containing <pkm/*.h> (referenced by peios.h's signatures)
2. pkg-config — otherwise, if libpeios installs its peios.pc on PKG_CONFIG_PATH. The build requires the minimum libpeios version declared in peios-sys/Cargo.toml under package.metadata.libpeios.minimum-version. If the installed SDK is older, the build stops before generating bindings and reports the required and detected versions, instead of failing later with a missing Rust binding. A missing SDK reports the required version and setup guidance too. This applies to both dynamic and static linking.

The explicit environment override bypasses pkg-config, including its version check. It remains useful for uninstalled development builds: you are responsible for selecting compatible libpeios headers and a matching library at or above the crate's declared minimum. The shipping headers do not expose a version macro, so the build script cannot verify a version for this path.

On a system where libpeios is installed from its packages, pkg-config just works and you set nothing. For a local checkout, point the three variables at your build tree:

PEIOS_LIB_DIR=../libpeios/target/release \
PEIOS_INCLUDE=../libpeios/include \
PKM_UAPI=../pkm/uapi \
cargo build

One bring-up gotcha for local dynamic builds: the crate bakes an rpath that resolves libpeios by its soname (libpeios.so.0), but a plain cargo build of libpeios emits only the unversioned libpeios.so. Create the soname link once so the run resolves:

ln -sf libpeios.so ../libpeios/target/release/libpeios.so.0

(This is a checkout convenience — on a real system the packaged libpeios.so.0 is already there.)

Privilege names #

peios::security::Privileges exposes the published kernel privileges, including TAKE_OWNERSHIP, SYSTEM_PROFILE and RELABEL. Their canonical names are SeTakeOwnershipPrivilege, SeSystemProfilePrivilege and SeRelabelPrivilege. Use parse_name for a canonical name and canonical_names to enumerate a mask in bit order. Names are case-sensitive; an unknown name returns None.

The values come from the kernel ABI constants. Naming a privilege does not grant it: the token must hold it and the operation's privilege rules still apply. The retired SeBindPrivilegedPortPrivilege is not accepted.

For checkout builds, use the versioned pkm/uapi source headers rather than an old out/build/headers installation. With the uapi feature, peios-sys pins the same peios-uapi revision as libpeios.

The bottom line #

• Depend on the peios crate; drop to peios-sys only for the raw surface.
• Concepts: these docs. API reference: cargo doc -p peios --open.
• Use the default dynamic link unless you are no_std.

Everything the library conventions page teaches still holds underneath — the crate just wraps it in Rust idiom.

KACS — the Kernel Access Control Subsystem — is the heart of Peios's security model, and it is the part of the SDK you are most likely to reach for. This section is a tour: it explains how the pieces fit together and points you at the right guide (and the right reference page) for each task. If you have not yet read the library conventions, read those first — everything here assumes the error and buffer rules they describe.

The four nouns #

Almost everything in KACS is built from four things:

The relationship is simple to state: an access check asks whether a token (the subject) is granted some access to an object protected by a security descriptor, and both the token and the SD are expressed in terms of SIDs.

The shape of a decision #

When you need to make an authorisation decision in your own code, the pattern is almost always the same three steps:

1. Get the subject's token. Usually the caller's — often via peios_token_open_peer on a socket, so you learn who connected — or your own effective token (token_fd = -1).
2. Get the object's security descriptor. You either hold it already, read it off a file with peios_file_get_sd, or build one with a peios_sd_builder.
3. Run the check. peios_access_check tells you whether the desired rights are granted, and exactly which subset was granted.

The checking access guide walks that end to end.

Advisory versus enforced #

There is one distinction worth internalising early. The SDK's access check is advisory: it computes what the answer would be. It does not enforce anything — enforcement of a real operation (opening a file, adjusting a token) happens inside the kernel against the subject's own process security block.

So you use peios_access_check when your code is the resource manager: you own some object — a record in your database, a slot in your service — that isn't a kernel object, and you want to make the grant/deny decision using Peios identities and the same rules the kernel would apply. For actual kernel objects (files, tokens, registry keys), you don't pre-check and then act; you just act, and the kernel enforces, returning EACCES if denied.

Identity is not always your identity #

A recurring theme in KACS is acting as someone other than yourself:

• Impersonation lets a service temporarily adopt a caller's identity so its access checks run as them — the way a server does work "on behalf of" a client without running as root and hand-rolling permission logic. See working with tokens.
• Restricted tokens let you drop power — derive a strictly less-privileged token to hand to less-trusted code.
• Integrity levels and confinement bound what a token can touch regardless of its SIDs.

These are what make KACS more than POSIX uid/gid, and the token module is where you reach for them.

Where to go in this section #

• Working with tokens — who am I, who is calling me, and how to act as someone else.
• Checking access — building a security descriptor and making a decision end to end.
• Securing files — the native open and reading/writing file security descriptors.
• Hardening a process — turning on process mitigations.

For the exhaustive per-function detail behind any of these, the reference section documents every symbol.

A token is the runtime carrier of an identity, and it is a file descriptor. This guide covers the everyday token tasks; token.h is the exhaustive reference for every call and field.

Who am I? #

To inspect your own identity, open your effective token and query it:

int tok = peios_token_open_self(0, KACS_TOKEN_QUERY);
if (tok < 0) { /* errno */ }

unsigned char sid[PEIOS_SID_MAX_BYTES];
ssize_t n = peios_token_user(tok, sid, sizeof sid);   /* the user SID */

uint32_t il;
peios_token_integrity(tok, &il);                      /* integrity level RID */

struct peios_privilege_set privs;
peios_token_privileges(tok, &privs);                  /* held/enabled privileges */

close(tok);

peios_token_open_self gives you the effective token — if your thread is impersonating, that's the impersonated identity. Pass KACS_TOKEN_OPEN_REAL in the flags to get your process's real primary token regardless. The access argument is the handle rights you want; KACS_TOKEN_QUERY is enough to read.

Group SIDs and other list-valued classes come back as buffers you parse with the security.h views: read CLASS_GROUPS with peios_token_query, then peios_sid_array_parse it.

Who is calling me? #

The most useful token trick in a service is learning the identity of whoever connected to your socket. When a client connects over a Unix stream or seqpacket socket, KACS captures their token at connect() time, and you open it from the accepted connection:

int conn = accept(listener, NULL, NULL);
int caller = peios_token_open_peer(conn);   /* QUERY | IMPERSONATE rights */
if (caller < 0) { /* errno */ }

/* Now query the caller's identity, or impersonate them (below). */

This is local authentication with no passwords and no handshake — the kernel vouches for who is on the other end. The handle comes with fixed QUERY | IMPERSONATE | DUPLICATE rights — enough to inspect the caller, act as them, and (for a process launched on their behalf) turn the identity into a primary token, but never to adjust it.

It works in the other direction too: right after connect(), peios_token_open_peer(sock) on the client's socket returns the identity of whoever is listening (at Identification level — enough to check, not to act as), so a client can verify it reached the genuine service and not something else that bound the path.

Acting as the caller #

Once you hold a caller's (impersonation) token, you can impersonate them: adopt their identity on your current thread so every subsequent access check runs as them, not as your service. This is how you do work on a client's behalf without running privileged and re-implementing their permissions.

if (peios_token_impersonate(caller) != 0) { /* errno */ }

/* ... do the work here: file opens, access checks, etc. all run as the caller ... */

peios_token_revert();   /* back to your own identity */
close(caller);

Always pair peios_token_impersonate with peios_token_revert, ideally in the cleanup path, so a failure partway through can't leave your thread wearing someone else's identity. peios_token_revert is a safe no-op if you weren't impersonating.

The full flow for a request handler is: accept → peios_token_open_peer → peios_token_impersonate → serve the request → peios_token_revert → close. When the handler runs start to finish on one thread and has no other use for the token, peios_token_impersonate_peer(conn) collapses the open, impersonate and close into one call.

A client decides how far its identity travels: peios_socket_set_impersonation_level(sock, KACS_IMLEVEL_IDENTIFICATION) lets the server learn who it is without being able to act as it. And a client that writes on behalf of many identities over one connection — a service impersonating its callers through a connection pool — turns on peios_socket_set_pass_token(sock, true), after which every send carries whoever is impersonating at that moment and the server's peios_token_open_peer tracks it request by request.

Handing an identity to a manager #

Impersonation acts as someone on your thread. The other shape is handing an identity to another process so it can act — the pattern behind the Peinit jobs socket (PSPU §7): a submitter such as backupd holds a token for the user whose data it is backing up, and wants Peinit to run the backup job as that user, not as backupd. Nothing is impersonated; the token itself is attached to the request, and the kernel vouches that the sender could have acted as it.

int jobs = socket(AF_UNIX, SOCK_SEQPACKET | SOCK_CLOEXEC, 0);
connect(jobs, ...);                                   /* who may submit is who may connect */

const char *req = "{\"command\":\"submit\",\"image_path\":\"/usr/bin/backup\"}";
if (peios_socket_send_message(jobs, req, strlen(req), user_token, NULL, 0, 0) < 0) {
    /* EACCES: user_token lacks TOKEN_IMPERSONATE; EPERM: the attach would lower its level */
}

Three things make this safe, and none of them is the manager's to get wrong:

• The kernel gates the attach like an impersonation. You need TOKEN_IMPERSONATE on the handle, and the token arrives at the sending socket's impersonation level — so a token the sender could only identify, never act as, cannot be smuggled through. Peinit refuses anything below Impersonation. For a job that must reach remote systems as the user, set the socket to Delegation first: peios_socket_set_impersonation_level(jobs, KACS_IMLEVEL_DELEGATION) — and the attach then only succeeds if the token itself is at Delegation, since the level only ratchets down.
• The receiver owns what it is handed. peios_socket_recv_message gives the manager a token handle with QUERY | IMPERSONATE | DUPLICATE — enough to inspect the identity, check its level with peios_token_impersonation_level, and duplicate it into a primary token for the new process, but never to adjust it.
• No token means the sender's own. A request that attaches nothing is run as the connecting process's primary token: the manager opens it through peios_socket_peer_pidfd and peios_token_open_process — the kernel's handle on the peer, never a PID the peer named — which is fork-like and needs no privilege on the submitter's part.

Descriptors travel the same way: pass a socket for the job to serve on, or a pipe to receive its output, as SCM_RIGHTS on the same message. The full protocol — what the manager does with them and how the job is managed afterwards — is PSPU §7; the calls are in the reference.

From Rust the same pattern is peios::socket::send_message / recv_message, with the received Token and OwnedFds owned by the ReceivedMessage, and peios::socket::peer_pidfd for the fallback:

use std::os::fd::AsFd;
use peios::socket;
use peios::token::{ImpersonationLevel, Token, TokenAccess};

socket::send_message(jobs.as_fd(), request, Some(user_token.as_fd()), &[], 0)?;

// The manager's side. Every descriptor that arrived is owned by `msg`.
let msg = socket::recv_message(conn.as_fd(), &mut buf, 8, 0)?;
if msg.truncated || msg.control_truncated {
    return Err(refused());
}
let identity = match msg.token {
    Some(token) if token.impersonation_level()? >= ImpersonationLevel::Impersonation => token,
    Some(_) => return Err(refused()),   // below Impersonation
    None => {
        let pidfd = socket::peer_pidfd(conn.as_fd())?;
        Token::open_process(pidfd.as_fd(), TokenAccess::QUERY | TokenAccess::DUPLICATE)?
    }
};

Dropping power #

To run less-trusted code with less authority than you hold, derive a restricted token and hand it over. peios_token_restrict can delete privileges, demote groups to deny-only, and add restricting SIDs:

struct peios_token_restrict spec = {
    .privs_to_delete = KACS_SE_DEBUG_PRIVILEGE | KACS_SE_IMPERSONATE_PRIVILEGE,
    .flags           = KACS_TOKEN_RESTRICT_WRITE_RESTRICTED,
};
int weak = peios_token_restrict(my_primary, &spec);

The result is a strictly less-powerful token. Combined with integrity levels and confinement (both set when minting a token), this is the basis of sandboxing on Peios.

Minting tokens #

Creating a token from scratch requires SeCreateTokenPrivilege and is the province of authentication authorities, not ordinary programs. When you do need it, the token-spec builder is the ergonomic path — typed setters for the user SID, groups, privileges, integrity, claims, and the rest, then peios_token_builder_create. Mind the index convention for owner/primary-group references, and don't add the logon SID yourself — the kernel injects it.

Next #

• Checking access — use a token to make an authorisation decision.
• token.h reference — every token call in full.
• Impersonation — the operator-side model and its two gates.

This guide walks a complete access decision: you have an object to protect, a caller to check, and you want KACS to tell you what they're allowed. The exhaustive detail lives in access.h and security.h; here we put them together.

When to use this #

Reach for peios_access_check when your program is the resource manager — you own something that isn't a kernel object (a document, an API route, a record) and you want to gate it with Peios identities and rules. For actual kernel objects, don't pre-check; just perform the operation and let the kernel enforce.

Remember the check is advisory: it computes the answer, you enforce it.

Step 1 — describe what protects the object #

An object is protected by a security descriptor. If you don't already have one, build it. Say the resource should be readable and writable by its owner and read-only for a "viewers" group:

/* An ACL: allow OWNER full, allow VIEWERS read. */
peios_acl_builder *acl = peios_acl_builder_new();
peios_acl_builder_allow(acl, owner_sid, owner_len, KACS_ACCESS_ALL, 0);
peios_acl_builder_allow(acl, viewers_sid, viewers_len, KACS_ACCESS_READ, 0);

size_t acl_len;
const void *acl_bytes = peios_acl_builder_bytes(acl, &acl_len);

/* Wrap it in a security descriptor with an owner. */
peios_sd_builder *sd = peios_sd_builder_new();
peios_sd_builder_owner(sd, owner_sid, owner_len);
peios_sd_builder_dacl(sd, acl_bytes, acl_len);

size_t sd_len;
const void *sd_bytes = peios_sd_builder_bytes(sd, &sd_len);

(You can also write the descriptor as SDDL text and parse it — often easier when the policy is fixed.)

Step 2 — identify the subject #

The subject is a token. Most often it's the caller you opened from a socket, or your own effective token. In the request you pass either a token fd or -1 for your own effective token.

Step 3 — run the check #

Fill in a request and call. desired is what you're testing; mapping folds any generic rights to the object class's specific bits (use the class's published mapping — here we'll treat the object like a file):

struct peios_access_request req = {
    .token_fd = caller_fd,               /* or -1 for my own token */
    .sd       = sd_bytes, .sd_len = sd_len,
    .desired  = KACS_ACCESS_READ | KACS_ACCESS_WRITE,
    .mapping  = peios_file_generic_mapping,
};

uint32_t granted = 0;
int rc = peios_access_check(&req, &granted, NULL);

Step 4 — interpret the result #

if (rc == 0) {
    /* Every desired right was granted. */
} else if (errno == EACCES) {
    /* Denied. `granted` still holds what WAS allowed — e.g. maybe READ
       succeeded but WRITE did not. Decide per-right from `granted`. */
    bool may_read  = granted & KACS_ACCESS_READ;
    bool may_write = granted & KACS_ACCESS_WRITE;
} else {
    /* A real error: bad token fd, malformed SD, etc. */
    perror("access_check");
}

The key idea: a denial is not an error to log and bail on — it's the expected "no". And because granted is filled even on denial, you can ask for a broad set of rights in one call and read back exactly which subset the subject has, rather than probing right by right. Clean up the builders (peios_acl_builder_free, peios_sd_builder_free) and the token fd when done.

Per-property checks #

If your object has properties or property-sets with their own object ACEs, evaluate the whole tree in one call with peios_access_check_list: supply an object-type tree and get one result per node, so you learn (for instance) that a caller may read most of an object but not one protected field — without a separate check per field.

Auditing a decision #

Pass a non-NULL peios_access_audit to learn what a SYSTEM_AUDIT ACE match would log, and whether a staged central access policy would decide differently — the signal you watch when rolling out a policy change.

If your daemon guards objects of its own, name the object in the request's audit context, so the kernel's audit record of the decision says what was checked:

struct peios_audit_field name = {
    .key = "name", .value_type = PEIOS_AUDIT_STR,
    .bytes = "jellyfin", .len = strlen("jellyfin"),
};
uint8_t ctx[128];
ssize_t n = peios_audit_context_encode("service", &name, 1, ctx, sizeof ctx);
req.audit_context = ctx;
req.audit_context_len = (size_t)n;   /* check n >= 0 first */

Do not write an event of your own recording the grant or the refusal. The kernel's record is the audit record, and a SACL on the object decides whether it is written (PGSS §6.7).

Next #

• access.h reference — every field of the request and the audit outputs.
• Access decisions — the operator-side account of how KACS reaches a verdict (and how to debug a surprising denial).

Peios files carry real security descriptors, and the SDK opens them with a native KACS open rather than POSIX open(). This guide covers the two everyday tasks: opening a file with a specific access, and reading or changing a file's security. The full surface is in file.h.

To keep the fragments readable, most error checks are elided here — every call below returns -1 with errno on failure, and real code must check each one (see Library conventions).

The native open #

peios_file_open is shaped like NtCreateFile: you state the access you want, what to do about existence (the disposition), any create options, and — when creating — the security descriptor to stamp on the new file. It returns an ordinary Linux fd whose granted access is fixed for the fd's lifetime, which means you can safely hand it to another process by SCM_RIGHTS, dup, or across exec: the fd carries exactly the access it was opened with.

Create a new file, readable and writable, with a creator SD. An existing path is an error:

struct peios_open_params p = {
    .desired_access = KACS_FILE_READ_DATA | KACS_FILE_WRITE_DATA,
    .disposition    = KACS_DISPOSITION_CREATE,    /* fail if the path exists */
    .sd             = creator_sd, .sd_len = creator_sd_len,
};

uint32_t status = 0;
int fd = peios_file_open(AT_FDCWD, "state.db", &p, &status);
if (fd < 0) { perror("open"); return -1; }

/* On success, status == KACS_STATUS_CREATED. */

To open an existing file, use KACS_DISPOSITION_OPEN with sd = NULL and sd_len = 0. If the create-only call returns EEXIST, decide whether accepting the existing object is appropriate before making that separate open call. The two calls are not an atomic create-or-open transaction; checking stat first does not remove the race either.

If parent inheritance is appropriate for a newly created file, OPEN_IF with sd = NULL and sd_len = 0 can report created versus opened in status_out without a separate stat. Only DIRECTORY and DELETE_ON_CLOSE create-option bits are accepted by the pinned kernel; put no-follow in flags. See the opening reference for the SDK fields.

Reading a file's security descriptor #

To see who can do what to a file, read its SD. secinfo selects which components you want — owner, group, DACL, SACL — so you fetch only what you need:

/* Probe, allocate, read (two-call). */
ssize_t need = peios_file_get_sd(AT_FDCWD, "state.db",
                                 KACS_SECINFO_OWNER | KACS_SECINFO_DACL,
                                 NULL, 0, 0);
void *sd = malloc(need);
peios_file_get_sd(AT_FDCWD, "state.db",
                  KACS_SECINFO_OWNER | KACS_SECINFO_DACL, sd, need, 0);

/* Parse it with a security.h view. */
peios_sd_view v;
peios_sd_parse(sd, need, &v);
peios_acl_view dacl;
if (peios_sd_view_dacl(&v, &dacl) == 0) {
    unsigned n = peios_acl_view_count(&dacl);
    /* iterate ACEs … */
}
free(sd);

If you already hold a file fd, use the fd-targeted peios_fd_get_sd instead of a path — no second path resolution, and for a normal file fd the check uses the access already baked in at open.

Changing a file's security descriptor #

Writing an SD is component-selective too: name the components you're changing in secinfo, and everything you don't name is preserved. To tighten a file's DACL without touching its owner or SACL:

/* Build an SD carrying only a DACL. */
peios_sd_builder *b = peios_sd_builder_new();
peios_sd_builder_dacl(b, new_acl, new_acl_len);
size_t sd_len; const void *sd_bytes = peios_sd_builder_bytes(b, &sd_len);

peios_file_set_sd(AT_FDCWD, "state.db", KACS_SECINFO_DACL, sd_bytes, sd_len, 0);
peios_sd_builder_free(b);

Because only KACS_SECINFO_DACL is selected, the owner, group, and SACL are left exactly as they were. The security.h builders are how you assemble the SD to apply.

Raw file-security interface #

The SDK helpers above wrap kacs_get_sd and kacs_set_sd. The following low-level details belong to programs implementing descriptor tools; shell users should use Managing file security. The generated KACS ABI is the source for syscall numbers and KACS_SECINFO_* constants; the *_SECURITY_INFORMATION names below are their specification spellings.

Raw access to security.peios.sd or system.ntfs_security is denied for reads, writes and removal. In particular, a raw read would expose the SACL without the component-specific ACCESS_SYSTEM_SECURITY gate. The syscall pair unifies access rules, validates descriptors and abstracts filesystem storage; see File Descriptor Storage.

kacs_get_sd #

The read syscall:

size = kacs_get_sd(dirfd, path, security_info, buf, buf_len, flags)

Returns the SD bytes for the requested components.

The kernel:

1. Resolves the path.
2. Checks the access rights corresponding to the requested components (covered below). Paths and O_PATH handles use a live AccessCheck; ordinary file descriptors use their cached granted mask.
3. Reads the file's SD from its filesystem-native storage.
4. Constructs a subset SD containing only the requested components. Other components have offset 0 in the header and the corresponding PRESENT bit is clear.
5. Returns the subset SD in buf, with the total length as the return value.

Probe mode #

Calling with buf_len = 0 and buf = NULL is a probe — the kernel computes the size the SD would take and returns it without writing to the buffer. The probe returns the same size value that a non-probe call would; the caller can use this size to allocate exactly the right buffer.

The probe call always returns the size on success. It does not return -ERANGE — the probe is itself a question about size, and answering it is the kernel's job. -ERANGE would be the wrong signal for a deliberate probe.

A non-probe call with buf_len < required fails with -ERANGE without truncating the result. Probe again, allocate and retry; the size can change between calls. Do not assume an out-parameter receives the required size: this signature has none. The SDK two-call protocol describes the wrapper convention.

Access rules #

Different components need different rights:

(The numeric flag values are catalogued in Other constants.)

READ_CONTROL is the standard "read SD" right. Its implicit grant to the owner is subject to OWNER RIGHTS and the other access layers. ACCESS_SYSTEM_SECURITY is gated by SeSecurityPrivilege; an administrator label alone is not sufficient.

A caller asking for components they do not have rights for gets -EACCES. The component check is all-or-nothing: if any requested component fails its access check, the whole call fails rather than returning the permitted subset.

For combining requested components: just OR the flags. kacs_get_sd(..., OWNER | DACL, ...) returns owner and DACL but not SACL or group.

SACL and LABEL are mutually exclusive #

SACL_SECURITY_INFORMATION and LABEL_SECURITY_INFORMATION cannot be combined in one call. Setting both flags returns -EINVAL. The reasoning: LABEL_SECURITY_INFORMATION is a focused query for just the integrity label (which lives in the SACL); it has different access requirements than reading the full SACL. The kernel keeps the two paths separate.

kacs_set_sd #

The write syscall:

result = kacs_set_sd(dirfd, path, security_info, sd_buf, sd_len, flags)

The kernel:

1. Resolves the path.
2. Parses the SD blob. Rejects malformed SDs (size limit, bad ACL structure, etc.) with -EINVAL.
3. Checks the required rights per the components being updated, using a live AccessCheck for a path or O_PATH handle and the cached granted mask for an ordinary file descriptor.
4. Validates additional rules — owner SID is the caller's own or a SE_GROUP_OWNER group (unless SeRestorePrivilege), MANDATORY-flagged resource attributes are not removed (unless SeTcbPrivilege), integrity label is not raised above caller's own (unless SeRelabelPrivilege).
5. Writes the SD to the file's native storage.
6. Returns 0 on success.

Validation and component-right checks must succeed before the selected components are merged; unselected components are preserved. This is not a concurrent-update transaction. The Kernel TRM storage rules describe a last-writer-wins window: the xattr write and cache publication are not atomic with each other, although readers do not see a partially written descriptor. Coordinate writers rather than treating a read/edit/write sequence as compare-and-swap.

Access rules for writes #

WRITE_DAC is the standard "modify DACL" right; the owner implicit grant is subject to OWNER RIGHTS suppression and the other access layers. WRITE_OWNER is needed to change the owner field (and the validation rules apply per Ownership). ACCESS_SYSTEM_SECURITY is the SACL gate.

The integrity label #

LABEL_SECURITY_INFORMATION (0x10) is the focused write path for setting just the integrity label. The label lives in the SACL as a SYSTEM_MANDATORY_LABEL_ACE, but setting it via this flag is treated as a separate operation from setting the full SACL — with different access requirements:

• The right needed is WRITE_OWNER, not ACCESS_SYSTEM_SECURITY.
• The caller cannot raise the integrity label above the calling token's own integrity level (without SeRelabelPrivilege).
• Lowering the integrity label to at or below the caller's own integrity level is allowed.

LABEL_SECURITY_INFORMATION and SACL_SECURITY_INFORMATION cannot be combined in one call — same rule as for reading.

The use case: a process that wants to lower its files' integrity labels without holding SeSecurityPrivilege. The label is in the SACL conceptually, but setting it gets the WRITE_OWNER gate rather than the SACL gate, because adjusting the label down is a less sensitive operation than rewriting the audit policy.

SD parsing and validation #

The provided SD blob must be:

• In self-relative format (SE_SELF_RELATIVE flag set in control bits).
• Within the 65,535-byte size limit.
• Internally consistent — the offsets in the header point to valid locations, the ACLs parse cleanly, the SIDs are well-formed.

Any failure of validation returns -EINVAL. The original SD on the file is unchanged.

Setting only some components #

The security_information flags tell the kernel which components of the provided SD to apply. A blob containing owner + DACL with only DACL_SECURITY_INFORMATION set updates only the DACL; the file's existing owner is preserved.

The blob structure must still be valid — components not being applied are typically absent (offset 0, PRESENT bit clear) in the blob, but the blob's header still needs to be a valid SD header. After the merge, the resulting descriptor must retain a non-null owner; its group may be null.

This is the pattern for updating one part of an SD without touching the others. Read the SD (probe + fetch), update the relevant component, write back with only that component's flag set.

Ownership transfer rules #

Setting the owner via kacs_set_sd triggers the rules described in Ownership:

• The new owner must be the caller's own user_sid, or a SID in the caller's groups with SE_GROUP_OWNER set, or the caller must hold SeRestorePrivilege.
• The operation must pass the WRITE_OWNER gate. SeTakeOwnershipPrivilege can supply that right through a live access check, subject to mandatory policy; possession does not bypass a cached fd mask or the new-owner SID restriction. See Ownership for availability and recovery limits.

A failed component-right check returns -EACCES; a failed owner-SID constraint without SeRestorePrivilege returns -EPERM.

The same rules apply whether you set ownership via OWNER_SECURITY_INFORMATION alone or in combination with other components.

File-security errors #

These are raw kernel error names; the SDK wrappers return -1 and set errno.

The Kernel TRM raw-call contract says AT_SYMLINK_NOFOLLOW on kacs_get_sd and kacs_set_sd selects the symlink object, unlike native open, which fails with ELOOP in that case. The flag descriptions above follow that kernel contract.

For live-check versus cached-fd restore behavior, mandatory SACL attributes and full-SACL label constraints, see The Set-Security Interface. A full SACL write replaces the entire SACL. A label-only write preserves non-label ACEs; its input is either no SACL, to remove the explicit label, or a SACL containing exactly one non-inherit-only mandatory-label ACE.

Pre-flighting an open #

Sometimes you want to know whether a caller could open a file before you actually do. Read the file's SD, then run an access check against the caller's token with peios_file_generic_mapping — no open, no side effects, just the verdict.

Next #

• file.h reference — every parameter, plus the fd-targeted calls and mount policy.
• File access — the operator-side model of native file security.

Peios lets a process opt into hardening — exploit mitigations enforced by the kernel on that process's security block. The SDK exposes this through a single call, peios_process_set_mitigations. This short guide covers using it well; the full flag set and semantics are in process.h and the operator docs.

Harden yourself at startup #

The common case is a program hardening itself early in main, before it processes any untrusted input:

#include <peios/process.h>

int main(void)
{
    /* Enforce W^X and speculation mitigation lock; abort on failure. */
    if (peios_process_set_mitigations(-1, KACS_MIT_WXP | KACS_MIT_SML) != 0) {
        perror("set_mitigations");
        return 1;   /* refuse to run unhardened */
    }
    /* ... the rest of the program runs with those protections on ... */
}

pidfd == -1 targets the calling process. mitigations is a mask of KACS_MIT_* bits (from <pkm/psb.h>); combine the ones you want and set them together.

Three things to know #

It's one-way. Mitigation bits can only be set, never cleared — once on, they stay on for the life of the process. That's the point: a mitigation you could turn off is one an attacker could turn off. Treat each call as a permanent commitment.

It's all-or-nothing, and fails closed. If any requested protection can't actually be activated, the call changes nothing and returns -1. You never end up believing a mitigation is on when it isn't. So request the set you require together and check the result once — success means the whole set is active. (Bits from earlier successful calls stay on regardless.)

Targeting another process is privileged. To harden a process other than your own, you need PROCESS_SET_INFORMATION on it and PIP dominance over it — you can't reach into a process you don't already dominate. For self-hardening (-1), neither is needed.

Choosing what to enable #

The bit catalogue and what each mitigation defends against is documented operator-side under process mitigations (and in the Peios Kernel TRM §3.3, the Process Security Block). A couple of notes for the SDK caller:

• KACS_MIT_ALL is the mask of all valid bits — useful for validating input, not usually what you'd blanket-enable without thought.
• KACS_MIT_CFI is a legacy alias that expands to KACS_MIT_CFIF | KACS_MIT_CFIB.

Enable the specific protections your program can tolerate, verify the call succeeded, and prefer to do it before you touch untrusted data.

Next #

• process.h reference — the call in full.
• Process mitigations — every mitigation and its threat model.

LCS — the Layered Configuration Subsystem — is Peios's registry: a kernel-mediated, hierarchical, secured configuration store. If you have used the Windows registry it will feel familiar — a tree of keys holding typed values — but LCS adds one defining idea: layers. This section teaches the client API; registry.h is the exhaustive reference.

Keys and values #

A key is a node in the tree. It has an immutable GUID identity, a KACS security descriptor that governs who can read or change it, and it holds values and child keys. You address a key by path and open it for specific KEY_* rights, getting back a key fd whose granted access is fixed for its lifetime.

A value is a named, typed piece of data on a key (REG_SZ, REG_DWORD, REG_BINARY, and the rest). An empty name is the key's default value.

Layers and precedence — the LCS idea #

Here is what makes LCS more than a key/value store. Every value write is tagged with a layer, and layers have a fixed precedence order. When you read a value, LCS resolves the effective entry — the one from the highest-precedence layer that has something to say — and that's what you get back.

This is what lets configuration compose cleanly:

• A base layer ships default configuration.
• A site or policy layer overlays organisation-wide settings.
• A machine-local layer overrides per-host.

They all coexist on the same key. Reading gives you the winner; writing targets a specific layer (or the base layer by default). And because it's layers rather than destructive overwrites, removing a higher layer's entry lets the lower one re-emerge — you can override and then un-override without losing the original.

Tombstones are the tool for "hide, don't delete": a per-value tombstone masks lower layers for one value, and a blanket tombstone masks all lower values of a key on a layer at once. Keys have the same idea via hide.

Reads report where the answer came from #

Because a value can come from any layer, the read tells you which layer won and gives you a sequence number for the effective entry. That sequence number is the basis of safe updates: pass it back as a compare-and-swap guard on a write, and the write only lands if nothing changed underneath you.

Transactions #

Mutating operations — creating keys, setting and deleting values — can be grouped into a transaction and committed atomically, so a multi-step configuration change either fully applies or not at all. Transactions are abort-by-default: close the transaction fd without committing and nothing happens. See watching and transactions.

Watches #

You can ask a key to notify you when it changes — values, subkeys, or its security — optionally across its whole subtree. The elegant part: once armed, the key fd itself becomes pollable, so a registry watch drops straight into an epoll loop with no side channel.

The client, not the source #

This SDK is the registry client — it reads and writes the store. It does not implement a registry source (a storage backend); that's a separate library, librsi. As a client you speak only the calls in registry.h.

Where to go in this section #

• Reading and writing — open a key, read effective values, write to layers, do safe updates.
• Watching and transactions — react to changes and apply atomic multi-step edits.
• registry.h reference — every call in full.

This guide covers the bread-and-butter registry operations. The full call signatures and error sets are in registry.h; here we string them together. Recall the registry's descriptor-struct buffer convention: reads fill *_cap/*_len fields and a zero-capacity buffer probes.

The fragments below elide some error checks for brevity — every call returns -1 with errno on failure, and real code must check each one (see Library conventions).

Opening a key #

Open a key for the rights you need:

int key = peios_reg_open_key(-1, "/System/MyApp", KEY_READ, 0);
if (key < 0) {
    if (errno == ENOENT) { /* not there */ }
    else if (errno == EACCES) { /* not allowed */ }
    return -1;
}

parent_fd == -1 means path is absolute. To open relative to a key you already hold, pass that key fd as the parent. Use peios_reg_create_key instead when the key might not exist yet — it opens-or-creates and reports which happened.

Reading the effective value #

Reading resolves layer precedence for you and hands back the winning value, its type, and which layer it came from:

struct peios_reg_value v = {0};
unsigned char data[256];
v.data = data;  v.data_cap = sizeof data;
/* leave v.layer NULL if you don't care which layer won */

if (peios_reg_query_value(key, "Timeout", 7, -1, &v) == 0) {
    /* v.type is REG_*, v.data_len bytes valid in `data`, v.sequence is
       the effective entry's sequence number. */
} else if (errno == ENOENT) {
    /* no effective value (or a tombstone masks it) */
} else if (errno == ERANGE) {
    /* data buffer too small; v.data_len holds the required size — grow & retry */
}

The name_len is explicit (value names are length-counted; 0 reads the key's default value). Pass a transaction fd as the fourth argument to read within a transaction, or -1 for none.

To read every value at once, use peios_reg_query_values_batch — one call fills a buffer with all effective values in a packed record format. To walk them one at a time, loop peios_reg_enum_value from index 0 until ENOENT.

Writing a value #

Writes target a specific layer. Pass NULL/0 for the layer to write the base layer:

uint32_t timeout = 30;
int rc = peios_reg_set_value(key, "Timeout", 7, REG_DWORD,
                             &timeout, sizeof timeout,
                             NULL, 0,      /* base layer */
                             -1,           /* auto-commit (no transaction) */
                             0);           /* no CAS guard */

Writing to a higher-precedence layer overrides lower ones without destroying them; deleting that layer's entry later lets the lower value re-emerge.

Safe updates with compare-and-swap #

To read-modify-write without clobbering a concurrent change, feed the sequence you read back as the expected_seq guard on the write. The write only lands if nothing changed underneath you; otherwise it fails with EAGAIN and you retry:

for (;;) {
    struct peios_reg_value v = {0};
    unsigned char buf[64]; v.data = buf; v.data_cap = sizeof buf;
    if (peios_reg_query_value(key, "Counter", 7, -1, &v) != 0)
        break;                                     /* real error — don't spin */

    uint32_t n; memcpy(&n, buf, sizeof n); n++;

    int rc = peios_reg_set_value(key, "Counter", 7, REG_DWORD,
                                 &n, sizeof n, NULL, 0, -1,
                                 v.sequence);          /* CAS on the sequence */
    if (rc == 0) break;                                /* success */
    if (errno != EAGAIN) { /* real error */ break; }   /* else: retry */
}

Passing expected_seq == 0 disables the guard (an unconditional write).

Cleaning up #

Close key fds with close() when done. Values you wrote with auto-commit (txn_fd == -1) are already durable to the layer; to force the source to persist a hive's pending writes at a known point, call peios_reg_flush.

Next #

• Watching and transactions — react to changes and batch atomic edits.
• registry.h reference — every call, field, and error.

Beyond simple reads and writes, LCS gives you two higher-order tools: watches to react to change, and transactions to apply several edits atomically. Both are in registry.h; this guide shows the shape of using them. To keep that shape visible, the fragments elide most error checks — every call returns -1 with errno on failure, and real code must check each one (see Library conventions).

Watching for changes #

Ask a key to notify you when it changes, then poll its fd. Because the armed key fd is itself pollable, a watch integrates directly into whatever event loop you already run:

int key = peios_reg_open_key(-1, "/System/MyApp", KEY_READ | KEY_NOTIFY, 0);

/* Watch values and subkeys, across the whole subtree. */
peios_reg_notify(key, REG_NOTIFY_VALUE | REG_NOTIFY_SUBKEY, 1 /* subtree */);

struct pollfd pfd = { .fd = key, .events = POLLIN };
for (;;) {
    poll(&pfd, 1, -1);
    if (pfd.revents & POLLIN) {
        /* read() the key fd to drain the change records, then re-read
           whatever you care about. */
        char records[512];
        ssize_t n = read(key, records, sizeof records);
        /* ... process change records ... */
    }
}

filter is a mask of REG_NOTIFY_VALUE, REG_NOTIFY_SUBKEY, and REG_NOTIFY_SD; REG_NOTIFY_ALL covers all three. The subtree flag extends the watch to descendants. Arming needs KEY_NOTIFY on the key. Call peios_reg_notify(key, 0, 0) to disarm.

Each read() drains as many complete change records as fit — every record starts [total_len: u32][event_type: u16][name_len: u16][name], so you step through the buffer by total_len. The full layout, the REG_WATCH_* event types, and the extra path fields a subtree watch appends are in the reference. Two practical notes: a buffer too small for even one record fails EINVAL, so size it generously rather than exactly; and a REG_WATCH_OVERFLOW record means events were dropped — re-read the key's state instead of trusting the stream.

This is how a service picks up configuration changes live — no polling loop re-reading values on a timer, just a blocking poll that wakes when something actually changed.

Transactions #

When a configuration change spans several operations — create a key, set a few values, delete a stale one — you usually want it to be all-or-nothing. That's a transaction.

Begin one, pass its fd as the txn_fd argument to each operation you want enlisted, then commit:

int txn = peios_reg_begin_transaction();

int key = peios_reg_create_key(-1, "/System/MyApp/v2", KEY_WRITE, 0,
                               NULL /* base layer */, txn, NULL);
uint32_t one = 1;
peios_reg_set_value(key, "Enabled", 7, REG_DWORD, &one, sizeof one,
                    NULL, 0, txn, 0);
peios_reg_delete_value(key, "LegacyFlag", 10, NULL, 0, txn);

int rc = peios_reg_commit(txn);
if (rc == 0) {
    /* everything applied atomically; txn is terminal — close it */
} else if (errno == EBUSY || errno == EIO) {
    /* transient: the transaction is still active — retry the commit */
}
close(txn);
close(key);

Two things to keep in mind:

• Abort is the default. If you close the transaction fd without committing — including on any early-return error path — nothing is applied. So you don't need explicit rollback logic; just don't commit.
• Commit can be retried. EBUSY (write-lock contention) and EIO (source failure) leave the transaction active, so you can retry peios_reg_commit. Only 0 (committed — the fd is now terminal) and EINVAL (already committed or never bound) are final. Check state at any point with peios_reg_txn_status.

Backup and restore #

To snapshot a key and its whole subtree, or replace one from a snapshot, use peios_reg_backup and peios_reg_restore. They stream to and from an fd and are gated by SeBackupPrivilege / SeRestorePrivilege; restore applies in a single transaction.

Next #

• registry.h reference — the notify filters, transaction states, and every error in full.
• Reading and writing — the value operations you enlist in a transaction.

KMES is Peios's event system, and it is the sole event path on the system. Audit records, subsystem events, and your own application events all travel the same way: the kernel stamps each event with trusted metadata and writes it into a per-CPU, lock-free ring buffer, and consumers drain those rings. This section teaches both sides — producing and consuming — via event.h and msgpack.h.

What an event is #

An event has two parts:

1. Kernel-stamped metadata you cannot forge — a CLOCK_REALTIME timestamp, a per-CPU monotonic sequence number, the CPU id, an origin class, and identity GUIDs (the effective token, the true token, and the process). This is the trustworthy skeleton: when you consume an event, you know who emitted it and when, because the kernel wrote that, not the emitter.
2. A payload — a single MessagePack value that you define. This is your event's actual content.

The event type names the kind of event. It's a dotted name made of your package name, what the event is about, and what happened, such as org.example.backup.snapshot.created. Its fields follow one vocabulary shared by every emitter on the system. Naming and shaping your events shows how to choose both.

Payloads are MessagePack, and you own them #

The kernel does not build or interpret payloads — it only structurally validates them on emit (one well-formed MessagePack value, within size and nesting limits). So userspace owns encoding and decoding, and the SDK ships a MessagePack codec whose validator's acceptance is matched to the kernel's check. Build a payload with the writer, and a successful peios_mp_writer_bytes (or peios_mp_validate) means the emit call will accept it.

Per-CPU rings and lost events #

Events live in per-CPU ring buffers — one ring per logical CPU, lock-free so producers never block on consumers. Two consequences shape how you consume:

• You drain per CPU. To see everything, run a reader per CPU (discover the count by attaching upward from CPU 0 until it fails).
• Rings can lap. If you don't drain fast enough, new events overwrite old ones you haven't read. The per-CPU sequence numbers are contiguous, so a gap in the sequence means events were lost — and the reader tracks that count for you.

Privileges #

The two sides are gated separately:

• Emitting requires SeAuditPrivilege.
• Consuming (attaching to a ring) requires SeSecurityPrivilege.

Two ways to consume #

The SDK offers a high-level reader that hides the entire lock-free drain — barriers, lapping recovery, lost-event accounting, buffer-resize handling, and the wait — behind a simple next/wait loop. That's what almost everyone should use. There is also a low-level ring API for callers who need to drive the drain inside their own event loop. Both are covered in consuming events.

Where to go in this section #

• Naming and shaping your events — design an event before you emit it: its type, its fields, its tier and its catalogue entry.
• Emitting events — build a payload and emit, singly or in batches.
• Consuming events — drain the rings with the high-level reader (and, briefly, the low-level ring).
• event.h and msgpack.h — the exhaustive reference.

Every event on Peios follows one naming scheme and one field vocabulary, so that an operator can find your events with the same queries and security descriptors they use for everyone else's. This guide walks through designing one event, from deciding that it should be an event to describing it for the catalogue. The rules themselves are in PGSS Events; this page applies them.

The running example is a backup tool, packaged as org.example.backup, that writes a snapshot archive and wants to record each one.

Decide that it is an event #

Ask two questions, in order:

1. Does an operator care? If only the tool's developers would read it, write a log line instead.
2. Does one instance matter on its own? If it does, it's an event. If only the trend matters — snapshots per hour, bytes per day — it's a metric.

An operator wants to know that last night's snapshot failed, so each snapshot is an event. See Events, logs and tiers.

Name the event type #

An event type is your package name, then one or more nouns from general to specific, then a past-tense verb:

org.example.backup.snapshot.created

• The root is your package name, split at its dots. Short roots such as kacs and peinit are reserved to platform components.
• Add a noun only where someone would write a policy on the set beneath it. org.example.backup.snapshot groups everything about snapshots, which an administrator might plausibly switch off or grant access to as a whole.
• End with what happened, in the past tense: created, started, ended, deleted.
• Use one type for success and failure. A failed snapshot is still org.example.backup.snapshot.created, carrying outcome.success = false. Don't add a snapshot.failed type.
• Use lowercase and kebab-case within a segment: copied-up, never copied_up or copiedUp.

See Event types for the full grammar.

Choose the fields #

A field is named for the part it plays, then what it is, then which property:

Look a field up before you invent one. The standard fields cover almost everything an event carries: who acted (subject.*), what was acted on (object.*), where something came from or went to (source.* and destination.*), and how it turned out (outcome.*). Every defined field is described in /usr/share/evman/, and evman looks them up: evman object.file lists what is defined under object.file, and evman -k size searches.

A few things never go in your payload:

• Anything the header already carries. The kernel stamps the time, the sequence number and your token and process identities on every event. Don't write a timestamp.
• A principal's name. Carry its SID in subject.token.sid or similar. Consumers resolve names when they read the record.
• A field you have no value for. Leave the key out rather than writing nil, "" or 0.

If your event genuinely needs a field the catalogue doesn't have, put it beneath your package name, under the role it describes:

object.org.example.backup.snapshot.id

This should be rare. If you find a field that every backup tool would want, that's a gap in the standard set worth reporting.

Encode the values #

Each field's type fixes its wire form. The ones you'll meet most:

The full table is in Values.

Build the payload #

A dotted field path is a chain of nested maps: object.file.path is {object: {file: {path: …}}}. Never write a key containing a dot; it becomes a different field that no query can reach.

peios_mp_writer *w = peios_mp_writer_new();

peios_mp_write_map(w, 3);                       /* object, operation, outcome */

peios_mp_write_str(w, "object", 6);
peios_mp_write_map(w, 2);                       /* kind, file */
peios_mp_write_str(w, "kind", 4);
peios_mp_write_str(w, "file", 4);
peios_mp_write_str(w, "file", 4);
peios_mp_write_map(w, 2);                       /* path, size */
peios_mp_write_str(w, "path", 4);
peios_mp_write_str(w, path, path_len);
peios_mp_write_str(w, "size", 4);
peios_mp_write_uint(w, size_bytes);

peios_mp_write_str(w, "operation", 9);
peios_mp_write_map(w, 1);
peios_mp_write_str(w, "duration", 8);
peios_mp_write_uint(w, elapsed_ns);

peios_mp_write_str(w, "outcome", 7);
peios_mp_write_map(w, 1);
peios_mp_write_str(w, "success", 7);
peios_mp_write_bool(w, true);