# Using Peios

> Operating a Peios system — the registry, filesystems, and the everyday tools.

All of Using Peios as one markdown file: [/peios/using-peios/print.md](/peios/using-peios/print.md)

- [Peiosutils](/peios/using-peios/peiosutils.md): The Peios core utilities — the everyday commands, reworked for the Peios security model.
- [Peios Events Index](/peios/using-peios/events.md): Every event Peios emits, in one place — the KMES envelope, the shared subject and process records, and a field-by-field schema for each event from the kernel, the filesystem, the registry, peinit, peipkg and eventd.

## Threads and processes

- [Threads and processes](/peios/using-peios/threads-and-processes/overview.md): A process is a running program; a thread is a single line of execution inside it. Every action the system takes happens on some thread.
- [The process and thread model](/peios/using-peios/threads-and-processes/the-process-and-thread-model.md): A thread is the basic unit of work; a process is the boundary around its threads, holding the memory, open resources, and identity they share.
- [Creating processes](/peios/using-peios/threads-and-processes/creating-processes.md): How processes are created — fork, exec, spawn, and clone — what a new process starts with, and how to hold a reliable handle to one with a pidfd.
- [Process lifecycle](/peios/using-peios/threads-and-processes/process-lifecycle.md): How a process ends, how its result is collected, what happens when its parent ends first, and how the system cleans up after it.
- [Process relationships and job control](/peios/using-peios/threads-and-processes/relationships-and-job-control.md): The two ways processes relate — descent, forming a family tree rooted at PID 1, and grouping into process groups and sessions for job control.
- [The Process Security Block](/peios/using-peios/threads-and-processes/the-process-security-block.md): The Process Security Block (PSB) records what a process is — its program's trust, its hardening, and who may operate on it — as distinct from who it acts as.
- [Process creation reference](/peios/using-peios/threads-and-processes/process-creation-reference.md): The precise contract for fork, vfork, clone and clone3, the clone sharing flags, the exec family, posix_spawn, and the pidfd calls.
- [Process lifecycle reference](/peios/using-peios/threads-and-processes/process-lifecycle-reference.md): The precise contract for ending a process and collecting its result — exit, _exit and exit_group, the exit-status encoding, and the wait family.
- [Thread operations reference](/peios/using-peios/threads-and-processes/thread-operations-reference.md): The per-thread operations a program uses directly — reading a thread's ID, the exit-notification mechanism behind thread joins, and thread-local storage.

## Services & jobs

