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/index.html | 96 +++++--- doc/overview.html | 149 ++++++++++++ doc/quickstart.html | 178 ++------------- doc/s6-linux-init-echo.html | 69 ++++++ doc/s6-linux-init-halt.html | 102 --------- doc/s6-linux-init-hpr.html | 87 +++++++ doc/s6-linux-init-logouthookd.html | 84 +++++++ doc/s6-linux-init-maker.html | 451 ++++++++++++++++++------------------- doc/s6-linux-init-poweroff.html | 102 --------- doc/s6-linux-init-reboot.html | 102 --------- doc/s6-linux-init-shutdown.html | 36 +-- doc/s6-linux-init-shutdownd.html | 16 +- doc/s6-linux-init-telinit.html | 72 ++++++ doc/s6-linux-init-umountall.html | 61 +++++ doc/s6-linux-init.html | 154 +++++++++++++ doc/upgrade.html | 9 + doc/why.html | 139 ++++++++++++ 17 files changed, 1152 insertions(+), 755 deletions(-) create mode 100644 doc/overview.html create mode 100644 doc/s6-linux-init-echo.html delete mode 100644 doc/s6-linux-init-halt.html create mode 100644 doc/s6-linux-init-hpr.html create mode 100644 doc/s6-linux-init-logouthookd.html delete mode 100644 doc/s6-linux-init-poweroff.html delete mode 100644 doc/s6-linux-init-reboot.html create mode 100644 doc/s6-linux-init-telinit.html create mode 100644 doc/s6-linux-init-umountall.html create mode 100644 doc/s6-linux-init.html create mode 100644 doc/why.html (limited to 'doc') diff --git a/doc/index.html b/doc/index.html index c8d7e7e..1b4dda6 100644 --- a/doc/index.html +++ b/doc/index.html @@ -26,22 +26,52 @@ system, including a /sbin/init binary, on a Linux kernel.

- s6-linux-init is meant to automate creation of scripts revolving -around the use of other skarnet.org tools, especially s6, in order -to provide a complete booting environment with integrated supervision -and logging without having to hand-craft all the details. + The resulting architecture follows the Unix philosophy (one job → +one tool) as closely as possible, and is fully dedicated to the s6 way of +managing a system:

s6-svscan +runs as process 1 for the whole machine lifetime.
Every daemon is supervised.
No logs are ever lost.
Policy is entirely left to the user. Typically, any service manager +can be run on top of s6-linux-init.

+ +

+ Nevertheless, the architecture is fully compliant with various +empirical and historical specifications. For instance, it provides: +

+ +

utmp management compatible with sysvinit
runlevel management, with a configurable default, overridable from the +kernel command line
sysvinit-like commands to shut the system down, including a +shutdown command that follows the +LSB specification

+ +

Getting started

Please read the documentation for the s6-linux-init-maker program carefully, but if you're impatient, you can also read this -quickstart guide, which includes -a small FAQ. +quickstart guide.

Why s6-linux-init ?
An overview of s6-linux-init

+ +

Installation

Requirements

@@ -50,30 +80,31 @@ a small FAQ.

A Linux-based system with a standard C development environment

GNU make, version 3.81 or later

skalibs version -2.6.4.0 or later

+2.8.0.1 or later

execline version -2.3.0.4 or later

s6-portable-utils version -2.2.1.1 or later

s6-linux-utils version -2.4.0.2 or later

+2.5.1.0 or later

s6 version -2.7.1.0 or later

+2.8.0.0 or later

-When you build s6-linux-init, the - s6-linux-init-maker tool -is created (as well as the shutdown commands); - then you run that tool to create an init script, -and then you can boot your system on that init script. + The following optional dependencies are also supported:

If you're using musl and +want nsswitch-like functionality: +nsss version +0.0.1.1 or later
If you want secure utmp functionality: +utmps version +0.0.2.1 or later

- skalibs is a build-time dependency. If you are linking binaries -against the shared version of the skalibs library, it also becomes a -run-time and boot-time dependency.
- All the other listed packages are boot-time dependencies only. + All those dependencies are build-time and run-time, +except possibly skalibs, which is not needed at run time if you are linking +all the other packages against the static version of libskarnet.

Licensing

@@ -87,7 +118,7 @@ against the shared version of the skalibs library, it also becomes a

The current released version of s6-linux-init is -0.4.0.0.

1.0.0.0

Alternatively, you can checkout a copy of the s6-linux-init git repository: @@ -114,6 +145,14 @@ the previous versions of s6-linux-init and the current one.

Reference

General

A rationale for this package
An overview of s6-linux-init
A quickstart page

Commands

@@ -123,9 +162,14 @@ the previous versions of s6-linux-init and the current one.

Related resources

s6-linux-init: overview

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

s6-linux-init: quickstart and FAQ

s6-linux-init: quickstart

skarnet.org

Quickstart and FAQ for s6-linux-init

Quickstart for s6-linux-init

Quickstart

Install s6-linux-init itself.
Save your old /sbin/init binary.
Save and remove your old /etc/s6-linux-init directory, if you have one.
Install s6-linux-init itself.
Save your old /sbin/init, /sbin/telinit, /sbin/shutdown, +/sbin/halt, /sbin/poweroff and /sbin/reboot binaries.
Make sure you have a /run directory.
Write a machine initialization script in /etc/rc.init and -a machine shutdown script in /etc/rc.shutdown. Make sure they are -executable. See below for more information on how to write these scripts.
Edit the scripts in /etc/s6-linux-init/skel.
Check that your devtmpfs is automounted by your kernel at boot time. If it is not, add the -d 1 option to the s6-linux-init-maker command line below.

As root, run:

-     rm -rf /tmp/s6-linux-init /tmp/init
-     s6-linux-init-maker /tmp/s6-linux-init
-     mv /tmp/s6-linux-init /etc/
-     ln -sf /etc/s6-linux-init/init /sbin/init

Reboot.
Congratulations! your machine is now running a s6-based init system.
To shut the machine down, use the -s6-halt, -s6-poweroff or -s6-reboot command as appropriate.
To shut the machine down, use /sbin/shutdown, /sbin/halt, +/sbin/poweroff or /sbin/reboot as usual.

What should go into `/etc/rc.init` and `/etc/rc.shutdown` ?

`/etc/rc.init`

- This script will be run after s6-linux-init has done is job, i.e. -s6-svscan is running as process 1, and it -is now up to /etc/rc.init to get the machine to its usable state. -It normally contains a call to the service manager to bring up all the services; -for instance, if you're using -s6-rc as your service manager, and -your top bundle (containing all the services you want to bring up) is named -ok-all, a proper /etc/rc.init could look like this: -

#!/bin/sh
-s6-rc-init /run/service && exec s6-rc -u change ok-all
-

- The script can assume that: -

There is a tmpfs partition, only writable by root, mounted on /run
There is a s6 supervision tree -running on /run/service
/dev is mounted, but /proc and /sys are not

`/etc/rc.shutdown`

- This script is spawned by s6-svscan -when the administrator calls s6-halt, -s6-poweroff or -s6-reboot. When this script exits, the final -shutdown sequence is run, which means that the supervision tree is dismantled, -all processes are killed, the file systems are umounted and the system -undergoes a hardware shutdown or reboot. So the goal of this script is to -bring services down in an orderly fashion and perform all the necessary -cleanups before all remaining processes are summarily killed. -

- If you're using s6-rc as your -service manager, a proper /etc/rc.shutdown could look like this: -

