s6-linux-init
Software
skarnet.org

# 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:

- 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.