From 1bfba3b0be32306b078f5ee527b864e758b2c77b Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Fri, 26 Apr 2019 15:52:54 +0000 Subject: Make a single hpr. Full doc, first draft. --- doc/overview.html | 149 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 doc/overview.html (limited to 'doc/overview.html') diff --git a/doc/overview.html b/doc/overview.html new file mode 100644 index 0000000..e1f3b31 --- /dev/null +++ b/doc/overview.html @@ -0,0 +1,149 @@ + + + + + + s6-linux-init: overview + + + + + + +

+ +

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

+ +

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. Each of these services uses very few resources. +The services are: +
- s6-svscan-log: the catch-all logger
- 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-linux-init-runleveld: the runlevel manager, running +the runlevel script in a reproducible environment when a telinit +command is executed.
- (optionally) s6-linux-init-logouthookd: a local service performing +utmp record cleanup duty for patched login programs.
- (optionally) s6-linux-init-early-getty: the early getty, +allowing the user to login even if rc.init fails early.
- (optionally) utmpd and wtmpd: the services performing +utmp and wtmp 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. +

+ + + -- cgit v1.2.3