#!/bin/sh
-exec s6-rc -da change
-

FAQ

Why is it so complicated to use s6 as an init process? It's much -simpler with runit.

- Yes, runit is simpler, because it provides a simple -runit binary -suitable as a /sbin/init program and calls scripts to -handle the three stages of init. However, the runit design has a -few perfectible points: -

The one-time initialization is performed in /etc/runit/1, but -the supervision tree is not run until /etc/runit/2, which means -means that it is impossible to start supervised services during the -one-time initialization. Early daemons such as udevd, for -instance, have to remain unsupervised.
runit runs with its descriptors pointing to /dev/console, -which means that error messages from the supervision tree, and uncaught -logs, will be displayed on the system console; they are not saved beyond -the console buffer capabilities.
The runit supervision tree is of height 3 -(runit, runsvdir, runsv), when height 2 is enough - some init -systems, like sysvinit, systemd or launchd, even provide a -supervision tree of height 1! (At the expense of complexity in the init -process, of course.) Height 3 is a bit redundant, because the supervision -capabilities of the root will be redundant with either those of the trunk -or those of the branches. Its display is also aesthetically less pleasing than -height 2: try out ps afuxww on a runit-based system. -Yes, this point is extremely minor, but still deserves a mention. :-)

- Running a s6-based init addresses those issues: -

Save for the initial tmpfs mount, all of the machine -initialization runs in the stage 2 script, i.e. /etc/rc.init, -and the supervision tree is already available at that point. This -makes it possible to start one-shot services as well as long-run -services in the desired order while ensuring that every long-run service -is properly supervised, i.e. it lays the ground for a proper dependency -management system.
s6-linux-init solves the problem of uncaught logs in a clean -way, and any error message from any process in the system is -guaranteed to end up in a logging directory. The only -exception is error messages from the catch-all logger process itself: -those naturally go to /dev/console.
When s6-svscan runs as process 1, the supervision tree is of -height 2, and ps afuxww looks clean.

- To sum up, a s6-based init is cleaner than a runit-based -init; it's a bit more complex to set up, but it organizes the system -in a better way, without using more resources. And the goal of -s6-linux-init is to make the setup more accessible. -

My `/etc/rc.init` script is not printing anything!

- You probably gave the -r option to -s6-linux-init-maker, and -your /etc/rc.init's output is being logged into the -/run/uncaught-logs directory instead of printed to -/dev/console. -

I want to run s6 in a container, and I just want to log -to stdout/stderr, without this tmpfs and `/dev/console` -stuff and -without having a catch-all logger inside the container. Is it -possible ?

- Yes, it is possible, but then s6-linux-init may not be what you -are looking for. For your case, it will be simpler to run s6-svscan -directly! -

- If you are using -Docker, there is a -s6-overlay -project specifically made for integrating s6 into Docker images. -

s6-linux-init: the s6-linux-init-echo program

+s6-linux-init
+Software
+skarnet.org +

The `s6-linux-init-echo` program

+ s6-linux-init-echo writes its arguments to stdout. +

Interface

+     s6-linux-init-echo [ -n ] [ -s sep ] args...
+

+ s6-linux-init-echo writes its arguments args to stdout, separated with spaces. +

Options

-n : do not output a trailing newline.
-s sep : separate arguments with the sep +character instead of a space.

Notes

Strange, and appalling, as it may seem for such a simple task, there is +no way to ensure that the echo program will behave consistently from +Unix system to Unix system - and even from Linux distribution to Linux +distribution. Despite there being a +standard +for it, the echo commands in GNU coreutils, busybox, toybox, sbase, and +other implementations basically all exhibit different behaviours. Every shell has +a built-in echo command, that fails to follow the POSIX standard. echo +is the prime example of the consequences of the blatant disregard of early Unices +for cross-system compatibility, and its followup as a turf war between GNU and the +rest of the Linux world. As a distribution-agnostic software developer, it is ironically +impossible to rely on a definite behaviour of the echo command on every +supported system, and that is why s6-linux-init provides its own implementation. +Fortunately, it is very easy to do so, with minimal overhead.
This command is an exact duplicate of the +s6-echo command +provided in the s6-portable-utils +package. It was decided not to have a dependency from s6-linux-init to +s6-portable-utils: that dependency would arguably be a higher cost than the small +amount of code duplication.

s6-linux-init: the s6-linux-init-halt program

-s6-linux-init
-Software
-skarnet.org -

The `s6-linux-init-halt` program

-s6-linux-init-halt triggers the shutdown procedure in order to -halt the system; or, with the -f option, it performs an immediate -hard shutdown. -

Interface

-     s6-linux-init-halt [ -h | -p | -r ] [ -d | -w ] [ -W ] [ -f ] [ -R tmpfsdir ]
-

If the -f option is present, s6-linux-init-halt halts the system immediately.
Else, it triggers the machine's shutdown procedure. -
It exits 0. The shutdown procedure happens asynchronously.

- This interface follows the traditional sysvinit interface for the -halt, poweroff and reboot programs as close as possible. -

Exit codes

0: shutdown procedure triggered.
100: wrong usage, or user does not have root privileges.
111: system call failed.

Options

-h : halt. No matter the name of the command, it will order -a halt (i.e. the system will be shut down, but the power will remain up). -This is the default for s6-linux-init-halt.
-p : poweroff. No matter the name of the command, it will order -a power off. This is the default for s6-linux-init-poweroff.
-r : reboot. No matter the name of the command, it will order -a reboot. This is the default for s6-linux-init-reboot.
-d : Do not write a wtmp shutdown entry.
-w : Only write a wtmp shutdown entry; do not actually shut down -the system.
-W : Do not send a wall message to users before shutting -down the system. Some other implementations of the halt, poweroff -and reboot commands use the --no-wall long option to achieve this.
-f : force. The command will not trigger a clean shutdown -procedure; it will just sync the filesystems then tell the kernel to immediately -halt, poweroff or reboot. This should be the last step in the lifetime of the -machine.
-R tmpfsdir : assume that the root-only -boot-time tmpfs has been mounted on tmpfsdir. Default is /run. -It is important to get this right, because the contact point with the -s6-linux-init-shutdownd daemon, -which manages the shutdown procedure, is located under this directory. The -halt, poweroff and reboot scripts created by a -s6-linux-init-maker invocation -automatically use the correct -R option.

Notes

The -s6-linux-init-halt, -s6-linux-init-poweroff, -s6-linux-init-reboot and -s6-linux-init-shutdown -binaries are not meant to be called directly by administrators. -Instead, their purpose is to be used in halt, poweroff, -reboot and shutdown scripts created by -s6-linux-init-maker; those scripts -will call them with the correct -R tmpfsdir option. -The scripts should typically be linked to /sbin after -s6-linux-init-maker execution, to -provide drop-in replacements for the sysvinit programs with the -same names.

s6-linux-init: the s6-linux-init-hpr program

+s6-linux-init
+Software
+skarnet.org +

The `s6-linux-init-hpr` program

+ s6-linux-init-hpr triggers the software shutdown procedure, +or, with the -f option, it perform an immediate hardware shutdown. +It is normally invoked as /sbin/halt, /sbin/poweroff or +/sbin/reboot. +

Interface

+     s6-linux-init-hpr [ -f ] [ -h | -p | -r ] [ -d | -w ] [ -W ]
+

If the -f option is present, the hardware command is executed immediately.
Else, the machine's shutdown procedure is started. +
The command exits 0; the shutdown procedure happens asynchronously.

