bible/rules/patterns/unattended-boot-services/contract.md

Contract: Unattended Boot Services (OpenRC)

Version: 1.0

Purpose

Rules for OpenRC services that run in unattended environments: LiveCDs, kiosks, embedded systems. No user is present. No TTY prompts. Every failure path must have a silent fallback.

See README.md for sample init scripts and ordering sketches.

Rules

• Never block boot. A service failure must not stop the rest of the runlevel.
• Never prompt. Do not use read, pause logic, or any interactive fallback.
• Every start() must end with eend 0 unless failure makes the environment fundamentally unusable, such as breaking SSH setup.
• Write service diagnostics to /var/log/. TTY output is secondary.
• Missing tools, absent network, or driver load failures must degrade gracefully: log and continue.
• Use the minimum dependency set. Prefer after and use; do not add need net, need networking, or need network-online unless the service is truly useless without network and failure should be loud.
• SSH services must start without requiring network availability.
• DHCP must be non-blocking and persistent. Run the client in background retry mode rather than failing the boot sequence when no lease is immediately available.
• External commands must be timeout-bounded so a bad device or tool cannot hang boot indefinitely.