S6-linux-init (package)

s6-linux-init is s6-based init system, with optional s6-rc support, on top of the Linux kernel]]. The package's documentation is provided in HTML format, and can be read on a text user interface using for example.

Environment variables

 * UID - The catch-all logger's user ID set by when invoked with the   option.
 * GID - The catch-all logger's group ID set by when invoked with the   option.

Files

 * - Default directory containing the generated stage1 script's scan directory and catch-all logger's logging directory images.
 * - Default environment directory used by the generated stage1 script to set up the init system's supervision tree environment.
 * - Default pathname of the stage2 init expected by the generated stage1 script.
 * - Default pathname of the shutdown file expected by the generated diverted signal handlers.
 * - Default scan directory set up by the generated stage1 script for.
 * - Default pathname of the s6 service directory for the generated catch-all logger.
 * - Default pathname of the s6 service directory for the generated early service.
 * - Default catch-all logger's logging directory.

Usage
The package provides the program, which helps create several components of an s6-based init system, and the,  and  programs, which can shut the machine down if these init system components are used unmodified.

s6-linux-init-maker
The program must be run as root, so that it can create files and directories with appropriate owner, group and permissions, and must be invoked with a directory pathname. It creates a directory at with specified pathname, which must not exist beforehand, containing several init system components:


 * An execline script named, that is a stage1 init.
 * A subdirectory named, which contains:
 * An s6 scan directory image.
 * An empty directory named.
 * A directory named, that might be empty.

To use these components to make an init system, they must be copied to the target machine —which might be the same as the host machine, i.e. the machine that was run on— in appropriate locations. The file must be copied to the place where the kernel is configured to find the program it'll run as process 1. For example, if the bootloader is configured to pass an  argument to the kernel, then the  file generated by  must be copied to  and renamed as. The and  directories must be copied to the location the  script expects them to be. Care must be taken to ensure that owner, group and permissions of files and subdirectories are preserved, e.g. by using GNU or BusyBox with the   option, or the  program from s6-portable-utils.