+ This interface is the traditional sysvinit interface for the +halt, poweroff and reboot programs. +s6-linux-init-hpr must always be called with one of the +-h, -p or -r options. +

Exit codes

0: shutdown procedure triggered.
100: wrong usage, or user does not have root privileges.
111: system call failed.

Options

-f : force. The command will not trigger a clean shutdown +procedure; it will just sync the filesystems then tell the kernel to immediately +halt, poweroff or reboot. This should be the last step in the lifetime of the +machine.
-h : halt. The system will be shut down, but the power will remain up.
-p : poweroff. The system will be shut down and the power turned off.
-r : reboot. The system will reboot.
-d : Do not write a wtmp shutdown entry.
-w : Only write a wtmp shutdown entry; do not actually shut down +the system.
-W : Do not send a wall message to users before shutting +down the system. Some other implementations of the halt, poweroff +and reboot commands use the --no-wall long option to achieve this.

Notes

When an administrator runs +s6-linux-init-maker, the resulting +directory has a bin/ subdirectory that contains halt, +poweroff and reboot scripts that call s6-linux-init-hpr +with the relevant option. The +contents of this bin/ subdirectory should then be copied by the +administrator into /sbin for full interface compatibility with sysvinit.

s6-linux-init: the s6-linux-init-logouthookd program

+s6-linux-init
+Software
+skarnet.org +

The `s6-linux-init-logouthookd` program

+ s6-linux-init-logouthookd cleans up its client's utmp record when it dies. +

Interface

+     s6-ipcserver socket s6-linux-init-logouthookd
+

+ s6-linux-init-logouthookd implements a +local service +for getty programs that add an utmp record when a user logs in. +

+ In the sysvinit model, getty/login and similar programs add an utmp +record for every user that logs in, then exec into the user's shell. +At logout time, the shell dies; sysvinit is supervising the getty +program, so it's watching the pid, and respawns the getty when the +shell dies. But before respawning the getty, it cleans up the +utmp record, to correctly report that the user isn't logged in on this +terminal anymore. +