- [peinit](/peios/using-peios/services-and-jobs/overview.md): peinit is PID 1 — the single service manager. Services, jobs, and operations; identity built in; and how it differs from the init systems you know.
- [Defining a service](/peios/using-peios/services-and-jobs/defining-a-service.md): A service is a registry key under Machine\System\Services\, made of typed values. The schema, and the mutability class that decides when a change lands.
- [Simple and Oneshot services](/peios/using-peios/services-and-jobs/service-types.md): peinit has exactly two service types — long-running Simple and run-to-completion Oneshot — plus the readiness models that decide when each counts as started.
- [Triggers and timers](/peios/using-peios/services-and-jobs/triggers-and-timers.md): Boot and timer triggers, the Disabled flag, and the full OnCalendar grammar — persistent catch-up, jitter, and what happens when the clock jumps.
- [The service lifecycle](/peios/using-peios/services-and-jobs/the-service-lifecycle.md): The ten service states, the transitions that connect them, and the cause taxonomy that says why a service ended up where it is.
- [Keeping services running](/peios/using-peios/services-and-jobs/supervision.md): Restart policy with backoff and a budget, active health checks, the watchdog, timeout extension, OnFailure, and the Critical reboot path.
- [Dependencies and ordering](/peios/using-peios/services-and-jobs/dependencies.md): Requires, Wants, BindsTo, and Conflicts — start order, stop order, failure propagation, graph validation, and parallel start.
- [Service identity and privileges](/peios/using-peios/services-and-jobs/identity-and-privileges.md): How a service token is materialised — minted for SYSTEM, requested from authd otherwise — plus the per-service SID and RequiredPrivileges trimming.
- [The execution environment](/peios/using-peios/services-and-jobs/execution-environment.md): What a service process starts with — its cgroup tree, stdio, layered environment, limits, hooks, conditions and asserts, and the fd store.
- [Controlling services](/peios/using-peios/services-and-jobs/controlling-services.md): peiosctl and the control socket — the verbs and their rights, wait semantics, the command-by-state matrix, status output, and error codes.
- [Who can manage a service](/peios/using-peios/services-and-jobs/who-can-manage-a-service.md): Every control command runs AccessCheck against the service's ServiceSecurity descriptor. The rights, the defaults, and the system control descriptor.
- [Jobs and operations](/peios/using-peios/services-and-jobs/jobs-and-operations.md): A job is one process execution; an operation is one requested action. Their lifecycles, types, and GUIDs — plus ad-hoc jobs submitted through JFS.
- [Service output and logging](/peios/using-peios/services-and-jobs/output-and-logging.md): peinit captures every service's stdout and stderr, buffers before eventd exists, and forwards after — best-effort logs, guaranteed audit events.
- [Boot and boot modes](/peios/using-peios/services-and-jobs/boot-and-boot-modes.md): The two-phase boot — hardcoded bootstrap, then registry-driven — and the Full, Safe, and Recovery modes with the boot-attempt counter between them.
- [Shutdown](/peios/using-peios/services-and-jobs/shutdown.md): Shutdown is boot in reverse — SIGTERM to SIGKILL in reverse dependency order, bounded by a global timeout, then seed, unmount, sync, and power off.
- [Troubleshooting peinit](/peios/using-peios/services-and-jobs/troubleshooting.md): A symptom-first guide — a service that won't start or keeps restarting, a change that didn't land, an access denial, and a machine stuck rebooting.
- [Registry key reference](/peios/using-peios/services-and-jobs/registry-key-reference.md): The complete catalog — every service-definition field with its registry type and default, and every key peinit reads or writes.

## Mount policies

- [Mount policies](/peios/using-peios/mount-policies/overview.md): Every mounted filesystem carries a mount policy — one per-superblock setting deciding whether FACS applies and how missing SDs are handled.
- [Policy classes](/peios/using-peios/mount-policies/policy-classes.md): The four policy classes, the synthesis chain that produces an SD when one is missing (parent → mount template → fallback), and the universal corrupt-SD rule.
- [SD storage by filesystem](/peios/using-peios/mount-policies/sd-storage-by-filesystem.md): How each filesystem stores SDs — ext4 xattrs and ea_inode, NTFS round-tripping via system.ntfs_security, FAT's in-memory synthesis — and the implications.
- [Managing mounts](/peios/using-peios/mount-policies/managing-mounts.md): kacs_set_mount_policy and kacs_get_mount_policy, the generation counter behind lazy invalidation, and the SeTcbPrivilege requirement.
- [mount](/peios/using-peios/mount-policies/mount.md): Attach a filesystem to the Peios mount tree — new mounts, binds, moves, remounts and propagation changes — and apply a KACS mount policy at mount time.
- [umount](/peios/using-peios/mount-policies/umount.md): Detach a filesystem from the Peios mount tree by mount point or by source, with lazy, forced, recursive and all-targets variants.
- [lsblk](/peios/using-peios/mount-policies/lsblk.md): List block devices as a tree, flat list, JSON or key=value pairs — with filesystem identity, topology, and SD-derived owner and mode columns.

## Disks and filesystems

- [Disks and filesystems](/peios/using-peios/disks-and-filesystems/overview.md): The tools Peios ships for creating, checking and inspecting ext2/3/4 and FAT filesystems, and why they are packaged from upstream rather than rewritten.
- [Stable device names](/peios/using-peios/disks-and-filesystems/stable-device-names.md): Why /dev/vda is not a name to keep, what /dev/disk/by-uuid and its siblings are, who creates them, and where they are not available.
- [Partitioning](/peios/using-peios/disks-and-filesystems/partitioning.md): part, the Peios partitioning tool: creating GPTs, adding and removing partitions, and what it refuses to touch.
- [Formatting with security descriptors](/peios/using-peios/disks-and-filesystems/formatting-with-security-descriptors.md): How a filesystem gets real security descriptors at creation time, rather than synthesised ones at mount time, and why that distinction matters.
- [mke2fs](/peios/using-peios/disks-and-filesystems/mke2fs.md): The Peios additions to mke2fs: the root_sddl and root_sd_file extended options, security-descriptor-aware population, and the compiled-in Peios defaults.
- [Installing to disk](/peios/using-peios/disks-and-filesystems/installing-to-disk.md): How a Peios system is copied from a live medium onto a disk, and how the installed system boots itself afterwards.
- [StrataFS](/peios/using-peios/disks-and-filesystems/stratafs/overview.md): StrataFS merges ordinary directories by precedence while keeping each stratum independently manageable. Mounting a stack and the stratafs inspection tool.

