An overview of s6-linux-init

Organisation of the package

When installed, the s6-linux-init package provides the following:

Binaries, that are typically installed in /bin:
- s6-linux-init-maker is the main program of the package and is used to create /sbin/init scripts and their supporting environment depending on configuration parameters given on its command line.
- s6-linux-init-hpr is an implementation of the SysV halt, poweroff and reboot commands; s6-linux-init-telinit is an implementation of the SysV telinit command; and s6-linux-init-shutdown is an implementation of the shutdown command. s6-linux-init is an implementation of stage 1 /sbin/init, but it needs to be given command-line options in order to do what the user has chosen. An invocation of s6-linux-init-maker will create proper wrappers for all those commands, named after their short SysV names; the wrappers are directly usable as turnkey replacements for SysV commands.
- Other binaries are support binaries, not meant to be called directly by the user. They are called internally, in scripts created by a s6-linux-init-maker invocation - typically in run scripts for early services.

A small library, that for now contains a single symbol, s6_linux_init_logouthook(), intended for distributions using login programs that add utmp entries for users logging in and expect init to clean up after them when users log out. See the s6-linux-init-logouthookd page for details.

Skeleton scripts, installed by default in /etc/s6-linux-init/skel; that location can be changed at build time via the --skeldir configure option. At s6-linux-init-maker invocation time, the scripts are copied from the skeleton directory to the scripts subdirectory of the directory created by s6-linux-init-maker, and the copy is meant to be edited by the user. The skeleton scripts are commented and examples of interaction with various service managers are given; it is recommended to review them, and possibly edit them too. These scripts are the following:
- rc.init: the script launching the system initialization procedure once stage 1 init is done and s6-svscan is safely running as pid 1.
- rc.shutdown: the script launching the system shutdown procedure when the admin runs a halt, poweroff, reboot or shutdown command.
- runlevel: the script executing a machine state change at boot time (normally invoked by rc.init, towards the default runlevel) or when the administrator runs a telinit command. This script is unused in a container.
- rc.shutdown.final: a script that will be run at the very end of the shutdown procedure, after all processes have been killed and all filesystems have been unmounted, just before the system is rebooted or the power turned off. This script normally remains empty.

Organisation of the booted system

When a system has booted on an /sbin/init program created by s6-linux-init-maker, the following invariants are met:

Global resource limits, if any, are set on the system.
A tmpfs is mounted on /run - that location can be changed at build-time via the --tmpfsdir option to configure. The rest of this document assumes it is /run.
s6-svscan is running as pid 1 on the /run/service scandir.
Every process on the system is running with at least the environment defined in the /etc/s6-linux-init/current/env envdir. The /etc/s6-linux-init/current location can be changed at s6-linux-init-maker invocation time via the -c option.
Some early services are defined in /run/service, and running. They are not seen by the service manager and should remain up all the time, until the machine shuts down: they are considered a part of the init system, even if they're not process 1. Apart from s6-linux-init-shutdownd, which is necessary for the machine (or container) to respond to shutdown requests, they are only present depending on the configuration, and different s6-linux-init-maker invocations will yield different sets of services. The services are picked from this list:
- s6-linux-init-shutdownd: the shutdown manager, running the shutdown sequence in a reproducible environment when a shutdown command is executed, then performing the last shutdown steps.
- s6-svscan-log: the catch-all logger
- s6-linux-init-runleveld: the runlevel manager, running the runlevel script in a reproducible environment when a telinit command is executed.
- s6-linux-init-logouthookd: a local service performing utmp record cleanup duty for patched login programs.
- s6-linux-init-early-getty: the early getty, allowing the user to login even if rc.init fails early.
- utmpd: a service performing utmp access when utmps is used.

Integration with the service manager

The s6-linux-init package's duties stop where the service manager's start. s6-linux-init simply brings the system up to the point where it is stable and operational enough for the service manager to take over; and at shutdown time, s6-linux-init just tells the service manager to bring down the services, and then performs the last steps of the shutdown: killing all the remaining processes, unmounting the file systems and halting/powering off/rebooting the machine.

All the interactions between s6-linux-init and the service manager are configurable: they happen in the rc.init, rc.shutdown and runlevel scripts. Examples are provided in the skeleton scripts, that you should review and edit.