gazagnaire.org / ocaml-pid1
Minimal OCaml PID 1
fork atom
OCaml 95.2%
C 1.9%
Dune 1.0%
Other 1.9%
19 1 0

Clone this repository

https://tangled.org/gazagnaire.org/ocaml-pid1 https://tangled.org/did:plc:jhift2vwcxhou52p3sewcrpx/ocaml-pid1
git@git.recoil.org:gazagnaire.org/ocaml-pid1 git@git.recoil.org:did:plc:jhift2vwcxhou52p3sewcrpx/ocaml-pid1

For self-hosted knots, clone URLs may differ based on your setup.

Download tar.gz
README.md

pid1#

Minimal OCaml PID 1 for Linux VMs.

Minimal init process for LinuxKit-style VMs with no shell or busybox. Mounts essential filesystems (devtmpfs, proc, sysfs), handles signals for zombie reaping and graceful shutdown, reads the superblock from virtio-blk devices, and provides a service supervisor state machine with exponential backoff.

The library uses C stubs for mount(2) and reboot(2) syscalls which have no Eio equivalent. The companion spaceos-init binary is the actual init process: it sets up filesystems, reads the superblock, manages parameters and event logs, communicates with the host via virtio-serial ports, and runs FDIR integrity monitoring.

Installation#

opam install pid1

Usage#

(* Library usage for building a custom init *)
Eio_main.run @@ fun env ->
Eio.Switch.run @@ fun _sw ->
let fs = Eio.Stdenv.fs env in
Pid1.setup_filesystems ~fs;
Pid1.setup_signals ();
match Pid1.read_superblock Eio.Path.(fs / "/dev/vda") with
| Ok sb when Pid1.check_magic sb && Pid1.check_crc sb ->
    Fmt.pr "%a@." Pid1.pp_superblock sb
| Ok _sb -> Fmt.epr "Invalid superblock@."
| Error e -> Fmt.epr "Error: %s@." e

API#

  • Filesystem setup -- mount wraps the mount(2) syscall. setup_filesystems mounts devtmpfs, proc, and sysfs at standard locations.
  • Signal handling -- setup_signals installs SIGCHLD (zombie reaping), SIGTERM, and SIGINT handlers. shutdown_requested reports whether a termination signal was received.
  • Superblock -- read_superblock reads a 48-byte superblock from a block device. check_magic validates the magic number (0x53504F53 / "SPOS"). check_crc validates the CRC-32C. A Wire codec is provided for encoding/decoding.
  • System control -- poweroff and halt invoke reboot(2).
  • Child exit tracking -- drain_child_exits atomically collects child process exit records accumulated by the SIGCHLD handler.
  • Service supervisor -- Pure state machine (svc_step) that drives service lifecycle through Pending, Starting, Running, Backoff, and Failed states with configurable exponential backoff and dependency tracking.
  • Watchdog -- pet_watchdog writes to /dev/watchdog to prevent hardware watchdog resets.