## Package management

- [Package management](/peios/using-peios/package-management/overview.md): peipkg installs, upgrades, removes, and queries software on a Peios system. This page covers packages, repositories, the security model, and the commands.
- [Installing and removing packages](/peios/using-peios/package-management/installing-and-removing.md): install puts packages on the system; remove takes them off. The plan-and-confirm flow, raw installs from a local .peipkg file, and cascade removals.
- [Keeping a system current](/peios/using-peios/package-management/keeping-a-system-current.md): refresh learns what is available; upgrade moves to it; downgrade and undo walk a bad change back. The routine update cycle and the recovery commands.
- [Repositories and trust](/peios/using-peios/package-management/repositories-and-trust.md): The repo commands, the trust ceremony that anchors a repository to a signing key, key rotation, signature policy, priority, and freshness protection.
- [Transactions and recovery](/peios/using-peios/package-management/transactions-and-recovery.md): Every peipkg change is an atomic, reversible transaction. This page covers the three phases, the commit instant, interrupted runs, and recover and history.
- [Dependency resolution](/peios/using-peios/package-management/dependency-resolution.md): How a request becomes a concrete plan — dependencies, conflicts, provides and replaces, version choice, and the elevated-authorisation prompt.
- [Claims](/peios/using-peios/package-management/claims.md): A claim is a shared filesystem name that only one installed package may hold. How claims materialise as symlinks, and the claim command for reassigning them.
- [Inspecting and verifying](/peios/using-peios/package-management/inspecting-and-verifying.md): The read-only commands — list, info, files, owns, and search to see what is installed and available, verify to check files are intact, clean to tidy the cache.
- [Named roots](/peios/using-peios/package-management/named-roots.md): peipkg can operate on several roots at once — named references, dotted composition, default_root, the cascading upgrade, and cross-root dependencies.
- [Composing a root](/peios/using-peios/package-management/composing-a-root.md): peipkg-compose builds a fresh, package-owned root from a declarative manifest — offline and deterministically. The lock and build verbs and the lock file.

## Concepts

- [The registry](/peios/using-peios/registry-concepts/overview.md): The registry is the system's typed, access-controlled, watchable configuration store — a tree of keys and values reached only through kernel system calls.
- [Keys, values, and types](/peios/using-peios/registry-concepts/keys-values-and-types.md): The registry's data model — a tree of keys holding named typed values, the value types, the naming rules, and why a value is typed but never interpreted.
- [Configuration, not storage](/peios/using-peios/registry-concepts/configuration-and-meaning.md): The registry stores values it does not understand — meaning lives in the owning subsystem and in regman, and a stored value can differ from the one in use.
- [Watching for changes](/peios/using-peios/registry-concepts/watches.md): A persistent watch on a key or subtree reports changes to effective state — best-effort delivery, so a watcher must be ready to re-read.

## Layers

- [Layers](/peios/using-peios/registry-layers/layers.md): A layer is a label on a write, not a position in a stack — most layers share one precedence, and the winner is chosen per value by recency.
- [What layers are for](/peios/using-peios/registry-layers/what-layers-are-for.md): Layering makes configuration removable — delete a layer and its writes vanish, the next-best write resurfaces, and nothing is left behind.
- [Deleting keys and values](/peios/using-peios/registry-layers/deleting-keys-and-values.md): Deleting a key withdraws one layer's claim to a name — the key stays if another layer still claims it, and there is no recursive delete.

## Security

- [Access control on keys](/peios/using-peios/registry-security/access-control.md): Every key is a secured object under the same AccessCheck as everything else — checked once at open, per key not per value, with no traversal check.
- [Default security descriptors](/peios/using-peios/registry-security/default-security-descriptors.md): Where a component keeps the security descriptors it stamps at runtime — the SdDefaults convention — and the reject-or-keep rule that guards it.