+ utmp is an old, clunky, insecure system (unless you're using +utmps) and it is definitely +not pid 1's job to have any knowledge of utmp and play janitor after +getty. s6-svscan +definitely will not do it. +

+ Some distributions use versions of login that fork the user's +shell instead of execing it. When the user logs out, the login +program cleans up after itself. This is a better model, but it's not +always easy to patch login to go from a "exec the shell" model to a +"fork the shell as a child" model. +

+ s6-linux-init comes with a small library which makes it easy +for a distribution to fully support utmp cleanup with an s6 init system +if they so choose. Before execing into the user's shell, the login +program should just make a call to s6_linux_init_logouthook(), +and that's it. That function will call the s6-linux-init-logouthookd +local service, which will do nothing but wait until the user's shell dies; +and when it happens, the user's utmp record will automatically be cleaned up. +

Notes

The local service +implementing logouthook support is automatically created at boot time when the +-L option has been given to +s6-linux-init-maker. Client-side, though, +the various login programs must be patched at the source level.

s6-linux-init-maker reads configuration options on the command line, and outputs a directory to place in the -root filesystem. That directory contains a script suitable -as an init program, as well as support file hierarchies to -get a complete +root filesystem. That directory contains +a script that is suitable as an /sbin/init program +as well as all the necessary files that this script needs +to properly boot and bring up a full s6 -infrastructure running when the system is booted on that -script. +infrastructure.

s6-linux-init-maker only writes scripts. At boot time, these scripts will call commands provided by other skarnet.org packages such as -execline or +execline and s6. It is the responsibility of the administrator to make sure that all the dependencies are properly installed at boot time, and that the -correct options have been given to s6-linux-init-maker so that -the programs are found on the root filesystem of the -machine - else the scripts will crash. -

s6-linux-init-maker

on the root filesystem of the +machine

Interface and usage

      s6-linux-init-maker \
        [ -c basedir ] \
-       [ -u log_uid -g log_gid | -U ] \
+       [ -u log_user ] \
        [ -G early_getty ] \
        [ -1 ] \
        [ -L ] \
@@ -59,13 +57,15 @@ machine - else the scripts will crash.
        [ -d dev_style ] \
        [ -s env_store ] \
        [ -e initial_envvar ] ... \
-       [ -E stage2_envvar ] ... \
        [ -q ] finalsleeptime
+       [ -D initdefault ] \
+       [ -U utmp_user ] \
        dir

s6-linux-init-maker should be run as root.
s6-linux-init-maker must be run as root, on the machine +that will boot an s6-based system.
s6-linux-init-maker parses options on its command line.
It writes data into a directory dir, which must not exist beforehand.

- dir should then be copied by the administrator to the place -declared as basedir. Be careful: it contains fifos, files with + Once the command has been run and dir has been created, there +are a few manual steps to take: +

s6-linux-init-maker has copied some scripts from the +/etc/s6-linux-init/skel directory (or the directory you +gave as an argument to the --skeldir configure option at +build time) to the dir/scripts directory. You +should edit these scripts and adapt them to your use case. +(Or you could edit the skeleton scripts before running +s6-linux-init-maker.) The scripts are: +
- rc.init: this script will be run as stage 2 +initialization, i.e. the initialization that happens once +s6-svscan +is running as process 1, and should contain all your normal +system bootup tasks. Typically, it should initialize the service +manager and then order it to bring the machine state to its +fully operational state. rc.init is given the default +runlevel as a first argument (i.e. the name of the state +the machine should be brought to, traditionally default +for OpenRC and 2 or 5 for sysv-rc), and the +rest of the command line is made of the kernel's command line +except for the kernel arguments of the key=value form, +which have been stored into env_store.
- rc.shutdown: this script will be run as the +shutdown sequence, when the administrator runs the +shutdown, halt, poweroff or reboot +command. (As well as init 0, init 6. +telinit 0 and telinit 6 for compatibility +reasons.) It should ask the service manager to bring all the +services down, and exit when it's done (in other words: it should +not try to perform a hard halt/poweroff/reboot itself.) +No arguments are given to this script.
- runlevel: this script will be invoked for every +runlevel change, i.e. change of machine states. It is +given one argument: the name of the runlevel to change to. +Typically, the runlevel script should just invoke the +service manager, asking it to bring the machine state to the +wanted runlevel.
Copy the dir directory to the place declared as +basedir (/etc/s6-linux-init/current by default). + Be careful: it contains fifos, files with precise uid/gid permissions, and files with non-standard access rights, so be sure to copy it verbatim. The s6-hiercopy -tool can do it, as well as the GNU or busybox cp -a or mv commands. -
- -
- The basedir/bin directory contains scripts, or -links to programs, that are suitable as System V-compatible programs -of the same name; the administrator should copy them to (or symlink -them from) a place where those programs are usually found, typically -/sbin. -
- -
- In particular, the basedir/bin/init script -suitable as a "stage 1" init program, i.e. the first program -run by the kernel (possibly after an initramfs execution). -Once this script is copied to, or symlinked from, -/sbin/init, the machine will be ready to boot on the -new s6-based system. -
+tool can do it, as well as the GNU or busybox cp -a or mv commands.
Back up your /sbin. Then copy, link or symlink all the scripts +and symlinks in the basedir/bin directory into /sbin. + In particular, the basedir/bin/init script should +be accessible as /sbin/init.

Boot sequence

When the kernel boots, it may run an initramfs first, but in any case it then runs the basedir/init script, -also known as stage 1. This is what happens during stage 1: -

stage 1 is an -execline script, so -the first process run by the kernel is the -execlineb -program launcher.
stage 1 mounts a -tmpfs -filesystem on tmpfsdir.
stage 1 copies basedir/run-image verbatim to -tmpfsdir.
stage 1 empties its environment, then reads a global set of environment variables from the -basedir/env -environment directory.
stage 1 forks a child that will block until -s6-svscan is running.
stage 1 executes, as process 1, into -s6-svscan, -with tmpfsdir/service as a -scan directory.
This scan directory already contains at least one service, which is the -catch-all logger: error messages from the supervision tree, and -from services that do not have a dedicated logger, are handled by a -special s6-log -instance and made available in tmpfsdir/uncaught-logs -instead of clogging the system console.
If the -G option has been given to s6-linux-init-maker, the -scan directory will also contain a service for an early getty.
s6-svscan starts all the services defined in the scan directory, -and unblocks the child forked by stage 1.
This child executes into initscript.

- initscript is the responsibility of the administrator - it will -not be written automatically! -It should -contain all the necessary initialization sequence to bring up a proper -system. When initscript is executed, the machine state is as follows: -

initscript's working directory is / and its stdin -is /dev/null. Its -stdout and stderr both point either to /dev/console or to the pipe -to the catch-all logger, depending on the -r option.
The system has a valid device directory mounted on /dev.
Depending on the kernel boot command line, the root filesystem -may be in read-only mode.
There is a tmpfs available for root only in tmpfsdir.
s6-svscan -is running as process 1. At any time, it is possible to make it supervise a long-lived -process by linking the appropriate -service directory -into tmpfsdir/service, then running the command -s6-svscanctl -a tmpfsdir/service. Services without a -dedicated logger will send their output to the catch-all logger.
A getty service may already be available. The point of this early -getty is essentially to make it easier to debug if initscript fails.

- There is nothing else. In particular, no filesystem has been -mounted yet, including /proc and /sys; and no one-time -initialization -has been performed. The point of stage 1 is only to make it -possible to run initscript with a logging infrastructure and a -supervision infrastructure already available, and all the -real machine and service initialization should happen in initscript, -also known as stage 2. -

Shutdown sequence

A shutdown is performed when the administrator runs one of the -s6-halt, -s6-poweroff or -s6-reboot commands.
Those commands send a signal to the -s6-svscan -process running as pid 1; this signal is caught and s6-svscan runs the -corresponding "signal handler" script that has been placed by -s6-linux-init-maker into the -basedir/run-image/service/.s6-svscan directory (and that -has been copied at boot time to tmpfsdir/service/.s6-svscan).
That script first spawns the shutdownscript script, who -must have been written by the administrator. The purpose of -shutdownscript is to perform the high-level shutdown sequence -while the supervision tree is still alive. Typically, when using a -service manager, shutdownscript would tell the service manager -to bring all services down. When using -s6-rc, a typical -stage2_finish script just contains s6-rc -da change. - More generally speaking, shutdownscript should undo what -stage2 has done at boot time.
The "signal handler" script then tells s6-svscan to exit via an -appropriate s6-svscanctl -command: s6-svscan then executes into the final shutdown sequence. This -sequence is made of the following actions: - -
- The supervision tree gets torn down.
- All data is flushed to disk.
- All processes get a SIGTERM, a SIGHUP, and a SIGCONT. This should -allow all processes to die gracefully. Note that most processes should -already have been killed during the /etc/rc.shutdown execution; -this phase only catches stragglers, background processs, etc.
- The sequence sleeps for finalsleeptime milliseconds, to -allow all processes to finish their clean exit routine.
- All processes get a SIGKILL.
- All zombies are reaped.
- All filesystems get unmounted, and the root filesystem is remounted -read-only.
- The machine performs a hardware reboot, halt or poweroff, depending -on the command that has been used.

- The examples/ subdirectory of the s6-linux-init package -contains an example of /etc/rc.init -and /etc/rc.shutdown scripts, suitable for -initscript and shutdownscript -respectively. Those scripts can practically be used as is if the machine -is managed by the s6-rc -service manager. +also known as stage 1. This script is just an execution +of the s6-linux-init program with +some command-line options that are directly transferred from the +s6-linux-init-maker invocation. Refer to the +s6-linux-init man page to know +exactly what it does.

s6-linux-init-maker options

-c basedir : at boot time, stage 1, which should be accessible as basedir/init, will read its read-only data from basedir. After running -s6-linux-init-maker, the administrator should make sure to copy the +s6-linux-init-maker, you should make sure to copy the created directory dir to basedir. basedir must be absolute. Default is -/etc/s6-linux-init.

- -

-u log_uid : the catch-all -logger will run with the uid log_uid. Default is 0.

- -

-g log_gid : the catch-all -logger will run with the gid log_gid. Default is 0.

+/etc/s6-linux-init/current.

-U : the correct log_uid and -log_gid values for the catch-all logger will be read from the -UID and GID environment variables that have been passed to -s6-linux-init-maker. This allows for invocations such as -s6-envuidgid nobody s6-linux-init-maker -U ... so that -the catch-all logger runs as the nobody user. Be aware that -this option is only safe when the user database on the -boot-time machine is the same as on the run-time -machine, else the catch-all logger may run with an unexpected uid -and gid.

-u log_user : the catch-all +logger will run as the log_user user. Default is root.

-G early_getty : if this option -is set, s6-linux-init-maker will define a service that will run -very early, before stage2 is executed. This early service -should be a getty, to allow logins even if stage2 fails. +is set, s6-linux-init-maker will define an additional s6 service +that will be named s6-linux-init-early-getty and started +at the same time rc.init is executed. This early service +should be a getty, or equivalent, to allow logins even if stage2 fails. early_getty should be a simple command line: for instance, "/sbin/getty 38400 tty1". By default, no early service is defined.

-1 : make it so that all the messages that are sent to the catch-all logger (i.e. all the error messages that are not -caught by a dedicated logger, as well as the output from stage2) +caught by a dedicated logger, as well as the output from rc.init, +runlevel and rc.shutdown, are also copied to /dev/console. This is generally useful to debug a system at a glance, but if a failing program keeps sending error messages, it may interfere with comfortable usage of an early -getty.

tty2

/dev/console

+ +

-L : add an early s6-linux-init-logouthookd +service to clean up utmp records at user logout time. Check the +s6-linux-init-logouthookd page +for details.

-p initial_path : the value to set the PATH environment variable to, for all the starting processes. -This will be done as early as possible in stage 1. It is -absolutely necessary for -execline, -s6, -s6-portable-utils and -s6-linux-utils +It is absolutely necessary for +execline and +s6 binaries to be accessible via initial_path, else the machine will not boot. Default is /usr/bin:/bin.

-m initial_umask : the value of the initial file umask for all the starting processes, in octal. -Default is -022.

+Default is 022.

-t timestamp_style : how logs are timestamped by the catch-all logger. 0 means no @@ -319,39 +210,37 @@ devtmpfs automounted by the kernel at boot time. Default is 2.

-s env_store : stage 1 init sometimes -inherits a few environment variables from the kernel. It empties its -environment before spawning stage2 and executing into s6-svscan, in +inherits a few environment variables from the kernel. (These variables +correspond to the arguments on the kernel command line that are of the +form key=value.) It empties its +environment before spawning rc.init and executing into s6-svscan, in order to prevent those "kernel" environment variables from leaking into the whole process tree. However, sometimes those variables are needed at a later time; in that case, giving the -s option -to s6-linux-init-maker makes stage 1 init dump the "kernel" environment -variables into the env_store directory, via the -s6-dumpenv -program, before erasing them. env_store should obviously be -a writable directory, so it should be located under tmpfsdir! -If this option is not given (which is the default), the environment -inherited from the kernel isn't saved anywhere.

+to s6-linux-init-maker makes stage 1 init dump the "kernel" environment +variables into the env_store directory (under a format that is +later readable with +s6-envdir -fn) +before erasing them. env_store should obviously be +a writable directory, so it should be located under /run +(or your chosen tmpfsdir)! +If this option is not given, the environment inherited from the kernel +isn't saved anywhere - which is the default.

-e initial_envvar : this option -can be repeated. For every initial_envvar, s6-linux-init-maker +can be repeated. For every initial_envvar, s6-linux-init-maker will adjust the global environment directory in dir/env. initial_envvar must either be of the form VAR, to make sure that VAR does not appear in the global environment, or of the form VAR=VALUE, to add an environment variable VAR with the value VALUE. The global environment is the environment that every supervised -process (as well as the stage2 script) will run with, +process (as well as the rc.init script) will run with, so it will be inherited by default by every process running on the system. The TZ variable, for instance, is a good candidate to be set in the global environment.

-E stage2_envvar : same behaviour -as the -e option, except that every declared -stage2_envvar will be put in the environment run by the -stage2 script. They will not be put in the global -environment.
-q finalsleeptime : when the machine shuts down, all processes that have not already been killed during shutdownscript will receive a SIGTERM or a SIGHUP to allow @@ -361,10 +250,113 @@ will go on. This option configures the amount of time that will elapse between the SIGTERM/SIGHUP and the SIGKILL. Default is 2000, meaning a grace period of 2 seconds.

-D initdefault : boot the system with +a runlevel set to initdefault, which can be an arbitrary +string, but is usually 2, 3, 5 (traditional +sysvinit behaviour) or default (OpenRC behaviour). Default is +default. Note that if a 2, 3, 4, +5, or default argument is encountered in the kernel +command line, it will be interpreted as the runlevel to boot the system +on, and will override the default given here.

+ +

-U utmp_user : this option is only +available when the s6-linux-init package has been built with the +--enable-utmps configure option, that enables support for the +utmps package. The option +defines the user that the utmpd and wtmpd services +will run as. Default is utmp.

+ +

Organization of the created directory

+ +

+ If s6-linux-init-maker returns successfully, dir +contains data that will be used at boot time. (Actually, +basedir will be used at boot time, not dir. Do not +forget to copy dir to basedir once you have checked +you are happy with what s6-linux-init-maker has created.) +

+ +

+ This boot-time data is made of several subdirectories: +

+ +

bin: this subdirectory contains scripts and symlinks +that should be copied to /sbin or /bin. There is +an init program performing stage 1 init, a telinit +program to change runlevels, and utilities to order a machine shutdown.
env: this subdirectory is the envdir that is +used to store the global environment. It will be read at boot time +by stage 1 init, and transmitted to all spawned processes.
scripts: this subdirectory contains a copy of the +skeleton scripts that have been installed in /etc/s6-linux-init/skel +(or the argument to the --skeldir configure option at +build time). These scripts should be edited before booting. They are +described above.
run-image: this is a file hierarchy that will be +copied verbatim at boot time to the newly made and mounted +/run tmpfs (or whatever your tmpfsdir is). The +subdirectories it contains are the following: +
- uncaught-logs: this is the directory where the +catch-all logger will store and rotate the error messages produced +by the s6 supervision tree and the services that do not redirect +their own logs.
- service: /run/service will be the scandir. +It initially contains a .s6-svscan subdirectory that +tells s6-svscan +what to do if it receives a signal (typically via the ctrlaltdel +combination) and ensures a hard reboot if s6-svscan ever fails. It +also contains a list of early services, i.e. s6 services that will +be run at boot time as soon as s6-svscan is executed. These +services are: +
  - s6-svscan-log: the catch-all logger.
  - s6-linux-init-shutdownd: a service that listens +to shutdown commands such as reboot and triggers the software +shutdown procedure. The service is asleep for the whole lifetime of +the machine and uses very few resources.
  - s6-linux-init-runleveld: a service that listens +to runlevel change commands such as telinit and calls the +runlevel script in a reproducible environment to bring the +machine to the wanted state.
  - (If the -L option has been given to +s6-linux-init-maker) s6-linux-init-logouthookd: +the "clean up user utmp records at logout time" service. See the +s6-linux-init-logouthookd +page for details.
  - (If the -G option has been given to +s6-linux-init-maker) s6-linux-init-early-getty: +the early getty service, that will allow a user to log in even if +rc.init fails to bring the machine to a state where logins +are possible.

+ +

+ If s6-linux-init has been built with +utmps support, some more +directories may exist: +

+ +

A directory somewhere under run-image, by default utmp, +that is the location where the utmp and wtmp files will be created.
Two additional early services named utmpd and wtmpd, +that are the utmps way of +providing secure utmp functionality.

Notes

+ A directory created by s6-linux-init-maker is only valid on +the machine it has been created on. Pre-creating init directories for +other machines is not supported. +

The difficult parts of running @@ -380,22 +372,27 @@ tree's output away from /dev/console (which is fine for a first process invocation but impractical for log management of a whole process tree) and into a logger that is itself managed by the supervision tree it's reading data from. +

Keeping appearances of compatibility with another init system +is difficult: in particular, the mechanisms around the shutdown +procedure are fundamentally different from about any other init +system, so even a simple command such as reboot needs an +ad-hoc implementation.

- The main benefit of s6-linux-init-maker is that it automates those -parts. This means that it has been designed for real hardware -where the above issues apply. - If you are building an init system for a -virtual machine, a container, or anything similar that does not -have the /dev/console issue or the read-only rootfs issue, -you will probably not reap much benefit from using s6-linux-init-maker: + The main benefit of s6-linux-init-maker is that it offers +transparent compatibility while automating the tricky technical part. +That means that s6-linux-init-maker has been designed for +real hardware, or at least full-fledged Linux systems, +where the above issues apply. If you are building an init system for a +container, or anything similar that does not +have the /dev/console issue, the read-only rootfs issue, +or the need for sysvinit compatibility, +you will probably not reap much benefit from using s6-linux-init-maker: you could probably invoke s6-svscan directly as your process 1, or build a script by hand, which would result in a simpler init with less dependencies. -Nevertheless, if you prefer using s6-linux-init-maker, it -supports this case via the -n option.

diff --git a/doc/s6-linux-init-poweroff.html b/doc/s6-linux-init-poweroff.html deleted file mode 100644 index 2126b23..0000000 --- a/doc/s6-linux-init-poweroff.html +++ /dev/null @@ -1,102 +0,0 @@ - - - - - - s6-linux-init: the s6-linux-init-poweroff program - - - - - - -

-s6-linux-init
-Software
-skarnet.org -

- -

The `s6-linux-init-poweroff` program

- -

-s6-linux-init-poweroff triggers the shutdown procedure in order to -halt the system; or, with the -f option, it performs an immediate -hard shutdown. -

- -

Interface

- -

-     s6-linux-init-poweroff [ -h | -p | -r ] [ -d | -w ] [ -W ] [ -f ] [ -R tmpfsdir ]
-

- -

If the -f option is present, s6-linux-init-poweroff halts the system immediately.
Else, it triggers the machine's shutdown procedure. -
It exits 0. The shutdown procedure happens asynchronously.

- -

- This interface follows the traditional sysvinit interface for the -halt, poweroff and reboot programs as close as possible. -

- -

Exit codes

- -

0: shutdown procedure triggered.
100: wrong usage, or user does not have root privileges.
111: system call failed.

- -

Options

- -

-h : halt. No matter the name of the command, it will order -a halt (i.e. the system will be shut down, but the power will remain up). -This is the default for s6-linux-init-halt.
-p : poweroff. No matter the name of the command, it will order -a power off. This is the default for s6-linux-init-poweroff.
-r : reboot. No matter the name of the command, it will order -a reboot. This is the default for s6-linux-init-reboot.
-d : Do not write a wtmp shutdown entry.
-w : Only write a wtmp shutdown entry; do not actually shut down -the system.
-W : Do not send a wall message to users before shutting -down the system. Some other implementations of the halt, poweroff -and reboot commands use the --no-wall long option to achieve this.
-f : force. The command will not trigger a clean shutdown -procedure; it will just sync the filesystems then tell the kernel to immediately -halt, poweroff or reboot. This should be the last step in the lifetime of the -machine.
-R tmpfsdir : assume that the root-only -boot-time tmpfs has been mounted on tmpfsdir. Default is /run. -It is important to get this right, because the contact point with the -s6-linux-init-shutdownd daemon, -which manages the shutdown procedure, is located under this directory. The -halt, poweroff and reboot scripts created by a -s6-linux-init-maker invocation -automatically use the correct -R option.

- -

Notes

- -

The -s6-linux-init-halt, -s6-linux-init-poweroff, -s6-linux-init-reboot and -s6-linux-init-shutdown -binaries are not meant to be called directly by administrators. -Instead, their purpose is to be used in halt, poweroff, -reboot and shutdown scripts created by -s6-linux-init-maker; those scripts -will call them with the correct -R tmpfsdir option. -The scripts should typically be linked to /sbin after -s6-linux-init-maker execution, to -provide drop-in replacements for the sysvinit programs with the -same names.

- - - diff --git a/doc/s6-linux-init-reboot.html b/doc/s6-linux-init-reboot.html deleted file mode 100644 index 422eeed..0000000 --- a/doc/s6-linux-init-reboot.html +++ /dev/null @@ -1,102 +0,0 @@ - - - - - - s6-linux-init: the s6-linux-init-reboot program - - - - - - -

-s6-linux-init
-Software
-skarnet.org -

- -

The `s6-linux-init-reboot` program

- -

-s6-linux-init-reboot triggers the shutdown procedure in order to -reboot the system; or, with the -f option, it performs an immediate -hard reboot. -

- -

Interface

- -

-     s6-linux-init-reboot [ -h | -p | -r ] [ -d | -w ] [ -W ] [ -f ] [ -R tmpfsdir ]
-

- -

If the -f option is present, s6-linux-init-reboot reboots the system immediately.
Else, it triggers the machine's shutdown procedure, which will end in a reboot. -
It exits 0. The shutdown procedure happens asynchronously.

- -

- This interface follows the traditional sysvinit interface for the -halt, poweroff and reboot programs as close as possible. -

- -

Exit codes

- -

0: shutdown procedure triggered.
100: wrong usage, or user does not have root privileges.
111: system call failed.

- -

Options

- -

-h : halt. No matter the name of the command, it will order -a halt (i.e. the system will be shut down, but the power will remain up). -This is the default for s6-linux-init-halt.
-p : poweroff. No matter the name of the command, it will order -a power off. This is the default for s6-linux-init-poweroff.
-r : reboot. No matter the name of the command, it will order -a reboot. This is the default for s6-linux-init-reboot.
-d : Do not write a wtmp shutdown entry.
-w : Only write a wtmp shutdown entry; do not actually shut down -the system.
-W : Do not send a wall message to users before shutting -down the system. Some other implementations of the halt, poweroff -and reboot commands use the --no-wall long option to achieve this.
-f : force. The command will not trigger a clean shutdown -procedure; it will just sync the filesystems then tell the kernel to immediately -halt, poweroff or reboot. This should be the last step in the lifetime of the -machine.
-R tmpfsdir : assume that the root-only -boot-time tmpfs has been mounted on tmpfsdir. Default is /run. -It is important to get this right, because the contact point with the -s6-linux-init-shutdownd daemon, -which manages the shutdown procedure, is located under this directory. The -halt, poweroff and reboot scripts created by a -s6-linux-init-maker invocation -automatically use the correct -R option.

- -

Notes

- -

The -s6-linux-init-halt, -s6-linux-init-poweroff, -s6-linux-init-reboot and -s6-linux-init-shutdown -binaries are not meant to be called directly by administrators. -Instead, their purpose is to be used in halt, poweroff, -reboot and shutdown scripts created by -s6-linux-init-maker; those scripts -will call them with the correct -R tmpfsdir option. -The scripts should typically be linked to /sbin after -s6-linux-init-maker execution, to -provide drop-in replacements for the sysvinit programs with the -same names.

- - - diff --git a/doc/s6-linux-init-shutdown.html b/doc/s6-linux-init-shutdown.html index 72bbfcf..b48ea61 100644 --- a/doc/s6-linux-init-shutdown.html +++ b/doc/s6-linux-init-shutdown.html @@ -20,24 +20,25 @@

s6-linux-init-shutdown triggers the system shutdown procedure. +It is normally invoked as /sbin/shutdown.

Interface

-     s6-linux-init-shutdown [ -h | -p | -r | -k ] [ -a ] [ -t sec ] [ -f | -F ] [ -R tmpfsdir ] time [ message ]
-     s6-linux-init-shutdown -c [ -R tmpfsdir ] [ message ]
+     s6-linux-init-shutdown [ -h | -p | -r | -k ] [ -a ] [ -t sec ] [ -f | -F ] time [ message ]
+     s6-linux-init-shutdown -c [ message ]

If the -c option is present, a pending shutdown is cancelled.
Else, it triggers the shutdown procedure. +
Else, it triggers the shutdown procedure.
It exits 0. The shutdown procedure happens asynchronously.

The s6-linux-init-shutdown program conforms to the LSB-3.0.0 -shutdown +shutdown interface.

@@ -49,29 +50,16 @@ interface.

111: system call failed.

Supplementary options

- -

- These options are supported by s6-linux-init-shutdown but are not -part of the LSB-3.0.0 shutdown specification. -

- -

-R tmpfsdir : assume that the root-only -boot-time tmpfs has been mounted on tmpfsdir. Default is /run. -The shutdown script created by a -s6-linux-init-maker invocation -automatically execs into s6-linux-init-shutdown with the correct --R option.

Notes

The s6-linux-init-shutdown -binary is not meant to be called directly by administrators. -Instead, its purpose is to be used in a shutdown script created by -s6-linux-init-maker.
The s6-linux-init-shutdown +binary is not meant to be called directly by administrators. Instead, after a +s6-linux-init-maker invocation, +the bin/ subdirectory of the target will contain a shutdown +symlink to s6-linux-init-shutdown. The bin/ subdirectory +should be copied by the administrator into /sbin for full +interface compatibility with sysvinit.

diff --git a/doc/s6-linux-init-shutdownd.html b/doc/s6-linux-init-shutdownd.html index b6ea412..f4cf8a0 100644 --- a/doc/s6-linux-init-shutdownd.html +++ b/doc/s6-linux-init-shutdownd.html @@ -3,8 +3,8 @@ - s6-linux-init: the s6-linux-init-shutdownd internal program - + s6-linux-init: the s6-linux-init-shutdownd program + @@ -16,7 +16,7 @@ skarnet.org

The `s6-linux-init-shutdownd` internal program

The `s6-linux-init-shutdownd` program

s6-linux-init-shutdownd is the daemon that manages the shutdown @@ -27,7 +27,7 @@ directly by the user.

Interface

-     s6-linux-init-shutdownd [ -b bindir ] [ -c basedir ] [ -g gracetime ] fifo
+     s6-linux-init-shutdownd [ -c basedir ] [ -g gracetime ] fifo

s6-linux-init-shutdown

When it receives a command to shut down, s6-linux-init-shutdownd -first spawns the stage3 script defined by the last -s6-linux-init-maker invocation.

rc.shutdown

s6-linux-init-maker

When this script exits, s6-linux-init-shutdownd kills all processes, first with a SIGTERM, then (after the grace time specified by the shutdown command) with a SIGKILL.

Options

-b bindir : look for the -execlineb -script interpreter in the bindir directory. Default is /bin.
-c basedir : look for the stage3 and stage4 scripts in the basedir directory. Default is /etc/s6-linux-init.

s6-linux-init: the s6-linux-init-telinit program

+s6-linux-init
+Software
+skarnet.org +

The `s6-linux-init-telinit` program

+s6-linux-init-telinit changes runlevels, i.e. changes the +system state. It is normally invoked as /sbin/telinit or +just init with an argument. +

Interface

+     s6-linux-init-telinit rl
+

s6-linux-init-telinit may be called with the same options as +s6-linux-init, but it ignores them all.
It calls the runleveld +local service with +the rl argument. This local service executes the user-provided +runlevel script, which changes the system state to the state +described by rl.
As a special case, if rl is 0 or 6, +s6-linux-init-telinit then executes into +s6-linux-init-hpr with the -p +or -r option respectively, +for compatibility with sysvinit's 0 and 6 runlevels +that respectively halt and reboot the machine.

Notes

Traditional sysvinit only allows integer runlevels, from 0 to 6. +More advanced service managers, like OpenRC or s6-rc, allow the admin to +define alphanumerical runlevels, or states. s6-linux-init-telinit +does not implement policy; it only makes sure the user-provided runlevel +script is called with the rl argument, under a safe and reproducible +environment. The runlevel script can then change the machine state +as chosen by the user - typically by invoking the service manager.
The 0 and 6 special case has been added because +some legacy programs may assume that calling init 0 and init 6 +respectively halt and reboot the system.
The s6-linux-init-telinit +binary is not meant to be called directly by administrators. Instead, after a +s6-linux-init-maker invocation, +the bin/ subdirectory of the target will contain a telinit +symlink to s6-linux-init-telinit. The bin/ subdirectory +should be copied by the administrator into /sbin for full +interface compatibility with sysvinit.

s6-linux-init: the s6-linux-init-umountall program

+s6-linux-init
+Software
+skarnet.org +

The `s6-linux-init-umountall` program

+ s6-linux-init-umountall unmounts all the filesystems. +

Interface

+     s6-linux-init-umountall
+

s6-linux-init-umountall unmounts all partitions according to /proc/mounts. +It processes /proc/mounts in the reverse order, starting with the most recently mounted +partition and ending with the root filesystem ("unmounting" the root filesystem means remounting +it read-only).
s6-linux-init-umountall does not touch /etc/mtab.
If a filesystem fails to unmount, a warning is printed to stderr, but +s6-linux-init-umountall still attempts to unmount all the other ones.

Notes

s6-linux-init-umountall is automatically called at the very end of the shutdown procedure, +in "stage 4", i.e. after a SIGKILL has been sent to all the processes on the system, and +right before the system reboots (or halts, or is powered off). By that point, there is +no possible process that could prevent real file systems from being unmounted.
It is likely that some filesystems will still fail to unmount, typically +/proc and /dev. That's okay: those are pseudo-filesystems, and +will not cause data loss or a fsck if the system shuts down while they are still mounted.
Distributions usually provide a umount command with a -a option +to unmount all filesystems. That command is usually bloated with historical artifacts +and relies on unsafe interfaces, so it was decided not to use it. The +s6-linux-utils package also +provides a s6-umount +command with a -a option, but adding a dependency to that package would be a +higher cost than simply reimplementing the specific functionality here.

s6-linux-init: the s6-linux-init program

+s6-linux-init
+Software
+skarnet.org +

The `s6-linux-init` program

+s6-linux-init is a program that is meant to run as pid 1, +as a stage 1 init: it performs the necessary early system preparation +and execs into s6-svscan. +

Interface

+     s6-linux-init [ -c basedir ] [ -p initial_path ] [ -s env_store ] [ -m umask ] [ -d dev_style ] [ -D initdefault ] [ args... ]
+

If s6-linux-init isn't pid 1, it execs into +s6-linux-init-telinit with the +same arguments.
Else, it performs some early preparation, spawns a process that +will run the rc.init script, then execs into +s6-svscan. +

Options

+ These options should exactly mirror the options with the same name that +have been given to s6-linux-init-maker. +If there is a discrepancy, the system might not boot. +

-c basedir : read all its initialization +data from basedir. If the data has not indeed been copied to +basedir, the system will not boot.
-p initial_path : the value to +set the initial PATH environment variable to. +
-s env_store : the place where to dump +kernel environment variables.
-m initial_umask : the value of +the initial file umask.
-d dev_style : how /dev is +handled on this system. 0 means a static /dev, 1 means +devtmpfs but not automounted by the kernel at boot time, and 2 means +devtmpfs automounted by the kernel at boot time.
-D initdefault : the initial runlevel +to boot to, if it isn't overridden by the kernel command line. +This is only given as a first argument to rc.init. +Default is default.

Early preparation

+ When booting a system, s6-linux-init performs the following +operations: +

It prints a banner to /dev/console.
It chdirs to /.
It sets the umask to initial_umask.
It becomes a session leader.
It mounts a devtmpfs on /dev, if necessary.
It uses /dev/null as its stdin (instead of /dev/console). +/dev/console is still used, for now, as stdout and stderr.
It unmounts /run (or the directory you have given to the +--tmpfsdir configure option at package build time), just in case.
It creates a tmpfs on /run (or your chosen tmpfsdir).
It copies the whole basedir/run-image hierarchy to +/run (or your chosen tmpfsdir).
It reads the initial environment from basedir/env.
If required, it stores the kernel environment into env_store.
It performs "the fifo trick", i.e. it redirects its stdout to the +catch-all logger's fifo, without blocking, before the catch-all +logger is even up (because it's a service that will be spawned a bit +later, when s6-svscan +is executed).
It forks a child. +
- The child scans the kernel command line to find a suitable runlevel +(default, 2, 3, 4, or 5). If +it doesn't find any kernel command line argument that defines a runlevel, +it uses initdefault.
- The child becomes a session leader.
- The child blocks until the catch-all logger runs.
It also makes the catch-all logger's fifo its stderr.
It execs into s6-svscan +with /run/service as its scandir (or tmpfsdir/service)