accepts a set of options that customize all these components. Many of them use programs from packages s6-linux-utils ( and s6-portable-utils internally, so they are pulled in as runtime depencencies ( RDEPEND ). The only build-time dependency that needs itself is.

Because execline scripts require the absolute path of the program in the shebang line (i.e. the first line of the file, that starts with '#!'),  accepts a   option to specify the path prefix for this program, and defaults it to.

The generated stage1 init and the diverted signal handlers need two files that must be supplied by the user to complete the init system: a stage2 init, and a shutdown file that is shared by all signal handlers. This means that will not generate them, as they are higly system-dependent and subject to distribution policy, but generated components will expect them to be present. The package provides examples of both, they are the and  files, respectively, in the  directory of the package's  subdirectory.

For the full description of, please consult the HTML documentation in the package's subdirectory. A summary of each init system component and some of the options that customize it follows.

The stage1 script
This is an execline script that runs as process 1 during the machine's boot sequence and performs these actions:
 * Sets the working directory to /.
 * Sets the PATH environment variable to a specified or default value.
 * Mounts a read-write tmpfs with options  using program  from s6-linux-utils.
 * Copies the directory created by  to the tmpfs, preserving owner, group and permissions of files and subdirectories, using program  from s6-portable-utils.
 * Optionally mounts a devtmpfs on, again using.
 * Optionally dumps the enviroment set up by the kernel to a specified enviroment store, using program from s6-portable-utils. The environment store is a directory that, for every environment variable VAR, contains a text file named . Each file has a single line containing the variable's value.
 * Unsets all enviroment variables except PATH.
 * Adjusts the enviroment according to the directory created by, using  from s6.
 * Spawns the stage2 init as a session leader using from s6, with its standard input redirected to.
 * Replaces itself with.

The stage1 script makes execute as process 1 with signal diversion turned on, periodic scanning turned off, its standard input redirected to , and its standard output and error redirected to the catch-all logger.

Aspects of the stage1 script that can be customized via options are:


 * The location of the and  directories:  . Default:.
 * The pathname of the user-provided stage2 init: . Default:.
 * The mountpoint for the read-write tmpfs: . Default:.
 * The value the PATH environment variable is set to: . This value affects all programs invoked by the script, the stage2 init and, and will be the initial value of PATH for all the init system's supervision tree processes. Default:.
 * The value of the initial file umask for all the starting processes: . Default: 022.
 * Whether a devtmps filesystem is mounted on or not:  . Default:  is left untouched.
 * The pathname of a read-write directory for storing the kernel's environment variables: . If no   options is given, the environment set up by the kernel is discarded before the stage1 script replaces itself with.
 * The initial environment of, and therefore, of all the init system's supervision tree processes: .  constructs directory  as an environment directory with all the variable settings specified by repeated use of this option. The stage1 script expects this directory to be in the same directory as ; therefore, its absolute pathname will be  with 's defaults. If no   options are given, 's environment only has the PATH variable, and  will be empty.

The stage2 init
The stage2 init must be provided by the user, runs as a child process of the stage1 script, and blocks until starts running as process 1. If is passed an   option ('redirect'), the stage1 script redirects the stage2 init's standard output and error to the catch-all logger, i.e. all messages will be logged in its logging directory. Otherwise, the stage2 init's standard output and error are redirected to.

The init system's scan directory
The scan directory image contains:


 * An s6 service directory for the init system's catch-all logger, named.
 * An optional s6 service directory for an early getty service, named.
 * The subdirectory with  and  files, as well as  diverted signal handlers. All of these files are execline scripts, and  is the init system's stage3 init.

This scan directory image is copied to the tmpfs by the stage1 script, and becomes 's scan directory when it starts running as process 1.

accepts a  option followed by a suitable invocation (program name and arguments) of some  implementation, for example,   for Gentoo. If this option is supplied, the early getty service directory contains a execline script with the specified  invocation, which means that a (single)  process will be spawned by  as soon as it starts running as process 1. This allows logging in to the machine from its console as early as possible. If no  option is given, there will be no early getty service, and any  setup must be done by the user-provided stage2 init.

The catch-all logger
The catch-all logger is an process that logs to a logging directory named, and placed in the read-write tmpfs mounted by the stage1 script. Therefore, its absolute pathname will be with 's defaults. The standard output of the process are redirected to, and its standard error, to , i.e. the machine's console.

The file opens the logger's FIFO for reading, which is created by  in the service directory with the name, uses  from s6 to set the effective user and group, and then invokes  with the   option, so that it cannot be killed by the   signal.

creates the directory with an owner and group that match 's effective user and group, and the stage1 script copies it to the tmpfs.

Aspects of the catch-all logger that can be customized via options are:


 * The process' effective user and group: ,   and  . They can be specified as a numeric user ID (UID) and group ID (GID) valid for the target machine with the  ,   options, respectively, or read from environment variables UID and GID , respectively, if the   option is used. This allows, for example the invocation of  as s6-envuidgid larry s6-linux-init-maker -U dir to make  run with effective user set to 'larry', as defined in the host machine's account database, assuming this is also appropriate for the target machine. If any of these options is specifed,  creates the  directory with permissions 2700 (i.e. it has set-group-ID on execution enabled and the ls -l command would show  ). Otherwise, 's effective user and group are those that correspond to UID 0 and GID 0, and  creates the  directory with permissions 0700 (i.e. the ls -l command would show  ). Therefore, on Gentoo, if no  ,   and   options are given,  would run with effective user set to root.
 * How logged lines of text are timestamped:  . Default: timestamps in external TAI64N format are used, as generated by 's t directive.

The diverted signal handlers
All diverted signal handlers are execline scripts that invoke a common shutdown file, wait for it to finish its execution, and then invoke the  program to make  perform its finish procedure, which tears down the init system's supervision tree and initiates execution of the stage3 script. The shutdown file must be provided by the user, and runs with its standard input redirected to, and its standard output and error redirected to the catch-all logger.

The behaviour of the different signals sent to process 1 when these handlers are used is:
 * : Makes send a   signal to all its  children before performing its finish procedure, using an s6-svscanctl -h command.
 * : Makes send a   signal to all its  children before performing its finish procedure, using an s6-svscanctl -q command.
 * : reboots the machine using an s6-svscanctl -6 command. The operating system is usually configured to send a  to process 1 when key combination ++ is pressed, resulting in a machine reboot too.
 * : currently equivalent to.
 * : powers the machine off using an s6-svscanctl -7 command.
 * : halts the machine using an s6-svscanctl -0 command.

Aspects of the signal handlers that can be customized via options are:


 * The pathname of the shutdown file: . Default:.

The stage3 script
This is an execline script that runs as process 1 during the machine's shutdown sequence, and performs these actions:
 * Sets the working directory to /.
 * Redirects its standard output and error to, i.e. the machine's console.
 * Uses an s6-svc -X command to make the catch-all logger exit.
 * Syncs all disks, flushing all the dirty system buffers, using program from s6-portable-utils.
 * Sends a  signal and   signal to all remaining processes, to allow them to exit on their own, using program  from s6-portable-utils.
 * After a grace period, sends a  signal to all remaining processes to kill them, again using.
 * Unmounts all filesystems according to using program  from s6-linux-utils.
 * Remounts the root filesystem read-only using program from s6-linux-utils.
 * Invokes the, or  program with the   option to shut the machine down.

Aspects of the stage3 script that can be customized via options are:


 * Grace period given to remaining processes after tearing down the supervision tree: . Default: 2 seconds.

s6-rc support
All the necessary setup needed to make s6-rc part of the init system is done in the stage2 init and in the shutdown file. Because both files are provided by the user, the s6-linux-init does not have, or need, any specific support for s6-rc. Nevertheless, the and  execline scripts provided by the package as examples illustrate an s6-rc setup.

s6-halt, s6-poweroff and s6-reboot
These programs can be used in combination with the init system components generated by to shut the machine down:  to halt it,  to power it off, and  to reboot it.

These programs support an  ('force') option, just like their sysvinit counterparts, to perform their respective action without going through the init system (using the Linux   system call). Otherwise, they just send a signal to process 1 that corresponds to the diverted signal handler generated by for the requested shutdown operation.

For further information about these programs, please consult the HTML documentation in the package's subdirectory.

Unmerge
If the init system relies on, and , this can render it non-functional unless the machine has replacements with equivalent functionality.