From ff781adeb26caca82a717d7f1dd83c4ad94b5165 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Wed, 17 Jun 2015 18:33:06 +0000 Subject: Fix some bugs, add some doc --- doc/index.html | 24 +++++--- doc/quickstart.html | 142 +++++++++++++++++++++++++++++++++++++++++++ doc/s6-linux-init-maker.html | 63 ++++++++++++++++--- 3 files changed, 213 insertions(+), 16 deletions(-) create mode 100644 doc/quickstart.html (limited to 'doc') diff --git a/doc/index.html b/doc/index.html index ad0d3b0..c3426e0 100644 --- a/doc/index.html +++ b/doc/index.html @@ -20,9 +20,9 @@

What is it ?

- s6-linux-init is a set of minimalistic tools to create and manage -the init process on a Linux system - i.e. the first process created -by the kernel at boot time. + s6-linux-init is a set of minimalistic tools to create a +s6-based init +system, including a /sbin/init binary, on a Linux kernel.

@@ -61,11 +61,12 @@ and then you can boot your system on that init script.

- The listed dependencies are all build-time dependencies and also -boot-time dependencies, i.e. you need the tools installed to build -s6-linux-init and to boot your system. There are no run-time -dependencies, except skalibs if you linked against the shared version of -the library. + skalibs and execline are build-time dependencies. + There are no run-time dependencies. + And every listed package, save skalibs, is a boot-time dependency. + If you are using the shared version of the skalibs library, +then skalibs also becomes a run-time and a +boot-time dependency.

Licensing

@@ -101,6 +102,13 @@ the previous versions of s6-linux-init and the current one.

Reference

Quickstart guide and FAQ

+ +

+ There is one, + here ! +

Commands

diff --git a/doc/quickstart.html b/doc/quickstart.html new file mode 100644 index 0000000..da47334 --- /dev/null +++ b/doc/quickstart.html @@ -0,0 +1,142 @@ + + + + + + s6-linux-init: quickstart and FAQ + + + + + + +

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

+ +

Quickstart and FAQ for s6-linux-init

+ +

Quickstart

+ +

Install all the s6-linux-init dependencies: +
- skalibs
- execline
- s6-portable-utils
- s6-linux-utils
- s6
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
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 them executable.
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 > /tmp/init
+     chmod 0700 /tmp/init
+     mv /tmp/s6-linux-init /etc/
+     mv /tmp/init /sbin/

Reboot.
Congratulations! your machine is now running a s6-based init system.

+ +

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

+ + + diff --git a/doc/s6-linux-init-maker.html b/doc/s6-linux-init-maker.html index cdf617e..530cd41 100644 --- a/doc/s6-linux-init-maker.html +++ b/doc/s6-linux-init-maker.html @@ -49,6 +49,7 @@ machine - else the scripts will crash. [ -u log_user ] \ [ -g early_getty ] \ [ -2 stage2 ] \ + [ -r ] \ [ -3 stage3 ] \ [ -p initial_path ] \ [ -m initial_umask ] \ @@ -74,7 +75,7 @@ declared as basedir. 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 command. +tool can do it, as well as the GNU or busybox cp -a or mv commands.

@@ -133,11 +134,10 @@ system. When stage2 is executed, the machine state is as follows:

stage2's working directory is / and its stdin -is /dev/null. stage2's -stdout and stderr both point to the pipe to the catch-all logger, so -unless redirected, stage2's output will be logged into the -tmpfsdir/uncaught-logs directory.
The system has a valid device directory mounted on /dev. +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.

/etc/rc.init

-r : redirect. By default, stage2 is +run with stdout and stderr pointing to /dev/console, so that +users can see what init scripts print. However, it may conflict +with an early getty, or be undesirable for other reasons. The +-r option redirects stage2's stdout and stderr +to the catch-all logger, so the output will be made available +in the tmpfsdir/uncaught-logs directory.

-3 stage3 : stage3 is the location of the stage 3 script that will be run at the end of the machine lifetime, when s6-svscan is told to terminate. @@ -235,8 +243,14 @@ It must be absolute. Default is
-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 stage1. Default is -the value that has been compiled in +This will be done as early as possible in stage1. It is +absolutely necessary for +execline, +s6, +s6-portable-utils and +s6-linux-utils +binaries to be accessible via initial_path, else the machine +will not boot. Default is the value that has been compiled in skalibs via the --with-default-path configure option, i.e. by default /usr/bin:/bin.

@@ -272,5 +286,38 @@ The TZ variable, for instance, is a good candidate to be set in the global environment.

Notes

+ +

+ The difficult parts of +running +s6-svscan as process 1 are: +

+ +

The fact that the supervision tree requires writable directories, +so in order to accommodate read-only root filesystems, there needs to +be a tmpfs mounted before s6-svscan is run.
The catch-22 coming for the need to redirect the supervision +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.

+ +

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

+ -- cgit v1.3.1