## Administration

- [How the registry boots and configures itself](/peios/using-peios/registry-administration/bootstrap-and-self-configuration.md): The registry runs on compiled-in defaults from the instant the kernel loads and hot-swaps to registry-backed configuration once its store is up.
- [Backup and restore](/peios/using-peios/registry-administration/backup-and-restore.md): Export a subtree to a stream and restore one back wholesale — how the system is seeded, recovered, and migrated. Restore is a replace, not a merge.
- [LCS and sources](/peios/using-peios/registry-administration/lcs-and-sources.md): Underneath, the registry is two components — LCS, the kernel authority, and userspace sources that only persist data, with loregd as the default.
- [The registry manual (regman)](/peios/using-peios/registry-administration/regman.md): regman documents what a registry key or value means — type, default, valid range, and when a change applies — from shipped docs, never the live registry.
- [reg](/peios/using-peios/registry-administration/reg.md): The reg command reads and writes the live registry — values, keys, layers, links, security descriptors, watches, and atomic batches.

## Advanced

- [Private hives and layers](/peios/using-peios/registry-advanced/private-hives-and-layers.md): Private hives and layers give one caller its own view of the registry — the building block for sandboxing, with authorisation deferred to KACS.
- [Transactions](/peios/using-peios/registry-advanced/transactions.md): A transaction groups several registry writes into one all-or-nothing commit — how a role installs without ever being half-applied.
- [Registry links](/peios/using-peios/registry-advanced/registry-links.md): A key can be a symbolic link to another key — the one place the registry interprets a value — with layered targets and privileged creation.

## Constants and Catalogs

- [Constants and catalogs](/peios/using-peios/constants-and-catalogs/overview.md): Where every numeric constant in Peios is catalogued — access rights and GenericMappings here, ACE types and well-known SIDs in PCDS, privileges in the kernel manual.
- [Well-known SIDs](/peios/using-peios/constants-and-catalogs/well-known-sids.md): Where the well-known SID catalogue lives — PCDS §4.4 — and the PIP trust label ladder.
- [Privilege catalog](/peios/using-peios/constants-and-catalogs/privilege-catalog.md): Where the per-privilege catalogue lives — the Peios Kernel TRM — and the two privileges that are enforced but unnamed.
- [ACE types and flags](/peios/using-peios/constants-and-catalogs/ace-types-and-flags.md): Where the ACE type and flag catalogues live — PCDS §5.4 — including the AceType constant table and the MIC policy bits.
- [Access mask bits](/peios/using-peios/constants-and-catalogs/access-mask-bits.md): The per-object-type access rights — file, process, token, registry key, service — plus the standard, special and generic rights, the GenericMapping tables, and the aggregate *_ALL_ACCESS constants.
- [Other constants](/peios/using-peios/constants-and-catalogs/other-constants.md): Enumerated values that are not access rights — impersonation levels, integrity levels, logon types, PIP tiers, token audit policy, create dispositions, SECURITY_INFORMATION flags, mitigation flags, and the kernel's size limits.

## Wire Formats Reference

- [Wire formats reference](/peios/using-peios/wire-formats-reference/overview.md): Where every byte-level layout in Peios is specified — security descriptors, SIDs, conditional-ACE bytecode, claim entries, token and session specs, CAAP, and the KMES event envelope.
- [Security descriptors (wire format)](/peios/using-peios/wire-formats-reference/security-descriptors.md): Where the byte-level security descriptor layouts are specified — PCDS chapters 4 and 5.
- [CAAP format](/peios/using-peios/wire-formats-reference/caap-format.md): Where the central access policy wire format is specified.
- [Token and session specs](/peios/using-peios/wire-formats-reference/token-and-session-specs.md): Where the binary token and session specifications are laid out — the Peios Kernel TRM's KACS ABI appendix.

## Kernel ABI Reference

- [Kernel ABI reference](/peios/using-peios/kernel-abi-reference/overview.md): Where the KACS and LCS kernel ABIs are documented — syscall numbers, ioctls, structure layouts, and constants, generated from uapi.