_       _
| |_ ___| |_ _
|   | . | | | |
|_|_|___|_|_  |
          |___|

file man/holy-init.8

.TH HOLY-INIT 8 "September 2026" "Holy" "System Administration"
.SH NAME
holy-init \- prepare live runtime mounts and execute dinit
.SH DESCRIPTION
holy-init runs as PID 1 from a live initramfs. It mounts devtmpfs, attaches
standard descriptors to /dev/console, makes mount propagation private, and
mounts proc, sysfs, tmpfs at /run and /tmp, and a new devpts instance.
It then executes /sbin/init, supplied as a link to dinit by the image profile.
dinit retains PID 1. Mount and exec failures print a diagnostic and leave
the process waiting for intervention; they do not report a successful boot.
.PP
The boot profile uses /etc/dinit.d, a control socket at /run/dinitctl,
PATH=/usr/bin and HOME=/root. The default service is boot. An exact
holy.test=1 kernel argument selects holy-test instead. Other kernel words
are not interpreted as shell code.
.PP
Calling holy-init outside PID 1 returns 2 before mounting anything.
Without holy.root it boots an in-memory live root. holy.root=/dev/DEVICE
selects an ext4 disk root; holy.rootfstype=ext4 is the supported filesystem
selector. Empty or repeated holy.root arguments are errors. The helper waits
up to 30 seconds for the block device, mounts it at /newroot, verifies that
the target init is executable and moves /dev, /proc, /sys, /run and /tmp there.
It then executes the static BusyBox switch_root applet with the dinit argv.
The process retains PID 1. Failure does not fall back to the RAM root.
Device discovery must be available through built-in kernel drivers/devtmpfs.
.PP
holy.esp=/dev/DEVICE mounts a FAT ESP at /boot within the disk root before
switch_root. It requires holy.root and a real block device; empty or repeated
ESP arguments fail. The boot directory must be a directory, not a symlink.
The mount uses nosuid,nodev,noexec, root ownership, file mode 0644 and
directory mode 0755. The kernel must provide vfat and its required NLS tables.
Failure leaves the boot incomplete rather than using a hidden rootfs copy.
Encrypted roots, UUID discovery, modules and other filesystems are not yet
implemented by this helper.
.SH BUILD
make builds holy-init with the configured C99 compiler. make static builds
it with the selected musl toolchain. The image builder also compiles it
using its explicit STATIC_CC input and verifies static ELF classification.
.SH SEE ALSO
.BR holy-image (7),
.BR holypkg (8)