diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/index.html | 6 | ||||
| -rw-r--r-- | doc/overview.html | 19 | ||||
| -rw-r--r-- | doc/s6-linux-init-maker.html | 120 | ||||
| -rw-r--r-- | doc/s6-linux-init-shutdownd.html | 11 | ||||
| -rw-r--r-- | doc/s6-linux-init-telinit.html | 5 | ||||
| -rw-r--r-- | doc/s6-linux-init.html | 16 | ||||
| -rw-r--r-- | doc/upgrade.html | 21 |
7 files changed, 159 insertions, 39 deletions
diff --git a/doc/index.html b/doc/index.html index 85727a8..2b912ab 100644 --- a/doc/index.html +++ b/doc/index.html @@ -74,9 +74,9 @@ kernel command line </li> <li> <a href="//skarnet.org/software/skalibs/">skalibs</a> version 2.9.1.0 or later </li> <li> <a href="//skarnet.org/software/execline/">execline</a> version -2.5.3.0 or later </li> +2.6.0.0 or later </li> <li> <a href="//skarnet.org/software/s6/">s6</a> version -2.9.0.1 or later </li> +2.9.1.0 or later </li> </ul> <p> @@ -110,7 +110,7 @@ all the other packages against the <em>static</em> version of libskarnet. <ul> <li> The current released version of s6-linux-init is -<a href="s6-linux-init-1.0.3.1.tar.gz">1.0.3.1</a>. </li> +<a href="s6-linux-init-1.0.4.0.tar.gz">1.0.4.0</a>. </li> <li> Alternatively, you can checkout a copy of the <a href="//git.skarnet.org/cgi-bin/cgit.cgi/s6-linux-init/">s6-linux-init git repository</a>: diff --git a/doc/overview.html b/doc/overview.html index d779dd2..adaa414 100644 --- a/doc/overview.html +++ b/doc/overview.html @@ -80,7 +80,8 @@ procedure when the admin runs a <tt>halt</tt>, <tt>poweroff</tt>, <tt>reboot</tt> or <tt>shutdown</tt> command. </li> <li> <em>runlevel</em>: the script executing a machine state change at boot time (normally invoked by <em>rc.init</em>, towards the default -runlevel) or when the administrator runs a <tt>telinit</tt> command. </li> +runlevel) or when the administrator runs a <tt>telinit</tt> command. +This script is unused in a container. </li> <li> <em>rc.shutdown.final</em>: a script that will be run at the very end of the shutdown procedure, after all processes have been killed and all filesystems have been unmounted, <em>just before</em> the system @@ -110,21 +111,25 @@ via the <tt>-c</tt> option. </li> <li> Some early services are defined in <tt>/run/service</tt>, 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: +even if they're not process 1. +Apart from <tt>s6-linux-init-shutdownd</tt>, which is necessary for the +machine (or container) to respond to shutdown requests, they are only present +depending on the configuration, and different +<a href="s6-linux-init-maker.html">s6-linux-init-maker</a> invocations will +yield different sets of services. The services are picked from this list: <ul> - <li> <tt>s6-svscan-log</tt>: the catch-all logger </li> <li> <tt>s6-linux-init-shutdownd</tt>: the shutdown manager, running the shutdown sequence in a reproducible environment when a shutdown command is executed, then performing the last shutdown steps. </li> + <li> <tt>s6-svscan-log</tt>: the catch-all logger </li> <li> <tt>s6-linux-init-runleveld</tt>: the runlevel manager, running the <em>runlevel</em> script in a reproducible environment when a <tt>telinit</tt> command is executed. </li> - <li> (optionally) <tt>s6-linux-init-logouthookd</tt>: a local service performing + <li> <tt>s6-linux-init-logouthookd</tt>: a local service performing utmp record cleanup duty for patched <tt>login</tt> programs. </li> - <li> (optionally) <tt>s6-linux-init-early-getty</tt>: the early getty, + <li> <tt>s6-linux-init-early-getty</tt>: the early getty, allowing the user to login even if <em>rc.init</em> fails early. </li> - <li> (optionally) <tt>utmpd</tt> and <tt>wtmpd</tt>: the services performing + <li> <tt>utmpd</tt> and <tt>wtmpd</tt>: the services performing utmp and wtmp access when <a href="//skarnet.org/software/utmps/">utmps</a> is used. </li> </ul> </li> diff --git a/doc/s6-linux-init-maker.html b/doc/s6-linux-init-maker.html index 7fe963b..d8c1432 100644 --- a/doc/s6-linux-init-maker.html +++ b/doc/s6-linux-init-maker.html @@ -62,6 +62,8 @@ machine</em>. If it is not the case, the system will fail to boot. [ -n | -N ] \ [ -f <em>skeldir</em> ] \ [ -U <em>utmp_user</em> ] \ + [ -C ] \ + [ -B ] \ <em>dir</em> </pre> @@ -102,13 +104,20 @@ the machine should be brought to, traditionally <tt>default</tt> for OpenRC and <tt>2</tt> or <tt>5</tt> 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 <em>key=value</em> form, -which have been stored into <em>env_store</em>. </li> +which have been stored into <em>env_store</em>. If the <tt>-C</tt> +option has been given to <tt>s6-linux-init-maker</tt> and the +system is indeed running in a container, the rest of the +command line is just the command line that has been given to +the container's <tt>init</tt> (e.g. for Docker: the CMD). Note +that the <tt>runlevel</tt> script should not be invoked in a +container, which does not have a notion of runlevels. </li> <li> <tt>rc.shutdown</tt>: this script will be run as the <em>shutdown sequence</em>, when the administrator runs the <tt>shutdown</tt>, <tt>halt</tt>, <tt>poweroff</tt> or <tt>reboot</tt> -command. (As well as <tt>init 0</tt>, <tt>init 6</tt>, -<tt>telinit 0</tt> and <tt>telinit 6</tt> for compatibility -reasons.) It should ask the service manager to bring all the +command. (As well, for non-containerized systems, +as <tt>init 0</tt>, <tt>init 6</tt>, <tt>telinit 0</tt> and +<tt>telinit 6</tt> for sysvinit 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. </li> @@ -117,7 +126,8 @@ No arguments are given to this script. </li> given one argument: the name of the runlevel to change to. Typically, the <em>runlevel</em> script should just invoke the service manager, asking it to bring the machine state to the -wanted runlevel. </li> +wanted runlevel. In a containerized system, this script should +not be used at all.</li> </ul> </li> <li> Copy the <em>dir</em> directory to the place declared as <em>basedir</em> (<tt>/etc/s6-linux-init/current</tt> by default). @@ -312,6 +322,60 @@ available when the s6-linux-init package has been built with the <a href="//skarnet.org/software/utmps/">utmps</a> package. The option defines the user that the <tt>utmpd</tt> and <tt>wtmpd</tt> services will run as. Default is <strong><tt>utmp</tt></strong>. </li> <p /> + + <li> <tt>-C</tt> : create a set of scripts that is suitable +for running <em>in a container</em>. This modifies some behaviours: + <ul> + <li> No early <tt>runleveld</tt> service is created. Changing +runlevels via +<a href="s6-linux-init-telinit.html">s6-linux-init-telinit</a> +will be unsupported in a container. </li> + <li> Consequently, the first argument to the <tt>rc.init</tt> script +will always be <tt>default</tt> (or <em>initdefault</em> if the <tt>-D</tt> +option has been given to <tt>s6-linux-init-maker</tt>). The rest of the +arguments to the <tt>rc.init</tt> script will be the arguments given +to the <tt>init</tt> program when running the container. </li> + <li> If the <tt>-s</tt> option has been given, <em>env_store</em> +will contain the initial environment given to the container. </li> + <li> The ultimate output fallback (i.e. the place where error messages +go when nothing catches them, e.g. the error messages from the catch-all +logger and the +<a href="//skarnet.org/software/s6/s6-supervise.html">s6-supervise</a> +process managing the catch-all logger) is not <tt>/dev/console</tt>, but +the descriptor that was <tt>init</tt>'s standard error. </li> + <li> Stopping the container with <tt>reboot</tt> will make the +container's init program report being killed by a SIGHUP. Stopping it +with <tt>poweroff</tt> will make it report being killed by a SIGINT. +(This is according to the +<a href="http://man7.org/linux/man-pages/man2/reboot.2.html">reboot(2)</a> +specification. </li> + <li> Stopping the container with <tt>halt</tt>, however, is different. +It will make the container's pid 1 read a number in the +<tt>/run/s6-linux-init-container-results/exitcode</tt> file (the +<tt>/run</tt> prefix can be changed at build time via the <tt>--tmpfsdir</tt> +configure option), and exit with the code it has read. (Default is 0.) +This means that in order to run a command in a container managed by +s6-linux-init and exit the container when the command dies while reporting +the exit code to its parent, you should: + <ul> + <li> Run that command via <tt>rc.init</tt> </li> + <li> Store its exit code in the +<tt>/run/s6-linux-init-container-results/exitcode</tt> file </li> + <li> Call <tt>halt</tt> </li> + </ul> + All the running services will be killed, all the zombies will be +reaped, and the container will exit with the required exit code. </li> + </ul> </li> + + <li> <tt>-B</tt> : run the system without a catch-all logger. +On a non-containerized system, that means that all the logs from the +s6 supervision tree will go to <tt>/dev/console</tt>, and that +<tt>/dev/console</tt> will also be the default stdout and stderr for +services running under the supervision tree: use of this option is +discouraged. On a containerized system (when paired with the <tt>-C</tt> +option), it simply means that these outputs go to the default stdout and +stderr given to the container's <tt>init</tt> - this should generally +not be the default, but might be useful in some cases. </li> </ul> <h2> Organization of the created directory </h2> @@ -349,7 +413,8 @@ subdirectories it contains are the following: <li> <tt>uncaught-logs</tt>: 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. </li> +their own logs. Not present if the <tt>-B</tt> option has been +given. </li> <li> <tt>service</tt>: <tt>/run/service</tt> will be the scandir. It initially contains a <tt>.s6-svscan</tt> subdirectory that tells <a href="//skarnet.org/software/s6/s6-svscan.html">s6-svscan</a> @@ -359,24 +424,26 @@ also contains a list of early services, i.e. s6 services that will be run at boot time as soon as <tt>s6-svscan</tt> is executed. These services are: <ul> - <li> <tt>s6-svscan-log</tt>: the catch-all logger. </li> + <li> <tt>s6-svscan-log</tt>: the catch-all logger. Not present +if the <tt>-B</tt> option has been given. </li> <li> <tt>s6-linux-init-shutdownd</tt>: a service that listens to shutdown commands such as <tt>reboot</tt> and triggers the software shutdown procedure. </li> <li> <tt>s6-linux-init-runleveld</tt>: a service that listens to runlevel change commands such as <tt>telinit</tt> and calls the <em>runlevel</em> script in a reproducible environment to bring the -machine to the wanted state. </li> - <li> (If the <tt>-L</tt> option has been given to -<tt>s6-linux-init-maker</tt>) <tt>s6-linux-init-logouthookd</tt>: +machine to the wanted state. Not present if the <tt>-C</tt> option +has been given. </li> + <li> <tt>s6-linux-init-logouthookd</tt>: the "clean up user utmp records at logout time" service. See the <a href="s6-linux-init-logouthookd.html">s6-linux-init-logouthookd</a> -page for details. </li> - <li> (If the <tt>-G</tt> option has been given to -<tt>s6-linux-init-maker</tt>) <tt>s6-linux-init-early-getty</tt>: +page for details. Not present if the <tt>-L</tt> option has not been +given. </li> + <li> <tt>s6-linux-init-early-getty</tt>: the early getty service, that will allow a user to log in even if <em>rc.init</em> fails to bring the machine to a state where logins -are possible. </li> +are possible. Not present if the <tt>-G</tt> option has not been +given. </li> </ul> </li> </ul> </li> </ul> @@ -400,7 +467,9 @@ providing secure utmp functionality. </li> <p> A directory created by <tt>s6-linux-init-maker</tt> is only valid on the machine it has been created on. Pre-creating init directories for -other machines is not supported. +other machines is not supported. Of course, the scripts are editable, +so advanced users can run <tt>s6-linux-init-maker</tt> to create a +basic template, and then make their own modifications. </p> <p> @@ -430,22 +499,19 @@ 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 <tt>reboot</tt> needs an ad-hoc implementation. </li> + <li> Even for simple systems such as containerized ones, making +sure that the wanted commands only run when s6-svscan is ready +requires a bit of manipulation. </li> </ul> <p> The main benefit of <tt>s6-linux-init-maker</tt> is that it offers -transparent compatibility while automating the tricky technical part. -That means that <tt>s6-linux-init-maker</tt> has been designed for -<em>real hardware</em>, 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 <tt>/dev/console</tt> issue, the read-only rootfs issue, -or the need for sysvinit compatibility, -you will probably not reap much benefit from using <tt>s6-linux-init-maker</tt>: -you could probably invoke -<a href="//skarnet.org/software/s6/s6-svscan.html">s6-svscan</a> -directly as your process 1, or build a script by hand, which -would result in a simpler init with less dependencies. +transparent compatibility while automating the tricky technical parts. +Whether it is used for real hardware or for containers, +<tt>s6-linux-init-maker</tt> gives you a turnkey init system that +frees your mind from the details of getting a +<a href="//skarnet.org/software/s6/">s6</a> supervision tree running +prior to everything else. </p> </body> diff --git a/doc/s6-linux-init-shutdownd.html b/doc/s6-linux-init-shutdownd.html index ce03543..a5e92ca 100644 --- a/doc/s6-linux-init-shutdownd.html +++ b/doc/s6-linux-init-shutdownd.html @@ -27,7 +27,7 @@ directly by the user. <h2> Interface </h2> <pre> - s6-linux-init-shutdownd [ -c <em>basedir</em> ] [ -g <em>gracetime</em> ] + s6-linux-init-shutdownd [ -c <em>basedir</em> ] [ -g <em>gracetime</em> ] [ -C ] [ -B ] </pre> <ul> @@ -57,6 +57,15 @@ directory. Default is <tt>/etc/s6-linux-init/current</tt>. </li> <li> <tt>-g <em>gracetime</em></tt> : if the shutdown command does not specify a grace time between the SIGTERM and the SIGKILL, use <em>gracetime</em> milliseconds. Default is 3000. </li> + <li> <tt>-C</tt> : inform the shutdown daemon that it is running +in a container. This changes the nature of <em>stage 4</em>, since +exiting a container is slightly different from rebooting a real machine +(in particular, pid 1 has to exit, and great care must be given not to +leave any zombie hanging around). </li> + <li> <tt>-B</tt> : inform the shutdown daemon that no catch-all +logger is running. This also changes the shutdown procedure slightly, +since some operations are specific to the existence of a catch-all +logger. </li> </ul> <h2> Notes </h2> diff --git a/doc/s6-linux-init-telinit.html b/doc/s6-linux-init-telinit.html index 49862d7..e01b44d 100644 --- a/doc/s6-linux-init-telinit.html +++ b/doc/s6-linux-init-telinit.html @@ -78,6 +78,11 @@ the <tt>bin/</tt> subdirectory of the target will contain a <tt>telinit</tt> symlink to <tt>s6-linux-init-telinit</tt>. The <tt>bin/</tt> subdirectory should be copied by the administrator into <tt>/sbin</tt> for full interface compatibility with sysvinit. </li> + <li> When the system is running inside a container (and the <tt>-C</tt> +option has been given to +<a href="s6-linux-init-maker.html">s6-linux-init-maker</a>), the runleveld +service is not running, so <tt>s6-linux-init-telinit</tt> is not +functional and the <tt>runlevel</tt> script is never invoked. </li> </ul> </body> diff --git a/doc/s6-linux-init.html b/doc/s6-linux-init.html index 184877a..21d97bf 100644 --- a/doc/s6-linux-init.html +++ b/doc/s6-linux-init.html @@ -27,7 +27,7 @@ and execs into <a href="//skarnet.org/software/s6/s6-svscan.html">s6-svscan</a>. <h2> Interface </h2> <pre> - s6-linux-init [ -c <em>basedir</em> ] [ -p <em>initial_path</em> ] [ -s <em>env_store</em> ] [ -m <em>umask</em> ] [ -d <em>slashdev</em> ] [ -D <em>initdefault</em> ] [ -n | -N ] [ <em>args...</em> ] + s6-linux-init [ -c <em>basedir</em> ] [ -p <em>initial_path</em> ] [ -s <em>env_store</em> ] [ -m <em>umask</em> ] [ -d <em>slashdev</em> ] [ -D <em>initdefault</em> ] [ -n | -N ] [ -C ] [ -B ] [ <em>args...</em> ] </pre> <ul> @@ -67,6 +67,19 @@ Default is <tt>default</tt>. </li> <li> <tt>-n</tt> : instead of unmounting <tt>/run</tt> and mounting a tmpfs on it, just remount <tt>/run</tt>. </li> <li> <tt>-N</tt> : do not touch <tt>/run</tt> at all. </li> + <li> <tt>-C</tt> : run in a container. This option modifies a few +of the operations described below, to accommodate running in a container +instead of on real hardware. For instance: it does not scan the command +line for a specific runlevel, it does not trap ctrl-alt-del, and before +anything else it waits for its descriptor 3, if present, to close. +(Docker uses this fd 3 mechanism as synchronization between the Docker +daemon and the container's <tt>init</tt>.) </li> + <li> <tt>-B</tt> : do not run the catch-all logger. This option +removes the catch-all-logger-related operations from the list below; +<tt>s6-linux-init</tt> will not redirect output descriptors, and will +use a different synchronization mechanism to ensure <tt>rc.init</tt> +only runs when <a href="//skarnet.org/software/s6/s6-svscan.html">s6-svscan</a> +is ready. </li> </ul> <h2> Early preparation </h2> @@ -107,6 +120,7 @@ it uses <em>initdefault</em>. </li> <li> The child blocks until the catch-all logger runs. </li> </ul> </li> <li> It also makes the catch-all logger's fifo its stderr. </li> + <li> It traps the ctrl-alt-del keyboard combination. </li> <li> It execs into <a href="//skarnet.org/software/s6/s6-svscan.html">s6-svscan</a> with <tt>/run/service</tt> as its scandir (or <em>tmpfsdir</em>/service). </li> <ul> diff --git a/doc/upgrade.html b/doc/upgrade.html index 0331011..5bc518a 100644 --- a/doc/upgrade.html +++ b/doc/upgrade.html @@ -18,6 +18,27 @@ <h1> What has changed in s6-linux-init </h1> +<h2> in 1.0.4.0 </h2> + +<ul> + <li> <a href="//skarnet.org/software/execline/">execline</a> +dependency bumped to 2.6.0.0. </li> + <li> <a href="//skarnet.org/software/s6/">s6</a> +dependency bumped to 2.9.1.0. </li> + <li> New <tt>-n</tt> option to +<a href="s6-linux-init-hpr.html">s6-linux-init-hpr</a>, to +disable the <tt>sync()</tt> call before the hardware reboot or +power off. </li> + <li> New options added to +<a href="s6-linux-init-maker.html">s6-linux-init-maker</a> and +impacted binaries (<a href="s6-linux-init.html">s6-linux-init</a> +and <a href="s6-linux-init-shutdownd.html">s6-linux-init-shutdownd</a>): + <ul> + <li> <tt>-C</tt>: to boot a s6-based system in a container </li> + <li> <tt>-B</tt>: to disable the catch-all logger </li> + </ul> </li> +</ul> + <h2> in 1.0.3.1 </h2> <ul> |