# `schinit` — PID 1 as a role Shaped after launchd rather than sysvinit, and it breaks one Unix rule on purpose. --- ## The rule that was changed Unix's rule is *PID 1 is special and must never die*. Every init since 1975 has honoured it by being careful. > **SchOS's rule instead: PID 1 is a role. The kernel guarantees the role is > filled. The role's state lives outside whichever process currently holds it.** "Must never die" is not a mechanism — it is a hope, and the thing it hopes about is the one program on the machine with no supervisor. What replaced it is four pieces: a split by role, state in `/proc`, a heartbeat, and a kernel that re-execs PID 1 in place instead of panicking. ### The arrangement it is not The obvious design — init 1 starts init 2; if init 1 dies, init 2 revives it — was tried on paper and rejected. The failures are worth keeping, because they are the traps any redundant-supervisor scheme falls into: - **It defends against an attack that already fails.** Userspace cannot kill PID 1 here: `init_ignores()` drops `SIGKILL` to `initproc`. - **Init 2 is the same binary.** If init 1 died of its own bug, init 2 reaches the same line and dies the same way — *faster*, having just watched the input that caused it. - **The chain has no bound.** Init 2 makes init 3 by symmetry. With a cap, the cap is the real design and the chain is decoration. - **Two supervisors is split brain.** Both hold the job table, both see a pid exit, both restart it. Now the console shell exists twice, both reading `/dev/console`. That is worse than no redundancy: it corrupts the state it was added to protect. - **It only detects death.** The common way an init breaks is *hanging*, and `wait()` never returns for a process that is merely stuck. The scheme is armed against the rare failure and blind to the likely one. --- ## The split | | | |---|---| | **`schinit`** (PID 1) | Reaps children, holds the job table in memory, supervises exactly one child. No manifest parsing, no filesystem walking after boot, no allocation. About 520 lines. Its entire job is to be too boring to fail. | | **`schinitd`** (PID 2) | Manifests, respawn policy, backoff, socket sections, and the eventual `schinitctl`. This is where the bugs will be, and it is restartable. | The detail that makes this work, and that two copies of one program cannot have: > **Jobs are forked by PID 1, not by `schinitd`.** `schinitd` decides and asks; > PID 1 acts. Every job on the machine is a child of PID 1 at all times, so > `schinitd` crashing orphans nothing, reparents nothing and restarts nothing. It > comes back, reads the state, and finds the world exactly as it left it. So there are still two processes with one watching the other — but their roles are *different*, which is what stops the second being a second copy of the first one's bug. ### The protocol `include/schinit.h`. **Every message is exactly one struct**, and PID 1 reads `sizeof(struct)` or nothing: no length prefix to get wrong, no partial-message state machine, and no allocation in the process that must not fail. The socket is a `socketpair` inherited as fd 3. | To PID 1 | | To the supervisor | | |---|---|---|---| | `HELLO` | version handshake | `WELCOME` | PID 1's version, echoed | | `SPAWN` | start this job | `SPAWNED` | the pid, or negative | | `PONG` | answer to a ping | `EXITED` | a child was reaped | | | | `PING` | answer within the deadline | --- ## State outside the process `/proc/schinit` is the serialised job table: a generation, the supervisor's pid, then one line per running job — cookie, pid, start tick, label. It is **written by PID 1**, because PID 1 is the process that cannot lose it, and written whenever the table changes rather than generated on read — a procfs generator runs in the kernel, and the kernel has no business walking this program's memory. procfs rather than a file on disk for four reasons: it survives a read-only root, it survives a full disk, it costs no I/O, and it is already the pattern this kernel uses for exactly this kind of question. A resurrected supervisor reads it back and adopts what is already running instead of starting it again. The side benefit is that the job table is no longer invisible: `cat /proc/schinit` is the observation. --- ## The heartbeat PID 1 pings the supervisor every 2 seconds and expects an answer within 10. This is the failure the sibling-init scheme cannot see: a supervisor that is *stuck* rather than dead never causes a `wait()` to return. Silence from `schinitd` means PID 1 replaces it — **without waiting for the corpse**, because `kill()` on a wedged process never completes and PID 1 waiting for it would be the hang it was trying to detect. Silence from PID 1 is what the kernel change exists for. --- ## `proc_reincarnate()` `exit()` on `initproc` used to `panic("init exiting")`. Now the kernel tears down the address space, keeps the `struct proc`, keeps **pid 1**, and re-execs `/bin/schinit` in place with a generation counter passed in. No init 2, no init 3, and no reparenting problem — **because pid 1 never stops being pid 1**. Every orphan the kernel already reparented to `initproc` is still correctly parented, `initproc` is still the pointer it always was, the children survive, and the state is in `/proc/schinit`. Three details in that path are not obvious and each was a bug first: - **`exec()` returns 0 on success.** It does not fail to return, so the code after it is the *success* path, not an error path to panic in. - **`killed` has to be cleared first**, or the new image exits before its first instruction — five generations in microseconds. - **`exec` preserves descriptors**, so the new PID 1 inherits the old supervisor's socket and never sees the hangup that tells it the supervisor is gone. It has to be closed deliberately. ### The escalation ladder | Generation | What happens | |---|---| | 1 | Normal boot. | | 2–3 | Re-exec in place. Log it, keep the jobs, carry on. | | 4 | Re-exec, but ignore `/etc/schinit` entirely and start only a console shell. **A manifest that kills init must not kill it forever.** | | 5 | Stop. `panic()`. | The last row is the honest one. A machine that cannot hold PID 1 up five times is not a machine that should keep trying, and PSOGM renders a stop code, a call chain and a QR code of the whole report — a far better end than a silent loop. ### Both paths are tested by doing them, not by reasoning Two `sysrq` keys exist for this: | | | |---|---| | `sysrq i` | Kills PID 1. Signals cannot — `init_ignores()` drops them — so this sets `killed` directly, which is the kernel deciding rather than userspace asking. | | `sysrq w` | Wedges `schinitd` on purpose, so the heartbeat timeout is exercised. There is no way back from it; reboot afterwards. | ``` init: pid 1 exited with status 9 -- reincarnating, generation 2 schinit: reclaimed 2 running job(s) from /proc/schinit schinit: SchOS process 1, generation 2 (reincarnated) schinitd: adopting os.schos.console-shell schinitd: adopting os.schos.tty2-shell ``` The shell being typed into keeps its pid across the death and rebirth of PID 1. --- ## Why launchd **Demand launching.** The supervisor holds the listening socket or watches the path, and starts a job when something actually arrives. That inverts the dependency graph. A job stops needing to declare what must be running before it, because the thing it depends on answers on first use — and runlevels stop being a concept at all. SchOS has the two pieces that make it possible: `AF_UNIX` sockets and a real `/proc`. Socket sections are parsed and remembered but not yet held, so this is still the reason for the shape rather than a feature of it. ## Constraints on the programs themselves Both link against `lib/`, which is raw syscall stubs. **There is no libc here** — no `malloc`, no `printf`, no `strlen`. Everything is static storage and hand-rolled, which is also why the limits are constants rather than growable: | | | |---|---| | `MAXJOBS` | 32 | | `MAXARGS` | 16 | | manifest size | 4 KB, read into one static buffer | ## Bootstrap Before any job runs, PID 1 creates the device nodes and mounts that a job needs in order to have somewhere to send its output. **This cannot itself be expressed as a job** without a bootstrapping problem, which is why it is a function and not a manifest. Console first, as fd 0/1/2, so every message after it has somewhere to go. Then the `/dev` nodes — minor numbers under major 1 follow Linux's mem-major layout where it costs nothing (`null=2`, `zero=5`, `full=7`, `random=8`, `urandom=9`) — then `/dev/input/event0` and `event1`, the raw disks, and `/proc`. Two details that look like carelessness and are not: **The nodes are created unconditionally, including for absent hardware.** Opening `/dev/hdb` with no drive present fails with `ENXIO`, which is a better answer than a missing path. It matters more than it looks: with no node, `echo x > /dev/hdb` silently creates an ordinary *file* of that name and appears to succeed. **The `mknod`'d `/proc` files still happen and are then covered by the mount.** A failure to mount degrades to the old behaviour rather than losing `/proc` entirely. ## Job manifests Held by `schinitd`, not by PID 1. Every `*.job` file in `/etc/schinit` is loaded at boot, found with `getdents64` rather than a hardcoded list — so dropping a file in the directory is all it takes to add a job. Sectioned `key = value`, `#` starts a comment, keys are case-insensitive (a manifest may say `KeepAlive`, `keepalive` or `KEEPALIVE`; keys are for humans and this is not a language). | Key | | |---|---| | `Label` | A reverse-DNS name, as launchd uses. Identity, not a path. | | `Program` | The binary to execute | | `Args` | argv, space separated. argv[0] is conventionally the basename, so `Args = sh` for `/bin/sh` | | `RunAtLoad` | Start it when schinit loads | | `KeepAlive` | Restart it when it exits — unless it exits `SCHINIT_EXIT_NORESTART`, below | | `Disabled` | Load it but do not start it | | `ThrottleInterval` | Seconds between respawns (default 1) | | `ControllingTerminal` | Claim the console | | `StandardIn` / `StandardOut` / `StandardError` | Paths to open as fd 0, 1, 2 | | `[Socket ]` → `Path` | Parsed, recorded, not yet honoured | **Unknown keys and unknown sections are ignored rather than fatal.** A manifest written for a newer schinit must not stop this one booting the machine. ## Starting a job Each job gets **its own session** (`setsid`), so it cannot reach back and signal the rest of the system through a shared controlling terminal. That is exactly what makes `ControllingTerminal` necessary, and the interaction is the least obvious thing in the program: > A fresh session has no controlling terminal, and a terminal only delivers input > to the foreground process group it is tracking. Without > `ControllingTerminal = yes`, the shell comes up, echoes every keystroke through > the line discipline, and executes none of them — which looks like a hung shell > and is really a terminal that is not listening to it. It is **off by default**. A daemon has no business seizing a terminal, and launchd's model is that the terminal is something a job asks for. `exec.c` enables the Linux ABI automatically for musl binaries, so a job must not call `enable_linux_abi()` itself — it would renumber the syscalls the child still has to make. ## Supervision PID 1 loops on `wait()` and reports every reaped pid to the supervisor. **It reaps whatever exited, including processes reparented here when their own parent died.** Those are not jobs, and that is the whole handling they need. A `KeepAlive` job is restarted by the supervisor asking PID 1 to spawn it again, subject to `ThrottleInterval` — a job that exits immediately and forever would otherwise spin the machine. launchd defaults to 10 seconds; 1 is enough here, where the common case is a shell someone just exited on purpose and expects back. ### One exit status the supervisor reads Throttling stops a restart loop from costing CPU. It does not stop it being a loop, and a job that can never succeed on this machine will print its reason every `ThrottleInterval` for the rest of the uptime — measured at fifteen spawns in forty-five seconds for `vgpud` on a machine with no virtio-gpu. So a `KeepAlive` job that exits **`SCHINIT_EXIT_NORESTART`** (78, sysexits.h's `EX_CONFIG`) is not restarted, and the supervisor says which job stopped and why: ``` vgpud: no virtio-gpu on this machine schinitd: os.schos.vgpud has nothing to do on this machine; not restarting ``` The distinction it draws is the right one: the status is wait(2)-encoded, so a job that was **killed or faulted** has a signal in the low bits, never matches, and comes back exactly as `KeepAlive` promises. Only a job that exited deliberately, saying this machine is not one it can run on, is believed. This is not a new manifest key and there is no policy knob. The wait status has always travelled from PID 1 to the supervisor inside `struct schinit_reply`; `note_exit()` simply stopped discarding it. ## The fallback With no manifests found, the supervisor says so and starts `/bin/sh` on the console anyway. > An unbootable-looking machine because a manifest was missing would be a poor > trade for purity. --- ## What it does not do - **Socket activation is not implemented.** The manifest key is parsed and the path remembered; nothing holds the socket, so demand launching — the entire reason for copying launchd — does not happen yet. - **No `schinitctl`.** Jobs cannot be started, stopped or reloaded at runtime. They can now be *inspected*, through `/proc/schinit`, which is half of it. - **No dependency ordering of any kind**, deliberately — demand launching is meant to make it unnecessary, and until that exists there is nothing in its place either. - **No log capture.** `StandardOut` is a path, so a job's output goes wherever the manifest says and nothing aggregates it. - **`/proc/schinit` records running jobs, not the whole table.** A job that is loaded and stopped is not in it, so a resurrected supervisor learns what is alive and re-reads the manifests for everything else. - **A new compatibility surface exists between PID 1 and PID 2** that did not before, and the tree's own [../plan/schapi.md](../plan/schapi.md) §3 spends a section warning about exactly those. `SCHINIT_PROTO` is versioned in the handshake, which is the least that can be done about it. - **32 jobs, 16 arguments, 4 KB manifests**, all compile-time.