The s6-linux-init-maker program
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
infrastructure running when the system is booted on that
s6-linux-init-maker only writes scripts. At boot time, these
scripts will call commands provided by other skarnet.org packages
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.
Interface and usage
[ -c basedir ] \
[ -l tmpfsdir ] \
[ -b execline_bindir ] \
[ -u log_uid -g log_gid | -U ] \
[ -G early_getty ] \
[ -2 stage2 ] \
[ -r ] \
[ -Z ] stage2_finish \
[ -3 stage3 ] \
[ -p initial_path ] \
[ -m initial_umask ] \
[ -t timestamp_style ] \
[ -d dev_style ] \
[ -s env_store ] \
[ -e initial_envvar ] ... \
[ -n ] \
- s6-linux-init-maker should be run as root.
- s6-linux-init-maker parses options on its command line.
- It writes data into a directory dir, which must not
- It exits 0 if everything went well, 100 if a user error occurred,
and 111 if a problem occurred during the creation of the directory
or its contents.
dir should then be copied by the administrator to the place
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
tool can do it, as well as the GNU or busybox cp -a or mv commands.
The basedir/init script
is then suitable as a "stage 1" init program, i.e. the first program
run by the kernel. The administrator should make a symbolic link
from /sbin/init to basedir/init; the
machine will then be ready to boot
When the kernel boots, it runs the basedir/init script,
also known as stage 1. and this is what happens:
- stage 1 is an
execline script, so
the first process run by the kernel is the
- stage 1 mounts a
filesystem on tmpfsdir.
- stage 1 copies basedir/run-image verbatim to
- stage 1 empties its environment, then reads a global set of environment variables from the
- stage 1 forks a child that will block until
s6-svscan is running.
- stage 1 executes, as process 1, into
with tmpfsdir/service as a
- 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
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 stage2.
stage2 is the responsibility of the administrator - it will
not be written automatically!
contain all the necessary initialization sequence to bring up a proper
system. When stage2 is executed, the machine state is as follows:
- stage2'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.
is running as process 1. At any time, it is possible to make it supervise a long-lived
process by linking the appropriate
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 stage2 fails.
There is nothing else. In particular, no filesystem has been
mounted yet, including /proc and /sys; and no one-time
has been performed. The point of stage 1 is only to make it
possible to run stage2 with a logging infrastructure and a
supervision infrastructure already available, and all the
real machine and service initialization should happen in stage2.
- A shutdown is performed when the administrator runs one of the
- Those commands send a signal to the
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 stage2_finish script, who
must have been written by the administrator. The purpose of
stage2_finish is to perform the high-level shutdown sequence
while the supervision tree is still alive. Typically, when using a
service manager, stage2_finish 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, stage2_finish should undo what
stage2 has done at boot time.
- The "signal handler" script then tells s6-svscan to exit via an
command: s6-svscan then executes into the stage3 script, which, like
stage2 and stage2_finish, is the responsibility of the
administrator. When stage3 runs, the machine is in the following
- The supervision tree has been torn down: it is not operational
anymore. (So, commands such as
require a live supervision tree, will not work.)
- stage3 runs as process 1. Doing so makes it easier to recover
after killing all processes by kill -9 -1 or
- Its working directory is / and its stdin is /dev/null
- Its stdout and stderr are both /dev/console
- Depending on the exact configuration and what the administrator has
written in stage2_finish, there may or may not be
long-running services that remain alive. The catch-all logger and its
supervisor will always be alive; this is not a problem because they
do not hold any file descriptor to a filesystem that would need to be
- The last command that stage3 executes should be
s6-$1 -f, $1 being the first argument that has been
given to it. This command will instantly execute the hard system halt,
poweroff or reboot that has initially been asked by the admin.
The examples/ subdirectory of the s6-linux-init package
contains an example of /etc/rc.init, /etc/rc.tini
and /etc/rc.shutdown scripts, suitable for
stage2, stage2_finish and stage3
respectively. Those scripts can practically be used as is if the machine
is managed by the s6-rc
- -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
created directory dir to basedir. basedir
must be absolute. Default is
- -l tmpfsdir : at boot time, a tmpfs will
be mounted on tmpfsdir. The directory should already exist in
the root filesystem, and be empty. tmpfsdir must be absolute. Default is
- -b execline_bindir : init is run by the kernel
without a PATH, and since it is a script, it is necessary to tell it where
to find the
launcher and the first few early commands before PATH can be set.
execline_bindir is the location where the execline binaries can be
found. It must be absolute. Default is
- -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.
- -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
- -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.
early_getty should be a simple command line: for instance,
"/sbin/getty 38400 tty1". By default, no early service
- -2 stage2 : stage2 is
the location of the stage 2 script that will be run when the
system has an operational supervision tree. It must be absolute. Default is
- -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.
- -Z stage2_finish :
stage2_finish is the location of the script that will be
run when s6-svscan receives a signal that tells it to stop the
machine, before it executes into stage3. It must be
absolute. Default is /etc/rc.tini.
Note that this script is run with its stdout and stderr
redirected to the tmpfsdir/uncaught-logs logging
directory, so its output will not appear on the system's console.
- -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.
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 stage 1. It is
absolutely necessary for
binaries to be accessible via initial_path, else the machine
will not boot. Default is
- -m initial_umask : the value of
the initial file umask for all the starting processes, in octal.
- -t timestamp_style : how
logs are timestamped by the catch-all logger. 0 means no
timestamp, 1 means
external TAI64N format,
ISO 8601 format,
and 3 means both. Default is
- -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. Default is
- -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
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
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.
- -e initial_envvar : this option
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 TZ variable, for instance, is a good candidate to be set in
the global environment.
- -n : tells s6-linux-init-maker that the init script
is going to run in a container, as pid 1 in a non-root namespace.
This modifies the .s6-svscan/finish, .s6-svscan/SIGHUP
and .s6-svscan/SIGINT scripts slightly, in order to provide
adequate functionality when the containerized system is asked to
shutdown. Do not add this option if the init script is going to run
in the root pid namespace.
The difficult parts of
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 from 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
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.