Peinit

peinit is PID 1 — the single process that manages every service from boot to shutdown. It is a service manager with identity built in: each service runs under a KACS token and is itself an access-controlled object. This page is the map: what peinit is, the three kinds of object it works with, the ways it is unlike the init systems you know, and where the rest of the topic goes.

A service is a key in the registry under Machine\System\Services\, made of typed values. This page covers where definitions live, the naming rules, the definition schema grouped by what each field is for, and the single most important operational idea: peinit works from a snapshot, so a field's mutability class decides whether your change takes effect now, on the next start, or never until restart.

peinit has exactly two service types. A Simple service is a long-running process that IS the service. A Oneshot service is a task that runs to completion. This page covers both, the readiness models that decide when a Simple service counts as started, RemainAfterExit and success exit codes for Oneshot, and why peinit does not supervise forking daemons.

A trigger decides when a service starts. peinit has two: boot and timer, plus demand-only for services with no trigger at all. This page covers the trigger model, the Disabled flag, and the calendar-expression language that timer schedules are written in — the full OnCalendar grammar, persistent catch-up after a reboot, jitter, and how timers behave when the clock jumps.

Every service is in exactly one of ten states at any moment, and every transition between them records a cause. This page is the one to read before you read a status output: what each state means when you see it, the transitions that connect them, and the cause taxonomy that tells you why a service ended up where it is.

Supervision is everything peinit does after a service is up: restarting it when it fails, throttling restart storms with exponential backoff and a budget, checking its health actively, watching for watchdog keepalives, and escalating to a reboot when a Critical service cannot be kept alive. This page covers restart policy, health checks, the watchdog, timeout extension, OnFailure, and ErrorControl.

peinit has four dependency relationships — Requires, Wants, BindsTo, and Conflicts — and they decide start order, stop order, and how failure spreads. This page covers what each one does at start, stop, and failure; how peinit validates the graph for cycles and missing targets; how it starts services in parallel; and how shutdown reverses the whole thing.

Every service runs under a KACS token, and peinit is responsible for obtaining the right one and installing it before the binary runs. This page covers how a token is materialised — minted for SYSTEM services, requested from authd for everyone else — the per-service SID every service carries, how RequiredPrivileges trims a token down, and which identity each part of a service runs as.

What a service process looks like the instant it starts: a clean context with only the file descriptors peinit hands it, its own cgroup tree, a constructed environment, configured limits, and — before any of that — the pre-exec hooks and the condition and assert checks that gate the start. This page covers cgroups, stdio, environment layering, working directory, limits, hooks, command parsing, conditions and asserts, and the fd store.

peiosctl is the command-line front end for driving peinit — starting, stopping, restarting, reloading, and querying services, and shutting the system down. This page is the command reference: the verbs and their required rights, wait semantics, the command-by-state matrix that says which commands are valid when, the status and list output, and the error codes.

A service is a securable object: a security descriptor decides who may start, stop, query, or reload it, enforced by peinit on every control command. This page covers the ServiceSecurity descriptor and its access rights, how it differs from the registry key's own descriptor, the system-wide control descriptor that guards shutdown and reload-config, and how the two layers stay independent.

Beyond the service, peinit has two more first-class objects you see in status and event logs: a job is one process execution, and an operation is one requested action. This page covers both — their lifecycles, types, and GUIDs — plus ad-hoc jobs, the mechanism by which a service asks peinit to run a process on a client's behalf.

peinit is not a logging system, but it holds every service's stdout and stderr at birth, so it decides where output goes — and it has to handle the window before eventd exists. This page covers how output is captured and tagged, the pre-eventd buffer, the crucial split between best-effort logs and guaranteed audit events, flood protection, and what peinit writes to the console.

peinit boots in two phases — a hardcoded bootstrap that brings up the registry, then a registry-driven phase that starts everything else — and it has three boot modes that form an escalation path from normal operation to a last-resort recovery shell. This page covers both phases, the registryd/loregd split, Full/Safe/Recovery modes, and the boot-attempt counter that decides when to escalate.

Shutdown is boot in reverse: peinit stops services in reverse dependency order, escalating from SIGTERM to SIGKILL, bounded by a global timeout, then saves a random seed, unmounts, syncs, and powers off. This page covers the four ways shutdown is triggered, the graceful sequence, forced shutdown, how signals are handled, and the STOPPING=1 courtesy notification.

A symptom-first guide to peinit problems: a service that won't start, one that keeps restarting, a config change that didn't take, an access denial, a dependent that never came up, and a machine stuck rebooting or sitting in Safe or Recovery mode. Each works backward from what you see to the cause and the fix.

The complete catalogue: every field of the service definition schema with its registry type and default, and every registry key peinit reads or writes — service definitions, boot configuration, and operational parameters. Each entry links to the page that defines its meaning.