Using Peios

Use this guide to get a Peios machine running and look after it. You can use the desktop in a browser or the command-line tools on the machine. Start with the task you have now; you do not need to read the kernel or protocol manuals first.

Install and sign in #

1. Install Peios. Install on a PC covers the live medium, connecting to the installer and choosing a destination disk. Read the disk-erasure warning before continuing.
2. Complete first boot. First-boot setup sets the machine's identity, network and initial administrator account after an installation through the graphical or text installer.
3. Open the desktop. Sign in from a browser explains how to reach the machine and check its certificate before entering credentials.

For manual disk preparation and the legacy peios-install script, use Installing to disk. That route has different account and first-boot behavior; follow the instructions for the installer you actually used.

For a local console or SSH session, see Sign in.

Do everyday work #

• Manage the machine: accounts, software, services, networking, storage and configuration.
• Set up your desktop: wallpaper, clock, dock, shortcuts and default applications.
• Troubleshoot a problem: find the relevant state and records before changing anything.

Understand permissions when you need them #

Peios tools act with the authority of the account running them. A desktop app does not grant extra rights simply because it offers a button. Machine-wide settings are commonly restricted to Administrators; the individual task guides say what access is needed.

If an action is denied, start with the task's permissions section. Use Security fundamentals when you need to understand identities, privileges and access rules in more detail.

Find technical documentation #

• Peios technical reference contains technical reference manuals, specifications and implementation reference.
• Developing for Peios covers building and shipping software, the SDK and developer tools.

The event and command references remain available from Using Peios for looking up an event you have seen or a command you are about to run.

Choose the task below. The linked guides explain the controls, required permissions and how to check the result. Use the machine-wide settings only when you intend to affect everyone who uses the machine.

Accounts and desktop settings #

Manage local accounts and groups collects the account tasks and access precautions in one place.

• Create an account or change local membership: Principals Manager on the desktop, or Creating accounts and the lps reference in a terminal.
• Sign in remotely from a terminal or manage SSH keys: Signing in over SSH.
• Change your own password: The passwd command.
• Change your own desktop: Desktop Settings.
• Set defaults for everyone or change how the desktop is served: Settings for all users. Changing the listen address can disconnect open desktops; an overlay prevents normal sign-in while it is set.

Software #

• Find, install or remove a package: Package Manager on the desktop, or Installing and removing packages in a terminal. Review the plan, including dependencies, before applying it.
• Update or undo a package change: Keeping a system current.
• Set up or enable a feature delivered by a package: Feature Manager. Installing a package puts files in place; feature setup is a separate action. Remove a feature before its package, while the scripts needed to undo its setup are still available.
• Handle an interrupted package operation: Transactions and recovery. Feature operations have their own interrupted-state guidance.

Services and running programs #

• Inspect, start, stop or restart a service: Controlling services.
• See running programs, resource use and jobs: Task Manager.
• Read a service's output: Event Viewer or Service output and logging.
• Shut down or reboot: Shutdown.

Network, time and storage #

• Inspect connections or change network settings: Network Manager, or The net command to inspect state and Configuring profiles to change configuration. Read the confirmation and rollback behavior before changing the network through a remote desktop.
• Allow or block a network service: Check and change network policy safely.
• Set the time zone or clock: Time zone and setting the clock.
• Find software, configuration or service data on disk: Where files live.
• Inspect disks and filesystems: Disk Manager is read-only. For changes, follow Managing mounts, Partitioning or Formatting with security descriptors. Partitioning and formatting can destroy data; follow the warnings in those guides before making changes.

Configuration beyond the settings apps #

Start with Find where a setting lives to locate its documentation and the component that reads it.

Use Registry Editor or reg for settings that require a registry change. Consult regman first: it explains what a key means, accepted values and when changes apply. A value being stored does not by itself prove the service accepted it. Follow Change a setting and verify it for the complete workflow.

For configuration backup and recovery, read Backup and restore before changing the registry's stores or layers.

Start with what failed and when. Keep the error text and the name of the service, package, account or interface involved. Read the current state and relevant records before restarting a service, changing permissions or repeating an operation that changes the machine. For a reviewable event capture, follow Save incident event evidence.

The browser cannot reach the desktop #

1. Check the address and port against Sign in from a browser. A machine configured to listen only on 127.0.0.1 is not reachable from another device.
2. If the browser shows a certificate warning, follow The machine's certificate. Do not enter credentials when the certificate fingerprint does not match.
3. At a console you can still reach, use net status to inspect the address, link and readiness. Check the GXWI service, gxwid, through Controlling services.
4. If this happened during installation or first boot, return to that installer's guide. Network changes, reboot and completion of setup can change the address or what the browser shows.

Sign-in is refused #

An unknown account and a wrong credential intentionally produce the same sign-in failure. Check that you are using an account on this machine and follow Creating accounts for local-account administration. Do not infer that an account is missing from the sign-in error alone.

For an administrator investigating the failure, the sign-in audit trail explains the authority's and local account service's events. Those records are available only to accounts permitted to read them.

A service will not start, stops, or keeps restarting #

Use Service troubleshooting. It covers configuration, identity, dependency and crash-loop failures. Inspect the service's state and its latest output before retrying: a running process is not always a ready or healthy service.

In Services Manager, select the service and choose Logs… to open Event Viewer on its output, including hooks and health checks. Widen the time range if the failure is older than the default last 24 hours.

Networking is missing or changed unexpectedly #

Use Network Manager or net status to check the interface's verdict, selected profile, address, gateway and warnings.

• Not managed / IGNORE: check which profile rule applies.
• A rejected configuration: the last working rules can remain active; read the rejection before assuming the new settings took effect.
• An address but no route: distinguish local connectivity from a route out of the machine.
• Addresses work but names do not: follow Name resolution.

Make lasting changes through the supported network settings or registry profiles. Manual changes to a managed interface can be reverted by netd. Network Manager labels some firewall displays Example data; do not use those displays as evidence of live traffic. For the next check for your symptom, follow Network diagnostic tools.

The clock or displayed time is wrong #

Start with Keeping the time: inspect the effective time zone, clock state and source failures before changing the clock. A wrong time zone and an unsynchronised clock need different corrections.

A write fails or a filesystem is full #

Keep the exact error and affected path. Find why a filesystem is full distinguishes block space, inode pressure and incomplete directory measurements before choosing a supported remedy. Do not turn a permission or I/O failure into a deletion task without evidence.

A package or feature change was interrupted #

For a package operation, follow Transactions and recovery before starting another transaction. For a feature, follow Interrupted features; their recovery uses the feature's own lifecycle, rather than package transaction recovery.

An action is denied, or records seem to be missing #

For a refused operation, follow Debugging a denial. Collect the failing operation, identity and required access before changing permissions. The task guide explains the access needed for that operation.

Event queries omit records you may not read. Event Viewer can show whether its read policy hides records, or whether it could not read that policy. An empty list is not proof that nothing happened. Also check the time range and filters, and remember that logs are best effort.

Follow Find missing records to distinguish filtering, access, retention and collection failures. What the machine records explains logs, events and metrics; Event Viewer explains filtering, older records and access notices.

Use this guide for a fresh installation on a physical PC. At the end, the PC boots from its own disk and you can sign in with the administrator account you created during setup.

If the disk already holds a Peios installation you want to keep, choose Upgrade an installation or Repair an existing system instead.

What you need #

• An x86-64 PC with UEFI firmware. Legacy BIOS boot is not supported.
• A USB stick of at least 2 GB that you can erase.
• A Peios .iso image. If you need to build one, follow the peiso quick start.
• A screen and keyboard for checking the machine, its network address, and its certificate. After setup, you can use another device's browser on the same network.
• A wired connection for browser access. Console setup works offline. Peios can detect supported Wi-Fi hardware, but joining a wireless network is not yet available.

Keep the machine on a network you trust while installing and setting it up: the live installer and pending first-boot setup can be opened without signing in.

Write the medium to a USB stick #

Write the .iso as a raw disk image. Copying the file onto an existing filesystem does not make a Peios boot medium.

On Linux:

1. Identify the stick by size, model, USB connection, and removable status (RM is 1):

   Copy

   lsblk -o NAME,SIZE,TRAN,MODEL,RM
   ls -l /dev/disk/by-id/ | grep usb
   

2. Unmount any of the stick's filesystems that the desktop mounted. Otherwise pending filesystem writes can overwrite part of the new image later.

3. Select the stable identifier for the whole stick, not a partition. Replace the placeholder below with the identifier you just checked. Verify the destination again before running dd; it overwrites that device.

   Copy

   sudo dd if=peios.iso of=/dev/disk/by-id/usb-REPLACE_WITH_VERIFIED_STICK_ID bs=4M oflag=direct conv=fsync status=progress
   

4. Wait for the command to finish successfully before unplugging the stick.

A stable identifier avoids relying on /dev/sdX letters, which can change as devices are attached. It does not replace checking that you selected the right stick.

On another operating system, use a raw image-writing tool. Choose DD mode or image mode when the tool offers a choice between raw writing and copying files.

Set up the firmware #

Enter firmware setup at power-on; the screen usually names the key, often Del or F2.

• Turn Secure Boot off. The Peios boot image is not signed with a key that PC firmware trusts out of the box.
• Use UEFI boot. Note the one-time boot-menu key, often F7, F11, or F12, so you can choose the stick without changing the permanent boot order.
• Leave the storage-controller mode unchanged unless disks are missing. If the installer reports an unclaimed RAID, Intel RST, or VMD controller, check the firmware's storage settings. AHCI is the documented alternative. Record the previous setting before changing it; a controller-mode change can affect an existing operating system.

Boot the live system #

Insert the stick and select it from the one-time boot menu. If there are two entries for it, choose the one marked UEFI.

During startup, look for a message like this; the device name can differ:

OK live-boot: mounted boot medium /dev/sdb at /mnt/medium

A medium with the console installer starts its form. A live login uses the peios account with no password. When you have a shell, check the hardware and networking:

lspci          # network, graphics, and storage controllers
net status     # interfaces and their assigned addresses

A wired interface with readiness routed and an address is on the network. A wireless interface showing down, no-carrier is expected while Wi-Fi joining is unavailable; its presence still indicates that the driver and firmware loaded.

The live system keeps changes in memory and discards them at reboot. The current installer copies the shipped image, not your live session's accounts or changes.

If the boot stops #

Install #

Use the console form, or open https://<address-from-net-status>:7780 on another device. Browser installation requires a medium with the graphical installer enabled.

Before trusting a browser certificate warning, compare its SHA-256 fingerprint with this file read at the machine's own console:

cat /var/state/gxwi/certificate.sha256

Do not enter credentials if the fingerprints differ. See the machine's certificate for verification and browser-trust details.

1. Choose the installation operation.
2. Select the internal disk by its device, model, size, and bus. The USB medium is marked and cannot be selected.
3. Review the erasure confirmation, including the existing systems and used filesystems it found. Go back if anything is unexpected. An unrecognised or encrypted filesystem may not have its contents listed; it will still be erased.
4. Confirm the install. In the browser, hold down the button that starts it.
5. Leave the machine and medium connected until the installer reports Installation complete. Reboot to start Peios. Closing a surface does not cancel the daemon's installation.

Installing to disk explains progress, failures, the disk layout, and the older command-line script.

Restart from the installed disk #

After the installation-complete message, remove the USB stick before choosing Reboot now. Do not remove it while installation is still running.

The installer does not change firmware boot order. If the machine returns to the installer, it probably booted from the stick again: remove the stick and restart. You do not need to install again.

Once disk boot is working, you can put the internal disk first in firmware boot order. Remove obsolete boot entries only after identifying them as entries for the system you replaced.

First boot #

First-boot setup creates your administrator account, sets the machine's name, and optionally applies a manual wired-network address. It is available on the console and, when the image includes it, at the browser address.

installerd attempts to carry the live medium's GXWI key and certificate into the installed system. The transfer can be skipped or fail without failing the installation, so the completion message does not prove that the certificate is unchanged. If the installed fingerprint differs, verify it through the installed machine's trusted console before entering credentials. See certificate carry-over and first boot. Automatic waiting and reconnecting also depend on browser trust; if the tab shows a browser error after restart, reopen the address manually.

Check the result:

• The PC starts from its internal disk with the USB stick removed.
• Setup finishes and gives you a sign-in prompt.
• You can sign in with the account and password you just created.
• If you changed the network address, the new address reaches the sign-in page.

If setup repeatedly fails, keep the install medium available and follow first-boot recovery.

Machines known to work #

Choose the sign-in route available on your machine. If you have just installed Peios, complete first-boot setup first. Manual and legacy installation routes can provision accounts differently; Creating accounts explains those distinctions.

Choose how to connect #

• Use the desktop in a browser: Open the desktop. Check the machine's certificate before entering credentials.
• Use a local console: The login command explains the prompt, live-medium autologon and multiple-console behavior. Switching consoles does not lock or log out the session you leave.
• Use a remote terminal: Sign in over SSH. Verify the host fingerprint and read the access precautions before changing the SSH service or credential policy.

Manage your own account #

Use passwd to change your own password. For your SSH keys, follow Changing your own keys. To change the name shown beside your account name, follow Changing your own display name. Changing another account's credentials is an administration task; start with Manage local accounts and groups.

A stored password and the account's credential policy are separate. Follow Creating accounts when changing whether a password or SSH key is required; setting a password alone does not change a passwordless account's policy.

If sign-in fails #

Start with Troubleshoot a problem. Keep a working administrator route available while investigating. Do not delete the local principal store to try to restore access: it holds the machine's identity, and a corrupt store is different from a missing one. See The local store.

For the model behind the prompts, read How authentication works and Logon sessions in Security Fundamentals.

login is the terminal client for signing in. It collects an identifier, renders whatever credential prompts the authority sends, installs the token it is granted, and replaces itself with your shell.

login [name] [options]
login --try <name> [options]
login --try-no-password <name> [options]

It does not know what a password is. It renders the prompts it is asked to render and returns the answers, so adding a new credential type — a one-time code, a smartcard — changes the authority and leaves login alone.

Naming a principal, or not #

With no name, login asks for one:

Username: alice
Logging in as alice
Password:

With a name, the first prompt is skipped. The Logging in as line comes from the authority rather than from login, so it will gain a realm once authorities have them.

A principal who needs no credential is signed in immediately, with no prompt at all — see passwordless accounts.

--try and --try-no-password #

Both attempt a named principal and fall back to an ordinary prompt rather than failing. They differ in what they offer to collect.

--try <name> attempts the principal with login's full capabilities. A principal whose policy requires no credential is signed in immediately; one whose policy calls for a password is prompted for it.

--try-no-password <name> attempts the principal while declaring that it can collect nothing, so only a principal who needs no credential can succeed. This is what a console autologon uses.

Neither flag asserts that anyone is authenticated. The authority still decides, and understating what you can collect only denies you prompts you could have rendered — so running either by hand gains you nothing you did not already have.

The first two columns below describe credential policy, not just whether a password is stored. They assume an enabled account with console logon permitted and, for password sign-in, a password set.

A fallback restarts the sign-in from Username:, so you are never locked to the principal that was attempted.

When a fallback explains itself #

login says why it fell back only if something was already on your terminal.

A --try that reached a password prompt has interrupted you, and dropping to Username: without a word would read as a fault — you typed a password and got asked for a name. So it reports first:

$ login --try alice
Logging in as alice
Password:
login: Password incorrect
Username:

A --try-no-password that was refused before anything was rendered has interrupted nobody, and stays quiet. That is what keeps a line about a failed autologon off the console of every machine where the principal requires a credential.

Falling back is limited to denials another principal could survive. A failure of the authority itself is reported and login exits, because offering a prompt that cannot work either would spin a console.

Where existence is checked #

login asks /run/ident.sock whether a principal exists, not the logon socket. The logon socket will not tell it — an authority never distinguishes an unknown principal from a bad credential — while the identity socket answers plainly, which is what it is for.

If that lookup cannot be answered, login attempts the sign-in anyway rather than reporting an absence. An unreachable source reported as "no such user" would turn an outage into a fact.

Autologon on a console #

A console that signs in on its own is a passwordless principal plus --try-no-password. On a live image, peinit starts:

/bin/login --console --try-no-password peios

The same service definition suits an image where peios requires a password: the attempt is refused before anything is rendered, and an ordinary prompt appears. No second seed, and no conditional configuration.

To require a password instead of autologon, first set the principal's password with lps password, then select lps policy <name> password. Setting the password alone leaves the none credential policy and autologon unchanged.

Taking --try-no-password out of the login-console service's Arguments stops the automatic attempt, but does not change the account's credential policy: a principal whose policy is still none can still sign in at that prompt without a credential. To move the prompt to another terminal, change the service's TTYPath — see controlling services.

System Settings chooses it in its Startup & Shutdown section, under Console Sign-In: Automatic Sign-In is Off, or one of the local accounts. The choice is written the moment it is made, as Arguments: --console, followed by --try-no-password and the account if one is chosen. It applies the next time login-console starts, at the latest the next boot. Changing it needs write access to Machine\System\Services\login-console, which as shipped only Administrators have.

GXWI information on the console #

Managed login --console sessions show GXWI's browser address and certificate SHA-256 fingerprint before authentication when GXWI is installed. Compare the fingerprint on this trusted local console with the browser's certificate details before accepting its warning. See the machine's certificate.

The banner reads /var/state/gxwi/certificate.sha256 and the configured Machine\Software\GXWI\Listen address and port. With the IPv4 wildcard listener Peios ships (0.0.0.0:7780), it lists the machine's active non-loopback IPv4 addresses. If the value is missing or unreadable, the banner shows GXWI's own fallback, the loopback address 127.0.0.1:7780. An IPv6 wildcard lists IPv6 addresses; link-local addresses that need an interface zone are omitted. A specific listen address is displayed as configured. This is connection information, not a check that GXWI is currently running.

Information is read once each time login starts. Missing or malformed fingerprints and unavailable addresses are reported without preventing login. Ordinary login invocations without --console do not show this banner.

Options #

-f is not implemented. On Linux it means "trust me, they are already authenticated", gated only by the caller being root. On Peios that decision belongs to the authority, taken from the verified peer, so accepting a flag here would put an authentication bypass in an unprivileged process.

The environment your shell starts in #

Without -p, login builds a fresh environment: HOME, SHELL, USER, LOGNAME, PATH=/bin, and TERM. The shell's argv[0] gets a leading dash, which every shell reads as "this is a login shell, run the profile files".

