Add -C and -B options, prepare for 1.0.4.0

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>&nbsp;: 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>&nbsp;: 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&nbsp;<em>gracetime</em></tt>&nbsp;: 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>&nbsp;: 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>&nbsp;: 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>&nbsp;: instead of unmounting <tt>/run</tt> and mounting
 a tmpfs on it, just remount <tt>/run</tt>. </li>
  <li> <tt>-N</tt>&nbsp;: do not touch <tt>/run</tt> at all. </li>
+ <li> <tt>-C</tt>&nbsp;: 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>&nbsp;: 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>:&nbsp;to boot a s6-based system in a container </li>
+   <li> <tt>-B</tt>:&nbsp;to disable the catch-all logger </li>
+  </ul> </li>
+</ul>
+
 <h2> in 1.0.3.1 </h2>
 
 <ul>