s6-svscan +spawns the early services that are defined in +basedir/run-image/service, and have been copied into +/run/service (or tmpfsdir/service).
One of those early services is s6-svscan-log, which is +the catch-all logger. When this service is up, s6-linux-init's +child unblocks.

+ The child execs into basedir/scripts/rc.init. +The first argument to rc.init is the chosen runlevel. The kernel +command line, as given by the kernel to s6-linux-init (i.e. without +the key=value arguments, which were passed into s6-linux-init's +environment and were stored into env_store), makes for the rest of +the arguments given to rc.init. +

+

+ + + By the time rc.init runs, +s6-svscan is running +as pid 1 and has spawned its early services - at least the catch-all logger, +and the other services, including the early getty if it has been defined, are +started in parallel and will be ready instantly. rc.init can then +perform stage 2 of the initialization process, i.e. the initialization +sequence per se. + + + Notes + + + The s6-linux-init +binary is not meant to be called directly, or be linked to /sbin/init +directly, because it takes command-line options. + Instead, after a +s6-linux-init-maker invocation, +the bin/ subdirectory of the target will contain a script called +init, which execs into s6-linux-init with the appropriate +command-line options, and is suitable as a /sbin/init program. +The bin/ subdirectory +should be copied by the administrator into /sbin for full +interface compatibility with sysvinit. + + + + diff --git a/doc/upgrade.html b/doc/upgrade.html index 1acbba5..02aaeea 100644 --- a/doc/upgrade.html +++ b/doc/upgrade.html @@ -18,6 +18,15 @@ What has changed in s6-linux-init + + in 1.0.0.0 + + + This is a complete rewrite and redesign of s6-linux-init: the +lifetime version number has increased. No compatibility +whatsoever is retained with previous versions. + + in 0.4.0.1 diff --git a/doc/why.html b/doc/why.html new file mode 100644 index 0000000..2c200c5 --- /dev/null +++ b/doc/why.html @@ -0,0 +1,139 @@ + + + + + + s6-linux-init: why? + + + + + + + +s6-linux-init +Software +skarnet.org + + + Why s6-linux-init ? + + The s6 software stack + + + The s6 ecosystem is made of several parts, which are mainly the following: + + + + skalibs: a C system +programming library that is used in all skarnet.org software. + execline: a small +scripting language that is mainly used in various parts of the s6 +ecosystem because: + + It is very quick to launch, and efficient with small scripts, so it +is a good choice for s6 run scripts. + It is much easier to programmatically generate execline scripts than +shell scripts. execline allows programs such as +s6-linux-init-maker to generate scripts +quite easily, whereas using the shell syntax would require them to understand +the full subleties of shell quoting. + + s6, the main dish: a process +supervision suite. + s6-rc: a service manager +for s6. + and s6-linux-init: this +package. + + + Providing a complete init system + + + As explained in +this +presentation">, an init system is made of four parts: + + + + /sbin/init: the first userspace program that is run by the +kernel at boot time (not counting an initramfs). + pid 1: the program that will run as process 1 for most of +the lifetime of the machine. This is not necessarily the same executable +as /sbin/init, because /sbin/init can exec into something +else. + a process supervisor. + a service manager. + + + + The s6 package obviously provides +part 3. It also provides part 2, because +s6-svscan is suitable +as being pid 1 after some small setup is performed. + + + + Part 4, service management, can be provided in a variety of ways. The +s6-rc service manager is the +natural complement to the s6 process supervisor, but it is not the only +possibility. The +anopa package also provides a +service manager designed to work with s6. And, at the expense of +tight integration with the supervisor, it is possible to run a "traditional" +service manager, such as sysv-rc or OpenRC, with an s6-based init system. +This flexibility is possible because service management is one layer above +the mechanisms of init and process supervision. + + + + Remains part 1. And that's where s6-linux-init enters the picture. + + + Portability + + + Part 1 of an init system, the /sbin/init program, has been purposefully +omitted from the main s6 package, for a simple reason: s6 aims to be portable +to any flavor of Unix, and it is impossible to implement /sbin/init +in a portable way. + + + + For instance, to do its job, +s6-svscan needs +a writable directory. Such a directory may not be available at boot time, +before mounting filesystems, because the root filesystem may be read-only. +So, at least one writable filesystem (typically a RAM-backed one) must be +mounted before s6-svscan can be executed and be pid 1. And mounting a +filesystem is a non-portable operation. + + + Complexity + + + Moreover, the sequence of operations that a /sbin/init program +needs to perform before executing into s6-svscan is a bit +tricky. It can be scripted, but it's not easy, and since it's so early +in the lifetime of the machine, there's no safety net at all (the +supervision tree itself, and the early getty, are supposed to be the +safety net! and they're not there yet). So it's better to automate +these operations. + + + Conclusion + + + s6-linux-init aims to provide a fully functional /sbin/init +program that executes into an s6 supervision tree with all the necessary +support services already in place, as well as the corresponding shutdown +commands. It also aims to be flexible enough to accommodate various needs +and be compatible with any user-chosen service manager. + + + +As usual, it is about mechanism, not policy. + + + + -- cgit v1.2.3

Getting started

Installation

Requirements

Licensing

Reference

General

Commands

Related resources

An overview of s6-linux-init

Organisation of the package

Organisation of the booted system

Integration with the service manager

Quickstart and FAQ for s6-linux-init

Quickstart for s6-linux-init

Quickstart

What should go into /etc/rc.init and /etc/rc.shutdown ?

/etc/rc.init

/etc/rc.shutdown

FAQ

Why is it so complicated to use s6 as an init process? It's much -simpler with runit.

My /etc/rc.init script is not printing anything!

I want to run s6 in a container, and I just want to log -to stdout/stderr, without this tmpfs and /dev/console -stuff and -without having a catch-all logger inside the container. Is it -possible ?

The s6-linux-init-echo program

Interface

Options

Notes

The s6-linux-init-halt program

Interface

Exit codes

Options

Notes

The s6-linux-init-hpr program

Interface

Exit codes

Options

Notes

The s6-linux-init-logouthookd program

Interface

Notes

Interface and usage

Boot sequence

Shutdown sequence

s6-linux-init-maker options

Organization of the created directory

Notes

The s6-linux-init-poweroff program

Interface

Exit codes

Options

Notes

The s6-linux-init-reboot program

Interface

Exit codes

Options

Notes

Interface

Supplementary options

Notes

The s6-linux-init-shutdownd internal program

The s6-linux-init-shutdownd program

Interface

Options

The s6-linux-init-telinit program

Interface

Notes

The s6-linux-init-umountall program

Interface

Notes

The s6-linux-init program

Interface

Options

Early preparation

Notes

What has changed in s6-linux-init

in 1.0.0.0

in 0.4.0.1

Why s6-linux-init ?

The s6 software stack

Providing a complete init system

Portability

What should go into `/etc/rc.init` and `/etc/rc.shutdown` ?

`/etc/rc.init`

`/etc/rc.shutdown`

My `/etc/rc.init` script is not printing anything!

I want to run s6 in a container, and I just want to log -to stdout/stderr, without this tmpfs and `/dev/console` -stuff and -without having a catch-all logger inside the container. Is it -possible ?

The `s6-linux-init-echo` program

The `s6-linux-init-halt` program

The `s6-linux-init-hpr` program

The `s6-linux-init-logouthookd` program

The `s6-linux-init-poweroff` program

The `s6-linux-init-reboot` program

The `s6-linux-init-shutdownd` internal program

The `s6-linux-init-shutdownd` program

The `s6-linux-init-telinit` program

The `s6-linux-init-umountall` program

The `s6-linux-init` program