TERM is carried through if login was started with one. Otherwise login decides it from the terminal it is on, the way a getty does elsewhere: linux on a virtual console (/dev/tty1 and its siblings, the display), vt220 on anything else (a serial line, a hypervisor's paravirtual console). /dev/console is whichever of those the kernel chose, and login resolves it through the kernel's own record of the active console rather than guessing, so one service definition on /dev/console gets the right answer on a machine with a display and on one without.

The home directory comes from the profile the authority sent, and a missing one is not fatal. login reports it and starts you in /. Refusing to proceed over an absent directory would turn a cosmetic problem into being locked out.

login does not create it. Two reasons, and either would be enough. It has already made your token its own by the time it changes directory, so it is you rather than the system — and /home lets you walk through it but not create in it. And directory provisioning has no business inside the one program that has to keep working when everything else is broken. The authority creates the directory when it grants the logon, before login is handed anything; reaching this fallback means the authority named no home, or could not make one.

Exit status #

login does not return on success — it replaces itself with your shell, so what you see afterwards is the shell's exit status.

Multiple local consoles #

The Experimental edition provides independent login sessions on tty1, tty2 and tty3. Switch between them with Alt+F1, Alt+F2 and Alt+F3 at a text console, or use chvt 1, chvt 2 and chvt 3 with the required console authority. Switching does not lock or log out the session you leave.

login-console follows the kernel's primary console: peinit resolves a display console to the fixed tty1, or uses the selected serial/paravirtual terminal. It retains the live-medium passwordless peios attempt. Additional services login-tty1, login-tty2 and login-tty3 show ordinary username prompts. On a display-primary machine, the duplicate login-tty1 service is skipped because login-console already owns that terminal. On a serial-primary machine all three local prompts can run alongside the serial session. Missing terminals are skipped.

First-boot setup retains the primary console. Additional terminals wait until both setup service definitions have been removed; they collect no credentials while setup is pending. Logging out terminates that terminal service's remaining processes and produces a fresh prompt with canonical input and echo restored. A normal logout does not consume the crash-restart budget. This resets terminal input settings; it does not implement a session lock or promise to erase all screen history.

passwd changes your own password.

passwd

It takes no arguments. The account it changes is the one you are signed in as: the authority reads it from your token, and the request has no field in which to name anybody else. To set another principal's password, an administrator uses lps password.

What it asks #

$ passwd
Changing the password for alice
Current password:
New password:
Retype new password:
password changed

Your current password is always asked for, even though you are signed in. Being signed in shows that someone authenticated as you; it does not show that the person at the keyboard now is you, and a password changed from an unattended terminal could not be recovered by signing in again.

If the new password and its confirmation differ, or the new one is empty, you are told why and asked again. After three attempts the change ends with the password unchanged.

The prompts come from the principal source that holds your account, not from passwd. passwd renders what it is asked and returns the answers, so a source with different requirements asks for what it needs without passwd changing.

How it works #

passwd opens a credential-change conversation with the authority on /run/logon.sock (PGSS §2.20). authd finds the source that holds your account from your token's SID and relays the conversation to it. lpsd checks your current password, sets the new one, and writes its store to disk before it reports success, so password changed means the next sign-in checks the new password. It records the change as an lpsd.credential.changed event, naming your account by SID, and records a refused change the same way with the reason, such as wrong-credential for a current password that did not verify.

Nothing is minted. Your current session carries on as it was, and so does every other session you hold.

Other ways to change it #

passwd is one client of this conversation, not the only one. A program can hold the same conversation for you. On the desktop, My Settings (type my in the launcher) does: its Password section collects your current password and the new one twice, and hands them over when the authority asks. The line along the bottom of the window shows what the authority said, then whether the password changed, and the fields are emptied whatever happened. An account with no password sees why in place of the form. The authority asks the same questions, applies the same rules and gives the same refusals whichever program asks; only how the questions are shown differs. A program written in Rust gets the conversation from the credential module of libauthd-client, which passwd itself uses.

Adding or removing your own SSH keys is a sibling conversation on the same socket, and asks for your current password the same way: see Changing your own keys.

From a script #

When standard input is not a terminal, passwd prints no prompts and reads one line for each, in order:

printf '%s\n' "$current" "$new" "$new" | passwd

When it refuses #

A message ending whether the password changed is not known means the authority went away after the change was asked for and before it said how it ended. Sign in with each password to find out which one holds.

Who can reach the socket #

Every authenticated principal can connect to /run/logon.sock so that passwd works for them. That does not let them originate a logon for anybody else, which still takes a LogonTypes record on their own policy entry.

A machine whose administrator has replaced the socket's descriptor with LogonSocketDescriptor may not admit you. See assigning privileges.

Exit status #

See also #

• How authentication works — the conversation this is one kind of.
• The lps command — setting another principal's password, as an administrator.
• PGSS §2.20 — the credential-change conversation, specified.

The SSH server lets people sign in to this machine from another over the network, with their password or one of their SSH keys. It is the sshd service, from the dev.peios.openssh package. Every SSH sign-in is a RemoteInteractive logon through the same authority as any other: see How authentication works.

That includes commands without a PTY and SFTP: the account must permit remote-interactive, not just network. An account with credential policy none cannot sign in over SSH. Password authentication requires an actual password and a policy allowing it; key authentication requires an enrolled key and a policy of key or either. The SSH implementation contract records the release-qualification and compatible-build requirements.

Four things about the server are settings:

The port and password sign-in are machine policy in the registry, not lines of sshd_config. start-sshd reads them each time the service starts and gives them to sshd on its command line, and a Port or PasswordAuthentication line in /lcl/etc/ssh/sshd_config has no effect. Other sshd options still go in that file.

Change them with ssh-settings on a terminal, or SSH Settings on the desktop (type ssh in the launcher), which is the same program and does the same things.

Looking #

$ ssh-settings
server       running
port         22
passwords    accepted
host key     SHA256:Wm3…

Anyone may look, except at the host key, which only SYSTEM and Administrators may read; others see why instead.

Connect from another computer #

1. From a trusted administrator session on the Peios console, or a certificate-verified GXWI session as an administrator, read the machine's address, SSH service state, port and host fingerprint:

   Copy

   net status
   ssh-settings
   ssh-settings fingerprint
   

   Check that the server is running. Choose an address on an interface reachable from the other computer; Reading net status explains the interface blocks. For a direct connection, use the port shown by ssh-settings, which is 22 as shipped. The QEMU Makefile's host-forwarded port 2222 is a separate route described in the build quick start.

2. On the other computer, use your account name, the machine's address and that observed port:

   Copy

   ssh -p <observed-port> <name>@<machine-address>
   

   Before accepting a first-connection prompt, compare its SSH host fingerprint with the trusted reading from step 1. This is the SSH host key, not GXWI's TLS certificate fingerprint. If they differ, stop and investigate; do not accept the key or discard a remembered key just to suppress a warning.

3. Sign in with the intended password or enrolled key and check that a new shell opens. A running service or an already-open session alone does not prove that a new sign-in works.

Turning it on and off #

ssh-settings on
ssh-settings off

on sets the service to start at boot and starts it now; off stops it and keeps it from starting. People signed in over SSH are disconnected when it stops. Each needs write access to the service's key, Machine\System\Services\sshd, and the right to start and stop sshd, which as shipped only Administrators have; see who can manage a service. Without the second, the setting is still saved and takes effect at the next boot, and you are told so.

Moving the port #

ssh-settings port 2222

A port is three things that must agree, and ssh-settings changes all three in one registry transaction, so none is ever moved without the others:

• the Port value;
• sshd's port reservation, the descriptor under Machine\System\Network\TcpIp\PortReservations that lets only sshd bind the port (see port reservations);
• the ssh firewall rule, Machine\System\Network\Rules\Flow\ssh, whose DstPort.Equal is the port let in (see network policy).

It then restarts sshd onto the new port, which disconnects everyone signed in over SSH, you too if you are. Connect again on the new port: ssh -p 2222 alice@host.

A port another program has reserved is refused: a reservation naming that one port and nothing else, such as tcp:80 for a web server, makes it that program's. A wider range that contains the port, such as tcp:1-1023, is fine, since reservations nest. Moving the port needs write access to all three keys, which as shipped only Administrators have.

Keys only #

ssh-settings passwords off disables password authentication for SSH. It does not require an account-wide policy of key. Keep the account policy either when its password must also work through GXWI: GXWI does not currently offer SSH-key authentication, so a key-only account cannot use that sign-in path.

With SSH passwords off, an account whose policy is password cannot sign in over SSH, though it can still use its password at the console and on the desktop, subject to its other sign-in restrictions.

Before changing the server:

1. Enroll a key for each person who needs SSH. They can use My Settings where permitted, or an administrator can use lps key add <name> <public-key-file> [label]. Adding a key does not change credential policy. For a password-enabled account that will also use keys, an administrator sets lps policy <name> either; retain that policy if GXWI password access is needed.
2. Inspect lps show <name> and lps key list <name> to check the enabled account, enrolled key, credential policy and permitted remote-interactive logon type. While SSH passwords are still available, make a fresh SSH connection that actually authenticates with the enrolled key, following the host-key check above. A connection that falls back to a password does not count as a key test. If the key test fails, stop before disabling passwords and check those account settings and the service state.
3. Verify a fresh administrator sign-in through a separate non-SSH route, such as the local console or certificate-verified GXWI, and keep that route available. The last-administrator guard does not prove that a usable route exists. Keeping another SSH session open is insufficient: this change restarts sshd and ends every SSH session.

Only after both access paths work, disable SSH passwords:

ssh-settings passwords off

Then make another new key-authenticated SSH connection and verify that its shell opens. If it fails, use the surviving console or GXWI administrator route to inspect the settings and restore SSH password acceptance with ssh-settings passwords on. This reversal also restarts sshd; it does not change account credential policy. Keep the separate administration route until fresh SSH access has been verified again.

The host key #

ssh-settings fingerprint

The first time someone connects, their SSH client shows the server's host key fingerprint and asks whether to trust it. Compare it with this one, read on the machine itself or by someone you trust who can read it, before answering yes. The key is made on the server's first start and never replaced automatically.

On the desktop #

SSH Settings shows the same four things on one page: the server, with how it is and a switch to turn it on or off; Port, with Apply once it is changed; Password Authentication, as a switch; and Host Key Fingerprint, with Copy. Turning the server on happens at once. Anything that restarts or stops it — turning it off, moving the port, password sign-in either way — ends every SSH session, so it asks first, under its row, and changes nothing until it is told to go ahead. What you may not change is shown read-only, with the reason, once. Each change says what it did along the bottom of the window, including whether sshd was restarted.

Exit status #

Local accounts and groups are held by lpsd, the local principal source. Use Principals Manager on the desktop or the lps command in a terminal to manage them. The guides distinguish changes you can make to your own account from administrator operations.

Choose a task #

• Create an account: Creating accounts covers credentials, membership and the different first-account provisioning routes. The desktop equivalent is Making a user.
• Change an account or its sign-in policy: Changing a user or the lps reference. A password being set does not by itself require that password at sign-in.
• Create a group or change membership: Groups in Principals Manager or Grouping people together.
• Inspect or change privileges and integrity policy: Assigning privileges. This is the machine's local policy, separate from the account's identity. A policy change affects newly minted sign-in tokens, not existing tokens.
• Change your own password, SSH keys or display name: Sign in links the self-service procedures.

Keep a usable administrator route #

Before changing an administrator's credentials, membership or sign-in access, keep a working administrator session and verify the replacement route. The last-administrator guard checks account state; it does not prove that you can actually sign in through a usable route. SSH configuration changes can end every SSH session, so follow the separate-access precautions there.

Read Disabling rather than deleting before removing an account. Recreating a name does not restore the old SID or the access granted to it.

Understand the model when needed #

Security Fundamentals explains authorities and principal sources, local identity storage, name resolution and privileges. Tool authors and administrators investigating a refused request can consult the local principal interfaces in the technical reference.

Creating an account #

Run lps add with no arguments and it asks for what it needs:

$ lps add
Name: alice
Full name [optional]: Alice Chen
Additional groups [comma-separated, optional]: Administrators
Primary group [the daemon's default]:
Home directory [the daemon's default]:
Shell [the daemon's default]:
Password for alice:
Again:

  name           alice
  full name      Alice Chen
  primary group  (the daemon's default)
  home           (the daemon's default)
  shell          (the daemon's default)
  groups         Administrators

Create this principal? [Y/n]:
created alice with RID 1002

An empty answer takes the default, and nothing is sent until you confirm. Or say it all on one line:

$ lps add alice --group Administrators

Anything you supply is not asked for, so either style works and they mix freely.

Groups are named however you like — Administrators, a local group's name, or a literal SID such as S-1-5-32-544. lpsd resolves it.

You need to be an administrator to do this. See the lps command for the full surface.

What a new account gets #

No per-user group is created. That Linux convention exists so a file's group ownership means something, and under KACS it means nothing — access is decided by the token, not by the mode bits. A group per user would be ceremony with a RID attached.

The home directory is not created here. lps records the path and nothing more. The directory appears at the principal's first sign-in, made by the authority when it grants the logon — and only when the account has a home recorded, which is why a service principal never grows one.

The shipped authd service explicitly retains SeRestorePrivilege so it can assign the new directory's owner and group to that principal. Removing it from RequiredPrivileges can leave a newly created home accessible only to SYSTEM and Administrators, preventing an ordinary user's session from starting there. Authd reports this failure and leaves existing directories alone; an administrator must repair their descriptors deliberately.

It is created owned by the principal, with a protected DACL: full control for its owner, for SYSTEM and for Administrators, and nothing for anybody else. Protected matters — without it the root's inheritable "Everyone may read" ACE would apply and every account could read every other account's files.

A principal whose home could not be created still signs in, starting in /, and login says so. A directory is not worth failing a logon over.

An existing directory is left exactly as it is, and one owned by somebody else is reported rather than taken over. So pointing a new account's home at another principal's directory does not hand it over — it produces a warning in the log and an account that starts somewhere it does not own.

Accounts with no password #

lps add <name> --no-password creates a principal whose credential policy is none. It signs in without being asked for anything where the client and authority permit credential-free sign-in.

The sign-in is otherwise completely ordinary. lpsd still vouches for the principal, authd still mints the token and still applies this machine's privilege and integrity policy to it, and the session that results is indistinguishable from one reached by typing a password. Nothing is bypassed; there is simply nothing to collect.

It is a property of the account. Nothing ties it to a particular terminal: any client that permits credential-free sign-in can use it, subject to the account's logon-type restrictions and the authority's policy for that client. SSH does not permit it; SSH requires an actual password or an enrolled key and a policy that allows that credential. A passwordless account enables console autologon, but do not assume that its use is limited to that console.

An empty password is not the same thing and is refused. See the lps command.

Make the first account an administrator #

An ordinary account is usable on a stock image. The descriptor the system tree ships with grants Everyone read and execute — and on Peios execute is also traverse — so any principal can list directories, read the system tree and run what is in it. What it cannot do is write there. A non-administrator writes only where something grants it: its own home directory, which is created at first sign-in with a protected DACL admitting the owner, LocalSystem and BUILTIN\Administrators and nobody else, and /tmp, where anyone may create files and only their owner may remove them. See Installing to disk for the root descriptor itself.

What an ordinary account cannot do is administer the machine. lps refuses it, so it cannot create the next account; it cannot mount a filesystem, install a package or change a service definition either. The first account is therefore an administrator because nothing else on the machine can make one, and it stays one because lps will not leave the machine without an enabled administrator (see The last-administrator guard below). The accounts after it need Administrators only if they are going to administer.

Where the first account comes from #

A machine with no store provisions one at first boot, and it is empty — lpsd generates the domain, because a source with no domain can answer nothing, but it does not invent accounts.

So something has to create the first one, and there is a chicken-and-egg problem: lps talks to lpsd, so lpsd must already be running, which means this cannot be done by an early-boot script. Autorun scripts run before any service has started.

The provisioning path depends on the edition. An installed edition can enable first-boot setup; a development image can instead ship a oneshot service, ordered after lpsd, that runs lps to create a known account. An image with no first-account provisioning path needs an already-authorised way to create the first account.

On an installed edition with first-boot setup #

Complete first-boot setup creates the first administrator after installation. Use the console form, or the browser form when the image includes oobe-gxwi, then verify sign-in with the new account. Use lps add as that administrator for further accounts.

This path is enabled only when the edition includes dev.peios.oobe and opts into its oobe-service seed through install_autoapply. The oobed service runs as SYSTEM to create the account; the user-facing form does not need an existing administrator sign-in. Do not assume every custom image includes or enables it. The development-account seed below is a separate provisioning choice.

On a development image #

Images built for development ship two things: a script that creates a known account, and a registry seed defining the oneshot service that runs it. If your image has them, it boots with an account already present, and lps list will show it.

On a live image that account has no credential at all, and it is an administrator. The script creates it with lps add peios --group Administrators --no-password, so anyone who reaches a prompt that permits credential-free sign-in on that machine can become it — and the console signs in as it automatically, without asking anything.

That is deliberate rather than an oversight. A live ISO is an unauthenticated medium: anyone holding it can boot it and read everything on it, so a password would be a formality rather than a boundary, and one printed in the image at that. What it is not is a posture to carry anywhere else.

Give it a password the moment the machine becomes something you care about, then say it signs in with that password. The two together turn it into an ordinary account and stop the console signing in on its own:

$ lps password peios
New password for peios:
Again:
set the password for peios
$ lps policy peios password
credential policy updated

The password alone changes nothing: until lps policy says otherwise, the account still signs in with nothing. Set the password first, since a policy of password is refused for the last administrator while they have none.

Better still, build an image without the development-account seed, with first-boot setup or another deliberate account-provisioning path. Omitting the development seed alone does not create an account; see On an image with no account provisioning below.

On an image with no account provisioning #

On a fresh image with no accounts, no enabled first-boot setup and no account-provisioning seed, lpsd starts, provisions an empty store, and logs that no principals exist and no logon can succeed until one is created. The login prompt will appear and nothing will satisfy it.

That is the correct behaviour rather than a fault, but it does mean you need a way in. Create the first account from a console session that is already SYSTEM — lps accepts LocalSystem as well as administrators, precisely for this case.

Disabling rather than deleting #

$ lps disable guest
disabled guest

A disabled account keeps its RID, its SID, and its group memberships. It cannot start a new sign-in. Re-enable it with lps enable.

Disabling an account, changing its password or removing a key does not revoke already issued tokens or end its existing sessions. Use Task Manager's sign-out action when existing sessions must end. Signing out ends processes and can lose unsaved work; session lifecycle explains its permissions and limits, including token references held outside those processes.

Prefer this to lps remove. A removed principal's SID keeps appearing in the security descriptors of everything they owned, and because RIDs are never reused nothing will ever hold that SID again — the files become owned by a principal that no longer resolves.

The last-administrator guard #

This is a guard on the local account store, not a guarantee that a usable sign-in path is reachable.

lps refuses to remove the last enabled administrator, to disable them, or to take Administrators away from them. It refuses as firmly to leave them no way to sign in: no kind of sign-in at the machine, remotely or over the network (lps logon-types), or nothing to sign in with (lps policy and lps key remove).

$ lps disable jack
lps: jack is the only principal who can administer this machine; disabling them would leave no way back in

The check counts only enabled administrators, so a disabled standby account does not license removing the working one.

The guard does not check that a console, remote service or network route is available. After changing credentials or sign-in policy, inspect the account with lps show <name> and verify a fresh sign-in through the intended path before closing your working administrator session. A stored credential and a permitted logon type are not evidence that the whole path works.

This guard exists because there is currently no offline repair. lps reaches the store only through lpsd, and lpsd only authenticates — so a machine with no enabled administrator has no way back short of editing its disk from another system.

Grouping people together #

For anything beyond the built-in groups, create one:

$ lps group create developers
created the group developers with RID 1001
$ lps group add alice developers
added alice to developers

A local group is a real object with its own SID and gid, so it can be named in a security descriptor and it shows up in getgroups. Deleting one is refused while anybody is still in it.

Changing your own password #

Run passwd. It asks for your current password and then the new one:

$ passwd
Changing the password for alice
Current password:
New password:
Retype new password:
password changed

It goes over PGSS Logon rather than through lps, so it works the same way whichever source holds your account — a domain principal changes their password exactly as a local one does. lps password is the other operation: an administrator setting somebody else's.

An account created with --no-password has no current password to prove, so it cannot give itself one. An administrator sets one with lps password, and lps policy <name> password to have it used, or with Principals Manager's Set password, which does both.

Where to go next #

For the full command surface — every flag, the group and claim subcommands, and the exit statuses — read The lps command.

For what the store holds and why RIDs are never reused, read The local store.

lps administers the local principal store — this machine's own accounts and groups, held by lpsd.

lps subcommand [arguments]

It is a client and nothing more. It holds no state, opens no store, and has no privilege of its own: every command is a request over /run/lpsd/admin.sock that lpsd decides whether to honour. lpsd must be running.

You must be a member of BUILTIN\Administrators — enabled, not deny-only — or be LocalSystem.

Naming a group #

Anywhere lps takes a group, you may write it three ways:

lps group add jack Administrators              # a well-known name
lps group add jack BUILTIN\\Administrators      # the same, qualified
lps group add jack developers                  # a local group
lps group add jack S-1-5-32-544                # a literal SID

Names are matched case-insensitively, and lpsd resolves them, not lps. The tool carries no copy of the well-known table and does not know this machine's domain — a second copy of the machine's identity scheme would be free to disagree with the first.

A well-known name always wins over a local group of the same name, which is why you cannot create a local group called Administrators.

Inspecting #

lps list #

Every principal, with RID, uid, state, and how many groups each is in.

$ lps list
NAME     RID       UID  STATE     GROUPS
jack    1000   1001000  enabled   1
guest   1001   1001001  disabled  0

A - in the UID column means nothing numbers that principal — authd has assigned this machine no identifier range, and they will sign in as nobody. See the local store.

lps show <name> #

One principal in full.

$ lps show jack
name           jack
display name   Jack Palfrey
rid            1000
sid            S-1-5-21-2847362817-1094533892-3310298447-1000
uid            1001000
state          enabled
primary group  Authenticated Users [S-1-5-11]
home           /home/jack
shell          /bin/sh
logon types    default (interactive, remote-interactive, network, network-cleartext, batch, new-credentials)
credential     password
groups         Administrators [S-1-5-32-544]
               developers [S-1-5-21-2847362817-1094533892-3310298447-1001] (gid 1001001)
claims         Department (string) = "Engineering"

logon types are the kinds of sign-in the principal may be used for (see lps logon-types below); default means none were chosen, and the machine's default applies. credential is what it signs in with: password, key (an SSH key), either, none (nothing is asked for), or denied.

Groups show a name where this machine knows one, and always show the SID. The two are kept side by side deliberately: the name is what you recognise, the SID is what a security descriptor actually holds, and the moment they disagree is exactly when you need to see both.

Only local groups show a gid. lpsd numbers the groups it owns and nothing else — Administrators and Authenticated Users are numbered by authd, from a table below every source's range, so lpsd genuinely does not know their gid and does not guess. To see the numbers a running session actually holds, read Groups: in /proc/self/status.

lps domain #

This machine's domain SID — the namespace every local principal and local group is numbered under.

$ lps domain
S-1-5-21-2847362817-1094533892-3310298447

Generated at first boot and unique to this machine.

Creating and removing principals #

lps add [name] [options] #

Creates a principal. Run with no arguments, it asks for what it needs:

$ lps add
Name: alice
Full name [optional]: Alice Chen
Additional groups [comma-separated, optional]: Administrators, developers
Primary group [the daemon's default]:
Home directory [the daemon's default]:
Shell [the daemon's default]:
Password for alice:
Again:

  name           alice
  full name      Alice Chen
  primary group  (the daemon's default)
  home           (the daemon's default)
  shell          (the daemon's default)
  groups         Administrators, developers

Create this principal? [Y/n]:
created alice with RID 1002

Any option you supply is not asked for, so scripted invocations keep working unchanged:

Nothing is sent until you confirm, so answering n creates nothing. Everything is sent in one request, so a principal is created whole or not at all: if lpsd refuses the shell, say, no principal is made.

lps never prompts when standard input is not a terminal. A prompt down a pipe would consume the next line of whatever is driving the tool. See From a script below.

The RID is allocated by lpsd and reported back. You do not choose it, and the uid follows from it.

--service #

Creates a principal that may be used only to run a service, and for nothing else. It cannot sign in at a console, over the network, or as a batch job — a sign-on of any other kind is refused even with the correct credential.

Most services do not need one. A service already gets an identity without an account: it runs as LocalService and carries a per-service SID derived from its name, which you can name in a security descriptor like any other principal. Reach for --service when a service needs something a bare SID cannot be — membership of a group, a home directory, or a profile.

A service principal has no credential and cannot be given one. The authority mints its token on the service manager's attestation instead, and only the service manager may ask: nothing else on the system can obtain a token for it, with or without a password.

The restriction is a property of the account rather than of this machine, so it travels with the principal. It is also the reason the flag exists at all: without it, an ordinary account could be named as a service's identity, and the machine would then be able to obtain a token for that account with no credential.

Every principal created without this flag permits every kind of sign-on a person uses and never a service logon, so an existing account cannot become a service identity by accident.

--no-password #

Creates a principal with credential policy none, which signs in without being asked for anything where the client and authority permit credential-free sign-in. No password is collected at creation, including in the interactive flow — an operator who has said the account needs no credential is not then asked to invent one.

$ lps add kiosk --group Administrators --no-password --no-prompt
created kiosk with RID 1003

This is a property of the account, not of a terminal. Nothing scopes it to one console: any client that permits credential-free sign-in can use it, subject to logon-type and originator policy. SSH requires an actual password or an enrolled key and a policy allowing that credential; it refuses none. Credential-free sign-in is the right posture for a live image, where the medium is unauthenticated anyway and anyone holding it can read everything on it. It is the wrong posture for almost anything else.

An empty password is not a way to spell this, and lps refuses one:

$ lps add alice
...
Password for alice:
Again:
lps: an empty password is not a password: pass --no-password to create a
principal that authenticates without one

The two produce accounts that behave differently — an empty password is still collected, still prompted for, and still has to be answered — so having both spellings would mean two things that look identical at creation and diverge at every sign-in. lpsd refuses an empty password too, so the rule holds however the request arrives.

lps remove <name> #

Deletes a principal.

The RID is not reclaimed. Files the principal owned keep naming a SID that now resolves to nobody, and nothing will ever hold that SID again. lps disable is usually what you wanted — see creating accounts.

lps rename <name> <new-name> #

Renames a principal.

$ lps rename erin erin.k
renamed erin to erin.k

Its SID stays, so every file, permission and group membership that names it still does, and it signs in by the new name from now on. Its home directory stays where it was. lps set --home changes the recorded path only; it does not move the directory or its files.

A name held by another principal or by a local group is refused. Changing only the case, erin to Erin, is allowed.

Enabling and disabling #

lps enable <name> / lps disable <name> #

A disabled principal keeps everything except the ability to start a new sign-in. It does not revoke already issued tokens or end existing sessions. Use Task Manager’s sign-out action when existing sessions must end. Signing out can lose unsaved work; session lifecycle explains its permissions and limits, including token references held outside the session's processes.

Both are refused if they would leave the machine with no enabled administrator.

lps logon-types <name> <type>... #

Sets the kinds of sign-in a principal may be used for. Any other kind is refused, even with the right credential.

$ lps logon-types backup network batch
set the logon types for backup
$ lps logon-types backup default
set the logon types for backup

The SSH mapping here follows the current PGSS SSH implementation contract, including its release-qualification and compatible-build limits.

default returns the principal to the machine's default: every kind a person uses, and never service. There is no setting for "no sign-in at all"; lps disable is that.

The last enabled administrator must keep interactive, remote-interactive or network. This is an account-store guard; it does not check whether the corresponding console, service or network path is reachable.

Passwords #

lps password <name> #

Sets a principal's password, prompting twice.

$ lps password jack
New password for jack:
Again:
set the password for jack

This is an administrator resetting somebody else's password. A principal changes their own with passwd, which goes over PGSS Logon instead, so that it works identically whichever source holds the account.

An empty password is refused here for the same reason it is refused at creation. A password doesn't change what a principal signs in with: one created with --no-password keeps signing in with nothing until lps policy <name> password says otherwise (see credentials below). There is no command that deletes a password; lps policy decides whether it is used.

From a script, lps reads a single line from standard input when it is not attached to a terminal, and does not ask for confirmation:

printf '%s\n' "$password" | lps add alice --group Administrators --no-prompt

Credentials and SSH keys #

A principal's credential policy says what it signs in with. Its SSH keys are the public keys it may sign in with over SSH. The two are kept apart: adding a key, or setting a password, never changes the policy, and changing the policy never adds or removes either. Enrolling a key and letting it be used are two decisions.

lps policy <name> <policy> #

$ lps policy erin either
credential policy updated

none is what lps add --no-password gives, and carries the same warning. denied stops a principal signing in and keeps everything else, as lps disable does, but nothing shows it as disabled, so lps disable is usually clearer.

It applies from their next sign-in. lps show and lps key list both say what it is now.

It is refused if it would leave the last enabled administrator nothing to sign in with: denied, key when they have no key, or password when they have no password.

lps key list <name> #

$ lps key list erin
credential  key
ID                                FINGERPRINT                                         ADDED       LABEL
893dab4342ba215def78c4036b598b65  SHA256:QDzrP/cBqV7YSxqoCgCJQqKJlo6ijyJ8U05BIEKmYnI  2026-10-04  laptop

The first line is the credential policy. ID is what lps key remove takes, FINGERPRINT is as ssh-keygen -l prints it, and ADDED is the day the key was added, in UTC.

lps key add <name> <file> [label] #

$ lps key add erin erin.pub laptop
key enrolled; credential policy unchanged

The file is one line of an OpenSSH public key file, such as ~/.ssh/id_ed25519.pub. Ed25519 keys are accepted, and RSA keys of 3072 to 8192 bits; nothing else is. Without a label, the key's own comment is its label.

A key the principal already has is refused, as is a 33rd.

lps key remove <name> <id> #

$ lps key remove erin 893dab4342ba215def78c4036b598b65
key removed

Removing the last key of the last enabled administrator, when a key is all they may sign in with, is refused.

Changing your own keys #

lps is for administrators, but a principal does not need one to manage their own SSH keys. Anyone signed in to an account this machine holds can add a key to it or remove one, through a program that asks on their behalf, such as a desktop settings app. Nothing is changed for anybody else's account: the account is always the one the program's token belongs to.

Three things differ from lps key:

• The current password is asked for, every time. Being signed in shows that someone signed in as you, not that you are at the keyboard now, and a key added from an unattended session would be a way back into the account. A wrong password changes nothing and says Authentication failed.
• An account with no password cannot do it. That is an account whose policy is key or none, or one whose policy is password but that has no password set. There is nothing to prove who you are with, so the change is refused and you are told to ask an administrator, who can make it with lps key.
• A key is removed by its fingerprint, the SHA256: value ssh-keygen -l prints for your .pub file, rather than by lps key list's ID.

Everything else is as lps key add and lps key remove: the same key types and sizes, a key you already have or a 33rd refused, the key's comment as its label. Adding a key does not let you sign in with it unless your credential policy is key or either, which only an administrator can set.

Each change, and each refusal once the account is known, is recorded as an lpsd.credential.changed event, as a change of your own password is. operation.name is ssh-key-added or ssh-key-removed, and outcome.reason says what stopped a refused one, such as wrong-credential. A change an administrator makes with lps key is recorded as lpsd.account.modified instead: see what is recorded.

On the desktop, the program is My Settings, the app for your own account; type my in the launcher to open it. Its SSH Keys section lists your keys by label, fingerprint, type and the day each was added. Add Key… opens a form under the list for the one line of your .pub file and your password. Remove asks for your password under the key before it is taken away, and asks again if it was wrong. An account with no password sees why its keys are an administrator's to change, in place of these forms.

Your password is changed with passwd, or in My Settings.

Changing your own display name #

Programs acting on your behalf can show you your own account as lpsd holds it — your name, display name, credential policy, whether you have a password, and your keys — and set your display name, the human name shown beside your account name. Setting a display name asks for no password, since it is not something you sign in with. Both are served on /run/lpsd/self.sock; see the administrative socket.

Open My Settings (type my in the launcher). In Account, Display Name sets your display name, with Apply once it is changed. The desktop reads it when you sign in, so it shows from your next session.

Profiles #

lps set <name> [options] #

Changes part of a profile, leaving the rest alone.

$ lps set jack --shell /bin/bash --display-name "Jack Palfrey"
updated jack

None of this is identity — no security descriptor names a home directory, and the token carries none of it. It is what login needs in order to start a session, and it reaches login on the logon reply itself.

lps does not create the home directory. It records the path. A principal whose home does not exist still signs in, starting in /, and login says so.

The primary group need not be a membership: authd adds it to the token if it is missing, so the order of two commands does not matter.

Groups #

Local groups are objects with a name, a RID, a gid and a description — unlike well-known groups, which exist on every Peios machine and are not stored here.

lps group list #

$ lps group list
NAME          RID       GID  MEMBERS  SID                                             DESCRIPTION
developers   1001   1001001        2  S-1-5-21-2847362817-1094533892-3310298447-1001  Builds the software

MEMBERS counts principals in this store, which is the only count lpsd can answer for. DESCRIPTION appears when any group has one.

lps group create <name> [description] / lps group delete <name> #

$ lps group create developers "Builds the software"
created the group developers with RID 1001

A group's description says what it is for. Anyone may read it — getent doesn't show it, but Principals Manager does, to everyone.

Deleting is refused while anyone is still a member, or while the group is anybody's primary group. Either would leave a record pointing at something that no longer exists.

lps group rename <name> <new-name> #

$ lps group rename developers engineers
renamed the group developers to engineers

It keeps its SID, so its members, and every permission that names it, stay as they are. A name held by a principal or another group is refused.

lps group describe <name> <description> #

$ lps group describe engineers "Builds and ships the software"
set the description of the group engineers

An empty description, lps group describe engineers "", clears it.

lps group add <name> <group> / lps group remove <name> <group> #

$ lps group add alice Administrators
added alice to Administrators

Removing BUILTIN\Administrators is refused if it would leave no enabled administrator.

Claims #

Claims are named, typed attributes carried on the token and read by conditional ACEs. They are how a security descriptor can say anyone in Engineering rather than naming principals one by one.

lps claim set <name> <claim> <type> [value]... #

$ lps claim set jack Department string Engineering
set the claim Department on jack
$ lps claim set jack Level int64 7
set the claim Level on jack

A claim may hold several values, and may hold none — lps claim set jack Department string empties it, which is different from removing it.

Claim names are matched case-insensitively, so setting department replaces Department.

lps claim remove <name> <claim> #

$ lps claim remove jack Department
removed the claim Department from jack

A claim reaches a principal at their next sign-in. A token's claims are fixed when it is minted, so setting one changes nothing for a session already running.

Exit status #

The split lets a script distinguish "I called this incorrectly" from "it was refused".

Common failures #

cannot reach lpsd … it does not appear to be running — lpsd is not up. It exits if it cannot reach authd, or if the store will not read; check its logs before restarting it.

permission denied — you are not an administrator, or the socket's descriptor does not admit you. See the administrative socket.

there is no principal named … — names are case-insensitive, so this means the account genuinely is not there. lps list will show what is.

there is no group named … and it is not a SID — the name matched no well-known group and no local one, and does not parse as a SID. lps group list shows the local ones.

Principals Manager shows this machine's principals, the users and groups it knows, and lets an administrator manage the local ones. A local principal is one this machine holds itself, in lpsd's store; a built-in one, such as SYSTEM or Administrators, is the same on every Peios machine and is defined by authd.

Start it from the launcher: Principals Manager.

Users and groups #

Users and Groups, in the bar, switch between the two lists.

• A user is listed with their full name, if they have one, whether they are local or built-in, and whether they are enabled. A disabled user keeps everything but can't sign in, and is greyed.
• A group is listed with whether it is local or built-in, how many members it has, and its description: what it is for. Some built-in groups, such as Everyone, have no list of members at all: who is in them is decided by a rule as each person signs in, and they say By rule.

Type in Find to narrow the list to names, full names, descriptions or SIDs containing what you type.

A user or group in full #

Select one to see it in full on the right.

For a user, that is their user ID, primary group, home folder, shell and SID; the kinds of sign-in they may use, such as at the machine or over the network; the groups they are in; and their claims, the named values that permissions written with conditions are checked against. Copy SID copies their SID.

An administrator also sees what a local user signs in with, such as a password or an SSH key, and their SSH keys: the public keys they may sign in with over SSH, each with its label, its fingerprint and the day it was added.

For a group, it is its description, group ID and SID, and who is in it. Who is in a built-in group such as Administrators is recorded on this machine, as a local group's is, so it is listed too. Someone whose primary group it is, is in it.

Select a group a user is in, or a member of a group, to go to it.

Making a user #

New user, in the bar, or Ctrl+N, asks for:

• a name, which they sign in with;
• a full name, if you want one shown;
• a password, typed twice; or tick Signs in without a password, and nothing is asked for on sign-in paths that permit credential-free access; SSH does not permit this;
• whether they are an Administrator, who may change the machine and its users and groups;
• a home folder and a shell, if not /home/<name> and /bin/sh.

Create makes the user with all of it, or not at all: if anything is refused, such as a name already taken, nothing is made and the window says why.

Changing a user #

Select a local user, and their buttons are below their details:

• Edit changes their full name, home, shell and primary group. Their home folder is made at their first sign-in, and is not moved if you change it. Their primary group is the one their new files belong to, and they are in it whatever their other groups.
• Rename changes the name they sign in with. They keep their SID, so their files, permissions and groups stay theirs. Their home stays where it is; change it under Edit if it should follow.
• Set password gives them a new password. A user who signed in without one needs it from then on. Their sessions already signed in carry on.
• Sign-in chooses what they sign in with, and the ways they may sign in.
  • Signs in with: a password, an SSH key, either, nothing (no credential is asked for where credential-free sign-in is permitted, excluding SSH), or nothing accepted (every sign-in is refused, though nothing shows them as disabled). Adding a key doesn't change this, so a key added isn't used until this allows one.
  • May sign in: as the machine's default allows (at the machine, on a remote desktop, over the network, and the rest a person uses), or only the ways you tick. To run a service lets the service manager start a service as them without any password, and is never part of the default.
• Add to group puts them in a local group, or in a built-in one whose members are recorded here, such as Administrators or Users. Remove, beside a group they are in, takes them out of it.
• Add, beside SSH keys, adds a public key: paste one line of their .pub file, such as ~/.ssh/id_ed25519.pub. Ed25519 keys are accepted, and RSA keys of 3072 to 8192 bits. Without a label, the key's own comment is its label. Remove, beside a key, removes it.
• Add, beside Claims, gives them a claim: its name, its type, and its values, one to a line. Each value is checked against the type, and one that doesn't fit is named. A claim of SIDs may name a user or group instead of giving a SID. Edit changes a claim's type and values, and Remove takes it away. A claim with no values is still a claim they have, which conditions treat differently from one they don't.
• Disable stops them signing in and keeps everything else; Enable lets them again.
• Delete removes them, after asking. Their SID is never given to anyone again, so files and permissions that name it name nobody; Disable instead is offered, and is usually what you want.

Changes to how a user signs in, to their keys, to the groups they are in and to their claims apply from their next sign-in. Disabling an account does not end existing sessions. Use Task Manager’s sign-out action when those must end; it can lose unsaved work. Session lifecycle explains the permissions and limits.

Groups #

In Groups, New group (or Ctrl+N) makes a local group, with a name and a description of what it is for. Anyone may read the description.

Select a local group, and its buttons are below its details:

• Edit changes its description; empty, it has none.
• Rename changes its name. It keeps its SID, so its members, and the permissions that name it, stay as they are.
• Add member puts a local user in it. Remove, beside a member, takes them out; a member whose primary group it is has to be given another under Edit first.
• Delete removes it, after asking, once nobody is in it. Its SID is never given to anything again.

A built-in group whose members are recorded here, such as Administrators, has Add member and Remove too, but can't be renamed, described or deleted: authd defines it, the same on every Peios machine.

The local account store protects the last enabled administrator under its sign-in checks. Disabling or deleting the last one, taking away every way they could sign in to administer, or leaving them nothing to sign in with, such as removing the only key of one who signs in only with a key, is refused, and the window says why.

This last-administrator guard does not check whether a console, remote service or network path is reachable. Verify fresh access before closing a working administrator session.

Privileges #

What a person may do beyond what permissions allow them, such as back up any file or shut the machine down, is this machine's local policy: one record per user or group in the registry, which authd reads at every sign-in. Each record may give privileges, an integrity level, an owner for what they make, and a default DACL, the permissions an object they make gets when it has no parent to inherit from. See Assigning privileges for what each does and how records combine.

Privileges, in the bar, lists the records: who each is for, how many privileges it gives, and its integrity. A service's record is named by the service. Select one to see it in full, each privilege with what it lets its holder do. Denied to everyone, the first row, is the privileges no record can give.

A user's page says what they would get in all if they signed in now: the privileges, integrity, owner and default DACL that their own record, their groups' records and Everyone's come to, and which records those are. Signed in chooses the kind of sign-in, such as at the machine or over the network, since a record may be for one kind of sign-in. A group's page says what its record gives its members.

Changing them:

• New record (or Ctrl+N) makes a record, for a user or group here, a well-known name such as Everyone or Network, or a SID. Give them their own record, on a user's page, and Give it a record, on a group's, do the same for them.
• Edit changes what a record gives: tick its privileges, choose its integrity, and type an owner or a default DACL, in SDDL. Anything left empty, the record says nothing about. A default DACL that isn't SDDL authd could use is refused.
• Delete removes a record, after asking. What it gave is no longer given.
• Edit, on Denied to everyone, chooses what no record may give.

Taking SeChangeNotifyPrivilege from Everyone or Administrators is asked about first: without it, nobody who has it only from there can pass through a folder, so no shell starts for them.

A record names a user or local group by its SID, since authd doesn't ask lpsd what a name means; the window does this for you. What authd warns about in the records is shown above the list, with why: a record it ignores, such as one named by a name it doesn't know, or two records for the same principal, such as Administrators and S-1-5-32-544, which both apply and should be one.

On a machine with no policy at all, authd gives Everyone SeChangeNotifyPrivilege and nothing more, and the list says so. The first record saved makes the policy, with that in it, since once there is a policy it is all there is.

Changes apply from each person's next sign-in.

Changes made elsewhere #

The lists are read again every few seconds, so a user, group or privileges record added, changed or removed with lps or reg, or by another administrator, appears without your doing anything. Refresh, or F5, reads everything at once.

What you may see and change #

Anyone may see the users and groups: the identity socket that Principals Manager reads them from answers everyone.

What a user signs in with, and their SSH keys, are shown here only to an administrator: lpsd holds them, and tells nobody else, except each user about their own (see Changing your own keys). The privileges records are shown to anyone signed in, and changed by whoever the registry key's permissions let, which as shipped is Administrators.

Changing them needs BUILTIN\Administrators, enabled in your token, as lps does. Without it, the window says You may look, but not change anything, and why, and offers no changes. Built-in principals and groups can't be renamed or deleted, and the window says so when one is selected.

In a terminal #

lps list lists the users, lps show NAME shows one in full, and lps group list lists the local groups. getent group Administrators lists who is in a group, and lps key list NAME lists a user's keys. lps add, lps set, lps rename, lps password, lps policy, lps key, lps logon-types, lps claim, lps group, lps disable and lps remove make the same changes as the window. See The lps command. The privileges records are registry keys under Machine\Generic\Authn\Policy, read and changed with reg, and token show --all lists what a session's token actually holds.

A principal source says who someone is — their SID, their memberships, their POSIX identifiers. It never says how much this machine trusts them. Privileges and integrity are local policy: authd's alone, decided here, and there is no message with which a source could ask for one.

That policy lives in the registry:

Machine\Generic\Authn\Policy

authd reads it at every logon, not once at startup. A policy change takes effect the next time someone signs in, rather than the next time you restart the one daemon on the system that is most disruptive to restart.

Principals Manager shows and edits it from the desktop. Its Privileges list is the records on this page, and each user's page says what they would get in all, worked out by the same code authd mints from.

One record per principal #

Each subkey is a principal, and holds everything this machine grants them:

Machine\Generic\Authn\Policy
  DeniedPrivileges  REG_MULTI_SZ  ["SeDebugPrivilege"]
  \Everyone
      Privileges    REG_MULTI_SZ  ["SeChangeNotifyPrivilege"]
      DefaultDacl   REG_SZ        "D:(A;;GA;;;S-1-3-4)(A;;GA;;;SY)(A;;GA;;;BA)"
  \Administrators
      Privileges    REG_MULTI_SZ  ["SeBackupPrivilege", "SeRestorePrivilege"]
      Integrity     REG_SZ        "High"
      Owner         REG_SZ        "Administrators"

Keyed by principal rather than by privilege on purpose. One key shows the totality of a principal's authority — reg ls on \Administrators answers "what can an administrator do on this machine?" completely. Authority scattered across twenty per-privilege values is authority nobody audits: a right granted somewhere unexpected does not surface when you look at the principal, and you would have to know to check every other place.

It is also the only shape that holds more than privileges. Integrity, the default owner, the default DACL and the logon types a peer may originate all live on the same record.

Naming a principal #

A subkey's name is either a well-known name or a literal SID:

\Administrators
\S-1-5-21-2847362817-1094533892-3310298447-1000

Names are matched case-insensitively. The recognised ones are SYSTEM, Everyone, Authenticated Users, Administrators, Users, Guests, Local Service, Network Service, Local (everyone signed in on this machine), and the logon types Interactive, Remote Interactive, Network, Batch, Service and Anonymous.

Two limits are worth knowing before you hit them:

BUILTIN\Administrators cannot be a subkey name. A backslash is the registry's path separator, so the qualified spelling is unrepresentable. Write the bare name.

A local group's name does not resolve. authd cannot know what developers means without asking lpsd, and policy must never depend on a principal source being up — that would make "what may this principal do" unanswerable exactly when a source is broken. Name local groups by SID, which lps group list will show you.

A subkey that is neither a known name nor a parseable SID is ignored with a warning. It is worth checking for that warning after editing: a record naming nobody sits in the key looking authoritative and applying to no one.

Two subkeys naming one principal, such as \Administrators and \S-1-5-32-544, both apply, and authd warns about them. Their privileges add up like any two records', but for integrity, Owner and DefaultDacl whichever is read first wins, which is an order nobody chose. Merge them into one. Principals Manager shows the warning above its Privileges list.

If the key exists, the key is the whole policy #

This is the most important behaviour on the page.

authd carries a compiled-in floor, but it applies only when the key is absent entirely. It is not merged in value by value. So a policy you write is the complete policy: anything not granted below is not granted.

The alternative — a compiled default that each record replaces — fails in the wrong direction. An administrator who writes one record believing they have locked the machine down would still be handing out whatever a compiled table said for every principal they did not mention, from a table they cannot read. That is a security failure, and a silent one. Failing towards less privilege makes things stop working, which is far easier to diagnose than authority you did not know you were granting.

An unreadable key is treated as granting nothing rather than as absent, for the same reason: reading it as absent would silently restore every privilege an administrator may have deliberately removed, at the one moment nobody can check.

What a machine ships with #

The defaults are registry data, not compiled in — authd-policy.reg, shipped to /usr/share/regim/ and applied if the image opts in. So they can be read, edited, and replaced wholesale by an image that wants a different policy, rather than being invisible inside a binary.

A stock machine grants:

The operational set is SeBackupPrivilege, SeRestorePrivilege, SeShutdownPrivilege, SeRemoteShutdownPrivilege, SeSystemtimePrivilege, SeSecurityPrivilege, SeLoadDriverPrivilege, SeImpersonatePrivilege, SeIncreaseQuotaPrivilege, SeIncreaseBasePriorityPrivilege and SeProfileSingleProcessPrivilege.

SeDebugPrivilege is deliberately not granted. It writes to any process regardless of integrity label, so it is the single privilege that most directly defeats the integrity boundary, and ordinary administration does not need it. Add it when a machine genuinely does.

Three privileges are never granted by the shipped policy and should not be added: SeCreateTokenPrivilege mints any identity without going near authd, which would make every other control here decorative; SeTcbPrivilege and SeAssignPrimaryTokenPrivilege belong to the trusted computing base.

Note that Administrators is granted SeChangeNotifyPrivilege directly, not only through Everyone. Privileges accumulate across every SID on a token, so that repetition is insurance: if someone edits the key and drops the Everyone record, ordinary users lose the ability to traverse a directory — but administrators keep working and can repair it.

How the values compose #

Privileges accumulate. A token holds the union of every record naming a SID it carries — the principal's own, and each of their groups. A group marked USE_FOR_DENY_ONLY contributes nothing.

DeniedPrivileges wins. Listed on the Policy key itself rather than on a record, it is applied after the union, so no record you have not read can defeat it. It is on the parent key so it cannot collide with a principal who happens to be called Denied.

Integrity, Owner and DefaultDacl are single values, so they cannot accumulate. The principal's own record wins outright; otherwise the groups decide:

• Integrity takes the maximum across the groups that name one.
• Owner and DefaultDacl have no ordering to compare, so two groups naming different values is a misconfiguration: it logs a warning and falls back to the default rather than picking by whichever the registry enumerated first. Two groups naming the same value is not a conflict.

The user's record winning outright is what makes a principal possible to lower. Under a plain maximum, a guest whose own record said Low would still come out Medium the moment any group they belonged to named Medium. The consequence is worth stating plainly: a group cannot impose an integrity floor on a member. If Administrators names High and a member's own record names Low, that member gets Low.

Writing each value #

Privileges — REG_MULTI_SZ #

Full ABI names, SeBackupPrivilege rather than SeBackup, matched case-sensitively. A name this build does not recognise is dropped with a warning and the rest of the list still applies — a policy written for a newer Peios should not lose the privileges it spelled correctly.

An empty list is meaningful: it grants nothing, and is different from the value being absent.

Integrity — REG_SZ or REG_DWORD #

A tier name, matched case-insensitively:

Or a raw REG_DWORD. The kernel compares integrity numerically and any value is legal, so the numeric form reaches levels between the tiers — 8193 sits just above Medium. Use the name unless you need that.

A principal no record names gets Medium. That default is compiled in and is not affected by the key existing, because unlike a privilege it is not a grant: every token must carry some level to be valid at all.

Owner — REG_SZ #

Which principal owns objects this token creates. Names a principal, exactly like a subkey name does; authd converts it to the index the token actually carries, which is a number meaningful only within one token and different on the next logon.

Absent — the ordinary case — means objects are owned by their creator.

The case this exists for is a shared administrative estate: objects an administrator creates being owned by Administrators rather than by the individual, so they remain manageable when that person's account goes away.

DefaultDacl — REG_SZ #

The DACL an object gets when this token creates it with no parent to inherit from, written as SDDL. The shipped policy names it on the Everyone record:

D:(A;;GA;;;S-1-3-4)(A;;GA;;;SY)(A;;GA;;;BA)

That is the owner, LocalSystem and BUILTIN\Administrators, full control, and nobody else — the same shape authd stamps on a home directory. S-1-3-4 is OWNER RIGHTS, which the access check resolves against the object's owner at the time of the check. You can also write it as the alias OW. It has to be OWNER RIGHTS rather than CREATOR OWNER: the kernel copies a default DACL onto a new file verbatim and substitutes no placeholders, so a CREATOR OWNER ACE would name nobody.

The value is a fallback and is reached rarely. Whenever the parent has inheritable ACEs the child takes those and the default DACL is not consulted (see Inheritance), and every filesystem root on Peios carries inheritable ACEs. What reaches it is an object with no parent, such as an abstract socket, or a child of a container whose descriptor was written without inheritable ACEs. There is no kernel fallback beneath it: a token with no default DACL leaves such an object with a null DACL, which grants every caller everything.

SDDL rather than raw bytes because the whole argument for policy living in the registry is that an operator can read it. Conditional ACEs are preserved, so D:(XA;;GA;;;WD;(@USER.Department == "Engineering")) works and keeps its condition.

A value that does not parse is dropped with a warning and the token is minted with no default DACL — a typo costs the customisation, not the session, but it does leave the null-DACL case open until it is corrected.

LogonTypes — REG_MULTI_SZ #

The logon types this principal may originate — request of authd over /run/logon.sock on somebody else's behalf. This is a statement about the asker, not about the account being signed in: login originates Interactive logons for whoever is at the console, a graphical greeter would too, and a web console would originate Network ones.

\S-1-5-80-…-…   (a greeter's service SID)
    LogonTypes  REG_MULTI_SZ  ["Interactive"]

The names are Interactive, Network, Batch, Service, NetworkCleartext, NewCredentials and RemoteInteractive, matched case-sensitively; an unrecognised name is dropped with a warning and the rest still applies.

The proposed logon type is not cosmetic. It selects the group SIDs the minted token carries — Interactive puts S-1-5-4 on it, RemoteInteractive puts S-1-5-4 and S-1-5-14 — and policy records can key on those SIDs, so the type must be what the peer is permitted, never merely what it proposed. A greeter granted ["Interactive"] cannot mint itself a network-shaped token, nor the reverse.

A principal with no LogonTypes originates nothing. SYSTEM is the exception and is permitted every type unconditionally — it administers this very key, so a registry constraint on it would enforce nothing, and authd does not pretend otherwise.

An empty list revokes: it is "may originate nothing", distinct from the value being absent only in that it says so on the record.

LogonSocketDescriptor — REG_SZ, on the Policy key itself #

The security descriptor /run/logon.sock carries, as SDDL, read once at authd startup. The built-in value gives SYSTEM and Administrators full access, and gives every authenticated principal connect access alone, so that anyone signed in can change their own password and sign themselves out:

O:SYG:SYD:P(A;;GA;;;SY)(A;;GA;;;BA)(A;;0x100082;;;AU)

Connect access is FILE_WRITE_DATA; 0x100082 grants it with stat and sync. Reaching the socket does not let a peer originate a logon: that is the LogonTypes record above, and a peer without one originates nothing however it connected. So admitting a new originator that is not already an authenticated principal takes both edits, and one that is takes only the record.

A replacement descriptor that leaves out the AU entry turns off self-service password change, and signing yourself out, for every principal it leaves out.

SessionEndSecurity — REG_SZ, on the Policy key itself #

Who may sign somebody else out: end a logon session that is not their own. authd does the work when asked over /run/logon.sock (Session lifecycle); this value, as SDDL, is the security descriptor it access-checks the caller's token against, for the one right 0x1 (every generic right maps to it). It is read on every request, so an edit applies to the next one. With the value absent, the descriptor is:

O:SYG:SYD:(A;;0x1;;;SY)(A;;0x1;;;BA)

— SYSTEM and Administrators. Granting 0x1 to a group lets its members sign anybody out.

Signing yourself out needs nothing here: a person may always end their own session. And nothing here lets anyone end SYSTEM's session, Anonymous's, or a service's — a service is stopped through the service manager.

A value that is present but unusable — not a REG_SZ, empty, or not valid SDDL — lets nobody sign anybody else out until it is fixed or removed, and authd logs why on each request. It does not fall back to the default, which might grant more than the site meant.

Locking a machine down #

To forbid a privilege regardless of what any record says:

Machine\Generic\Authn\Policy
  DeniedPrivileges  REG_MULTI_SZ  ["SeDebugPrivilege", "SeLoadDriverPrivilege"]

That is one edit, in one place, that a record you have not read cannot defeat. Removing the privilege from each record individually relies on having found them all.

What this cannot express yet #

Account sign-in restrictions are a separate control. These privilege records decide what a session gets. The account store also supports lps logon-types to limit which kinds of sign-in an account may use, and lps disable to prevent new sign-ins altogether. LogonTypes above constrains what the asking service may request; it does not replace the account restriction. Follow the account command reference for supported types and the last-administrator guard.

Privilege constants do not establish assignment support. Earlier privilege guidance described SeTakeOwnershipPrivilege, SeRelabelPrivilege and SeSystemProfilePrivilege as absent from the ABI and therefore impossible to assign. The current generated KACS ABI defines constants for all three. That contradicts the ABI-absence claim, but does not by itself establish the accepted privilege-name table in authd or a service configuration, or a release in which assignment became available. Confirm support for the deployed build and inspect the actual token rather than relying on either blanket claim. Even when take-ownership is available, changing the owner does not guarantee DACL repair.

Seeing what a token actually got #

$ token show --all

[privileges] lists what the token holds and integrity shows the label. A privilege the tool cannot name appears as <privilege bit N> rather than being omitted, so the list is always complete even when the name table is not.

To see what a sign-in would get before anyone signs in, open the user in Principals Manager: it works the policy out for them, for each kind of sign-in, and says which records it came from.

See also #

• Privileges — the model these records feed.
• The token command — reading the privileges and integrity a live token actually carries.
• Authorities and principal sources — the accounts these records apply to.

Task Manager shows what is running on the machine now: every process, which is a program that is running, with how much of the processor and memory it is using, what it belongs to, and who it runs as. What is defined to run, rather than what is running, is Services Manager's.

Start it from the launcher: Task Manager.

It looks at the machine as you, so it shows exactly what you may see of each process, and says what you may not, and why. It offers to change something only where you may.

Processes, Performance, Jobs and Signed in, in the bar, switch between its four views.

Find the right process before acting #

1. Open Processes. Use Find for a name, PID, person or service, or sort CPU or Memory to investigate resource use.
2. Select the process. Check its command, who it runs as, what started it, and the service or job it belongs to. Some details may be hidden by permissions.
3. Choose the scope of the action. To stop a service and everything it started, use Stop service; to stop a submitted job, use Stop job. Use End process when you intend to end only that process.
4. Read the confirmation and refresh the view to check the result. Ending a service's main process may cause peinit to restart it.

A process is one running program. A service is a persistent definition managed by peinit, and can start a new process after the old one ends. A submitted job is work someone asked peinit to run and watch. For those managed lifetimes, see Services and jobs. For process states and terminal signals, see Process lifecycle.

The processes #

Each process is listed with its name, its PID (the number the system knows it by while it runs), who it runs as, and its share of the processor (CPU) and the memory it holds. The CPU share is of the whole machine, since the last look, and is filled in from the second look on. The bar at the bottom gives the totals.

Group by chooses how they are arranged:

• None, which it opens with, lists them all together.
• Service puts each process under the service or job it belongs to, as peinit, the service manager, started it. A service's heading says its state; a job, which is a program someone asked peinit to run and watch, such as a person's desktop session, says who it runs as. Not in a service holds peinit itself.
• Person puts each under the person or service it runs as.

Name, PID, CPU and Memory, at the top of the list, sort by that. Find narrows the list to processes whose name, PID, person or service contains what you type.

The kernel's own threads, which no person runs, are left out; tick Kernel threads to show them.

The list is read again every two seconds. Refresh, or F5, reads it at once.

A process in full #

Select a process to see it in full on the right: what it is doing, how long it has run, its CPU, memory and threads, what started it (select it to go to it), the command it was started with, the service or job it belongs to and which part of it this is, who it runs as, the signed-in session it is part of, and its integrity.

Protection says whether the process is protected: signed as part of Peios, which closes it to every process not signed at its level, however much authority that process has. Mitigations are the hardening the process runs with, such as no memory being both writable and executable, each with what it does. See The process security block.

Ending a process, or stopping its service or job #

Below a process's details are what you may do to it:

• End process asks first, then asks the process to end. One that hasn't ended after five seconds is offered End it now, which ends it at once, without its finishing what it is doing. The process is held onto from the moment you ask, so another process given the same PID later can't be ended by mistake.
• Stop service, for a process that belongs to a service, asks peinit to stop the service, and everything it started. It stays stopped until it is started again. Ending a service's main process instead counts, to peinit, as the service crashing, and it may start it again; the window says so before you do.
• Stop job, for a process in a job, asks peinit to stop the job.

Each is there only where you may do it: End process where the process's permissions let you end it, and Stop where peinit says you may stop that service or job. Where you may not, the pane says why instead. A protected process can't be ended by any program not signed at its level.

Performance #

Performance shows the machine as a whole: how busy its processors are, how much of its memory is in use, and how fast each disk and network interface is moving data. Each is listed down the side with a small graph; select one to see it in full, with a graph of the last two minutes, newest at the right.

• CPU graphs how much of the processors' time is in use, and how much of that is the kernel's own work. Each processor gives each logical processor a graph of its own. Below are the processor's model and speed, the number of processes and threads, how long the machine has been up, and the load average: how many threads were running or waiting to, on average over the last 1, 5 and 15 minutes.
• Memory graphs how much is in use, and shows what all of it is made of: in use, cache the kernel gives back when programs need it, and free. Available is what programs could be given now. Committed is what programs have been promised, against how much may be.
• Each disk graphs how much of the time it was busy (its active time), and how fast it read and wrote. Its capacity, and what it has read and written since the machine started, are below.
• Each network interface graphs how fast it is receiving and sending, in bits a second as networks are measured. Its state, link speed and hardware address are below; its addresses and settings are Network Manager's.

The figures are the kernel's own, which anyone may read, so everyone sees the same view. Speeds are worked out between one look and the next, every two seconds. Nothing is kept once the window closes.

Jobs #

A job is a program someone asked peinit to run and watch, outside any service: a person's desktop session is one. Jobs lists them: what each is, its state, who it runs as, and how far it says it has got. A job in full shows what it last said of itself, its progress, its program and process, who it runs as and who asked for it, when it started and ended, and how it ended. Stop job is there where you may stop it.

peinit lists a job only to those who may see it: by default, whoever asked for it, and Administrators. The others are left out, and the window says so. A job that has ended stays in the list for a minute.

Who is signed in #

Signed in lists each session, which is one sign-in: who, how (at the machine, on the desktop, over SSH, or over the network), since when, and how many of its processes you can see. A session in full lists its processes, each of which leads to it, and its desktop session, if it has one. Services sign in too, each in a session of its own; tick Services' sessions to show them.

The full list is the kernel's, which only Administrators may read. Anyone else sees the sessions their own processes are in, and the window says so.

Signing someone out #

Sign out, in a session's details, ends the session: authd ends every process running in it, asking each to end and, after a few seconds, ending any that haven't. The window asks first, and says so when the session is its own. What came of it is said afterwards, including any process authd couldn't end, which keeps the session open.

You may sign out your own sessions, and anyone's the machine's permissions allow, which as shipped is Administrators. Where you may not, the window says why. A service's session ends when its service is stopped, and the kernel's own sessions never end. See Ending a session.

What you may see #

What you may see of a process is its own permissions' to say:

• Its name, CPU, memory and what it belongs to are visible to everyone, by default.
• Who it runs as, and the command it was started with, are visible to the person it runs as and to Administrators. Anyone else sees the process without them, and a note above the list says how many processes that is.
• A protected process, such as peinit or authd, is closed to everyone, Administrators included: only processes signed at its level may look into it. It is still listed, with its protection, and a note above the list says how many there are. Where peinit can say which service a protected process is, it is listed under that service.

A process in a job you may not see is listed under A job, and says so.

In a terminal #

The toolset documented here does not yet include ps; use Task Manager for the process list. The documented terminal tools cover these narrower tasks; replace PID, NAME and ID with the process, service or job/session you have checked.

The same access restrictions apply to terminal tools. logonse list can show only a partial view; a missing entry is not proof that nothing is running. Read Controlling services for service and job commands, and End, suspend, or resume a process before sending signals.

To see what is running, open Task Manager from the launcher. Find a process by name or PID, check its CPU and memory, and select it to see who it runs as and which service or job it belongs to. Start with the Task Manager guide for the controls and the limits on what you can see.

A process is a running program, together with its memory, open resources, and the state the system keeps for it. A thread is one line of execution inside that process. Every process starts with one thread and can create more; its threads share memory and open resources while each makes progress through its own work.

The actors of the system #

Every action, such as opening a file or sending data, is performed by a thread. The system checks whether that thread is allowed and records which thread acted. Each thread acts as a person, a service, or the system itself; there is no "nobody" state. Its token carries that identity, and a new child process begins with its parent's identity.

The thing to stop depends on what you want to achieve:

A service is a persistent definition; a process is one thing running now. A submitted job is work someone asked peinit to run and watch. A terminal's job-control group is another use of "job", described in Process relationships and job control.

What a process has #

The PID identifies a process while it exists and can be reused afterwards. The Process GUID identifies that one process permanently. Neither tells you who it runs as. For a lasting event record, use the GUID; before acting on a PID, check the current process again.

The Process Security Block (PSB) holds the GUID, protection, hardening and the process's own permissions. Being able to see a process does not mean you may stop or inspect all of it.

Where to start #

• Task Manager: find a process, investigate resource use, and choose a process, service, or job action.
• Process lifecycle: interpret states and safely end, suspend, or resume a process.
• The process and thread model: understand threads, PIDs, GUIDs, and identity.
• Creating processes: understand why starting a program adds a process, and why a process can change programs.
• Process relationships and job control: understand parents, terminal process groups, and sessions.
• The Process Security Block: understand protection and access refusals.

The syscall and threading-library contracts are in the developer Process runtime reference.

A process row in Task Manager represents a running program; its thread count tells you how many lines of execution it contains. Use the PID to find it now, the Process GUID to match historical records, and its token identity to understand who it runs as.

A running program has two separable parts: the threads, which run, and the process, which contains them.

The thread is the part that runs — one line of execution, a single sequence of steps the system works through. A machine with several cores runs that many threads genuinely in parallel, one per core; a single core runs many threads by switching between them. Which thread runs, on which core, and for how long is decided by the system's scheduler — a subject of its own. Some tools and logs call a thread a task; it is the same thing.

The process is the boundary around a group of threads. It does not run — it contains. A process holds the things its threads share: their private memory, their open files and connections, and their identity. Every thread inside one process sees the same memory and the same open resources; threads in two different processes do not. That separation is what stops one program from reaching into another's memory or files.

The thread does the work; the process is the shared space the work happens in. A program that does one thing at a time is a process with a single thread. A program that does several things at once is a process with several threads, all sharing one space.

Why the thread is the more basic idea #

Threads, not processes, are the fundamental unit: what the system runs is threads, and a "process" is the answer to the question "what does this thread share, and with whom?" Bundle some threads together so they share one memory, one set of open resources, and one identity, and that bundle is a process. Give a thread its own fresh, separate memory instead of sharing an existing one, and you have made a new process.

This matters because it explains creation. Making a new thread and making a new process are the same mechanism with a different answer to "how much does the new line of execution share with the one that made it?" Share everything, and the result is another thread in the same process. Share nothing, and the result is a new process. Everything in between is possible too. How the operation is actually performed is covered in Creating processes.

What threads share, and what they don't #

Within one process, every thread shares:

Each thread keeps its own place in its sequence — which step it is on right now. That is the point of having more than one: each thread makes progress through its own work independently of the others.

There is one exception to the shared identity. A single thread can temporarily act as a different principal — for example, a service handling a request can act as the requester for that one piece of work, then revert. Only that one thread is affected, and only until it reverts. This is covered in Impersonation; here it is enough to know that "every thread in a process shares the process's identity" is the default, not an unbreakable rule.

Naming a process #

The system gives each process a number called its process ID, or PID, so that people and other programs can refer to it — to inspect it, signal it, or wait for it to finish. Threads are individually identifiable too, by a thread ID — see the developer thread operations reference.

A PID is short and convenient, but it only names a process while that process exists. Once a process ends, its PID can later be reused for a completely different process. A PID tells you which process is which right now, but it is useless as a lasting record — two unrelated processes can hold the same PID at different times.

For that, every process also has a Process GUID (globally unique identifier): a name that is never reused, assigned to each process when it starts and fixed for the rest of its life. Where the PID is the convenient short handle for the moment, the Process GUID is the permanent one — it identifies that one specific process and no other, even long after it has ended. This is what lets a record of something that happened on the system name exactly the right process, with no chance of confusing two that happened to share a PID.

Both the PID and the GUID refer to a process. Neither says who the process is acting as — that is a separate question, answered by its identity rather than by any number or name.

Where to go next #

For interpreting a state or safely sending a signal, continue with Process lifecycle. To understand what a new program starts with, read Creating processes.

Starting a command or application can create new processes. In Task Manager, select one to see its parent, command and service or job. A new process gets a new PID and Process GUID, but a running process can also change the program it runs without changing either identifier.

These two cases explain most changes you see in the process list. You do not need to call the creation APIs to start an application from the launcher or run a command in a terminal.

Splitting: one process becomes two #

A running process can create a near-copy of itself. The original is the parent; the new process is its child. This is called fork.

The child gets private memory copied from the parent, copies of its open resources, and the same identity. Changes to one process's private memory do not change the other's. The child has its own PID and Process GUID, and some per-process state starts fresh. Identity inheritance is covered in Token lifecycle; the precise inheritance list is in the developer creation reference.

Replacing: same process, different program #

A process can replace its current program with another, called exec. Its PID and Process GUID stay the same, and it retains its identity; the previous program's memory and code are replaced. A changed program name therefore does not by itself mean a different process has taken over that PID.

For the identity rules, including programs marked to run as another principal, see Token lifecycle. The exact preserved and reset state is in The exec family.

Putting them together #

Launching a new program commonly combines the two steps: create a child, then replace the child's program. Spawn combines this pattern for callers. Thread creation uses the same underlying creation mechanism with resources shared instead of private; the general mechanism is called clone.

For operating the system, check the resulting process and what manages it. If a service keeps creating replacement processes, inspect the service's status and supervision policy, rather than repeatedly ending each new PID. API details belong in the developer process creation reference.

Getting hold of the new process #

A PID can be reused after a process ends. Recheck the current name, command, owner and service or job before signalling a PID from a terminal, especially if it came from an old log or an earlier inspection.

Programs can hold a pidfd, a file-descriptor handle tied to one specific process, obtained at creation or for a process that already exists. Unlike a bare PID, that handle cannot later refer to a different process; it can be used to wait for the process or signal it. Task Manager holds onto the process from the moment you ask to end it, protecting that action against PID reuse. For code that needs this guarantee, see Process handles.

Where to go next #

Process lifecycle explains states, termination, and cleanup. If you are implementing a launcher or threading library, use the developer Process runtime reference.

Read a process's state before deciding what to do. A sleeping process can be healthy, a stopped process is paused rather than finished, and a zombie has already ended. Use Task Manager to check the process, its parent, and whether a service or job manages it.

The states it passes through #

While it exists, a process is in one of a handful of states, and the system moves it between them. Most of the time it is either running — executing, or ready to run the moment a core is free — or sleeping, paused while it waits for something to happen, such as data to arrive or a timer to fire. A sleeping process uses no processor time until what it is waiting for is ready; most processes spend most of their lives asleep.

A few states are worth knowing by name:

• Stopped — suspended (for example by job control when a job is paused at the terminal); it does nothing until told to resume.
• Traced — stopped under the control of a debugger that has attached to it, so the debugger can inspect and step it.
• Uninterruptible sleep — waiting on something the system will not interrupt, almost always a brief piece of disk or device I/O. A process here cannot be woken or even killed until the operation finishes; it normally lasts an instant, and a process stuck in it is a sign that hardware or a filesystem is stuck too.
• Zombie — finished, but still held as a result waiting to be collected (see below).

Once its result has been collected the process is gone, removed from the system entirely.

End, suspend, or resume a process #

First check the scope. Stop service or svctl stop NAME asks peinit to stop a service and its processes; Stop job or svctl job stop ID stops a submitted job. Ending a service's main process directly can count as a crash and trigger a restart. See Controlling services.

For one process, Task Manager's End process asks it to end, then offers End it now after five seconds if it is still there. The immediate option does not let the program finish its work. Task Manager holds the process so a reused PID cannot redirect that action.

From a terminal, use kill. Replace 4821 in these examples with the PID you have just checked:

$ kill 4821                 # send TERM: ask the process to terminate

Give it time to finish, then refresh Task Manager and check the result. Only if TERM has failed, and losing unfinished work is acceptable, consider:

$ kill -KILL 4821           # force termination without application cleanup

To pause a process and later let it continue, use the documented stop and continue signals:

$ kill -STOP 4821           # suspend
$ kill -CONT 4821           # resume

Suspension is not completion: the process does no work until resumed. Check that pausing it will not interrupt work other programs or people depend on. This targets one process, not a whole service or terminal pipeline.

TERM and KILL require permission to terminate the process; STOP and CONT require permission to suspend or resume it. Protected processes also require sufficient program trust. Being an administrator or sharing a terminal session does not bypass protection. See Process permissions.

A successful kill exit status means the signal was sent, not that the process has finished. Exit status 1 means a signal could not be sent, for example because the process no longer exists or you may not signal it. Check the refreshed process or managed-service/job status before declaring it stopped.

Two ways a process ends #

A process ends in one of two ways.

Most often it ends on its own: it finishes its work and stops. A process that ends this way leaves behind an exit status — a small record of how it went, usually just "succeeded" or "failed" (and, on failure, a number giving a rough reason). The act of a process ending itself is called exit.

The other way is that a process is ended by a signal from outside. Its exit status records the terminating signal. This is different from the stopped state above, which means suspended and able to resume.

Either way, a record of the process remains until its result is collected.

Collecting the result #

Whenever a child changes state — ends, is stopped, or resumes — the system sends its parent a signal, SIGCHLD, prompting it to check. The parent then reads the child's exit status. This is called waiting for the process.

Between the moment a process ends and the moment its parent collects the result, the finished process is a zombie: no longer running, but with the system still holding its exit status so the parent can read it. Despite the name, a zombie is harmless — it does no work and uses almost nothing; it is a result waiting to be collected. The instant the parent collects it, the zombie is gone for good.

If a parent never collects, zombies accumulate — finished processes whose results no one read. That is a fault in the parent, not normal behaviour. Inspect the parent and its service or job; a zombie has already finished, so sending it another termination signal does not make the parent collect it.

A parent holding a pidfd for its child can wait on it directly — the dependable way to be told the exact moment the child ends.

The exact calls — every wait variant, and how an exit status is read — are in the developer process lifecycle reference.

When the parent ends first #

A parent does not always outlive its children. If a parent ends while one of its children is still running, that child becomes an orphan.

Orphans are adopted automatically, and keep running with a new parent. The system's first process — PID 1, which on Peios is peinit — is the final adopter when no nearer subreaper takes responsibility. When the adopted child ends, its new parent collects the result.

PID 1 is the catch-all. A subreaper can instead adopt orphaned descendants within its own subtree; service and container managers use this to retain responsibility for the work they launched. For the programmatic contract, see Orphan adoption and subreapers.

What the system cleans up #

When a process ends, the system reclaims what it was using. Its private memory is freed and its open files and connections are closed.

It also releases its identity. A process acts as a principal, carried on its token; when the process ends, its hold on that token is released. If other processes were sharing the same identity — for example, siblings from the same login — the identity lives on for them, and the system clears it away only once nothing is using it any more. The details are in Token lifecycle.

The process's PID becomes available for the system to assign to a future process. Its Process GUID is not reused — it remains a permanent marker of that one process, so records of what it did still point unambiguously back to it long after it is gone.

Where to go next #

Processes are arranged into a family tree and grouped together in ways that matter for running them. That is Process relationships and job control.

Use a process's parent to trace what started it. Use its service or submitted job to choose a managed stop. At a terminal, use the process group to understand which commands receive keyboard signals together. These are different relationships; stopping one PID need not stop all the work it belongs to.

Processes are related by descent, forming a family tree, and by grouping, which lets terminal job control handle several together.

The family tree #

Every process was started by another, so every process has a parent: the process that created it. A process can refer to its parent by the parent's PID, sometimes called the PPID (parent process ID).

Follow the parents upward and they all lead back to the same place — PID 1, the first process, which the system starts at boot. Every other process descends from it, directly or through a chain of parents, so the processes on a running system form a single family tree rooted at PID 1. This is the same tree that makes orphan adoption work: when a process loses its parent, PID 1 takes over the role, as covered in the lifecycle.

A few processes at the very root of the tree are special. PID 1 is the first process started at boot — on Peios, peinit — and the ancestor of all the rest; the system protects it, refusing to kill it with any signal it has not chosen to handle, because losing it would bring down the whole tree. Beneath the userspace processes the kernel runs threads of its own: PID 0 is the idle process (what a core runs when it has nothing else to do), and PID 2, kthreadd, is the parent of every kernel thread. The kernel's threads — among them the worker threads (kworker) that run deferred work and the threads that service hardware interrupts — appear in a process listing as the system's own work rather than as programs loaded from disk.

Process groups #

Several processes often do one job together. In a pipeline — the output of one command feeding into the next — each command is its own process, but they form one job: you stop, pause, or resume the whole job at once, not a piece at a time.

To make that possible, related processes are collected into a process group. A process group is a set of processes treated as a unit, so that an action — most often a signal, like the one that stops a job — can be delivered to all of them together instead of one by one.

A terminal job, such as a pipeline, is not the same thing as a submitted job watched by peinit. Task Manager's Jobs view and svctl job operate on submitted jobs; terminal job control operates on process groups. See Jobs and operations.

Sessions and the terminal #

Process groups are themselves collected into a larger unit: a session, tied to the terminal the work is running at.

A terminal can only take input for one job at a time, so within the session one process group is the foreground group: the one connected to the keyboard, the one typing reaches, the one a stop-or-interrupt keystroke acts on. Any other groups are in the background, running without holding the keyboard. Moving a job between foreground and background — and starting, stopping, and resuming jobs — is job control.

Ctrl-C sends the terminal's interrupt signal to the foreground process group; Ctrl-Z sends its stop signal. A command such as kill -STOP PID targets the named process instead. Resume that process with kill -CONT PID when permitted; see suspending and resuming. Keyboard signals and explicit kill commands take different permission paths, as explained in Signals in detail.

A different kind of "session" #

The word "session" has two meanings here, and they are unrelated:

• A job-control session, described above, organises processes at a terminal — which groups share a terminal, which one is in the foreground. It says nothing about who anyone is.
• A logon session records one sign-in — a single authentication event — and ties together every identity token that came from it. It is part of the identity model, covered in Logon sessions.

They often line up in practice — signing in at a terminal creates a logon session, and the processes run there share a job-control session — but they are separate things answering separate questions: "which processes share this terminal?" versus "where did this identity come from?"

Where to go next #

Beyond its place in the tree and its groups, every process carries a bundle of its security-related settings — its Process Security Block. That is The Process Security Block.

When Task Manager hides details or refuses End process, inspect the process's Protection and Mitigations. In a terminal, logonse psb --pid PID shows its protection, hardening and Process GUID without changing them.

A process's identity — who it is acting as — is carried on its token, and can change moment to moment, since a thread can impersonate another principal. A process has a second aspect that is independent of identity: what it is. What program is it running? How trusted is that program? How hardened is it against attack? Who is allowed to operate on it?

Those facts are gathered in one place — the Process Security Block, or PSB. Every process has one. Where the token answers who this process is acting as, the PSB answers what this process is. Unlike the token, the PSB never changes when a thread impersonates: impersonation changes who, never what.

What the PSB holds #

• Its permanent name. The process's Process GUID — the never-reused identifier — lives on the PSB.
• How trusted its program is. When a process starts running its program, the system checks the program's cryptographic signature and records from it how trusted the program is. This is the process's PIP (Process Integrity Protection) label, and it decides which other processes are allowed to inspect, signal, or interfere with this one. The barrier is based on what program is running, not on who is running it: even a fully privileged process cannot disturb a more-trusted one. The full treatment is Process integrity protection.
• How it is hardened. A set of mitigations — restrictions the process carries on what it may do with its own memory and code, so that a bug or injected code has far less room to do harm. They can only ever be tightened, never loosened. The catalog and rules are Process mitigations.
• Who may operate on it. Every process has its own security descriptor — the rules for who is allowed to act on the process itself: inspect it, signal it, and so on. It lives on the PSB alongside the rest.

A few more specialised settings live here too — a process can be marked so that it may no longer create children, for instance — but those four are the core.

Inspecting and managing the PSB #

A process's PSB can be read by anyone the process's permissions let see its name and CPU use, which by default is everyone — even where the process is protected and nothing else about it can be seen. That is what lets a tool say why a process is closed to you.

• On a terminal, logonse psb --pid PID shows a process's protection, mitigations and GUID, and with --mitigations turns mitigations on.
• On the desktop, Task Manager shows them for the process you pick.
• From a program, read /proc/<pid>/psb, or call peios_process_psb in the SDK.

When an action is refused #

Being able to see a process's name or PSB does not grant control of it. Its security descriptor determines which actions your identity may perform. Signals also have to pass Process Integrity Protection (PIP): the program sending the signal must have enough trust to act on the target.

The PSB inspection surface does not require PIP dominance, which is why a tool can explain that a process is protected even when its other details are closed. Detailed inspection and signalling still require it. Even SeDebugPrivilege does not bypass PIP, and impersonating a different identity does not change the calling program's trust.

For a managed service, use Stop service or svctl stop NAME when permitted. That asks peinit to perform the managed action under the service's own permissions, instead of trying to signal its protected process directly. See Who can manage a service.

Before changing mitigations #

logonse psb --pid PID is an inspection command. Adding --mitigations MASK changes hardening: those flags can only be turned on, never cleared during the process's lifetime. Check the mitigation rules and the logonse reference before using that option. It is not a way to gain permission to inspect or end the process.

Where to go next #

The two largest parts of the PSB each have a topic of their own: Process integrity protection, for the trust label that governs which processes may interfere with which, and Process mitigations, for the self-hardening flags and how they are applied.

Use Services Manager on the desktop or svctl in a terminal to see what is running and control it. Both talk to peinit, the service manager that runs as PID 1. Start with a status check; change the definition only when the running service needs different configuration.

$ svctl list
$ svctl status jellyfin
$ svctl boot

Replace jellyfin with the service name you want to inspect. list shows only services you have permission to query.

Where to start #

For exact field types and defaults, use the Registry key reference. For implementation and protocol details, use the peinit Technical Reference Manual.

Three kinds of object #

See Jobs and operations to follow a run or submit a one-off job.

peinit in one sentence #

peinit starts services from registry definitions, runs each under its configured identity, supervises it, and stops services in dependency order at shutdown. You use svctl or Services Manager to request those actions.

What peinit is not #

Service definitions live under Machine\System\Services\ in the registry. There are no systemd unit files or Windows SCM commands to edit or translate. Use Defining a service for configuration and Service types for programs that need to stay in the foreground.

Logs and durable history belong to eventd. Open Logs… for a service in Services Manager, or follow Service output and logging. The TRM compatibility notes describe the interface boundaries.

The one operational invariant #

peinit uses a cached service configuration. A saved change may wait for the next start or another relevant operation; it does not necessarily change a running process. Check when configuration changes apply. The event-loop design explains why.

Where peinit sits in the system #

The service’s Identity controls what its process may access. Its ServiceSecurity permissions control who may manage it. Permission to edit its registry definition is separate again. See Service identity and Who can manage a service. The TRM system map covers the components behind these checks.

Use svctl to inspect and control services from a terminal, or Services Manager on the GXWI desktop. Start by checking the service before issuing a command that interrupts it.

$ svctl list
$ svctl status jellyfin

Use the name from the list in place of jellyfin. The command form is svctl <command> [service] [flags]. To investigate a failure, keep the state, cause, job ID, and warnings, then open the service’s logs.

Reading status #

Read state and cause together, then check health and warnings:

$ svctl status jellyfin
$ svctl list

An Active service has met its configured readiness check. With Readiness=Alive, that only confirms the process exists; it does not prove the application is serving requests.

For a scheduled service:

$ svctl status logrotate
logrotate: inactive
cause: clean_exit
timers:
  *-*-* 02:00:00
    next: 2026-06-02T02:00:00Z, firing at 2026-06-02T02:07:12Z after jitter
    last fired: 2026-06-01T02:03:40Z

svctl prints timer times in UTC, to the second. Services Manager shows them in local time. svctl list has a NEXT TIMER column for each service’s soonest firing. Jitter is already included in the actual firing time.

list omits services you cannot query. job list does the same for jobs. An operation ID expires after its terminal retention grace; a submitted job is retained for 60 seconds after it ends. For older results, look in eventd. The TRM client examples retain the full JSON views and field formats.

From the desktop: Services Manager #

On a GXWI desktop, Services Manager does the same from a window. It lists every service, shows what the selected one is doing (its state and why, its process, the account it runs as, how long it has been running, anything it has reported), and offers Start, Stop, Restart, Reload and Reset. The same commands are on each row's right-click menu. Type in Find a service to narrow the list by name or description.

Services Manager is another client of the same control socket, so it has exactly your authority and no more:

• A command is offered only where it will act. A button is available only if you hold the right the command needs (see the table below) and the service is in a state where the command does something (see the command × state matrix). Otherwise the button is unavailable. The details pane says which commands you may use on the selected service.
• Commands do not block the window. A command is sent without waiting. Services Manager follows its operation and reports the result, such as "SSH server was restarted." or the reason it failed.
• Hidden services are listed, not silently dropped. list omits the services you cannot query. If you can read the service definitions in the registry, Services Manager still lists those services, marked Not yours to see, and says how many there are.
• If peinit does not let you connect at all, Services Manager says so. By default the control socket admits everyone who is signed in, but it can be locked down. Any definitions you can read are still listed, and no command is offered.
• Its definition opens in a window of its own, from Edit definition… in the details pane or on a row's menu. New service… on the bar defines one. Both are covered in Defining a service, with svctl definition, which does the same from a terminal.
• Who may control a service, and who may change its definition, open from the details pane in the permissions editor. They are covered in Who can manage a service.
• What it has logged opens in Event Viewer, from Logs… in the details pane or on a row's menu. The window shows the service's lines and those of its hooks and health checks, newest first and as they are written. See Event Viewer.
• Timers show when they run. The Next run column shows when each service's soonest timer fires. The details pane lists each timer under its schedule, with its next run and its last run, in the machine's local time. A timer with jitter says that its run is put back by a random delay, and the next run shown already includes that delay. A timer peinit could not arm says why it never runs. These are peinit's own figures, read from status, not worked out from the definition.

peinit doesn't announce state changes, so Services Manager asks it for the services' state every two seconds. Press F5, or select Refresh, to ask straight away. What the registry holds is different. That covers which services are defined, who may control them, and what you may change. Services Manager watches the Services key for changes and reads it again only when something changes, so a change made elsewhere, from svctl or another window, shows at once.

Before changing a service #

• Start begins the full start sequence and may start dependencies.
• Stop interrupts the service. A BindsTo dependent stops with its target; a Requires dependent that is already running does not. See Dependencies.
• Restart stops and starts as one operation, replacing the current process. Use it when a definition change needs a new process.
• Reload asks the running program to re-read its own configuration. reload-config instead asks peinit to re-read service definitions. Neither promises to apply launch-only settings to an existing process.
• Reset clears Failed, Abandoned, or Skipped to Inactive; it does not start the service or repair the cause.

After the action finishes, run svctl status <service> again. If it failed or only returned an advisory reload result, follow the troubleshooting guide before repeating it.

Service commands #

$ svctl start jellyfin
$ svctl restart jellyfin
$ svctl reload nginx
$ svctl reset failed-migration     # clear a Failed state without starting

Wait semantics #

By default, a lifecycle command blocks until its operation reaches a terminal state — start waits for Active (or Failed), stop waits for Inactive, and so on. Pass --no-wait to get the operation_id back immediately and poll with operation-status instead.

reload is the exception — it returns immediately by default, because a reload may have no observable completion. With --wait, the response carries a mode:

The detection window is a fixed 2 seconds — it is built in and is not configurable via the registry. If the service says nothing within that window, the reload resolves as advisory and the service stays Active.

System commands #

$ svctl shutdown poweroff
$ svctl reload-config
$ svctl operation-status a1b2c3d4-...

Job commands #

Submitted jobs are reachable from two places, and svctl job covers both. Querying and stopping a job is administration and goes over the control socket; submitting a job, waiting on it, and signalling it belong to its submitter and go over the jobs socket at /run/services/peinit/jobs.sock (--jobs-socket overrides the path). Every job command is checked against the job's own descriptor, which by default admits the submitter, SYSTEM, and Administrators.

$ svctl job list --state running
JOB       STATE    SUBMITTER              IDENTITY               PROGRESS   DESCRIPTION
5f2a...   running  S-1-5-21-...-1001      S-1-5-21-...-1001      3/5 items  nightly backup
$ svctl job status 5f2a...
$ svctl job stop 5f2a...
$ svctl job submit --description "nightly backup" --timeout 3600 -- /usr/bin/backup --full
$ svctl --wait job submit --env MODE=full /usr/bin/backup   # exits 0 only if the job completed
$ svctl job wait --for ready 5f2a...
$ svctl job signal 5f2a... SIGHUP

job submit takes the definition fields as options: --description TEXT, --cwd DIR, --env NAME=VALUE (repeatable), --timeout SECS, --stop-timeout SECS, --readiness none|notify, --readiness-timeout SECS, --success-exit-code N (repeatable), --security-descriptor SDDL. Two hand the job something of yours: --fd NAME=FD passes a descriptor of the svctl process to the job under NAME (from descriptor 3, with LISTEN_FDS/LISTEN_FDNAMES set), and --output attaches svctl's standard output as the job's output sink, so the job's lines appear on your terminal as well as in eventd. Everything after IMAGE belongs to the job, options included; use -- before an image path that starts with a dash.

The CLI has no way to attach a token, so a svctl-submitted job always runs as the caller. Running a job as someone else is a programmatic act — a service attaching the token of the client it is impersonating — and is described in Jobs and operations.

The command × state matrix #

A command sent to a service in an unexpected state returns an error, not a silent no-op. This matrix is the authority on what each command does in each state:

Legend:

• MERGE — an operation of this type is already running; your command merges into it and you get its GUID.
• DEFER — your start is accepted and creates a Pending start operation, but it does not run yet: it waits out the service's existing backoff deadline and then starts. If a deferred start is already waiting, you merge into it and get its GUID.
• ALREADY — already in the target state; returns the current status, not an error.
• QUEUE — queued as Pending; runs after the current operation finishes.
• NOOP — no effect; returns the current status.
• Clear / Cancel — clear the state to Inactive / abort the current operation, then proceed.
• ERROR — invalid for this state; returns an error with an explanation.

The Backoff column is the subtle one: the service is down with an automatic restart pending, so start is deferred — it creates a Pending start that honours the remaining backoff delay and only runs once that deadline expires (a second start merges into the one already waiting), stop cancels the pending restart and any deferred start (the service goes Inactive), restart cancels the automatic one and does an admin restart, and reload/reset are invalid because no process exists.

Error codes #

An error response is {"status": "error", "code": "...", "message": "..."}. The code is one of:

The jobs socket uses the same envelope and codes, plus two of its own:

The message is human-readable and non-normative — read it for context, key off the code.

Exit status #

How the control interface works #

Both tools use /run/services/peinit/control.sock. Connection admission and each service action are access-controlled. The default socket admits signed-in users; the target’s permissions decide which commands they may run.

Lifecycle commands create an operation ID you can follow. Concurrent identical requests can merge into one operation. For JSON framing and complete response examples, see the control-client reference.

Connection limits #

peinit enforces hard limits on the control socket, all tunable under Machine\System\Init\:

The jobs socket has its own set, under the same key:

Where to start #

To understand the states the matrix refers to, read The service lifecycle.

To understand the operations every lifecycle command creates and how to poll them, read Jobs and operations.

To configure who may run each command, read Who can manage a service.

In Services Manager, select the service and choose Logs…. It opens Event Viewer with the service’s lines and the output of its hooks and health checks, newest first and updating as they arrive.

For terminal queries, use evctl. peinit forwards output; eventd stores and queries the records it receives.

Find the failed run #

1. Run svctl status <service> and note its state, cause, current job ID, and warnings.
2. Open Logs… and inspect the time around the failure. Hook and health-check output can explain a start or health failure even when the main process wrote nothing.
3. Match the job GUID to isolate one execution. A restart has a new job ID.
4. For earlier attempts, look for peinit.job.started, peinit.job.ended, and the operation events in eventd. The live job or operation may already have expired.

Log origins identify the producer: the service name, a hook such as jellyfin/ExecStartPre[0], or jobs/<id> for a submitted job. A log’s stream tells you stdout or stderr, not whether the line necessarily describes an error.

Capturing output #

peinit captures stdout and stderr, including hooks and health checks, and tags lines with the origin, stream, timestamp, and job GUID. A submitted job cannot opt out of forwarding; --output requests an additional live copy.

Pipe wiring and tagging are described in the output-flow reference.

Logs and events have different limits #

Service logs and structured events take separate paths:

Do not assume an event has survived a reboot merely because it was emitted. The kernel ring is not persistent, and it can overwrite older events if consumers fall behind. See KMES failure modes for those limits and Auditing for event storage and queries.

The pre-eventd buffer #

Before eventd is available, peinit holds output in memory, by default up to PreEventdBuffer=1048576 bytes. Overflow drops the oldest lines. The buffer is replayed when eventd is ready, but it is not persistent storage and cannot guarantee a complete boot log.

The buffer reference explains the early-boot path.

Flood protection #

A [truncated] marker means a line exceeded MaxLogLineLength (8192 bytes by default). Output delivered faster than peinit can read can block the service’s writes at its pipe; downstream delivery to eventd is loss-tolerant.

If a submitted job’s live output has gaps, look for peinit.job.output.dropped. That reports loss in the extra output copy, not necessarily loss in eventd; query eventd separately. Ordinary log delivery remains best-effort there too.

See the registry limits before changing buffer sizes and the TRM flood-control detail for the implementation.

The eventd handoff #

When eventd reaches Active, peinit replays buffered output and forwards new lines. If eventd exits, peinit resumes buffering and repeats the handoff when it returns. Missing log lines around that interval can reflect buffer overflow or lossy delivery; an empty query alone does not prove the service wrote nothing.

Access policy can also hide records from a query. Check who may read what if the expected origin is absent. The handoff reference describes transport behaviour.

Console output #

peinit writes boot progress, shutdown progress, recovery entry, and critical failures to /dev/console. Service output is not echoed there by default. A terminal-attached service is the exception because it writes directly to its terminal.

peios.quiet can suppress peinit’s console messages, and suppressed messages are dropped rather than saved for later. See console noise settings when investigating a boot problem.

Where to start #

For symptom-based next steps, use Troubleshooting. For finding older executions or actions, use Jobs and operations. For query tools, use Event Viewer or evctl.

Collect the current state and cause before changing anything:

$ svctl status <service>
$ svctl list
$ svctl boot

Keep the job or operation ID and any warnings. Open Logs… for the service in Services Manager to inspect its main process, hooks, and health checks. For older attempts, query logs and events; live status is not a permanent history.

Use the symptom below to choose the next check. Avoid repeating a restart or changing permissions until you know which layer failed.

A service won't start #

status shows it Failed or Skipped. The cause says why:

A service keeps restarting #

The service flaps — up, down, up, down. This is restart policy doing its job, but it points at an unstable service.

• It eventually settles in Failed with RestartBudgetExhausted. It crashed RestartMaxRetries times faster than it could stay healthy for RestartWindow. The fix is the service, not the policy — read its logs for the crash. Raising the budget only delays the inevitable.
• It flaps forever and never exhausts the budget. Check whether it stays Active for the full RestartWindow between failures. Reaching Active briefly does not reset the budget. Inspect the health-check output too; a faulty check can restart a working service.
• It restarts on a clean exit you did not expect. RestartPolicy=Always restarts even successful exits (cause CleanExitRestart). If the service is meant to exit, use OnFailure instead.

The machine keeps rebooting #

Preserve the last console error and any service records before attributing repeated reboots to a service. If peinit reports a Critical service exhausting its restart budget, its ErrorControl=Critical policy makes peinit sync and reboot. Repeating that failure can produce a reboot loop; the symptom alone does not establish this cause.

The boot-attempt counter can break a sequence of boots that reach peinit's counter increment but never become confirmed: after N attempts (default 3), peinit enters Recovery mode. If each boot reaches the success grace before the Critical failure, its counter is reset and the reboot loop can continue without automatic Recovery. Check svctl boot while the normal control interface is available; it is unavailable in Recovery. Do not assume every reboot loop will stop after three attempts, or that peinit can deliver Recovery if it cannot start.

In Recovery, start with the failure reason on the console. Phase 2 services are skipped, so stored eventd history is not automatically queryable from that shell. Where a supported running eventd query service is available, use Find service logs and Find missing records to investigate earlier attempts. evctl queries that service; it does not open stored databases offline. Otherwise, retain the console evidence for the administrator or provider's recovery procedure.

Once the evidence identifies a Critical service failure, repair its cause or restore known-good configuration through a supported recovery path before rebooting. Disabling a required platform service can leave its dependents unable to start. If you need to intervene before the counter trips, boot with peios.recovery=1 on the kernel command line.

A service is Abandoned #

Abandoned means peinit SIGKILLed the process but it survived — stuck in uninterruptible kernel sleep (D-state), the signature of hung I/O (a dead NFS mount, a failing disk). Nothing in userspace can kill a D-state process.

• The underlying I/O fault is the real problem — investigate the storage or mount, not peinit.
• The service's cgroup is leaked and shows in warnings. A later start uses a fresh generational cgroup, so the new instance is unaffected.
• svctl reset <service> clears the Abandoned state and re-checks the cgroup: if the stuck process finally died, peinit cleans up; if not, it stays leaked and warns you. Leaked cgroups clear fully only on reboot.

I changed the config and nothing happened #

peinit works from an in-memory snapshot, and each field has a mutability class that decides when a change applies:

• Immutable at runtime (ImagePath, Type, Identity, RequiredPrivileges, ErrorControl) → takes effect only on restart.
• Apply on next start (dependencies, conditions, OnFailure) → next start or graph reload.
• Reloadable at runtime → next relevant operation. Timeouts and health-check policy can affect later checks; environment, arguments, working directory and process limits apply to a new process, not one already running.
• Hot-reloaded (ServiceSecurity) → next control request.

If a change is not landing, check its class first. For a wholesale re-read of every definition, run svctl reload-config — it rebuilds and validates the whole graph atomically and swaps it in only if validation passes (running services are untouched). And remember peinit pulls changes from registry notifications rather than having them pushed, so there can be a brief lag.

ACCESS_DENIED #

A control command returns ACCESS_DENIED. peinit ran AccessCheck on your token against the target's descriptor and the right was not granted:

• A service command needs the matching right in the service's ServiceSecurity descriptor (start needs SERVICE_START, restart needs both stop and start, …).
• shutdown and reload-config need SYSTEM_SHUTDOWN / SYSTEM_RELOAD_CONFIG in peinit's control descriptor.
• The check uses your effective identity at connect time — if you are impersonating, that is what is checked.

Under the default descriptors every denial is recorded by the kernel as a kacs.audit.access.checked event naming the caller, the target (its object kind is service, job or peinit-system) and the rights requested and granted. Walk it through Debugging a denial.

A job submission is refused #

A job submit — from svctl or from a service — comes back with an error rather than a job. The code says which door it hit:

A job that was accepted but never ran is not an error response: it is an ok response whose view is failed with a cause — parent_setup_failure (peinit could not prepare the launch) or pre_exec_failure (the program could not be executed as that identity, which is where "no such file" and "permission denied" land, because peinit does not check the image before accepting a submission).

A job's output has gaps #

If a submitter attached an output sink and sees gaps, look for a peinit.job.output.dropped event for the job in eventd: the sink was not being drained fast enough, and peinit dropped lines for the sink only rather than let it slow the job. Query eventd under the job’s GUID for the independently forwarded record. Sink loss does not itself drop that record, but eventd’s log path is also best-effort, so completeness is not guaranteed.

UNKNOWN_JOB #

The GUID is unknown or its retention has elapsed. A submitted job is retained for 60 seconds after it ends, then dropped; check eventd for any stored record. A known job that you lack permission to query returns ACCESS_DENIED. job list instead omits jobs you cannot query.

A dependent never started #

You started (or booted) a service, but something that depends on it never came up:

• A Requires/BindsTo dependent stays blocked until its target reaches a satisfying state (Active, Reloading, Completed, or Skipped). If the target is stuck in Starting or Failed, so is the dependent — fix the target.
• If a dependent got connection refused on boot, check the target's readiness setting and startup logs. With Readiness=Alive, peinit waited only for the process to exist, not to be serving. Use Readiness=Notify only if the program supports sending READY=1 from its tracked main process when ready; changing the setting does not add that support and can cause ReadinessTimeout. See the notification contract. If the program cannot signal readiness, have its service or package owner resolve the startup race. peinit's boot validation warning can identify an Alive-readiness dependency; it does not prove the cause of a refused connection.
• A Wants dependent waits for the optional target’s startup attempt to resolve, but starts even if the target failed. Use Requires when successful readiness is necessary.

Booted into Safe mode #

Safe mode selects Critical and SafeMode=1 services within the boot-triggered set. Those flags do not give a demand-only service a boot trigger. You land here when graph validation finds a cycle or unresolvable conflict involving a Critical service, or when peios.safemode=1 is on the kernel command line. The TCB is healthy; the configuration is broken.

Fix the graph: the logs name the cycle path (A → B → C → A) or the conflicting pair. Once the cycle is broken or the conflict resolved, a normal boot returns. You can start any service by hand from Safe mode in the meantime — it is only auto-start that is restricted.

Booted into Recovery mode #

Recovery mode gives you a SYSTEM shell on the console and skips Phase 2 services. It starts registryd only if the boot has not already attempted that start. You reach it when the boot counter hits N, when peios.recovery=1 is set, or when registryd failed in Phase 1 (Recovery is immediate; this boot attempt has already incremented the counter).

If the registry itself is failing:

1. Preserve peinit's console failure reason and the source's startup diagnostics. A failed registry operation does not prove the source process has exited.
2. Identify the installed registryd provider and version, its hive declarations and actual database paths. LCS and sources explains the default loregd provider and its diagnostics.
3. Establish whether the source is already active before any storage work. Recovery may retain a registryd started or attempted earlier in the boot. Do not launch a second source against the same hive files.
4. Obtain the installed provider's supported recovery procedure before attempting offline inspection or repair. The source-checked loregd implementation accepts hive declarations and has no offline repair switches. It does not create an automatic startup backup; its orphan cleanup is not corruption repair or backup restoration. Those references identify the checked revision. Verify what recovery copy actually exists and what it contains before planning a replacement.

When the source is serving the required registry operations, Backup and restore describes the supported privileged subtree workflow. That workflow depends on a working source; it does not repair an unavailable source. Restore replaces the target contents and descendants, including security descriptors, so review the target and backup before using it. Role definitions can re-supply service configuration but do not restore every registry value.

Recovery offers no TCB guarantee. Treat the unrestricted SYSTEM shell accordingly, and remember it needs console access (physical, IPMI, or serial); there is no remote recovery yet.

Where to start #

To read states and causes fluently, keep The service lifecycle handy.

For restart, backoff, and Critical-reboot behaviour, see Keeping services running.

For the commands and their outputs, see Controlling services.

Run svctl status <service> and read state and cause together. State tells you where the service is now; cause tells you why it got there. Failed with ValidationError calls for a definition fix, while Failed with RestartBudgetExhausted calls for the logs from repeated attempts.

Use the state table below for a quick interpretation, then the troubleshooting guide for the next action. You do not need the full state machine before running a status check.

The states #

Four of these — Active, Reloading, Completed, Skipped — satisfy dependents. Everything else blocks them. That single column is the rule the whole dependency system turns on: a service waiting on a Requires target does not move until that target reaches one of those four.

Choose the next check #

• Starting: inspect the current operation, readiness configuration, and pre-hook output. The main process may not exist yet.
• Backoff: an automatic retry is already pending. Another start honours the existing delay; stop cancels the pending restart.
• Failed: read the cause and the failed run’s logs before starting again. Definition and dependency faults are not fixed by increasing retries.
• Skipped: inspect the condition or terminal owner. Skipped satisfies dependents and is not itself a failure.
• Abandoned: investigate the underlying I/O fault. reset clears the state but cannot kill a process stuck in D-state.

Controlling services lists which actions are valid in each state.

Transition causes #

Every transition carries a cause. peinit keeps the cause of the most recent transition on the service, and emits all of them to eventd. The full taxonomy, grouped by what kind of thing happened:

Why a service started

Why a service stopped

Why a service failed or restarted — the diagnostic causes

Why a service was rejected — definition and graph problems

The grouping matters for what peinit does next: the diagnostic causes are mostly restart-eligible (peinit consults restart policy), whereas the definition/graph causes are never restarted — retrying a broken definition cannot help. The distinction is spelled out in Keeping services running.

The Abandoned state #

Abandoned is the one state that reflects a kernel-level problem rather than a service-level one. peinit reaches it when it has sent SIGKILL to a service's process group but the processes are still there after a grace period — the post-kill timeout, 5 seconds by default. If the service's cgroup has not emptied within it, the processes are wedged in uninterruptible kernel sleep (D-state), typically behind a hung mount or a broken storage controller, and the service is marked Abandoned (its cgroup leaked).

peinit cannot kill a D-state process; nothing in userspace can. So it stops trying: it marks the service Abandoned, leaks the cgroup (it cannot be removed while populated), and moves on rather than hanging. The leak is never silent — it shows up in the service's warnings and, on a later start, peinit creates a fresh "generational" cgroup so the new instance is unaffected by the stuck old one.

An Abandoned service is cleared with reset, which re-checks the cgroup: if it finally emptied, peinit cleans up; if it is still populated, peinit leaves it leaked and warns you. An Abandoned service is a sign of an underlying I/O fault that needs investigating, not something to paper over with a restart.

The common path #

Most of a service's life is a small loop. The diagram below shows the states a healthy Simple service moves through, plus the two ways it leaves Active.

stateDiagram-v2
    [*] --> Inactive
    Inactive --> Starting: start / trigger / dependency
    Starting --> Active: ready (READY=1 or alive)
    Active --> Stopping: stop / shutdown / conflict
    Stopping --> Inactive: exited (clean stop / shutdown)
    Stopping --> Failed: exited (conflict / BindsTo eviction)
    Active --> Backoff: crash + restart allowed
    Backoff --> Starting: backoff delay elapsed
    Active --> Failed: crash + no restart
    Starting --> Failed: timeout / hook / setup failure
    Failed --> Starting: explicit start

A few things this picture makes concrete:

• An automatic restart always routes through Backoff, never through Failed. Backoff → Starting is the retry; Failed is reached only when restarts are exhausted or disabled. This is why OnFailure fires once at the end, not on every retry.
• Starting can fail before any process exists — a parent-side setup error, a failed pre-hook, a condition or assert. The cause records which.
• Failed → Starting is how a manual start (or a recovery path) revives a dead service; automatic restarts never originate from Failed.
• Stopping has two exits. A clean stop or a shutdown lands in Inactive. But a service stopped because it lost a Conflicts race (ConflictEviction) or because its BindsTo target went away (BindsToPropagation) comes to rest in Failed, carrying that cause — so an evicted or bound-out service shows as Failed in status and needs a reset (or, for a bound service, its target returning) before it starts again. It was not shut down on purpose, so peinit does not treat it as cleanly Inactive.

Oneshot services follow a parallel path through Completed instead of Active: Starting → Completed, and then either staying there (RemainAfterExit=1) or passing through to Inactive. See Simple and Oneshot services.

Readiness gating during boot #

The dependent-satisfaction rule is what makes boot orderly. A service's dependents do not start until it satisfies them:

• A Simple service satisfies dependents when it signals READY=1 (Notify) or when its process exists (Alive).
• A Oneshot service satisfies dependents when it exits successfully and reaches Completed.
• A Skipped service satisfies dependents immediately — it succeeded by not needing to run.

If a service does not reach readiness within its StartTimeout, its dependents diverge by relationship: Requires dependents transition to Failed (DependencyFailure); Wants dependents start anyway. That difference is the whole point of the two relationship types — see Dependencies and ordering.

Invariants #

A handful of rules hold without exception:

1. A service is in exactly one state at any moment.
2. Only the transitions peinit defines are valid — there are no others.
3. Only peinit changes a service's runtime state. No external process can reach in and set it.
4. A service's securable identity (its ServiceSecurity descriptor — who can manage it) is independent of its process identity (its token — what it can access).
5. Readiness is per start generation — a READY=1 from a previous incarnation is never honoured for the current start.

Where to start #

To understand what happens after a service crashes — restart policy, backoff, health checks, watchdogs — read Keeping services running.

To understand how dependents block on and are released by these states, read Dependencies and ordering.

To see which commands are valid in which state, read the command × state matrix in Controlling services.

A job is one execution; an operation is one action requested on a service. Use the IDs from svctl status to follow what is happening. A service restart creates a new job, so its job ID also distinguishes its output from the previous run.

$ svctl status jellyfin
$ svctl operation-status <operation-id>
$ svctl job list --state running
$ svctl job status <job-id>

job list and job status here are for submitted jobs. For service-run history, follow the job ID into logs and events. Live status is short-lived; eventd is where to look after an ID expires.

Run a one-off job #

Use job submit when you want one supervised execution under your own identity. For example, if /usr/bin/backup is installed:

$ svctl job submit --description "nightly backup" --timeout 3600 -- /usr/bin/backup --full

Keep the returned ID, then query or wait for it:

$ svctl job status <job-id>
$ svctl job wait <job-id>

To end the whole job, use svctl job stop <job-id>. job signal sends a signal only to its main process and is not a substitute for stopping its cgroup. Check the final state and cause: a job that handles a requested stop and exits successfully is Completed with cause explicit_stop.

A submitted job remains queryable for 60 seconds after it ends. After that, use its GUID in eventd. See job command options and permissions before passing descriptors, changing the job descriptor, or attaching live output.

How they surface #

You meet jobs and operations in four places:

• status — current_job and current_operation give the GUIDs of the service's active execution and active action (or null).
• operation-status <id> — polls one operation to a terminal state; a --wait lifecycle command does this for you under the hood.
• job list / job status <id> — the submitted jobs you may query, and one job's view.
• eventd — the durable history. Every job and operation lifecycle transition lands there as a structured event, which is how you reconstruct what happened after the objects themselves are gone from peinit's memory.

Jobs: what actually ran #

Every time peinit forks a process — a service's main binary, a pre- or post-hook, a health check, or a submitted job — that single execution is a job, with its own GUID and exit result. If a service is the what, a job is what actually ran. A restart does not reuse a job; it creates a new one. The service always tracks its current job GUID, and a status query reports it.

Jobs come in five types:

Their lifecycle is simpler than a service's, because a job only tracks a process — not policy:

A job record carries the things you would want for forensics: the resolved identity and a token summary, the image path and arguments, created/started/ended timestamps, the exit code or signal, the cgroup, the failure cause, and the operation_id that created it (null for submitted jobs). The clean division of ownership is: the service owns policy (restart, dependencies, health schedule, current state); the job owns the execution facts (PID, exit, timestamps, identity, cgroup, log correlation).

Retention and log correlation #

For service executions, peinit keeps only active job records in memory. When a job reaches a terminal state it emits a structured event (through KMES) carrying the full record, then drops the job. Submitted jobs retain a terminal view for 60 seconds, as described below; peinit keeps no durable job history — eventd is the historian, consuming those events from the kernel ring buffer. The lifecycle events are peinit.job.created, peinit.job.started, and peinit.job.ended; a submitted job also emits peinit.job.status.reported as its progress changes. peinit.job.created and peinit.job.status.reported are verbose events, off unless the event emission policy (Machine\Generic\Events, PGSS §6.9) turns them on.

Separately, captured job stdout/stderr is forwarded to eventd tagged with the job's GUID. A service with TTYPath writes to its terminal instead; see the terminal-attached service exception. The GUID lets a query like "show me the logs for job X" distinguish that execution's records from the run before or after it.

Operations: what was requested #

An operation is a first-class object representing a requested state-machine action on a service. Rather than letting control commands mutate state directly, peinit turns each one into an operation that is validated, queued, and executed by its event loop. This is what gives concurrent callers — admin tools, automated triggers, dependency propagation — explicit, observable conflict resolution instead of races.

There are five operation types — Start, Stop, Restart, Reload, Reset — and each carries a source recording why peinit created it:

The source is why a status showing current_operation.source: "restart_policy" tells you the service is being auto-restarted, while "admin" tells you a person asked.

Operation lifecycle #

flowchart LR
    P["Pending"] --> R["Running"]
    R --> C["Completed"]
    R --> F["Failed"]
    R --> A["Aborted"]
    P --> M["Merged"]
    P --> X["Cancelled"]
    P --> F

Cancelled and Aborted are the same idea at two points: cancelled never ran, aborted was running. The reason (admin action, supersession) is a property of the event, not the state.

Conflict resolution and merging #

When a command arrives for a service that already has an operation in flight, peinit resolves the collision deterministically — the same logic the command × state matrix summarises:

• Same type (start over start, stop over stop, reload over reload) → merge. The new caller transparently receives the existing operation's GUID; from their side, their request is in progress.
• Stop wins over start. An explicit stop cancels a pending start or aborts a running one. The admin said stop.
• Later supersedes earlier, and a start while a stop is in flight is queued to run after the stop.

Timeout and retention #

An operation inherits its target's timeout as its maximum lifetime — StartTimeout for start/reload/reset, StopTimeout for stop, and the sum of both legs for restart. Crucially, the clock starts at operation creation, including queue time — from the caller's perspective they have been waiting since they sent the command, so a long queue can time an operation out before it even runs.

Operations are emitted as events (peinit.operation.requested, .started, .ended and .merged; one .ended covers completed, failed, cancelled and aborted, and says which) and terminal ones are dropped from memory after a short grace (default 60 s — long enough for a polling client to read the result). As with jobs, peinit keeps no operation history; eventd does.

Submitted jobs #

A submitted job is a program peinit runs once, under supervision, because a process asked it to — not because a definition in the registry said so. Two situations motivate it:

• A task on a client's behalf. backupd takes a request from a user, and wants the backup to run as that user, in its own cgroup, with a timeout, reporting progress, visible in job list — but supervised by peinit rather than by backupd itself.
• A session. A logon service (say, a web front-end) has authenticated a user and wants a long-lived per-logon process running as them, with a socket it can talk to, that it can stop when the session ends.

Both are the same mechanism: a jobs socket at /run/services/peinit/jobs.sock, separate from the control socket. A submitter connects, sends a job definition, and gets back the job's view and — while the job runs — a handle to its process.

Who may submit #

Being able to connect is the permission. peinit performs no access check of its own on a submission; the check is the one the kernel performs against the socket file's security descriptor when a process connects. The default descriptor gives SYSTEM and Administrators full control and Authenticated Users the write right that connecting requires — so out of the box, any logged-on principal may submit, and an administrator narrows or widens that by changing the socket's descriptor, not by configuring peinit.

What limits an over-eager submitter is a quota: at most MaxJobsPerSubmitter live jobs per submitting SID (default 64; SYSTEM is exempt). A submission that would exceed it is refused with QUOTA_EXCEEDED and creates nothing. A job stops counting the moment it ends.

What a job runs as #

A job submitted by svctl runs as your process’s own primary token. There is no CLI identity switch. A service can submit with a token it is authorised to convey; the kernel checks that authority, and a token below Impersonation level is refused with BAD_TOKEN. A job needing Delegation must be submitted through a connection already at that level; it cannot be raised later.

The view records both the submitter and the identity the job runs as, plus its logon session. The TRM identity-conveyance reference describes attached tokens.

The definition #

Choose an absolute image path, its arguments and environment, a working directory, and any timeout or readiness settings. A submitted job has no restart policy, dependencies, health check, or trigger; use a service definition if you need those.

Submission returns once the job is running or has failed to start, not when it has finished or signalled readiness. Use --wait to wait for completion or job wait --for ready for a job configured with notify readiness. An accepted submission can still fail at exec, for example because its identity cannot execute the image.

See svctl job options for the CLI and the submission reference for complete fields and descriptor passing.

Who may manage a job #

Every job carries its own security descriptor from the moment it exists. By default it is owned by the submitter and grants JOB_ALL_ACCESS to the submitter, SYSTEM, and Administrators — and to nobody else. In particular the job identity gets nothing: a process running as U cannot see or stop a job that happens to run as U, unless the submitter's descriptor says so. A submitter may supply its own descriptor (in SDDL) and peinit uses it exactly as given — including a descriptor that locks the submitter out of its own job.

These rights govern both the jobs socket's own commands (status, wait, stop, signal) and the control socket's job-status, job-list, job-stop. As with services, job list filters rather than denies: you see the jobs you hold JOB_QUERY on, while a command naming an existing job you cannot query returns ACCESS_DENIED. UNKNOWN_JOB means the ID is unknown or no longer retained.

The job view #

svctl job status <id> reports the job’s state and cause, submitter and execution identity, PID, readiness, exit code or signal, and timestamps. Its status text and progress are reported by the program itself; an absent value does not establish that it is stuck.

The TRM job-view reference describes the progress message forms and update limits.

Stopping, timeouts, and the end of a job #

A job ends when its process exits, when its timeout elapses, when its readiness_timeout elapses without READY=1, when someone stops it, or at shutdown. A stop — whichever of those triggers it — is a service stop in miniature: SIGTERM to the main process (skipped if the job already said STOPPING=1), then after stop_timeout a SIGKILL of everything in the job's cgroup, and if that survives, the job is Abandoned after the post-kill grace with cause process_unkillable.

cause records why peinit ended a job, and is null when the process ended of its own accord:

State follows the exit, not the cause: a stopped job whose process handled SIGTERM and exited 0 is Completed with cause explicit_stop — peinit asked, the process agreed, and both facts are recorded. One that died to the signal is Failed with exit_signal set. A signal command is the raw mechanism, by contrast: SIGKILL sent that way produces a Failed job with a null cause, because peinit did not decide to end it.

A terminal job is retained for 60 seconds — long enough for a submitter polling once a second to read the result — then dropped; after that its GUID answers UNKNOWN_JOB, and the durable record is in eventd.

Shutdown #

At shutdown, every live submitted job is stopped at once, in no particular order — jobs have no dependencies, so there is nothing to order — and a job still queued to launch is cancelled with cause shutdown. Shutdown does not complete while a live job remains, bounded by the global ShutdownTimeout like everything else. Submissions during shutdown are refused with INVALID_STATE.

Output #

A job's stdout and stderr are captured and forwarded to eventd tagged with the job's GUID, unconditionally — a submitter cannot turn that off. A submitter that wants a live copy attaches one extra descriptor and sets output: true: peinit then writes each line it reads to that output sink as well. The copy is best-effort — a sink that is not being drained never slows the job or peinit; lines that would block are dropped for the sink only while the independent forwarding to eventd continues, and the drop is reported once per job as a peinit.job.output.dropped event.

Submitted jobs bypass the operation model entirely — there is no service to "start," so the submission creates a job directly. The job is the whole lifecycle.

Where to start #

To create and poll operations from the command line, read Controlling services.

To understand the service states an operation drives a service through, read The service lifecycle.

To query the durable job and operation history, read Auditing.

Use svctl definition or Services Manager to change a service’s configuration. Both check field values before writing them. You need permission to change the service’s registry key; permission to start or stop the service is separate.

Start by reading the current definition and runtime state:

$ svctl definition show sshd
$ svctl status sshd

A definition lives at Machine\System\Services\<name>. Its typed registry values describe the program, identity, dependencies, triggers, and supervision policy. The name of the key is the name you use in svctl.

Change and verify #

1. Read the current definition. Decide which field needs to change and when it will apply.
2. Use svctl definition edit or Edit definition… in Services Manager. Check the reported changes before restarting a running service.
3. Validate the saved definition with svctl definition validate <service>. This checks fields; identity, privilege names, and dependency targets also need their runtime checks.
4. If launch settings require it, restart the service during an appropriate interruption window. svctl reload-config re-reads definitions but does not replace a running process.
5. Run svctl status <service> again. If it fails, inspect the cause and logs.

Creating and changing a definition #

A definition is a registry key, so reg can write one. Two tools also know what each field means, and check a definition before writing it.

From a terminal: svctl definition #

$ svctl definition show sshd
$ svctl definition validate sshd
$ svctl definition create web --set ImagePath=/usr/bin/web --set Requires=lpsd --set Requires=netd:routed
$ svctl definition edit web --set StopTimeout=20 --unset Wants

def is short for definition.

• Fields go by their registry names, in any case.
• Values are given as text:
  • a number as digits;
  • yes or no;
  • a choice by its name (Type=Oneshot);
  • a list with one --set for each item, in order.
• A change is checked first, as peinit checks it. It goes through peinit's own decoder, and every timer: schedule is parsed. If peinit would reject it, nothing is written and you are told why.
• Only the values that change are written, in one registry transaction. If one of them has changed since svctl read it, nothing is written.
• Values that are not fields are kept as they are.
• edit names any changed fields that wait for a restart on a running service. See the mutability classes.

Some things can't be checked until later:

• privilege names, when the token is made;
• whether the services a definition names exist, when the graph is built;
• the identity, by authd.

svctl status after the change is the final word.

From the desktop: Services Manager #

In Services Manager, Edit definition… opens the selected service's definition in a window of its own. It's in the details pane and on each row's right-click menu. It reads Definition… when you may only read the definition. New service… on the bar defines a new one. A service's definition opens in one window at a time: while it is open, Edit definition… is unavailable for that service.

• Every field is shown, by group. Each has its name in words with the registry name beside it, its default, and when a change takes effect.

• What you type is checked when you leave the field, as peinit checks it. Anything wrong is said beside the field, and Save stays unavailable until it is put right.

• Each timer's schedule says when it next comes round, under Triggers, in local time. A schedule that never comes round, such as *-02-30, is marked as one that never starts the service. peinit takes such a definition and arms its other timers, so it does not stop you saving. These times are the schedule's, before any jitter. When the timer will really fire is in the details pane, once it is saved (see Controlling services).

• Save writes as svctl does, from the button or with Ctrl+S. Only the changes are written, in one transaction, and it is refused if someone else changed a value meanwhile. Revert reads the definition again. If the service is running, Save says which changes wait for a restart.

• Delete… asks first. A running service carries on until it stops.

• What you may do is asked of the registry:

  • changing needs the right to set values on the service's key;
  • defining a service needs the right to create keys under Machine\System\Services;
  • deleting needs DELETE on the key.

  Without those rights, the definition is shown with every field fixed and the reason said.

• Who may control the service (ServiceSecurity) is changed with Who may control it…, not here. See Who can manage a service.

Field mutability: when a change takes effect #

Every field falls into one of four mutability classes. This table is the one to keep handy.

On a service that is not running, Triggers and Disabled take effect as soon as peinit has read the change: that is what arms a timer added to an inactive service.

The practical reading: changing what a process is or runs as (ImagePath, Identity, Type, privileges, ErrorControl) is fundamental enough that it only applies when a fresh process starts — you must restart. Changing policy that peinit consults each time it acts (timeouts, restart behaviour, health checks) is picked up the next time peinit acts. And ServiceSecurity is special: it is re-read on every control request, so an access-control change takes effect on the very next command without touching the running service.

Environment, Arguments, WorkingDirectory, and process limits do not alter an already-running process. Even though peinit can reload those fields, the process receives them only on its next start.

For inactive services the rules are simpler, because there is no running process to protect: a new service entry becomes available once the change notification is processed; a changed timer arms on the next evaluation; a changed dependency takes effect on the next start.

Removing a service definition #

Use svctl definition delete web only when you intend to remove the definition of web. To stop its current work, use svctl stop web instead.

Deleting a definition from the registry does not kill a running instance. peinit learns of the removal through the same notification path and behaves according to whether the service is running:

• Not running (Inactive, Failed, Completed, Skipped, Abandoned, Backoff): peinit discards the in-memory entry immediately. There is nothing to supervise.
• Running (Active, Starting, Reloading, Stopping): the running process is a job, and a job outlives its definition. peinit marks the entry definition-removed, keeps the cached definition only to finish supervising the existing instance, and does not restart it when it exits. Once it exits, the entry — and any stored fds — are discarded.

A removal that leaves a dangling hard dependency does not apply: peinit refuses the configuration read with MissingHardDependency. Remove or update the dependent definitions first. A definition-removed entry therefore has no dependents.

For a definition-removed entry, stop still works so you can drain it cleanly, but start, restart, and reload are rejected with UNKNOWN_SERVICE — there is no definition to start from. A status query reports it with a definition_removed: true flag so the draining instance is never invisible.

Service names #

A service name must be made of characters from [A-Za-z0-9._-] and be 1–128 bytes long. Anything else is a validation error. Two characters are pointedly excluded:

• / — names map directly onto cgroup ids and registry key names, and a slash would be ambiguous in both.
• : — reserved for peinit-internal synthetic names (for example, the way a hook job is labelled).

The name is how you refer to the service everywhere: in svctl commands, in another service's dependency list, in a ServiceSecurity descriptor, and in the per-service SID derived from it.

The definition schema #

A definition is a set of typed registry values. Rather than list all of them in one wall of rows, the tables below group the fields by what they are for, with a pointer to the page that explains each group in depth. Every field is optional unless noted; the only hard requirement is ImagePath. The full type-and-default catalog lives in the Registry key reference.

What to run — the binary and its execution context.

What kind of service — type and readiness. See Simple and Oneshot services.

When to start — triggers and conditions. See Triggers and timers.

Who it runs as — identity and privileges. See Service identity and privileges.

How it relates to other services — dependencies. See Dependencies and ordering.

How it is kept alive — supervision and health. See Keeping services running.

The transition phases — hooks and timeouts. See The execution environment and The service lifecycle.

The remaining knobs — scheduling, notify, fds, metadata.

Forward compatibility #

The schema version lives at Machine\System\Services\SchemaVersion (currently 1). peinit is deliberately forward-compatible:

• Unknown values are ignored. A definition written for a newer peinit does not break an older one.
• A newer schema version does not block boot. peinit logs a warning and continues.
• The schema only grows. New capability arrives as new optional fields, never as a breaking change to an existing one.

One defensive rule cuts the other way: a known field must not appear more than once in a collected definition. A duplicated known field is a validation error, even though the registry would ordinarily give you at most one value per name.

peinit works from a snapshot, not the live registry #

Here is the idea that explains most surprises. peinit does not re-read the registry every time it touches a service. It reads definitions at well-defined moments and operates on an in-memory model in between.

Two layers of snapshotting stack on top of each other:

• Boot generation. At the start of boot, peinit reads all definitions, builds the dependency graph, and validates it. The whole boot runs against that one snapshot. Changes made during boot — by an install script, a post-hook — do not perturb the boot in progress.
• Activation generation. When peinit starts a specific service, it snapshots that service's definition for the entire start. Pre-exec hooks, the token request, the readiness timeout, the first health checks — all use the values captured at activation. Edit a field while the service is Starting, and the edit waits for the next start.

peinit learns about registry edits through change notifications: it subscribes to Machine\System\Services\ and Machine\System\Init\ at boot, and processes events in its event loop at a time of its choosing. If the notification queue overflows — a bulk admin operation, a flurry of scripted writes — peinit detects the overflow marker and does a full reload-config to resynchronise. You never have to think about the queue; you do have to know that a change is picked up, not pushed, and that when it takes effect depends on the field.

Where to start #

To understand the Type and Readiness fields and the Simple/Oneshot split, read Simple and Oneshot services.

To understand how a definition becomes a running, supervised process — and what each state in a status output means — read The service lifecycle.

For the complete type-and-default catalog of every registry key peinit reads, see the Registry key reference.

Choose Simple for a program that stays running and Oneshot for a task that should finish. Then check how it reports success: a Simple service becomes ready through Notify or Alive; a Oneshot succeeds by exiting successfully.

The default is Type=Simple with Readiness=Notify. Before starting a new definition, make sure the program can send READY=1 from its main process. A program that never sends it will time out even if its process is alive. Keep daemons in the foreground; peinit does not follow a double-forked replacement process.

Simple vs Oneshot at a glance #

Simple services #

A Simple service is a long-running daemon. peinit forks, installs the token, and execs the binary. The process is the service: while it runs, the service is running; when it exits, the service has stopped. This is the default and covers the large majority of services — registryd, authd, sshd, application daemons.

The interesting question for a Simple service is when does it count as started — the moment its dependents are allowed to begin. That is the readiness model, set by the Readiness field.

Readiness: Notify vs Alive #

The distinction matters because it is a promise to dependents. With Notify, a service that declares itself a Requires target is telling peinit "do not start anything that needs me until I say READY=1." With Alive, peinit can only promise that the process was forked — not that it is functional.

Once ready, a Simple service transitions to Active and stays there until its process exits or it is stopped. What happens on exit — clean exit, crash, restart — is the subject of The service lifecycle and Keeping services running.

Oneshot services #

A Oneshot service is a run-to-completion task. peinit forks, installs the token, execs the binary, and waits for it to exit. It is the right type for setup work: creating directories, initialising a database, running a schema migration, applying a one-time fixup at boot.

For a Oneshot, readiness is exit, not a signal. The Readiness field is ignored entirely — READY=1 is meaningless for a process whose whole job is to finish. Success and failure are decided by the exit code:

• Exit 0 (or any code listed in SuccessExitCodes) → the service succeeded.
• Any other exit, or death by signal → the service failed, and the failure policy applies.

SuccessExitCodes is for binaries that signal a meaningful outcome with a non-zero code — for example, a tool that exits 2 to mean "nothing to do." Each entry is a decimal 0–255; code 0 is always success and need not be listed.

Completed, and RemainAfterExit #

A successful Oneshot transitions to Completed, and what happens next depends on RemainAfterExit:

Both forms satisfy dependents; the only difference is what a later status query shows. Use RemainAfterExit=1 when "this task is done" is a state worth seeing — a boot-time migration you want to confirm ran, say — rather than a service that quietly returns to Inactive.

Oneshot timing and hooks #

Two details distinguish a Oneshot's start sequence from a Simple one:

• StartTimeout covers the entire run. For a Simple service the timeout covers startup until readiness; for a Oneshot it covers everything from the first pre-hook to process exit. A long-running Oneshot must raise StartTimeout accordingly (or send EXTEND_TIMEOUT_USEC as it works — see Keeping services running).
• ExecStartPost runs only on success. Post-hooks fire after the successful exit. If the Oneshot fails, ExecStartPost does not run.

Restarting a Oneshot #

A Oneshot is not restarted on success, regardless of RestartPolicy — even Always. A successful exit is the goal, not a failure to retry. RestartPolicy governs only the response to failure (a non-zero exit). To re-run a Oneshot on a schedule, give it a timer trigger; that is the intended mechanism.

No forking daemons #

peinit does not support services that double-fork to background themselves. The whole reason a traditional daemon double-forks — to detach from the launcher — is moot when the launcher tracks the process it spawned. peinit obtains a pidfd for every process at fork time, which is a kernel handle to that exact process, immune to PID-reuse races. There is no MAINPID= mechanism for a service to redirect supervision onto a different process; peinit supervises what it forked.

If a legacy binary insists on daemonising, the fix lives at the packaging layer — wrap it so it stays in the foreground (commonly a --no-daemon/--foreground flag) — not at the init layer.

The sd_notify contract #

A Notify-readiness service signals readiness by sending READY=1 over the sd_notify protocol — a datagram to the socket named in the NOTIFY_SOCKET environment variable, which peinit sets for every service. READY=1 is only the most visible message; the same channel carries watchdog keepalives (WATCHDOG=1), graceful-stop notice (STOPPING=1), timeout extensions (EXTEND_TIMEOUT_USEC), status strings (STATUS=), and the fd store. These are covered where they belong — readiness here, the rest in Keeping services running and Controlling services.

Readiness is always per start generation. A READY=1 left over from a previous incarnation of the process is never valid for the current start — peinit ties every notify message to the specific process it is currently supervising, verified by pidfd.

Who is allowed to send these messages is governed by NotifyAccess, which currently has a single value: Main (0, the default). Under Main, only the tracked main PID — the process peinit forked and supervises — is authorised to send sd_notify readiness and status messages; a message arriving from any other PID (a child, a helper, an unrelated process) is ignored. So if a worker your service spawns sends READY=1, peinit will not act on it — the readiness signal must come from the main process itself.

Where to start #

To control when either type of service starts, read Triggers and timers.

To follow a service from definition to running process and read its states, read The service lifecycle.

To configure restart, health checks, and watchdogs for a Simple service, read Keeping services running.

To see when a scheduled service will run, use svctl status <service> or the Next run column in Services Manager. To change automatic starts, edit the definition’s Triggers field. A saved schedule is not evidence that a timer is armed; check status after saving it.

A trigger decides when the service starts on its own. It is independent of service type: boot and timer triggers can start either Simple or Oneshot services. Each entry in Triggers is written type or type:argument.

Without triggers, the service is demand-only: it starts through a control command or because another service needs it. To prevent automatic activation while keeping manual start, use Disabled.

Seeing when a timer runs #

peinit reports each timer as it has it armed, in the service's status:

• the schedule's next occurrence;
• when the timer will actually fire, with its jitter added;
• when it last fired.

A schedule peinit refused, such as *-02-30, which never comes round, is reported with the reason, rather than left out.

$ svctl status logrotate
...
timers:
  *-*-* 02:00:00
    next: 2026-06-02T02:00:00Z, firing at 2026-06-02T02:07:12Z after jitter
    last fired: 2026-06-01T02:03:40Z

svctl list has a NEXT TIMER column, with each service's soonest firing. On the desktop, Services Manager shows the same things in local time: a Next run column, and each timer in the details pane. See Controlling services for the fields.

These times are peinit's own. Jitter is drawn at random each time a timer is armed, so the time a timer fires can't be worked out from its definition.

The Disabled flag #

Disabled=1 suppresses automatic activation. A disabled service will not be started by any trigger — boot, timer, terminal handover, or anything added later — but it can still be started by hand through the control interface. It is the switch for "configured, but not running on its own right now."

Two related controls are easy to confuse with it:

Enabling and disabling are registry writes performed by admin tooling, not peinit commands. peinit picks up a Disabled change through a registry notification or on reload-config. A disabled service's definition is still loaded into peinit's model, so it is ready for an on-demand start the instant you ask.

Calendar expressions #

Timer schedules are written in systemd's OnCalendar format. peinit's grammar is normative and self-contained — what follows is the whole language. The general shape is:

DayOfWeek Year-Month-Day Hour:Minute:Second Timezone

Every field is optional and has a default, so most real schedules are short.

So 02:00:00 is a complete expression — date defaults to every day, and it means "every day at 02:00." Hour:Minute with no seconds defaults the seconds to 00.

Component syntax #

Each numeric component — year, month, day, hour, minute, second — and the weekday accept the same operators:

Weekdays are English names, case-insensitive, abbreviated (Mon) or full (Monday), and take lists and ranges.

Last day of the month #

A ~ in place of the - between Month and Day counts the day from the end of the month: ~01 is the last day, ~02 the second-to-last, and so on. So *-*~01 is the last day of every month. Repetition combines with it — Mon *-05~07/1 is "the last Monday in May."

Named shortcuts #

These stand in for the expression shown:

Timezones and precision #

A timezone specifier follows the IANA database — Europe/London, US/Eastern, UTC. With none, the expression is interpreted in system-local time.

Precision is second-level. Unlike systemd, peinit does not accept sub-second fractions; a fractional second is a parse error. Service scheduling has no use for finer granularity.

Examples #

What happens when a timer fires #

A timer firing does not blindly start the service — peinit considers the service's current state first, so a firing never collides with a run already in progress.

The Oneshot "pending" flag is deliberately not a queue: many firings that land while a Oneshot is busy collapse into one catch-up run, taken when the current run ends. A service cannot stampede itself.

That single flag is shared across all of a Oneshot's timers, not one per timer. If a Oneshot has several timer triggers and two of them fire while it is busy, at most one run is still pending when the current one finishes. The timers are otherwise fully independent — each keeps its own next-firing time and its own last-run timestamp — but they can only ever queue up a single shared catch-up between them.

Each timer firing creates a normal start operation, so a timer-started service is observable exactly like an admin-started one — same GUIDs, same events.

Persistent timers and catch-up #

TimerPersistent (default 1) controls whether runs missed while the machine was off are caught up after a reboot.

peinit records the last-run timestamp of each timer in the registry. On boot, for each persistent timer it reads that timestamp, computes the next firing after it, and — if that time is already in the past — fires once, immediately, then resumes the normal schedule.

The catch-up is always a single run, never one-per-missed-occurrence. A daily timer that was off for five days fires once on the next boot, not five times. A non-persistent timer (TimerPersistent=0) ignores history entirely and simply computes its next future firing from now.

One subtlety worth knowing: the last-run timestamp is keyed by the schedule string. If you change a timer's schedule, the old timestamp is orphaned and the new schedule has no history, which causes exactly one spurious catch-up run. Schedule changes are rare and the cost is one extra run, so peinit accepts it rather than tracking trigger identity.

Jitter #

TimerJitter (default 0) adds a random delay of 0 to TimerJitter seconds to each firing, recomputed every time. A timer scheduled for midnight with TimerJitter=900 fires at a slightly different moment between 00:00 and 00:15 each day. Jitter only ever delays — a timer never fires before its scheduled time. It is the standard remedy for a fleet of machines all hammering the same backend at exactly midnight.

When the clock jumps #

Calendar timers are wall-clock schedules: *-*-* 02:00:00 means "02:00 on the wall," not "every 86,400 seconds." peinit arms them as absolute real-time timers that are cancelled and recomputed whenever the system clock is stepped, so the schedule stays anchored to the wall clock across corrections.

Daylight-saving is the case most likely to surprise you, and it only affects timers that name an IANA zone that observes DST (a bare 02:30:00 in system-local time follows whatever the system does). For a scheduled local time inside the affected hour:

• Spring forward — that time does not exist on the transition day. The timer does not fire for that occurrence; it resumes at the next valid occurrence.
• Fall back — that time occurs twice. The timer fires exactly once, on the first occurrence.

This is distinct from peinit's interval timers — the watchdog, health-check intervals, restart backoff, and the start/stop/reload phase timeouts. Those are genuine durations measured on the monotonic clock, so "wait 30 seconds" means 30 elapsed seconds and never lurches when the wall clock is set.

There is one boot-time case worth calling out on its own. When peinit reads a timer's stored last-run timestamp at boot and finds it is in the future relative to the current wall clock — meaning the clock has gone backwards since that run — it can't trust the timestamp, so it treats the timer as having an unknown last run and fires the persistent catch-up immediately. This only applies to the boot-time check; the runtime handling above is unaffected.

Waiting for the boot to settle #

boot:settled is boot with one difference: the service starts once the Phase 2 boot set has stopped moving — every service in it reached a state it will not leave on its own — rather than during it.

It exists for services that write to a terminal. peinit reports its progress to /dev/console, and a service holding that same terminal writes there too, so a prompt started mid-boot gets written over: login emits Username: with no newline and waits, peinit appends a service line, and the result is unreadable until you press Enter and login redraws.

The wait is capped (Machine\System\Boot\SettleTimeout, 5 seconds by default). A service stuck in Starting therefore costs a deferred service a short delay rather than preventing it — which matters most exactly when something is broken and a console prompt is what you need.

A boot:settled service is deliberately not part of the boot plan. It does not consume the parallel-start budget, is not counted towards boot success, and cannot block another service. Waiting for quiet is a preference; it must not change what the boot means.

Queueing for a terminal #

A terminal has one owner at a time. Two services writing to the same TTYPath do not fail — they interleave, which on a console means a login prompt with a progress line through the middle of it. So peinit gives the device to one of them and skips the rest, and tty:released is how the ones that were skipped get their turn.

The whole arrangement is three fields. A first-boot setup flow and a login prompt, both on the console:

On a first boot both are deferred, oobe outranks the login prompt on TTYPrecedence, so oobe takes the console and login-console is skipped with cause TtyUnavailable. When oobe finishes — or crashes, or is stopped; all three free the device — tty:released starts the login prompt. On every later boot oobe is gone, nothing is holding the console, and the login prompt starts straight away.

A few rules worth knowing:

• Higher TTYPrecedence wins, and equal precedence breaks on service name, so the outcome is the same on every boot. The default is 0.
• Nobody is preempted. Precedence decides between services starting at the same moment; a service already using a terminal keeps it.
• A service that stops is not offered its own terminal back. Relaunching it is RestartPolicy's job, not this.
• Both fields need a TTYPath. tty:released or TTYPrecedence without one is rejected when the definition is read, rather than quietly doing nothing.
• tty:released on its own starts nothing until somebody takes the terminal and lets it go. Give a service that must come up either way a boot or boot:settled trigger as well, as login-console has above — otherwise a machine with no oobe installed never gets a login prompt.

Being skipped is not a failure: a skipped service satisfies anything that depends on it, exactly as a service skipped by a Conditions entry does.

You can list more than one trigger, including more than one of the same type. ["timer:*-*-* 02:00:00", "timer:*-*-* 14:00:00"] runs at 2 am and 2 pm. The model is built to grow — future trigger types (path, device, event) will slot into the same list without a schema change.

Where to start #

To see how a timer-started run appears as a job and an operation, read Jobs and operations.

To understand the states a timer-started service moves through, read The service lifecycle.

For the exact registry keys that store last-run timestamps, see the Registry key reference.

When a service keeps restarting, check its state, cause, and logs before changing the restart policy. Backoff means peinit is waiting to retry; Failed with RestartBudgetExhausted means the retry budget ran out.

Use the policy reference below to distinguish a program failure from a failing health check or watchdog. Preserve the underlying error while you investigate. Increasing a timeout or retry count can change when the failure appears without fixing it.

Restart policy #

When a service fails in a way that might be transient, peinit consults RestartPolicy:

Not every failure is restart-eligible. peinit splits causes into three groups:

• Restart-eligible — peinit consults the policy and budget: ProcessCrash, WatchdogTimeout, HealthCheckFailure, ReadinessTimeout, PreHookFailure, PreExecFailure, ParentSetupFailure. (The startup failures are eligible on purpose — a pre-hook that failed on a momentarily-missing mount deserves another try.)
• Never restarted — retrying cannot help: an explicit stop or reset, shutdown, conflict eviction, a broken definition (ValidationError, CycleDetected, DependencyFailure, AssertionError), an already-exhausted budget, or an unkillable process.
• Budget-exempt — BindsToRecovery, where a bound service came back and its dependents are revived. The dependent did not fail on its own, so this restart does not count against its budget.

The budget and backoff #

Restarting an instantly-crashing service in a tight loop is worse than useless, so every restart is throttled by two mechanisms working together.

Exponential backoff. Before each restart the service sits in the Backoff state for a delay that doubles on each consecutive failure, starting from RestartDelay (default 1 s) and capped at 60 s. So a crash-looping service backs off 1 s, 2 s, 4 s, 8 s, … up to a minute between attempts.

The budget. A consecutive-failure counter tracks how many times the service has failed in a row. Once it reaches RestartMaxRetries (default 5), the next failure is not restarted: the service transitions to Failed with cause RestartBudgetExhausted.

The reset. The counter resets to zero once the service stays Active for RestartWindow seconds (default 120) without failing. This is the crucial detail: the budget is not "N restarts ever" — it is "N restarts faster than the service can sustain RestartWindow of health." A service that crashes once a day and recovers cleanly each time never exhausts its budget, because every crash starts from a counter of zero. Only failures recurring faster than the service can stay healthy accumulate.

flowchart LR
    A["Active"] -->|crash| B{"budget left?"}
    B -->|yes| C["Backoff<br/>delay doubles"]
    C -->|delay elapsed| D["Starting"]
    D -->|ready, stays Active<br/>RestartWindow| A
    B -->|no| E["Failed<br/>RestartBudgetExhausted"]

Clean exits #

For a Simple service, exiting with code 0 (or a SuccessExitCodes match) is success, not a crash — a daemon chose to quit. What peinit does next depends on the policy:

• Under Never or OnFailure, the cause is CleanExit and the service goes straight to Inactive, with no restart-policy consultation at all.
• Under Always, the cause is CleanExitRestart and the service is restarted — but through the same backoff and budget as a failure, so a daemon that exits cleanly in a tight loop cannot bypass throttling. Logs and status make clear it exited successfully and was restarted only because the policy is Always.

A terminal-attached Simple service is an exception: a successful exit with RestartPolicy=Always is treated as a normal logout. It resets the failure counter and restarts at the base delay, capped at 60 seconds, without using the crash budget. Failures still use the ordinary budget.

(A Oneshot clean exit is never restart-eligible regardless of policy — see service types.)

Health checks #

A live process is not always a working one — it can lose its database connection, wedge in a bad state, or return errors while still "up." An active health check closes that gap by running a command periodically and treating its exit code as a verdict: 0 is healthy, non-zero is a failure.

Health checks apply to Simple services only. peinit starts a service's health-check timer once the service becomes Active; a Oneshot has no long-running process to probe, so it never has one. HealthCheck and its companion fields are inert on a Oneshot — no timer is started — so don't set them there expecting supervision.

HealthCheckRetries consecutive failures mark the service unhealthy and restart it through the normal restart policy — backoff and budget included. A single success resets the failure count. If a check is still running when the next interval fires, the new one is skipped rather than stacked.

The health field in a status response reflects this: healthy, unhealthy (failing but not yet failed out), unknown (configured, no result yet), or null (no health check).

The flap guardrail. Health-check throttling only works if a failure cycle is shorter than the restart window — otherwise the counter resets between failures and the service restarts forever. peinit enforces this at validation time as a hard rule:

HealthCheckRetries × HealthCheckInterval < RestartWindow

A definition that violates it is a validation error, not a warning — the service is marked Failed with ValidationError rather than allowed to restart indefinitely.

A health check stuck in D-state is handled like any other stuck helper: its sub-cgroup is leaked and surfaced as a warning, but — unlike a stuck main process — it does not push the service to Abandoned. A health check holds no service resources; it is only a probe.

The watchdog #

The watchdog inverts the health check: instead of peinit asking the service if it is alive, the service must periodically tell peinit. Set WatchdogTimeout (seconds; 0 disables) and the service must send WATCHDOG=1 via sd_notify at least that often. Miss the deadline and peinit treats it as a failure (cause WatchdogTimeout) and applies the restart policy.

Like health checks, the watchdog is a Simple-only supervision mechanism. peinit arms the watchdog timer only once a Simple service becomes Active; on a Oneshot WatchdogTimeout is inert — no timer is started, and setting it changes nothing.

A service can adjust its own watchdog at runtime by sending WATCHDOG_USEC=<microseconds>: a positive value re-arms the timer with the new interval immediately; 0 disables the watchdog. This is for services whose phases have different latencies — a database might run a tight 5 s watchdog normally but widen it to 60 s during a compaction pass, because it knows its own phases better than the schema author did. The runtime value does not persist: a restart reverts to the schema's WatchdogTimeout.

Timeout extension #

A service that does genuinely slow work during a transition can ask for more time by sending EXTEND_TIMEOUT_USEC=<microseconds> while it is Starting, Stopping, or Reloading. Each message replaces the current phase deadline (it is not additive); a service that keeps sending them keeps proving it is making progress, and if it stops, the last deadline fires and peinit escalates normally.

The extension is capped to prevent a buggy service from extending forever:

During shutdown a second, global cap also applies — the deadline can never exceed the remaining time in the global shutdown timeout, and the stricter of the two caps wins. A message received outside a transition (the service is Active, Failed, …) is ignored — there is no timeout to extend.

OnFailure #

When a service enters Failed, an OnFailure field names another service to start in response — a fallback for graceful degradation (the main web UI failed; bring up a minimal emergency endpoint). It is not a monitoring or alerting hook; that is eventd's job.

OnFailure fires for runtime failures — ProcessCrash, WatchdogTimeout, HealthCheckFailure, the startup-failure causes, and non-Critical budget exhaustion. It deliberately does not fire for:

• ShutdownWave — nothing new starts during shutdown.
• ValidationError, CycleDetected, DependencyFailure, AssertionError — these are definition or graph breakage, not a running service degrading. The fallback would likely sit in the same broken graph anyway.

Because a fallback can itself fail and carry its own OnFailure, peinit bounds the chain: it tracks which services it has already started for one originating failure, refuses to start one twice, and never follows the chain beyond a depth of 16. When the guard trips, it logs the loop and stops.

ErrorControl: when failure is not an option #

ErrorControl decides how serious an irrecoverable failure is:

A Critical service is one the system genuinely cannot run without — the platform daemons registryd, authd, lpsd, eventd are all Critical. "Irrecoverable" means the restart budget was exhausted: peinit tried, backed off, retried up to RestartMaxRetries, and the service still would not stay healthy. At that point the fastest path to a known-good system is a reboot.

A few consequences worth holding onto:

• Critical failure outranks OnFailure. When a Critical service exhausts its budget, peinit reboots; it does not start the OnFailure handler.
• ErrorControl=Critical implies SafeMode. A Critical service is always eligible to start in Safe mode.
• Critical services are OOM-protected. peinit sets their oom_score_adj to -1000, so the kernel will not pick them as out-of-memory victims.
• A runtime Critical crash does not enter Safe mode — it follows the reboot path. Safe mode is only for boot-time configuration errors (a cycle or conflict involving a Critical service). The escalation between reboots, the boot-attempt counter, and Recovery mode are covered in Boot and boot modes.

Where to start #

To see exactly which states these policies move a service through, read The service lifecycle.

To understand how a failed service propagates to the ones that depend on it, read Dependencies and ordering.

When a service will not stay up, work backward from the symptom in Troubleshooting peinit.

Check a service’s dependencies before stopping a shared component or diagnosing a blocked start. Requires waits for successful startup but leaves an already-running dependent alone if the target later stops. BindsTo also stops the dependent when its target goes away.

Relationships are set on the service that needs something, naming the target it needs. Wants attempts an optional target first; Conflicts makes two services mutually exclusive and is symmetric, so one side declaring it is enough.

Before changing a dependency #

1. Read the dependent’s definition with svctl definition show <service> and inspect each target with svctl status <target>.
2. Decide whether the requirement is successful startup (Requires), optional startup ordering (Wants), runtime coupling (BindsTo), or mutual exclusion (Conflicts).
3. Use a readiness level when the target must have reached a specific condition, such as a routed network.
4. After saving, validate the definition and check the next start. Dependency edits apply on a new start or graph reload; they do not rewrite a running process’s history.

A DependencyFailure usually points to the target to investigate first. An on-demand start can pull in other services and evict conflicting ones, so its effects can extend beyond the service you named.

The four relationships #

Requires — a hard dependency #

If A Requires B:

• Start. B must reach a satisfying state before A starts. If B is not running, peinit starts it first (cause DependencyStart). If B fails, A is marked Failed with DependencyFailure and never even attempts to start.
• Stop. Stopping B does not stop A. Requires is a start-ordering constraint, not a runtime leash — A keeps running.
• Runtime failure. If B crashes while A is already Active, A is unaffected. B's own restart policy handles B's recovery.

Requires is the workhorse: "I need this to have started, and if it can't, neither can I."

Wants — a soft dependency #

If A Wants B:

• Start. peinit starts B before A if B exists and is not Disabled — but if B fails to start, or does not exist, A starts anyway.
• Stop / failure. No effect either way. A and B are runtime-independent.

Wants is best-effort ordering: "start this first if you can, but I work without it."

BindsTo — a runtime coupling #

If A BindsTo B:

• Start. Identical to Requires — B must satisfy before A starts.
• Stop. If B stops for any reason — explicit stop, conflict, crash, shutdown — A is stopped too, transitioning to Stopping with cause BindsToPropagation. When A finishes stopping it comes to rest in Failed (carrying BindsToPropagation), not Inactive — so a status query shows the bound service as Failed, making it clear it was taken down by its target rather than shut down cleanly.
• Recovery. When B returns to Active, peinit automatically restarts A from that Failed state (cause BindsToRecovery). This is reactive — peinit watches B's transitions — and it is budget-exempt: A did not fail on its own, so the restart does not count against its budget. If B never comes back, A stays Failed until you reset (or start) it.

BindsTo is Requires plus a runtime leash: "I need this to start, and I should not outlive it." It is the right choice for a sidecar that is meaningless without its principal. BindsTo implies Requires; listing both for the same target is harmless, and BindsTo semantics win.

Conflicts — mutual exclusion #

If A Conflicts with B:

• Start. Starting A while B is Active creates a stop operation for B (source ConflictResolution), evicting it (cause ConflictEviction) before A starts — and vice versa. If the loser will not stop within its StopTimeout, SIGKILL escalation applies. The evicted loser does not land in Inactive: it comes to rest in Failed (carrying ConflictEviction), so it shows as Failed in status and needs a reset before it will start again. That is deliberate — an evicted service is not a clean stop, and leaving it Failed stops it from quietly restarting straight back into the conflict.
• Symmetry. Conflicts is two-way. If A declares Conflicts=["B"], starting either stops the other; B need not declare it back.

Conflicts is for true mutual exclusion — two services binding the same port, or two implementations of one role where exactly one must run — not for ordinary resource contention.

At a glance #

Waiting for a condition, not just a service #

A target may carry a readiness level after a colon. Requires = ["network:routed"] waits not merely for the network manager to be active but for it to have published the level routed — a default route in place — and holds the start until it does. Publishers report a set of currently true levels, and peinit checks membership. A routed network publishes link, addressed and routed, so a service can ask for the condition it actually needs. peinit clears the set the moment its publisher leaves a satisfying state.

network there is a role, not a service: the service that fills it declares Provides = ["network"], and peinit rewrites the entry to that service before anything else looks at it. Write the role, not the daemon. The levels link, addressed and routed are defined by network policy, so the definition keeps meaning the same thing whichever executor an image ships. svctl status shows the resolved dependency, netd:routed on a standard image.

On-demand starts #

When you start a service explicitly rather than at boot, peinit does the same graph work on a smaller scope — the requested service's transitive closure:

1. Collect all transitive Requires and BindsTo dependencies (and best-effort Wants).
2. Validate that sub-graph (cycles, missing targets).
3. Resolve Conflicts — stop anything that conflicts.
4. Start the sub-graph with the same parallel scheduler.

Anything already in a satisfying state (Active, Reloading, Completed, Skipped) is left alone — its dependency is already met, so there is no needless restart. Dependencies pulled in this way start with cause DependencyStart. If two on-demand starts need the same dependency at once, their start operations merge rather than racing.

Failure propagation #

When a service enters Failed during graph execution, the failure spreads along Requires and BindsTo edges — and only those:

1. Every service that Requires the failed one transitions to Failed with DependencyFailure.
2. Every service that merely Wants it is unaffected and starts normally.
3. Propagation is transitive: if A requires B and B requires C, and C fails, then B fails, then A fails — each with DependencyFailure.

This is the payoff of the Requires/Wants distinction. A hard dependency failing takes its dependents down with it; a soft one failing is shrugged off. Choosing the right relationship is choosing how far a failure is allowed to travel.

Graph validation #

Before peinit starts anything, it builds the dependency graph and validates it. Validation runs once per graph build — at boot for the whole boot graph, and per request for an on-demand start's transitive closure. It is not incremental.

Cycles. peinit topologically sorts the graph; if the sort fails, there is a cycle. Every service in the cycle is marked Failed with CycleDetected, and peinit logs the full path (dependency cycle: A → B → C → A) so you can find and break it. A service may not depend on itself — a self-reference is rejected as a cycle. If any service in the cycle is ErrorControl=Critical, peinit downgrades to Safe mode rather than rebooting, because a reboot would just hit the same cycle.

Missing targets. What a missing target means depends on the relationship:

Unresolvable conflicts. If two boot-triggered services conflict with each other, there is no way to honour both, so both are marked Failed with ValidationError. As with cycles, if either is Critical, Safe mode applies.

Warnings. Some conditions are logged but do not block boot — most notably a Readiness=Alive service that others Requires (see service types). Warnings appear in the logs and do not change state.

Validation errors. Some conditions do fail the service — for example a health-check configuration that violates the flap constraint. These mark the service Failed with ValidationError.

When more than one finding applies to the same service, peinit records a single primary cause by precedence — CycleDetected > ValidationError > DependencyFailure — but it logs all findings, so the primary cause never hides the others.

Parallel start #

After validation, peinit starts services whose dependencies are all satisfied, and it does so in parallel up to a configurable limit:

The scheduler is simple: every service with no unsatisfied dependencies is eligible; peinit starts up to MaxParallelStarts of them; as each one reaches a satisfying state its dependents become eligible and join the queue. The result is that independent subtrees of the graph come up at the same time, while ordering constraints are still honoured exactly.

Shutdown reverses the graph #

peinit does not need a separate stop-ordering configuration. Shutdown simply reverses the dependency graph: services with no dependents stop first, and services that others depend on stop last. A service is never stopped until everything that Requires or BindsTo it has already stopped.

Shared platform services stop after their dependents, with registryd last. The exact order comes from the installed graph; do not rely on a fixed list of daemon names. The full shutdown sequence is in Shutdown.

Where to start #

To see the states services move through as they start and stop in order, read The service lifecycle.

To understand how a target's failure interacts with the dependent's own restart policy, read Keeping services running.

To follow how dependency-driven starts appear as operations, read Jobs and operations.

A service’s Identity decides what its process can access. Its ServiceSecurity descriptor decides who may start, stop, or query it; the registry key descriptor decides who may edit the definition. Check the right boundary before changing permissions.

Read the definition with svctl definition show <service>. Prefer the identity and privileges the service actually needs. An absent or empty Identity means LocalService; SYSTEM must be explicit. peinit gives each service a separate token and never shares its own SYSTEM token.

A distinct virtual service account #

Set Identity to Service to run under the service's own S-1-5-80-… SID as its user identity. authd derives it from the attested service name, using the same case-insensitive derivation as the existing service group. Only SYSTEM PID 1 may request the attestation. No local principal record or stored credential is created, and this does not provide an interactive logon path.

Unlike shared LocalService, two differently named virtual services have distinct file and process owners. Grant storage access and policy privileges to the individual service SID. Renaming the service changes its identity and requires coordinated updates to those grants. The default remains LocalService for existing definitions; choosing Service is explicit.

The standard timed, resolvd and trustd deployments also use distinct Service identities, retaining their existing service-SID grants. Their SYSTEM preparation hooks, where present, remain separate from their main processes.

The standard eventd deployment uses this identity with SeChangeNotifyPrivilege, SeSecurityPrivilege (KMES consumption), and SeAuditPrivilege (event emission). Its System integrity level allows reception of higher-integrity client tokens; it does not grant SYSTEM account membership or SeTcbPrivilege. A short SYSTEM pre-start hook initializes registry authorization defaults, then exits before the long-running daemon starts. Private stores name eventd's own SID.

Services that need token minting/installation, raw network administration, device management or pre-authd bootstrap still require separate assessment. Granting SeTcbPrivilege solely to make an identity change work defeats the purpose of moving a service out of the machine-wide trust boundary.

The local principal source lpsd also runs as Service, with only SeChangeNotifyPrivilege and System integrity for handling client tokens. Its package provisions its private state scope; credential files are owned by lpsd and admit only lpsd and SYSTEM. Its administrative API still admits SYSTEM and Administrators. /run/psi.sock admits service connections, but authd registers a source only when its enabled service SID matches the configured source allowlist. Transport admission does not confer source authority.

Privilege restriction #

A token comes from its source (authd or the SYSTEM mint) with a default set of privileges. RequiredPrivileges lets a definition trim that set down to only what the service needs:

• peinit reads the RequiredPrivileges allow-list and removes every privilege not on it from the token before exec.
• Restriction is purely subtractive. peinit removes privileges; it never adds them. A service cannot acquire a privilege its token's source did not grant.
• If RequiredPrivileges is absent, the token's default privilege set is used unchanged.

This is least-privilege made concrete: eudev, for instance, runs as SYSTEM (it needs device access during early boot) but with its privilege set stripped to the minimum it actually uses, so a compromise of eudev does not hand an attacker the full SYSTEM privilege set. Removal is permanent for the life of that token — it is not a disable that the service can re-enable. See Privileges for what the individual privileges grant.

Which identity runs what #

A service is not just its main process — it has hooks, health checks, and a reload command, and each runs under a defined identity:

Token materialisation for hooks follows the same rules: a HookIdentity of SYSTEM is minted; any other principal is requested from authd, at the point the hook runs.

HookIdentity exists so hooks can run with different — usually higher — privileges than the service itself: creating directories in privileged locations, or running a database migration as an admin identity, before the long-running daemon drops to a lesser identity.

The per-service SID #

Every service token carries a SID derived from its service name. Granting access to that SID can distinguish two services even when they share LocalService. With Identity=Service, it is also the token’s user identity.

Renaming a service changes its SID. Update grants that name the old SID as part of the same planned change. The SID derivation reference gives the algorithm.

How a token is materialised #

Identity=SYSTEM uses a separate token minted by peinit. Other identities use authd; if authd cannot issue the required identity, the start fails rather than falling back to SYSTEM.

The SYSTEM path #

Use SYSTEM only when the service requires that authority, such as the services needed before authd is available. registryd and authd use this bootstrap path. Standard eventd and lpsd deployments now use their own Service identities and start through authd.

The authd path #

For a non-SYSTEM identity, check that authd is available and the account is permitted for service logon. The authd.service.attested event records the service, issued identity and privileges, or a refusal reason. peinit derives an authority dependency for a non-SYSTEM service or hook identity.

The token-materialisation reference retains the minting and authority flow. The current authd request is specified in the TRM authd path.

Security invariants #

The identity model rests on a few rules peinit never breaks:

1. peinit never shares its SYSTEM token. Even Identity=SYSTEM services get a separately minted token.
2. peinit never drops its own SYSTEM identity. PID 1 runs as SYSTEM for the life of the system — its identity is axiomatic, granted by the kernel at boot.
3. Privileges are subtractive only. RequiredPrivileges removes; it can never add.
4. Identity is deterministic. Every service runs as a known principal. SYSTEM must be declared explicitly; an empty Identity is the minimal LocalService, never SYSTEM.
5. A submitted job never runs as an identity its submitter could not act as. peinit installs only the submitter's own primary token or a token the kernel gated on the way in; it never opens a token by a PID or descriptor a submitter names, and there is no identity field to name one.

Where to start #

Identity decides what a service can do; the ServiceSecurity descriptor decides who can manage it — two independent concerns. Read Who can manage a service for the other half.

To see how the token is installed alongside the rest of the process setup, read The execution environment.

For the identity primitives themselves — tokens, SIDs, privileges — start at Tokens.

If a program works in your shell but fails as a service, compare its identity, environment, working directory, and standard streams. peinit does not inherit your login session. It launches the program with the context in its definition.

Start with svctl definition show <service>, then inspect svctl status <service> and the service’s logs. Check hook output as well as the main program. Environment and working-directory changes reach the next process start; they do not change a process already running.

The environment #

peinit constructs each service's environment in layers, lowest precedence first — it does not pass through its own near-empty startup environment.

1. Compiled-in base. A fixed floor peinit always provides — currently just PATH: /bin.
2. Global EnvVars. Each value under Machine\System\Init\EnvVars\ becomes a variable (value name → variable name). EnvVars\PATH overrides the base PATH; other names add. Every service gets this layer except registryd, which serves the key itself — see the warning below for why that exemption exists.
3. Per-service Environment. The definition's own KEY=VALUE entries, which override layers 1–2.
4. Protocol variables. NOTIFY_SOCKET (always) and LISTEN_FDS / LISTEN_FDNAMES (only when stored fds are injected). These have the highest precedence and cannot be overridden — a service that clobbered NOTIFY_SOCKET would break sd_notify.

A change to EnvVars\ takes effect on a service's next start, like the per-service Environment field — it is not pushed into running services.

peinit deliberately does not set HOME, USER, LOGNAME, SHELL, or TERM. Peios identity is a token (a SID), not a passwd entry, so there is no canonical home directory or login shell to fill in. A service that needs any of these supplies it through EnvVars\ or its own Environment.

Working directory and limits #

peinit also sets oom_score_adj: -1000 (OOM-immune) for ErrorControl=Critical services, and the default 0 for everyone else — so the kernel never picks a Critical platform daemon as an out-of-memory victim.

Runtime directories #

RuntimeDirectories gives a service private scratch space under /run without an ExecStartPre that has to mkdir it by hand. Each name you list becomes a directory created directly under /run — RuntimeDirectories=myapp yields /run/myapp — set up immediately before the main process starts. Each one gets a security descriptor granting full access to SYSTEM, Administrators, and the service's own SID, so the service can write to its directory while other principals cannot. If a directory can't be created, or its descriptor can't be applied, the start fails with ParentSetupFailure.

peinit does not remove these directories when the service stops. /run is a boot-scoped tmpfs, so they simply disappear at the next boot rather than being torn down on each stop — a restarting service finds its runtime directory (though not necessarily its contents) already in place.

For the exact naming rules on each entry and the field's type and default, see the Registry key reference.

Standard streams #

peinit wires a service's standard streams before exec:

• stdin is redirected to /dev/null. peinit never gives a service an interactive input channel; a service that needs input must obtain it explicitly (a socket, a stored fd).
• stdout and stderr are redirected to pipes peinit holds, so it can capture and forward every line. This is the subject of Service output and logging.

Attaching a terminal #

A service that sets TTYPath to an absolute terminal path — /dev/console, /dev/tty1, a serial line — gets that terminal on all three standard streams instead of the wiring above, and becomes a session leader owning it as its controlling terminal. That last part is what makes job control work: Ctrl-C interrupts, fg/bg behave, and a hangup reaches the process group. It is what a boot shell or a login prompt needs.

It carries a path rather than a flag because which terminal is a per-service question: a maintenance shell on tty1 while the kernel console is a serial line is an ordinary thing to want.

Two services pointed at the same terminal do not fight over it. peinit gives the device to one of them and skips the rest — highest TTYPrecedence wins — and a skipped service can ask to be started when the terminal frees, with the tty:released trigger. See Queueing for a terminal.

Pre-exec and post-exec hooks #

Hooks let a service do work around its main process without baking it into the binary.

• ExecStartPre runs before the main binary. Each command runs in sequence, in the hooks/ sub-cgroup; any hook exiting non-zero aborts the start (the whole cgroup is killed and the service Fails with PreHookFailure). Use it for prerequisites that must hold before the service starts — creating a runtime directory, waiting on a precondition.
• ExecStartPost runs after readiness (Simple) or after a successful exit (Oneshot). A post-hook failure is logged but does not fail the service — by the time it runs, the service is already up. (A Oneshot that fails never runs its post-hooks.)

Hooks run under HookIdentity if set, otherwise the service's own identity. Their output is captured and tagged like the main process's, labelled with the hook (e.g. jellyfin/ExecStartPre[0]).

Command string parsing #

The command fields — ExecStartPre, ExecStartPost, ExecReload, HealthCheck — are parsed into an argument list with simple, predictable rules. peinit never invokes a shell.

• Whitespace splits the command into arguments; double quotes group text containing spaces into one argument and are not retained (--name="hello world" → one argument --name=hello world).
• There is no shell expansion, variable substitution, or globbing. Backslash is literal; a single quote is an ordinary character.
• The first argument is the executable and must be an absolute path beginning with /. Relative names and PATH search are validation errors.
• An empty or whitespace-only command, or an unclosed quote, is a validation error.

If a command genuinely needs shell features, wrap it in a script and point the field at the script.

ExecReload can also be a signal, written signal:<NAME> — for example signal:SIGHUP. The name must be an exact, canonical Linux signal name (uppercase, no aliases, no numbers); SIGKILL and SIGSTOP are rejected because they cannot be handled as a reload. With no ExecReload at all, reload sends SIGHUP. The reload lifecycle is covered in Controlling services.

Conditions and asserts #

Before peinit runs any hook or the main process, it evaluates conditions and asserts — start-time checks in the same type:argument form. The difference is what failure means:

• A failed Condition skips the service — it transitions to Skipped, which satisfies its dependents (it succeeded by not needing to run). Conditions express "only run here if it makes sense."
• A failed Assert fails the service — it transitions to Failed with AssertionError. Asserts express "this was expected to run, and a precondition is missing."

Conditions are checked first; only if all pass are asserts checked. All entries are AND-ed. The check types:

Two constraints follow from peinit being single-threaded PID 1, which must never block:

• registry: checks are cache-only. Accepted paths are exactly Machine\System\Services, Machine\System\Init, and Machine\System\Services\<name> with one nonempty service-name component. The roots resolve as present; the last form checks whether the service exists in the in-memory model. Init descendants, deeper Services paths, trailing separators, and other keys are load-time decode errors. No live registry read is made.
• Filesystem checks run off the main loop. path:/file:/directory: checks are performed by a short-lived forked helper, not a stat() on the event loop, because stat() can wedge on a hung mount.

That timeout is the PreStartCheckTimeout field, which defaults to 5 seconds. A filesystem check that does not finish within it — say a stat() wedged on a hung mount — is treated as not satisfied, fail-safe: peinit kills the helper and treats the check as unmet, so a Condition skips the service and an Assert fails it, rather than letting the event loop hang.

The fd store #

The fd store lets a service preserve file descriptors across restarts — most usefully a listening socket, so a stateful daemon can restart without dropping connections. It is opt-in: FdStoreMax (default 0) sets the maximum number of fds peinit will hold; 0 disables it.

The mechanics ride on sd_notify:

• A service stores an fd by sending FDSTORE=1 with the fd attached (and optionally FDNAME=<name>; the default name is stored). peinit holds it.
• It removes one with FDSTOREREMOVE=1 and FDNAME=<name>.
• On the next start, peinit injects the stored fds starting at fd 3, sets LISTEN_FDS to the count and LISTEN_FDNAMES to the colon-separated names, then clears the store. (This is the same LISTEN_FDS convention systemd uses, so software with existing fd-passing support works unmodified.)

The store survives an automatic restart (crash → restart policy → new start) — that is the whole point. It is cleared on an explicit stop or shutdown (the service is not coming back), and when a removed definition is finally discarded.

A clean context #

A service receives its standard streams and explicitly supplied descriptors. It does not inherit peinit’s privileged connections or signal handling. The launch-isolation reference describes the descriptor and signal setup.

The cgroup tree #

peinit tracks a service’s main process, hooks, and health checks in separate cgroups beneath /sys/fs/cgroup/peinit/. It uses those groups for tracking and clean termination, not resource limits.

A leaked cgroup warning means a process survived cleanup, often because I/O is stuck. A later start can use a fresh <service>.gen<N> tree; that does not repair or kill the stuck old process. Investigate the Abandoned state. The cgroup reference retains the layout and rationale.

Where to start #

For the identity half of the launch — how the token is chosen and installed — read Service identity and privileges.

For what happens to the stdout/stderr pipes peinit holds, read Service output and logging.

For how conditions, asserts, and hooks fit into the start sequence and its states, read The service lifecycle.

System-console aliases and logout #

Peinit pins TTYPath=/dev/console to the kernel-selected terminal when reading service definitions. A display's moving tty0 alias becomes tty1, so switching the foreground console does not move the session. Both arbitration and launch use this fixed endpoint. When a terminal service's main process exits, peinit kills its remaining session processes before handing the terminal on. A clean exit under RestartPolicy=Always restarts the prompt at the base delay without spending the crash budget.

To let someone start or stop a service, change its ServiceSecurity permissions. Do not give them write access to the service definition just to grant control: definition writes can change the program and the identity it runs as.

In Services Manager, select the service and inspect the commands you may use. Who may control it… edits runtime control; Who may change its definition… edits the registry key’s permissions. If a command returns ACCESS_DENIED, check its required right and the caller’s identity before widening either descriptor.

Two descriptors, two questions #

A service is associated with two descriptors that are easy to conflate but answer different questions and are enforced by different components:

The registry key SD is ordinary registry access control and not peinit's concern — peinit reads definitions as SYSTEM, which has full access. The ServiceSecurity SD is peinit's domain, and the rest of this page is about it.

They are genuinely independent. An administrator might be able to query a service's status (ServiceSecurity grants SERVICE_QUERY_STATUS) but not read its configuration (the registry key SD denies read) — or the reverse. Runtime control and configuration access are separate concerns, and both combinations are valid.

Changing them from the desktop #

On a GXWI desktop, select the service in Services Manager. Below what you may do with it, the details pane says where its ServiceSecurity comes from: set for this service, the default set for every service, or peinit's built-in default. Two buttons open the permissions editor, and both are also on each row's right-click menu.

• Who may control it… opens the ServiceSecurity descriptor. Its boxes are the service rights in words: Full control, Start, Stop, Reload (SERVICE_INTERROGATE) and See its state (SERVICE_QUERY_STATUS). Restart needs Start and Stop together, and Reset needs Stop. When you apply, Services Manager writes the result as the service's own ServiceSecurity value. From then on, a change to the default no longer reaches that service. peinit applies the new descriptor on the next command, and the window's buttons change to match.
• Use the default appears beside it once the service has its own value. After you confirm, it deletes that value, so the service takes the default again.
• Who may change its definition… opens the descriptor of the service's registry key. Its boxes are Full control, Read and Write on the key. Entries you add there apply to the key and to any keys under it.

Under Every service, the pane says what a service without its own value takes:

• Default permissions… opens the ServiceSecurity on Machine\System\Services. If there isn't one, it starts from peinit's built-in default. Applying writes it to that key, and it reaches every service without its own value at the next command.
• Use the built-in default appears once that key has a value. After you confirm, it deletes the value, so services without their own go back to peinit's built-in default.

Each of these is offered for changing only if you are allowed to change it:

• ServiceSecurity is a value on a registry key: the service's key, or Machine\System\Services for the default. Changing it, or deleting it, needs the right to set values on that key (KEY_SET_VALUE).
• The service key's own descriptor needs WRITE_DAC, and WRITE_OWNER for its owner.

If you are not allowed, the editor still shows who may do what and says why it can't be changed, and the two "use the default" buttons are unavailable with the reason. Services Manager finds this out by asking the registry for those rights, not from your group memberships.

The same can be done from a terminal with reg. For example, this makes sshd take the default again:

$ reg del 'Machine\System\Services\sshd' ServiceSecurity

Service access rights #

The ServiceSecurity descriptor grants these rights:

restart requires both SERVICE_STOP and SERVICE_START, since it is a stop followed by a start. reset requires SERVICE_STOP.

When peinit evaluates the descriptor it maps the generic rights as follows, so a descriptor written with generic rights behaves sensibly:

The default descriptor #

If a service has no ServiceSecurity value, it inherits the one on Machine\System\Services itself. If that key has none either, peinit applies a built-in default:

• SYSTEM (S-1-5-18) — full access.
• Administrators (S-1-5-32-544) — full access.
• Authenticated Users (S-1-5-11) — query only.
• Everyone (S-1-1-0) — every refusal audited, in its SACL.