diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/index.html | 102 | ||||
| -rw-r--r-- | doc/overview.html | 149 | ||||
| -rw-r--r-- | doc/quickstart.html | 178 | ||||
| -rw-r--r-- | doc/s6-halt.html | 55 | ||||
| -rw-r--r-- | doc/s6-linux-init-echo.html | 69 | ||||
| -rw-r--r-- | doc/s6-linux-init-hpr.html | 80 | ||||
| -rw-r--r-- | doc/s6-linux-init-logouthookd.html | 98 | ||||
| -rw-r--r-- | doc/s6-linux-init-maker.html | 558 | ||||
| -rw-r--r-- | doc/s6-linux-init-shutdown.html | 103 | ||||
| -rw-r--r-- | doc/s6-linux-init-shutdownd.html | 72 | ||||
| -rw-r--r-- | doc/s6-linux-init-telinit.html | 84 | ||||
| -rw-r--r-- | doc/s6-linux-init-umountall.html | 68 | ||||
| -rw-r--r-- | doc/s6-linux-init.html | 164 | ||||
| -rw-r--r-- | doc/s6-poweroff.html | 55 | ||||
| -rw-r--r-- | doc/s6-reboot.html | 55 | ||||
| -rw-r--r-- | doc/upgrade.html | 12 | ||||
| -rw-r--r-- | doc/why.html | 139 |
17 files changed, 1413 insertions, 628 deletions
diff --git a/doc/index.html b/doc/index.html index 41c7139..83464df 100644 --- a/doc/index.html +++ b/doc/index.html @@ -20,26 +20,48 @@ <h2> What is it ? </h2> <p> - s6-linux-init is a set of minimalistic tools to create a + s6-linux-init is a set of minimalistic tools used to create a <a href="//skarnet.org/software/s6/">s6</a>-based init system, including a <tt>/sbin/init</tt> binary, on a Linux kernel. </p> <p> - s6-linux-init is meant to automate creation of scripts revolving -around the use of other skarnet.org tools, especially s6, in order -to provide a complete booting environment with integrated supervision -and logging without having to hand-craft all the details. + The resulting architecture follows the Unix philosophy (one job → +one tool) as closely as possible, and is fully dedicated to the s6 way of +managing a system: </p> +<ul> + <li> <a href="//skarnet.org/software/s6/s6-svscan.html">s6-svscan</a> +runs as process 1 for the whole machine lifetime. </li> + <li> Every daemon is supervised. </li> + <li> No logs are ever lost. </li> + <li> Policy is entirely left to the user. Typically, <em>any</em> service manager +can be run on top of s6-linux-init. </li> +</ul> + <p> - Please read the documentation for the -<a href="s6-linux-init-maker.html">s6-linux-init-maker</a> program -carefully, but if you're impatient, you can also read this -<a href="quickstart.html">quickstart guide</a>, which includes -a small FAQ. + Nevertheless, the architecture is fully compliant with various +empirical and historical specifications. For instance, it provides: </p> +<ul> + <li> utmp management compatible with sysvinit </li> + <li> runlevel management, with a configurable default, overridable from the +kernel command line </li> + <li> sysvinit-like commands to shut the system down, including a +<tt>shutdown</tt> command that follows the +<a href="http://refspecs.linuxbase.org/LSB_3.0.0/LSB-PDA/LSB-PDA/shutdown.html">LSB specification</a> </li> +</ul> + +<hr /> + +<ul> + <li> <a href="why.html">Why</a> s6-linux-init ? </li> + <li> <a href="overview.html">An overview</a> of s6-linux-init </li> + <li> <a href="quickstart.html">A quickstart guide</a> for the impatient </li> +</ul> + <hr /> <h2> Installation </h2> @@ -50,30 +72,31 @@ a small FAQ. <li> A Linux-based system with a standard C development environment </li> <li> GNU make, version 3.81 or later </li> <li> <a href="//skarnet.org/software/skalibs/">skalibs</a> version -2.8.0.0 or later </li> +2.8.0.1 or later </li> <li> <a href="//skarnet.org/software/execline/">execline</a> version 2.5.1.0 or later </li> - <li> <a href="//skarnet.org/software/s6-portable-utils/">s6-portable-utils</a> version -2.2.1.3 or later </li> - <li> <a href="//skarnet.org/software/s6-linux-utils/">s6-linux-utils</a> version -2.5.0.1 or later </li> <li> <a href="//skarnet.org/software/s6/">s6</a> version 2.8.0.0 or later </li> </ul> <p> -When you <em>build</em> s6-linux-init, the - <a href="s6-linux-init-maker.html">s6-linux-init-maker</a> tool -is created (as well as the shutdown commands); - then you <em>run</em> that tool to create an init script, -and then you can <em>boot</em> your system on that init script. + The following optional dependencies are also supported: </p> +<ul> + <li> If you're using <a href="https://www.musl-libc.org/">musl</a> and +want nsswitch-like functionality: +<a href="//skarnet.org/software/nsss/">nsss</a> version +0.0.1.1 or later </li> + <li> If you want secure utmp functionality: +<a href="//skarnet.org/software/utmps/">utmps</a> version +0.0.2.1 or later </li> +</ul> + <p> - skalibs is a <em>build-time</em> dependency. If you are linking binaries -against the shared version of the skalibs library, it also becomes a -<em>run-time</em> and <em>boot-time</em> dependency. <br /> - All the other listed packages are <em>boot-time</em> dependencies only. + All those dependencies are <em>build-time</em> and <em>run-time</em>, +except possibly skalibs, which is not needed at run time if you are linking +all the other packages against the <em>static</em> version of libskarnet. </p> <h3> Licensing </h3> @@ -87,7 +110,7 @@ against the shared version of the skalibs library, it also becomes a <ul> <li> The current released version of s6-linux-init is -<a href="s6-linux-init-0.4.0.1.tar.gz">0.4.0.1</a>. </li> +<a href="s6-linux-init-1.0.0.0.tar.gz">1.0.0.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>: @@ -114,25 +137,42 @@ the previous versions of s6-linux-init and the current one. </li> <h2> Reference </h2> +<h3> General </h3> + +<ul> + <li> A <a href="why.html">rationale</a> for this package </li> + <li> An <a href="overview.html">overview</a> of s6-linux-init </li> + <li> A <a href="quickstart.html">quickstart page</a> </li> +</ul> + <h3> Commands </h3> <p> - All these commands exit 111 if they encounter a temporary error, and -100 if they encounter a permanent error - such as a misuse. + Unless more details are provided in an <em>Exit codes</em> section +of a specific page, all these commands exit 0 on success, 111 if they encounter a +temporary error (such as a system call failure) and 100 if they encounter a +permanent error (such as a misuse). </p> <ul> <li><a href="s6-linux-init-maker.html">The <tt>s6-linux-init-maker</tt> program</a></li> -<li><a href="s6-halt.html">The <tt>s6-halt</tt> program</a></li> -<li><a href="s6-poweroff.html">The <tt>s6-poweroff</tt> program</a></li> -<li><a href="s6-reboot.html">The <tt>s6-reboot</tt> program</a></li> +<li><a href="s6-linux-init.html">The <tt>s6-linux-init</tt> program</a></li> +<li><a href="s6-linux-init-hpr.html">The <tt>s6-linux-init-hpr</tt> program</a></li> +<li><a href="s6-linux-init-shutdown.html">The <tt>s6-linux-init-shutdown</tt> program</a></li> +<li><a href="s6-linux-init-shutdownd.html">The <tt>s6-linux-init-shutdownd</tt> program</a></li> +<li><a href="s6-linux-init-telinit.html">The <tt>s6-linux-init-telinit</tt> program</a></li> +<li><a href="s6-linux-init-logouthookd.html">The <tt>s6-linux-init-logouthookd</tt> program</a></li> +<li><a href="s6-linux-init-echo.html">The <tt>s6-linux-init-echo</tt> program</a></li> +<li><a href="s6-linux-init-umountall.html">The <tt>s6-linux-init-umountall</tt> program</a></li> </ul> <h2> Related resources </h2> <ul> <li> <tt>s6-linux-init</tt> is discussed on the -<a href="//skarnet.org/lists.html#skaware">skaware</a> mailing-list. </li> +<a href="//skarnet.org/lists.html#skaware">skaware</a> and +<a href="//skarnet.org/lists.html#supervision">supervision</a> +mailing-lists. </li> <li> There is a <tt>#s6</tt> IRC channel on Freenode. Sometimes people are there and even answer questions. </li> </ul> diff --git a/doc/overview.html b/doc/overview.html new file mode 100644 index 0000000..8f19bcd --- /dev/null +++ b/doc/overview.html @@ -0,0 +1,149 @@ +<html> + <head> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>s6-linux-init: overview</title> + <meta name="Description" content="s6-linux-init: overview" /> + <meta name="Keywords" content="s6-linux-init overview architecture design" /> + <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> + </head> +<body> + +<p> +<a href="index.html">s6-linux-init</a><br /> +<a href="//skarnet.org/software/">Software</a><br /> +<a href="//skarnet.org/">skarnet.org</a> +</p> + +<h1> An overview of s6-linux-init </h1> + +<h2> Organisation of the package </h2> + +<p> + When installed, the <tt>s6-linux-init</tt> package provides the +following: +</p> + +<ul> + <li> <em>Binaries</em>, that are typically installed in <tt>/bin</tt>: + <ul> + <li> <a href="s6-linux-init-maker.html">s6-linux-init-maker</a> is the main +program of the package and is used to create <tt>/sbin/init</tt> scripts +and their supporting environment depending on configuration parameters +given on its command line. </li> + <li> <a href="s6-linux-init-hpr.html">s6-linux-init-hpr</a> is an +implementation of the SysV <tt>halt</tt>, <tt>poweroff</tt> and <tt>reboot</tt> +commands; <a href="s6-linux-init-telinit.html">s6-linux-init-telinit</a> +is an implementation of the SysV <tt>telinit</tt> command; and + <a href="s6-linux-init-shutdown.html">s6-linux-init-shutdown</a> +is an implementation of the +<a href="http://refspecs.linuxbase.org/LSB_3.0.0/LSB-PDA/LSB-PDA/shutdown.html">shutdown</a> +command. <a href="s6-linux-init.html">s6-linux-init</a> is an +implementation of stage 1 <tt>/sbin/init</tt>, but it needs to be +given command-line options in order to do what the user has chosen. +An invocation of <a href="s6-linux-init-maker.html">s6-linux-init-maker</a> +will create proper wrappers for all those commands, named after their +short SysV names; the wrappers are directly usable as turnkey replacements +for SysV commands. </li> + <li> Other binaries are support binaries, not meant to be called +directly by the user. They are called internally, in scripts +created by a +<a href="s6-linux-init-maker.html">s6-linux-init-maker</a> invocation - +typically in run scripts for early services. </li> + </ul> </li> <p /> + + <li> A <em>small library</em>, that for now contains a single symbol, +<tt>s6_linux_init_logouthook()</tt>, intended for distributions using +<tt>login</tt> programs that add utmp entries for users logging in and +expect <tt>init</tt> to clean up after them when users log out. See +the <a href="s6-linux-init-logouthookd.html">s6-linux-init-logouthookd</a> +page for details. </li> <p /> + + <li> <em>Skeleton scripts</em>, installed by default in +<tt>/etc/s6-linux-init/skel</tt>; that location can be changed at build +time via the <tt>--skeldir</tt> configure option. At +<tt>s6-linux-init-maker</tt> invocation time, the scripts are copied from the skeleton +directory to the <tt>scripts</tt> subdirectory of the directory created +by <tt>s6-linux-init-maker</tt>, and the copy is meant to be edited +by the user. The skeleton scripts are commented and examples of +interaction with various service manager are given; it is recommended +to review them, and possibly edit them too. +These scripts are the following: + <ul> + <li> <em>rc.init</em>: the script launching the system initialization +procedure once stage 1 init is done and +<a href="//skarnet.org/software/s6/s6-svscan.html">s6-svscan</a> is +safely running as pid 1. </li> + <li> <em>rc.shutdown</em>: the script launching the system shutdown +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> + </ul> </li> +</ul> + +<h2> Organisation of the booted system </h2> + +<p> + When a system has booted on an <tt>/sbin/init</tt> program created by +<a href="s6-linux-init-maker.html">s6-linux-init-maker</a>, the following +invariants are met: +</p> + +<ul> + <li> A tmpfs is mounted on <tt>/run</tt> - that location can be changed +at build-time via the <tt>--tmpfsdir</tt> option to configure. The rest +of this document assumes it is <tt>/run</tt>. </li> + <li> <a href="//skarnet.org/software/s6/s6-svscan.html">s6-svscan</a> is +running as pid 1 on the <tt>/run/service</tt> scandir. </li> + <li> Every process on the system is running with at least the environment +defined in the <tt>/etc/s6-linux-init/current/env</tt> envdir. The +<tt>/etc/s6-linux-init/current</tt> location can be changed at +<a href="s6-linux-init-maker.html">s6-linux-init-maker</a> invocation time +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: + <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-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 +utmp record cleanup duty for patched <tt>login</tt> programs. </li> + <li> (optionally) <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 +utmp and wtmp access when <a href="//skarnet.org/software/utmps/">utmps</a> is +used. </li> + </ul> </li> +</ul> + + <h2> Integration with the service manager </h2> + +<p> + The s6-linux-init package's duties stop where the service manager's start. +s6-linux-init simply brings the system up to the point where it is stable and +operational enough for the service manager to take over; and at shutdown +time, s6-linux-init just tells the service manager to bring down the services, +and then performs the last steps of the shutdown: killing all the remaining +processes, unmounting the file systems and halting/powering off/rebooting +the machine. +</p> + +<p> + All the interactions between s6-linux-init and the service manager are +configurable: they happen in the <em>rc.init</em>, <em>rc.shutdown</em> +and <em>runlevel</em> scripts. Examples are provided in the skeleton +scripts, that you should review and edit. +</p> + +</body> +</html> diff --git a/doc/quickstart.html b/doc/quickstart.html index 6a0069b..b214443 100644 --- a/doc/quickstart.html +++ b/doc/quickstart.html @@ -3,9 +3,9 @@ <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> <meta http-equiv="Content-Language" content="en" /> - <title>s6-linux-init: quickstart and FAQ</title> - <meta name="Description" content="s6-linux-init: quickstart and FAQ" /> - <meta name="Keywords" content="s6-linux-init installation quickstart faq" /> + <title>s6-linux-init: quickstart</title> + <meta name="Description" content="s6-linux-init: quickstart" /> + <meta name="Keywords" content="s6-linux-init installation quickstart quick start" /> <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> </head> <body> @@ -16,7 +16,7 @@ <a href="//skarnet.org/">skarnet.org</a> </p> -<h1> Quickstart and FAQ for s6-linux-init </h1> +<h1> Quickstart for s6-linux-init </h1> <h2> Quickstart </h2> @@ -25,175 +25,27 @@ <ul> <li> <a href="//skarnet.org/software/skalibs/">skalibs</a> </li> <li> <a href="//skarnet.org/software/execline/">execline</a> </li> - <li> <a href="//skarnet.org/software/s6-portable-utils/">s6-portable-utils</a> </li> - <li> <a href="//skarnet.org/software/s6-linux-utils/">s6-linux-utils</a> </li> <li> <a href="//skarnet.org/software/s6/">s6</a> </li> </ul> </li> - <li> Install <a href="index.html">s6-linux-init</a> itself. </li> - <li> Save your old <tt>/sbin/init</tt> binary. </li> <li> Save and remove your old <tt>/etc/s6-linux-init</tt> directory, if you have one. </li> + <li> Install <a href="index.html">s6-linux-init</a> itself. </li> + <li> Save your old <tt>/sbin/init</tt>, <tt>/sbin/telinit</tt>, <tt>/sbin/shutdown</tt>, +<tt>/sbin/halt</tt>, <tt>/sbin/poweroff</tt> and <tt>/sbin/reboot</tt> binaries. </li> <li> Make sure you have a <tt>/run</tt> directory. </li> - <li> Write a machine initialization script in <tt>/etc/rc.init</tt> and -a machine shutdown script in <tt>/etc/rc.shutdown</tt>. Make sure they are -executable. See below for more information on how to write these scripts. </li> + <li> Edit the scripts in <tt>/etc/s6-linux-init/skel</tt>. </li> <li> Check that your devtmpfs is automounted by your kernel at boot time. If it is not, add the <tt>-d 1</tt> option to the <tt>s6-linux-init-maker</tt> command line below. </li> <li> As root, run: <pre> - rm -rf /tmp/s6-linux-init /tmp/init - s6-linux-init-maker /tmp/s6-linux-init - mv /tmp/s6-linux-init /etc/ - ln -sf /etc/s6-linux-init/init /sbin/init </pre> </li> + rm -rf /tmp/blah + s6-linux-init-maker -1 -G "/sbin/getty 38400 tty1" /tmp/blah + rm -rf /etc/s6-linux-init/current + mv /tmp/blah /etc/s6-linux-init/current + cp -a /etc/s6-linux-init/current/bin/* /sbin/ </pre> </li> <li> Reboot. </li> <li> Congratulations! your machine is now running a s6-based init system. </li> - <li> To shut the machine down, use the -<a href="s6-halt.html">s6-halt</a>, -<a href="s6-poweroff.html">s6-poweroff</a> or -<a href="s6-reboot.html">s6-reboot</a> command as appropriate. </li> + <li> To shut the machine down, use <tt>/sbin/shutdown</tt>, <tt>/sbin/halt</tt>, +<tt>/sbin/poweroff</tt> or <tt>/sbin/reboot</tt> as usual. </li> </ol> -<h3> What should go into <tt>/etc/rc.init</tt> and <tt>/etc/rc.shutdown</tt> ? </h3> - -<h4> <tt>/etc/rc.init</tt> </h4> - -<p> - This script will be run after s6-linux-init has done is job, i.e. -<a href="//skarnet.org/software/s6/">s6-svscan</a> is running as process 1, and it -is now up to <tt>/etc/rc.init</tt> to get the machine to its usable state. -It normally contains a call to the service manager to bring up all the services; -for instance, if you're using -<a href="//skarnet.org/software/s6-rc/">s6-rc</a> as your service manager, and -your top bundle (containing all the services you want to bring up) is named -<tt>ok-all</tt>, a proper <tt>/etc/rc.init</tt> could look like this: -</p> - -<pre>#!/bin/sh -s6-rc-init /run/service && exec s6-rc -u change ok-all -</pre> - -<p> - The script can assume that: -</p> - -<ul> - <li> There is a tmpfs partition, only writable by root, mounted on <tt>/run</tt> </li> - <li> There is a <a href="//skarnet.org/software/s6/">s6</a> supervision tree -running on <tt>/run/service</tt> </li> - <li> <tt>/dev</tt> is mounted, but <tt>/proc</tt> and <tt>/sys</tt> are not </li> -</ul> - -<h4> <tt>/etc/rc.shutdown</tt> </h4> - -<p> - This script is spawned by <a href="//skarnet.org/software/s6/">s6-svscan</a> -when the administrator calls <a href="s6-halt.html">s6-halt</a>, -<a href="s6-poweroff.html">s6-poweroff</a> or -<a href="s6-reboot.html">s6-reboot</a>. When this script exits, the final -shutdown sequence is run, which means that the supervision tree is dismantled, -all processes are killed, the file systems are umounted and the system -undergoes a hardware shutdown or reboot. So the goal of this script is to -bring services down in an orderly fashion and perform all the necessary -cleanups before all remaining processes are summarily killed. -</p> - -<p> - If you're using <a href="//skarnet.org/software/s6-rc/">s6-rc</a> as your -service manager, a proper <tt>/etc/rc.shutdown</tt> could look like this: -</p> - -<pre>#!/bin/sh -exec s6-rc -da change -</pre> - -<h2> FAQ </h2> - -<h4> Why is it so complicated to use s6 as an init process? It's much -simpler with runit. </h4> - -<p> - Yes, runit is simpler, because it provides a simple -<a href="http://smarden.org/runit/runit.8.html">runit</a> binary -suitable as a <tt>/sbin/init</tt> program and calls scripts to -handle the three stages of init. However, the runit design has a -few perfectible points: -</p> - -<ul> - <li> The one-time initialization is performed in <tt>/etc/runit/1</tt>, but -the supervision tree is not run until <tt>/etc/runit/2</tt>, which means -means that it is impossible to start supervised services during the -one-time initialization. Early daemons such as <tt>udevd</tt>, for -instance, have to remain unsupervised. </li> - <li> runit runs with its descriptors pointing to <tt>/dev/console</tt>, -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. </li> - <li> 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 <tt>ps afuxww</tt> on a runit-based system. -Yes, this point is extremely minor, but still deserves a mention. :-) </li> -</ul> - -<p> - Running a s6-based init addresses those issues: -</p> - -<ul> - <li> Save for the initial tmpfs mount, <em>all</em> of the machine -initialization runs in the stage 2 script, i.e. <tt>/etc/rc.init</tt>, -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. </li> - <li> 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 <em>only</em> -exception is error messages from the catch-all logger process itself: -those naturally go to <tt>/dev/console</tt>. </li> - <li> When s6-svscan runs as process 1, the supervision tree is of -height 2, and <tt>ps afuxww</tt> looks clean. </li> -</ul> - -<p> - 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. -</p> - -<h4> My <tt>/etc/rc.init</tt> script is not printing anything! </h4> - -<p> - You probably gave the <tt>-r</tt> option to -<a href="s6-linux-init-maker.html">s6-linux-init-maker</a>, and -your <tt>/etc/rc.init</tt>'s output is being logged into the -<tt>/run/uncaught-logs</tt> directory instead of printed to -<tt>/dev/console</tt>. -</p> - -<h4> I want to run s6 in a container, and I just want to log -to stdout/stderr, without this tmpfs and <tt>/dev/console</tt> -stuff and -without having a catch-all logger inside the container. Is it -possible ? </h4> - -<p> - 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! -</p> - -<p> - If you are using -<a href="https://www.docker.com/">Docker</a>, there is a -<a href="https://github.com/just-containers/s6-overlay">s6-overlay</a> -project specifically made for integrating s6 into Docker images. -</p> - </body> </html> diff --git a/doc/s6-halt.html b/doc/s6-halt.html deleted file mode 100644 index 6f2a30e..0000000 --- a/doc/s6-halt.html +++ /dev/null @@ -1,55 +0,0 @@ -<html> - <head> - <meta name="viewport" content="width=device-width, initial-scale=1.0" /> - <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> - <meta http-equiv="Content-Language" content="en" /> - <title>s6-linux-init: the s6-halt program</title> - <meta name="Description" content="s6-linux-init: the s6-halt program" /> - <meta name="Keywords" content="s6 linux init administration root utilities shutdown halt poweroff reboot" /> - <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> - </head> -<body> - -<p> -<a href="index.html">s6-linux-init</a><br /> -<a href="//skarnet.org/software/">Software</a><br /> -<a href="//skarnet.org/">skarnet.org</a> -</p> - -<h1> The <tt>s6-halt</tt> program </h1> - -<p> -<tt>s6-halt</tt> sends a signal to process 1 in order to halt the machine; -or, with the <tt>-f</tt> option, it performs an immediate hard shutdown. -</p> - -<h2> Interface </h2> - -<pre> - s6-halt [ -h | -p | -r ] [ -f ] -</pre> - -<ul> - <li> s6-halt sends a signal to process 1. </li> - <li> It then exits 0. </li> -</ul> - -<h2> Options </h2> - -<ul> - <li> <tt>-h</tt> : halt. The command will order a halt (i.e. the system will -be shut down, but the power will remain up), which means -sending a SIGUSR2 to process 1. This is the default. </li> - <li> <tt>-p</tt> : poweroff. The command will order a power off, which means -sending a SIGUSR1 to process 1. </li> - <li> <tt>-r</tt> : reboot. The command will order a reboot, which means -sending a SIGINT to process 1. </li> - <li> <tt>-f</tt> : force. The command will not send any signal to process 1; -it will just sync the filesystems then tell the kernel to halt, poweroff or reboot. -<tt>s6-reboot -f</tt> or <tt>s6-poweroff -f</tt> should be the last program -executed in the lifetime of a machine, at the end of the shutdown script called -by process 1 when it receives a signal telling it to shut down. </li> -</ul> - -</body> -</html> diff --git a/doc/s6-linux-init-echo.html b/doc/s6-linux-init-echo.html new file mode 100644 index 0000000..837eab0 --- /dev/null +++ b/doc/s6-linux-init-echo.html @@ -0,0 +1,69 @@ +<html> + <head> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>s6-linux-init: the s6-linux-init-echo program</title> + <meta name="Description" content="s6-linux-init: the s6-linux-init-echo program" /> + <meta name="Keywords" content="s6-linux-init command s6-linux-init-echo echo" /> + <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> + </head> +<body> + +<p> +<a href="index.html">s6-linux-init</a><br /> +<a href="//skarnet.org/software/">Software</a><br /> +<a href="//skarnet.org/">skarnet.org</a> +</p> + +<h1> The <tt>s6-linux-init-echo</tt> program </h1> + +<p> + s6-linux-init-echo writes its arguments to stdout. +</p> + +<h2> Interface </h2> + +<pre> + s6-linux-init-echo [ -n ] [ -s sep ] <em>args...</em> +</pre> + +<p> + s6-linux-init-echo writes its arguments <em>args</em> to stdout, separated with spaces. +</p> + +<h2> Options </h2> + +<ul> + <li> <tt>-n</tt> : do not output a trailing newline. </li> + <li> <tt>-s</tt> <em>sep</em> : separate arguments with the <em>sep</em> +character instead of a space. </li> +</ul> + +<h2> Notes </h2> + +<ul> + <li> Strange, and appalling, as it may seem for such a simple task, there is +no way to ensure that the <tt>echo</tt> program will behave consistently from +Unix system to Unix system - and even from Linux distribution to Linux +distribution. Despite there being a +<a href="//pubs.opengroup.org/onlinepubs/9699919799/utilities/echo.html">standard</a> +for it, the <tt>echo</tt> commands in GNU coreutils, busybox, toybox, sbase, and +other implementations basically all exhibit different behaviours. Every shell has +a built-in <tt>echo</tt> command, that fails to follow the POSIX standard. <tt>echo</tt> +is the prime example of the consequences of the blatant disregard of early Unices +for cross-system compatibility, and its followup as a turf war between GNU and the +rest of the Linux world. As a distribution-agnostic software developer, it is ironically +impossible to rely on a definite behaviour of the <tt>echo</tt> command on every +supported system, and that is why s6-linux-init provides its own implementation. +Fortunately, it is very easy to do so, with minimal overhead. </li> + <li> This command is an exact duplicate of the +<a href="//skarnet.org/software/s6-portable-utils/s6-echo.html">s6-echo</a> command +provided in the <a href="//skarnet.org/software/s6-portable-utils/">s6-portable-utils</a> +package. It was decided <em>not</em> to have a dependency from s6-linux-init to +s6-portable-utils: that dependency would arguably be a higher cost than the small +amount of code duplication. </li> +</ul> + +</body> +</html> diff --git a/doc/s6-linux-init-hpr.html b/doc/s6-linux-init-hpr.html new file mode 100644 index 0000000..5f09574 --- /dev/null +++ b/doc/s6-linux-init-hpr.html @@ -0,0 +1,80 @@ +<html> + <head> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>s6-linux-init: the s6-linux-init-hpr program</title> + <meta name="Description" content="s6-linux-init: the s6-linux-init-hpr program" /> + <meta name="Keywords" content="s6 linux init administration root utilities shutdown halt poweroff reboot s6-linux-init-hpr" /> + <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> + </head> +<body> + +<p> +<a href="index.html">s6-linux-init</a><br /> +<a href="//skarnet.org/software/">Software</a><br /> +<a href="//skarnet.org/">skarnet.org</a> +</p> + +<h1> The <tt>s6-linux-init-hpr</tt> program </h1> +</h1> + +<p> + <tt>s6-linux-init-hpr</tt> triggers the software shutdown procedure, +or, with the <tt>-f</tt> option, it perform an immediate hardware shutdown. +It is normally invoked through <tt>halt</tt>, <tt>poweroff</tt> or +<tt>reboot</tt> wrappers created by +<a href="s6-linux-init-maker.html">s6-linux-init-maker</a>. +</p> + +<h2> Interface </h2> + +<pre> + s6-linux-init-hpr [ -f ] [ -h | -p | -r ] [ -d | -w ] [ -W ] +</pre> + +<ul> + <li> If the <tt>-f</tt> option is present, the system is stopped or rebooted immediately. </li> + <li> Else, the machine's shutdown procedure is started. + <li> The command exits 0; the shutdown procedure happens asynchronously. </li> +</ul> + +<p> + This interface is the traditional <em>sysvinit</em> interface for the +<tt>halt</tt>, <tt>poweroff</tt> and <tt>reboot</tt> programs. +<tt>s6-linux-init-hpr</tt> must always be called with one of the +<tt>-h</tt>, <tt>-p</tt> or <tt>-r</tt> options. +</p> + +<h2> Options </h2> + +<ul> + <li> <tt>-f</tt> : force. The command will not trigger a clean shutdown +procedure; it will just sync the filesystems then tell the kernel to immediately +halt, poweroff or reboot. This should be the last step in the lifetime of the +machine. </li> + <li> <tt>-h</tt> : halt. The system will be shut down, but the power will remain up. </li> + <li> <tt>-p</tt> : poweroff. The system will be shut down and the power turned off. </li> + <li> <tt>-r</tt> : reboot. The system will reboot. </li> + <li> <tt>-d</tt> : Do not write a wtmp shutdown entry. </li> + <li> <tt>-w</tt> : Only write a wtmp shutdown entry; do not actually shut down +the system. </li> + <li> <tt>-W</tt> : Do not send a <tt>wall</tt> message to users before shutting +down the system. Some other implementations of the <tt>halt</tt>, <tt>poweroff</tt> +and <tt>reboot</tt> commands use the <tt>--no-wall</tt> long option to achieve this. </li> +</ul> + +<h2> Notes </h2> + +<ul> + <li> When an administrator runs +<a href="s6-linux-init-maker.html">s6-linux-init-maker</a>, the resulting +directory has a <tt>bin/</tt> subdirectory that contains <tt>halt</tt>, +<tt>poweroff</tt> and <tt>reboot</tt> scripts that call <tt>s6-linux-init-hpr</tt> +with the relevant option. The +contents of this <tt>bin/</tt> subdirectory should then be copied by the +administrator into <tt>/sbin</tt> for full interface compatibility with sysvinit. </li> +</ul> + +</body> +</html> diff --git a/doc/s6-linux-init-logouthookd.html b/doc/s6-linux-init-logouthookd.html new file mode 100644 index 0000000..088f5d5 --- /dev/null +++ b/doc/s6-linux-init-logouthookd.html @@ -0,0 +1,98 @@ +<html> + <head> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>s6-linux-init: the s6-linux-init-logouthookd program</title> + <meta name="Description" content="s6-linux-init: the s6-linux-init-logouthookd program" /> + <meta name="Keywords" content="s6-linux-init command s6-linux-init-logouthookd login logout utmp hook sysvinit" /> + <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> + </head> +<body> + +<p> +<a href="index.html">s6-linux-init</a><br /> +<a href="//skarnet.org/software/">Software</a><br /> +<a href="//skarnet.org/">skarnet.org</a> +</p> + +<h1> The <tt>s6-linux-init-logouthookd</tt> program </h1> + +<p> + s6-linux-init-logouthookd cleans up its client's utmp record when it dies. +</p> + +<h2> Interface </h2> + +<pre> + s6-ipcserver <em>socket</em> s6-linux-init-logouthookd +</pre> + +<p> + s6-linux-init-logouthookd implements a +<a href="//skarnet.org/software/s6/localservice.html">local service</a> +for getty programs that add an utmp record when a user logs in. +</p> + +<p> + In the sysvinit model, <tt>getty</tt>/<tt>login</tt> and similar programs add an utmp +record for every user that logs in, then exec into the user's shell. +At logout time, the shell dies; sysvinit is supervising the <tt>getty</tt> +program, so it's watching the pid, and respawns the <tt>getty</tt> when the +shell dies. But before respawning the <tt>getty</tt>, it cleans up the +utmp record, to correctly report that the user isn't logged in on this +terminal anymore. +</p> + +<p> + utmp is an old, clunky, insecure system (unless you're using +<a href="//skarnet.org/software/utmps/">utmps</a>) and it is definitely +not pid 1's job to have any knowledge of utmp and play janitor after +<tt>getty</tt>. <a href="//skarnet.org/software/s6/s6-svscan.html">s6-svscan</a> +definitely will not do it. +</p> + +<p> + Some distributions use versions of <tt>login</tt> that fork the user's +shell instead of execing it. When the user logs out, the <tt>login</tt> +program cleans up after itself. This is a better model, but it's not +always easy to patch <tt>login</tt> to go from a "exec the shell" model to a +"fork the shell as a child" model. +</p> + +<p> + <tt>s6-linux-init</tt> comes with a small library which makes it easy +for a distribution to fully support utmp cleanup with an s6 init system +if they so choose. Before execing into the user's shell, the <tt>login</tt> +program should just make a call to <tt>s6_linux_init_logouthook()</tt>, +and that's it. That function will call the <tt>s6-linux-init-logouthookd</tt> +local service, which will do nothing but wait until the user's shell dies; +and when it happens, the user's utmp record will automatically be cleaned up. +</p> + +<h2> Exit codes </h2> + +<p> + <tt>s6-linux-init-logouthookd</tt>'s exit code does not matter, because +no program uses it. However, here's the list for completeness: +</p> + +<ul> + <li> 0: success, whether or not there was an utmp record to clean up. </li> + <li> 1: connection attempt from a non-root user. </li> + <li> 2: write attempt from a (misprogrammed) client. </li> + <li> 111: system call failed. </li> +</ul> + +<h2> Notes </h2> + +<ul> + <li> The <a href="//skarnet.org/software/s6/localservice.html">local service</a> +implementing logouthook support is automatically created at boot time when the +<tt>-L</tt> option has been given to +<a href="s6-linux-init-maker.html">s6-linux-init-maker</a>. Client-side, though, +the various login programs must be patched at the source level. </li> +</ul> + +</body> +</html> diff --git a/doc/s6-linux-init-maker.html b/doc/s6-linux-init-maker.html index 4c0b51d..02fd15d 100644 --- a/doc/s6-linux-init-maker.html +++ b/doc/s6-linux-init-maker.html @@ -21,27 +21,25 @@ <p> <tt>s6-linux-init-maker</tt> 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 +root filesystem. That directory contains +a script that is suitable as an <tt>/sbin/init</tt> program +as well as all the necessary files that this script needs +to properly boot and bring up a full <a href="//skarnet.org/software/s6/">s6</a> -infrastructure running when the system is booted on that -script. +infrastructure. </p> <p> s6-linux-init-maker only writes scripts. At boot time, these scripts will call commands provided by other skarnet.org packages such as -<a href="//skarnet.org/software/execline/">execline</a> or +<a href="//skarnet.org/software/execline/">execline</a> and <a href="//skarnet.org/software/s6/">s6</a>. 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 <em>on the root filesystem of the -machine</em> - else the scripts will crash. -</p> - +correct options have been given to <tt>s6-linux-init-maker</tt> +so that the programs are found <em>on the root filesystem of the +machine</em>. If it is not the case, the system will fail to boot. </p> <h2> Interface and usage </h2> @@ -49,26 +47,26 @@ machine</em> - else the scripts will crash. <pre> s6-linux-init-maker \ [ -c <em>basedir</em> ] \ - [ -l <em>tmpfsdir</em> ] \ - [ -b <em>execline_bindir</em> ] \ - [ -u <em>log_uid</em> -g <em>log_gid</em> | -U ] \ + [ -u <em>log_user</em> ] \ [ -G <em>early_getty</em> ] \ - [ -2 <em>initscript</em> ] \ - [ -r ] \ - [ -Z ] <em>shutdownscript</em> \ + [ -1 ] \ + [ -L ] \ [ -p <em>initial_path</em> ] \ [ -m <em>initial_umask</em> ] \ [ -t <em>timestamp_style</em> ] \ - [ -d <em>dev_style</em> ] \ + [ -d <em>slashdev</em> ] \ [ -s <em>env_store</em> ] \ [ -e <em>initial_envvar</em> ] ... \ - [ -n ] \ - [ -q ] <em>finalsleeptime</em> + [ -q <em>finalsleeptime</em> ] \ + [ -D <em>initdefault</em> ] \ + [ -n | -N ] + [ -U <em>utmp_user</em> ] \ <em>dir</em> </pre> <ul> - <li> s6-linux-init-maker should be run as root. </li> + <li> s6-linux-init-maker must be run as root, on the machine +that will boot an s6-based system. </li> <li> s6-linux-init-maker parses options on its command line. </li> <li> It writes data into a directory <em>dir</em>, which must not exist beforehand. </li> @@ -78,161 +76,72 @@ or its contents. </li> </ul> <p> - <em>dir</em> should then be copied by the administrator to the place -declared as <em>basedir</em>. Be careful: it contains fifos, files with + Once the command has been run and <em>dir</em> has been created, there +are a few manual steps to take: +</p> + +<ol> + <li> <tt>s6-linux-init-maker</tt> has copied some scripts from the +<tt>/etc/s6-linux-init/skel</tt> directory (or the directory you +gave as an argument to the <tt>--skeldir</tt> configure option at +build time) to the <em>dir</em><tt>/scripts</tt> directory. You +should <strong>edit these scripts</strong> and adapt them to your use case. +(Or you could edit the skeleton scripts before running +<tt>s6-linux-init-maker</tt>.) The scripts are: + <ul> + <li> <tt>rc.init</tt>: this script will be run as <em>stage 2 +initialization</em>, i.e. the initialization that happens once +<a href="//skarnet.org/software/s6/s6-svscan.html">s6-svscan</a> +is running as process 1, and should contain all your normal +system bootup tasks. Typically, it should initialize the service +manager and then order it to bring the machine state to its +fully operational state. <em>rc.init</em> is given the default +<em>runlevel</em> as a first argument (i.e. the name of the state +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> + <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 +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> + <li> <tt>runlevel</tt>: this script will be invoked for every +<em>runlevel change</em>, i.e. change of machine states. It is +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> + </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). + 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 <a href="//skarnet.org/software/s6-portable-utils/s6-hiercopy.html">s6-hiercopy</a> -tool can do it, as well as the GNU or busybox <tt>cp -a</tt> or <tt>mv</tt> commands. -</p> - -<p> - The <tt><em>basedir</em>/init</tt> 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 <tt>/sbin/init</tt> to <tt><em>basedir</em>/init</tt>; the -machine will then be ready to boot -</p> +tool can do it, as well as the GNU or busybox <tt>cp -a</tt> or <tt>mv</tt> commands. </li> + <li> Back up your <tt>/sbin</tt>. Then copy, link or symlink all the scripts +and symlinks in the <em>basedir</em><tt>/bin</tt> directory into <tt>/sbin</tt>. + In particular, the <tt><em>basedir</em>/bin/init</tt> script should +be accessible as <tt>/sbin/init</tt>. </li> +</ol> <h2> Boot sequence </h2> <p> - When the kernel boots, it runs the <tt><em>basedir</em>/init</tt> script, -also known as <em>stage 1</em>. and this is what happens: -</p> - -<ul> - <li> <em>stage 1</em> is an -<a href="//skarnet.org/software/execline/">execline</a> script, so -the first process run by the kernel is the -<a href="//skarnet.org/software/execline/execlineb.html">execlineb</a> -program launcher. </li> - <li> <em>stage 1</em> mounts a -<a href="https://www.kernel.org/doc/Documentation/filesystems/tmpfs.txt">tmpfs</a> -filesystem on <em>tmpfsdir</em>. </li> - <li> <em>stage 1</em> copies <tt><em>basedir</em>/run-image</tt> verbatim to -<em>tmpfsdir</em>. </li> - <li> <em>stage 1</em> empties its environment, then reads a global set of environment variables from the -<tt><em>basedir</em>/env</tt> -<a href="//skarnet.org/software/s6/s6-envdir.html">environment directory</a>. </li> - <li> <em>stage 1</em> forks a child that will block until -<a href="//skarnet.org/software/s6/s6-svscan.html">s6-svscan</a> is running. </li> - <li> <em>stage 1</em> executes, as process 1, into -<a href="//skarnet.org/software/s6/s6-svscan.html">s6-svscan</a>, -with <tt><em>tmpfsdir</em>/service</tt> as a -<a href="//skarnet.org/software/s6/scandir.html">scan directory</a>. </li> - <li> This scan directory already contains at least one service, which is the -<em>catch-all logger</em>: error messages from the supervision tree, and -from services that do not have a dedicated logger, are handled by a -special <a href="//skarnet.org/software/s6/s6-log.html">s6-log</a> -instance and made available in <tt><em>tmpfsdir</em>/uncaught-logs</tt> -instead of clogging the system console. </li> - <li> If the <tt>-G</tt> option has been given to s6-linux-init-maker, the -scan directory will also contain a service for an early getty. </li> - <li> s6-svscan starts all the services defined in the scan directory, -and unblocks the child forked by <em>stage 1</em>. </li> - <li> This child executes into <em>initscript</em>. </li> -</ul> - -<p> - <em>initscript</em> is the responsibility of the administrator - it will -not be written automatically! -It should -contain all the necessary initialization sequence to bring up a proper -system. When <em>initscript</em> is executed, the machine state is as follows: -</p> - -<ul> - <li> <em>initscript</em>'s working directory is <tt>/</tt> and its stdin -is <tt>/dev/null</tt>. Its -stdout and stderr both point either to <tt>/dev/console</tt> or to the pipe -to the catch-all logger, depending on the <tt>-r</tt> option. </li> - <li> The system has a valid device directory mounted on <tt>/dev</tt>. </li> - <li> Depending on the kernel boot command line, the root filesystem -may be in read-only mode. </li> - <li> There is a tmpfs available for root only in <em>tmpfsdir</em>. </li> - <li> <a href="//skarnet.org/software/s6/s6-svscan.html">s6-svscan</a> -is running as process 1. At any time, it is possible to make it supervise a long-lived -process by linking the appropriate -<a href="//skarnet.org/software/s6/servicedir.html">service directory</a> -into <tt><em>tmpfsdir</em>/service</tt>, then running the command -<tt>s6-svscanctl -a <em>tmpfsdir</em>/service</tt>. Services without a -dedicated logger will send their output to the catch-all logger. </li> - <li> A getty service may already be available. The point of this early -getty is essentially to make it easier to debug if <em>initscript</em> fails. </li> -</ul> - -<p> - There is <em>nothing else</em>. In particular, no filesystem has been -mounted yet, including <tt>/proc</tt> and <tt>/sys</tt>; and no one-time -initialization -has been performed. The point of <em>stage 1</em> is only to make it -possible to run <em>initscript</em> with a logging infrastructure and a -supervision infrastructure already available, and all the -real machine and service initialization should happen in <em>initscript</em>, -also known as <em>stage 2</em>. -</p> - -<h2> Shutdown sequence </h2> - -<ul> - - <li> A shutdown is performed when the administrator runs one of the -<a href="s6-halt.html">s6-halt</a>, -<a href="s6-poweroff.html">s6-poweroff</a> or -<a href="s6-reboot.html">s6-reboot</a> commands. </li> - - <li> Those commands send a signal to the -<a href="//skarnet.org/software/s6/s6-svscan.html">s6-svscan</a> -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 -<tt><em>basedir</em>/run-image/service/.s6-svscan</tt> directory (and that -has been copied at boot time to <tt><em>tmpfsdir</em>/service/.s6-svscan</tt>). </li> - - <li> That script first spawns the <em>shutdownscript</em> script, who -must have been written by the administrator. The purpose of -<em>shutdownscript</em> is to perform the high-level shutdown sequence -while the supervision tree is still alive. Typically, when using a -service manager, <em>shutdownscript</em> would tell the service manager -to bring all services down. When using -<a href="//skarnet.org/software/s6-rc/">s6-rc</a>, a typical -<em>stage2_finish</em> script just contains <tt>s6-rc -da change</tt>. - More generally speaking, <em>shutdownscript</em> should undo what -<em>stage2</em> has done at boot time. </li> - - <li> The "signal handler" script then tells s6-svscan to exit via an -appropriate <a href="//skarnet.org/software/s6/s6-svscanctl.html">s6-svscanctl</a> -command: s6-svscan then executes into the final shutdown sequence. This -sequence is made of the following actions: - -<ul> - <li> The supervision tree gets torn down. </li> - <li> All data is flushed to disk. </li> - <li> All processes get a SIGTERM, a SIGHUP, and a SIGCONT. This should -allow all processes to die gracefully. Note that most processes should -already have been killed during the <tt>/etc/rc.shutdown</tt> execution; -this phase only catches stragglers, background processs, etc. </li> - <li> The sequence sleeps for <em>finalsleeptime</em> milliseconds, to -allow all processes to finish their clean exit routine. </li> - <li> All processes get a SIGKILL. </li> - <li> All zombies are reaped. </li> - <li> All filesystems get unmounted, and the root filesystem is remounted -read-only. </li> - <li> The machine performs a hardware reboot, halt or poweroff, depending -on the command that has been used. </li> -</ul> </li> - -</ul> - -<p> - The <tt>examples/</tt> subdirectory of the s6-linux-init package -contains an example of <tt>/etc/rc.init</tt> -and <tt>/etc/rc.shutdown</tt> scripts, suitable for -<em>initscript</em> and <em>shutdownscript</em> -respectively. Those scripts can practically be used as is if the machine -is managed by the <a href="//skarnet.org/software/s6-rc/">s6-rc</a> -service manager. + When the kernel boots, it may run an initramfs first, but in any +case it then runs the <tt>/sbin/init</tt> script, +also known as <em>stage 1</em>. This script is just an execution +of the <a href="s6-linux-init.html">s6-linux-init</a> program with +some command-line options that are directly transferred from the +<tt>s6-linux-init-maker</tt> invocation. Refer to the +<a href="s6-linux-init.html">s6-linux-init</a> man page to know +exactly what it does. </p> <h2> s6-linux-init-maker options </h2> @@ -241,88 +150,53 @@ service manager. <li> <tt>-c</tt> <em>basedir</em> : at boot time, <em>stage 1</em>, which should be accessible as <tt><em>basedir</em>/init</tt>, will read its read-only data from <em>basedir</em>. After running -s6-linux-init-maker, the administrator should make sure to copy the +<tt>s6-linux-init-maker</tt>, you should make sure to copy the created directory <em>dir</em> to <em>basedir</em>. <em>basedir</em> must be absolute. Default is -<strong><tt>/etc/s6-linux-init</tt></strong>. </li> <p /> - - <li> <tt>-l</tt> <em>tmpfsdir</em> : at boot time, a tmpfs will -be mounted on <em>tmpfsdir</em>. The directory should already exist in -the root filesystem, and be empty. <em>tmpfsdir</em> must be absolute. Default is -<strong><tt>/run</tt></strong>. </li> <p /> - - <li> <tt>-b</tt> <em>execline_bindir</em> : 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 -<a href="//skarnet.org/software/execline/execlineb.html">execlineb</a> -launcher and the first few early commands before PATH can be set. -<em>execline_bindir</em> is the location where the execline binaries can be -found. It must be absolute. Default is -<strong><tt>/bin</tt></strong>. </li> <p /> - - <li> <tt>-u</tt> <em>log_uid</em> : the catch-all -logger will run with the uid <em>log_uid</em>. Default is 0. </li> <p /> - - <li> <tt>-g</tt> <em>log_gid</em> : the catch-all -logger will run with the gid <em>log_gid</em>. Default is 0. </li> <p /> - - <li> <tt>-U</tt> : the correct <em>log_uid</em> and -<em>log_gid</em> 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 -<tt>s6-envuidgid nobody s6-linux-init-maker -U ...</tt> so that -the catch-all logger runs as the <tt>nobody</tt> user. Be aware that -this option is only safe when the user database on the -<em>boot-time</em> machine is the same as on the <em>run-time</em> -machine, else the catch-all logger may run with an unexpected uid -and gid. </li> <p /> +<strong><tt>/etc/s6-linux-init/current</tt></strong>. </li> <p /> + + <li> <tt>-u</tt> <em>log_user</em> : the catch-all +logger will run as the <em>log_user</em> user. Default is <tt>root</tt>. </li> <p /> <li> <tt>-G</tt> <em>early_getty</em> : if this option -is set, s6-linux-init-maker will define a service that will run -very early, before <em>stage2</em> is executed. This early service -should be a getty, to allow logins even if <em>stage2</em> fails. +is set, <tt>s6-linux-init-maker</tt> will define an additional s6 service +that will be named <tt>s6-linux-init-early-getty</tt> and started +at the same time <em>rc.init</em> is executed. This early service +should be a getty, or equivalent, to allow logins even if <em>stage2</em> fails. <em>early_getty</em> should be a simple command line: for instance, <tt>"/sbin/getty 38400 tty1"</tt>. By default, no early service is defined. </li> <p /> - <li> <tt>-2</tt> <em>initscript</em> : <em>initscript</em> 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 -<strong><tt>/etc/rc.init</tt></strong>. </li> <p /> - - <li> <tt>-r</tt> : redirect. By default, <em>stage2</em> is -run with stdout and stderr pointing to <tt>/dev/console</tt>, so that -users can see what init scripts print. However, it may conflict -with an early getty, or be undesirable for other reasons. The -<tt>-r</tt> option redirects <em>stage2</em>'s stdout and stderr -to the catch-all logger, so the output will be made available -in the <tt><em>tmpfsdir</em>/uncaught-logs</tt> directory. </li> <p /> - - <li> <tt>-Z</tt> <em>shutdownscript</em> : -<em>shutdownscript</em> 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 the final shutdown sequence. It must be -absolute. Default is <strong><tt>/etc/rc.shutdown</tt></strong>. -Note that this script is run with its stdout and stderr -redirected to the <tt><em>tmpfsdir</em>/uncaught-logs</tt> logging -directory, so its output will not appear on the system's console. </li> <p /> - - <li> <tt>-p</tt> <em>initial_path</em> : the value to -set the PATH environment variable to, for all the starting processes. -This will be done as early as possible in <em>stage 1</em>. It is -absolutely necessary for -<a href="//skarnet.org/software/execline/">execline</a>, -<a href="//skarnet.org/software/s6/">s6</a>, -<a href="//skarnet.org/software/s6-portable-utils/">s6-portable-utils</a> and -<a href="//skarnet.org/software/s6-linux-utils/">s6-linux-utils</a> + <li> <tt>-1</tt> : make it so that all the messages that are +sent to the catch-all logger (i.e. all the error messages that are not +caught by a dedicated logger, as well as the output from <em>rc.init</em>, +<em>runlevel</em> and <em>rc.shutdown</em>) +are also copied to <tt>/dev/console</tt>. (Timestamps are not +copied to <tt>/dev/console</tt>.) This is generally useful to +debug a system at a glance, but if a failing program keeps sending +error messages, it may interfere with comfortable usage of an early +getty. A common workaround is to make the early getty start on +<tt>tty2</tt> and leave tty1 for <tt>/dev/console</tt> to print on. </li> <p /> + + <li> <tt>-L</tt> : add an early <tt>s6-linux-init-logouthookd</tt> +service to clean up utmp records at user logout time. Check the +<a href="s6-linux-init-logouthookd">s6-linux-init-logouthookd</a> page +for details. </li> <p /> + + <li> <tt>-p</tt> <em>initial_path</em> : the initial value +for the PATH environment variable, that will be transmitted to all the +starting process unless it's overridden by a PATH declaration via the +<tt>-e</tt> option. +It is absolutely necessary for +<a href="//skarnet.org/software/execline/">execline</a> and +<a href="//skarnet.org/software/s6/">s6</a> binaries to be accessible via <em>initial_path</em>, else the machine will not boot. Default is <strong><tt>/usr/bin:/bin</tt></strong>. </li> <p /> <li> <tt>-m</tt> <em>initial_umask</em> : the value of the initial file umask for all the starting processes, in octal. -Default is -<strong><tt>022</tt></strong>. </li> <p /> +Default is <strong><tt>022</tt></strong>. </li> <p /> <li> <tt>-t</tt> <em>timestamp_style</em> : how logs are timestamped by the catch-all logger. 0 means no @@ -333,44 +207,46 @@ timestamp, 1 means and 3 means both. Default is <strong><tt>1</tt></strong>. </li> <p /> - <li> <tt>-d</tt> <em>dev_style</em> : how <tt>/dev</tt> is -handled on this system. 0 means a static <tt>/dev</tt>, 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 -<strong><tt>2</tt></strong>. </li> <p /> + <li> <tt>-d</tt> <em>slashdev</em> : mount a devtmpfs. +If this option is given, <a href="s6-linux-init.html">s6-linux-init</a> +will mount a devtmpfs pseudo-filesystem on <em>slashdev</em>. This +is useful if the kernel has not been configured to mount +the devtmpfs at boot time and there is no static <tt>/dev</tt>. +By default, it is assumed that there is a suitable <tt>/dev</tt> +at boot time, and no additional devtmpfs is mounted. </li> <p /> <li> <tt>-s</tt> <em>env_store</em> : 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 +inherits a few environment variables from the kernel. (These variables +correspond to the arguments on the kernel command line that are of the +form <em>key=value</em>.) It empties its +environment before spawning <em>rc.init</em> 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 <tt>-s</tt> option -to s6-linux-init-maker makes stage 1 init dump the "kernel" environment -variables into the <em>env_store</em> directory, via the -<a href="//skarnet.org/software/s6-portable-utils/s6-dumpenv.html">s6-dumpenv</a> -program, before erasing them. <em>env_store</em> should obviously be -a writable directory, so it should be located under <em>tmpfsdir</em>! -If this option is not given (which is the default), the environment -inherited from the kernel isn't saved anywhere. </li> <p /> +to <tt>s6-linux-init-maker</tt> makes stage 1 init dump the "kernel" environment +variables into the <em>env_store</em> directory (under a format that is +later readable with +<a href="//skarnet.org/software/s6/s6-envdir.html">s6-envdir -fn</a>) +before erasing them. <em>env_store</em> should obviously be +a writable directory, so it should be located under <tt>/run</tt> +(or your chosen tmpfsdir)! +If this option is not given, the environment inherited from the kernel +isn't saved anywhere - which is the default. </li> <p /> <li> <tt>-e</tt> <em>initial_envvar</em> : this option -can be repeated. For every <em>initial_envvar</em>, s6-linux-init-maker +can be repeated. For every <em>initial_envvar</em>, <tt>s6-linux-init-maker</tt> will adjust the global environment directory in <em>dir</em>/env. <em>initial_envvar</em> must either be of the form <em>VAR</em>, to make sure that <em>VAR</em> does not appear in the global environment, or of the form <em>VAR=VALUE</em>, to add an environment variable <em>VAR</em> with the value <em>VALUE</em>. +The global environment is the environment that every supervised +process (as well as the <em>rc.init</em> script) will run with, +so it will be inherited by default by every process running on +the system. The TZ variable, for instance, is a good candidate to be set in the global environment. </li> <p /> - <li> <tt>-n</tt> : 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 <tt>.s6-svscan/finish</tt>, <tt>.s6-svscan/SIGHUP</tt> -and <tt>.s6-svscan/SIGINT</tt> 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. </li> <p /> - <li> <tt>-q</tt> <em>finalsleeptime</em> : when the machine shuts down, all processes that have not already been killed during <tt>shutdownscript</tt> will receive a SIGTERM or a SIGHUP to allow @@ -380,11 +256,150 @@ will go on. This option configures the amount of time that will elapse between the SIGTERM/SIGHUP and the SIGKILL. Default is <strong>2000</strong>, meaning a grace period of 2 seconds. </li> <p /> + <li> <tt>-D</tt> <em>initdefault</em> : boot the system with +a runlevel set to <em>initdefault</em>, which can be an arbitrary +string, but is usually <tt>2</tt>, <tt>3</tt>, <tt>5</tt> (traditional +sysvinit behaviour) or <tt>default</tt> (OpenRC behaviour). Default is +<tt>default</tt>. Note that if a <tt>2</tt>, <tt>3</tt>, <tt>4</tt>, +<tt>5</tt>, or <tt>default</tt> argument is encountered in the kernel +command line, it will be interpreted as the runlevel to boot the system +on, and will override the default given here. </li> <p /> + + <li> <tt>-n</tt> : at boot time, assume that a tmpfs is already +present on <tt>/run</tt> (or the argument that was given to the +<tt>--tmpfsdir</tt> configure option at build time) and that its +contents are essential. Instead of unmounting <tt>/run</tt> then +mounting a tmpfs on it, <a href="s6-linux-init.html">s6-linux-init</a> +will simply remount <tt>/run</tt>. This option is useful when +s6-linux-init is used on a distribution that imposes its initramfs +and said initramfs writes data to <tt>/run</tt> that is then used +by the distribution's initialization scripts. (An initramfs should +normally be transparent and leave no trace in the filesystem; +unfortunately, a lot of distributions do not care.) By default, +<tt>/run</tt> will be unmounted at boot time (just in case), and +then a tmpfs will be mounted on it. <strong>Do not</strong> use +this option if you are not sure: failure to remount <tt>/run</tt> +will cause init to die and the kernel to panic. This option is +incompatible with the <tt>-N</tt> option. </li> <p /> + + <li> <tt>-N</tt> : at boot time, do not perform +mounting/unmounting/remounting on <tt>/run</tt> (or the <em>tmpfsdir</em> +declared at build time) <strong>at all</strong>. By default, +a tmpfs is mounted on <tt>/run</tt> at boot time. This option is +useful when s6-linux-init is used to boot on an initramfs that +will remain the de facto rootfs of the system (which is the case +for instance in certain live CDs or certain embedded devices), in +which case the rootfs is already read-write and in RAM and mounting +an additional tmpfs is unnecessary. <strong>Do not</strong> use this +option if your rootfs is read-only: failure to write to <tt>/run</tt> +will cause init to die and the kernel to panic. This option is +incompatible with the <tt>-n</tt> option. </li> <p /> + + <li> <tt>-U</tt> <em>utmp_user</em> : this option is only +available when the s6-linux-init package has been built with the +<tt>--enable-utmps</tt> configure option, that enables support for 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 <tt>utmp</tt>. </li> <p /> +</ul> + +<h2> Organization of the created directory </h2> + +<p> + If <tt>s6-linux-init-maker</tt> returns successfully, <em>dir</em> +contains data that will be used at boot time. (Actually, +<em>basedir</em> will be used at boot time, not <em>dir</em>. Do not +forget to copy <em>dir</em> to <em>basedir</em> once you have checked +you are happy with what <tt>s6-linux-init-maker</tt> has created.) +</p> + +<p> + This boot-time data is made of several subdirectories: +</p> + +<ul> + <li> <tt>bin</tt>: this subdirectory contains scripts and symlinks +that should be copied to <tt>/sbin</tt> or <tt>/bin</tt>. There is +an <tt>init</tt> program performing stage 1 init, a <tt>telinit</tt> +program to change runlevels, and utilities to order a machine shutdown. </li> + <li> <tt>env</tt>: this subdirectory is the envdir that is +used to store the global environment. It will be read at boot time +by stage 1 init, and transmitted to all spawned processes. </li> + <li> <tt>scripts</tt>: this subdirectory contains a copy of the +skeleton scripts that have been installed in <tt>/etc/s6-linux-init/skel</tt> +(or the argument to the <tt>--skeldir</tt> configure option at +build time). These scripts should be edited before booting. They are +described above. </li> + <li> <tt>run-image</tt>: this is a file hierarchy that will be +copied verbatim at boot time to the newly made and mounted +<tt>/run</tt> tmpfs (or whatever your <em>tmpfsdir</em> is). The +subdirectories it contains are the following: + <ul> + <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> + <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> +what to do if it receives a signal (typically via the ctrlaltdel +combination) and ensures a hard reboot if <tt>s6-svscan</tt> ever fails. It +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-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>: +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>: +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> + </ul> </li> + </ul> </li> +</ul> + +<p> + If s6-linux-init has been built with +<a href="//skarnet.org/software/utmps/">utmps</a> support, some more +directories may exist: +</p> + +<ul> + <li> A directory somewhere under <tt>run-image</tt>, by default <tt>utmps</tt>, +that is the location where the utmp and wtmp files will be created. </li> + <li> Two additional early services named <tt>utmpd</tt> and <tt>wtmpd</tt>, +that are the <a href="//skarnet.org/software/utmps/">utmps</a> way of +providing secure utmp functionality. </li> </ul> <h2> Notes </h2> <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. +</p> + +<p> + After booting, <em>basedir</em> should remain untouched during the +lifetime of the machine, because the machine state change and shutdown +procedures will look for data in <em>basedir</em>. New invocations of +<tt>s6-linux-init-maker</tt> should use a different <em>basedir</em>. +</p> + +<p> The difficult parts of <a href="//skarnet.org/software/s6/s6-svscan-1.html">running s6-svscan as process 1</a> are: @@ -399,22 +414,27 @@ tree's output away from <tt>/dev/console</tt> (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. </li> + <li> Keeping appearances of compatibility with another init system +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> </ul> <p> - The main benefit of s6-linux-init-maker is that it automates those -parts. This means that it has been designed for <em>real hardware</em> -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 <tt>/dev/console</tt> issue or the read-only rootfs issue, -you will probably not reap much benefit from using s6-linux-init-maker: + 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. -Nevertheless, if you prefer using s6-linux-init-maker, it -supports this case via the <tt>-n</tt> option. </p> </body> diff --git a/doc/s6-linux-init-shutdown.html b/doc/s6-linux-init-shutdown.html new file mode 100644 index 0000000..519d1e3 --- /dev/null +++ b/doc/s6-linux-init-shutdown.html @@ -0,0 +1,103 @@ +<html> + <head> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>s6-linux-init: the s6-linux-init-shutdown program</title> + <meta name="Description" content="s6-linux-init: the s6-linux-init-shutdown program" /> + <meta name="Keywords" content="s6 linux init administration root utilities shutdown halt poweroff reboot" /> + <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> + </head> +<body> + +<p> +<a href="index.html">s6-linux-init</a><br /> +<a href="//skarnet.org/software/">Software</a><br /> +<a href="//skarnet.org/">skarnet.org</a> +</p> + +<h1> The <tt>s6-linux-init-shutdown</tt> program </h1> + +<p> +<tt>s6-linux-init-shutdown</tt> triggers the system shutdown procedure. +It is normally invoked as <tt>/sbin/shutdown</tt>. +</p> + +<h2> Interface </h2> + +<pre> + s6-linux-init-shutdown [ -h | -p | -r | -k ] [ -a ] [ -t <em>sec</em> ] [ -f | -F ] <em>time</em> [ <em>message</em> ] + s6-linux-init-shutdown -c [ <em>message</em> ] +</pre> + +<ul> + <li> If the <tt>-c</tt> option is present, a pending shutdown is cancelled. </li> + <li> Else, it plans the shutdown procedure at time <em>time</em>. </li> + <li> If a <em>message</em> argument has been given, <em>message</em> is +broadcast to all logged in users (as tracked by utmp). </li> + <li> <tt>shutdown</tt> exits 0. The shutdown procedure happens asynchronously. </li> +</ul> + +<p> + The <tt>s6-linux-init-shutdown</tt> program conforms to the LSB-3.0.0 +<a href="http://refspecs.linuxbase.org/LSB_3.0.0/LSB-PDA/LSB-PDA/shutdown.html">shutdown</a> +interface. +</p> + +<p> + <em>time</em> must follow the following format: +<tt>[ now | [+]<em>mins</em> | <em>hh</em>:<em>mm</em> ] +</p> + +<ul> + <li> <tt>now</tt> means: trigger the shutdown sequence immediately. </li> + <li> <em>hh</em>:<em>mm</em> means: absolute time. Trigger the shutdown sequence when the time +<em>hh</em>:<em>mm</em> occurs. If that time has passed for the day, it will wait for the +next day. <em>hh</em> must have 1 or 2 digits; <em>mm</em> must have 2 digits. </li> + <li> <em>mins</em> or <tt>+</tt><em>mins</em> means: relative time. Trigger the shutdown +sequence after <em>mins</em> minutes. </li> +</ul> + +<h2> Options </h2> + +<ul> + <li> <tt>-a</tt> : access control. The shutdown sequence will only be +launched if one of the users listed in <tt>/etc/shutdown.allow</tt> +is currently logged in (as tracked by utmp). <tt>/etc/shutdown.allow</tt> +is a text file, one user per line, lines starting with <tt>#</tt> are comments. </li> + <li> <tt>-t</tt> <em>sec</em> : at the end of the shutdown sequence, +when it's time to kill all processes, have a "grace time" period +of <em>sec</em> seconds between the SIGTERM and the SIGKILL (to allow processes +receiving SIGTERM to exit cleanly). Default is 3 seconds. </li> + <li> <tt>-k</tt> : warning only. <em>message</em> will be sent to all +logged in users, but the shutdown sequence will not be triggered. </li> + <li> <tt>-h</tt> : at the end of the shutdown sequence, halt the system. </li> + <li> <tt>-p</tt> : at the end of the shutdown sequence, power off the system. +(This option is provided as an extension, it is not required by the LSB interface.) </li> + <li> <tt>-r</tt> : at the end of the shutdown sequence, reboot the system. </li> + <li> <tt>-f</tt> : ignored. </li> + <li> <tt>-F</tt> : ignored. </li> + <li> <tt>-c</tt> l: cancel a planned shutdown (i.e. cancel the effect of a +previous call to <tt>shutdown</tt> with a <em>time</em> argument that was not <tt>now</tt>). +This cannot be used to interrupt a shutdown sequence that has already started. </li> +</ul> + +<h2> Notes </h2> + +<ul> + <li> The <tt>s6-linux-init-shutdown</tt> +binary is not meant to be called directly by administrators. Instead, after a +<a href="s6-linux-init-maker.html">s6-linux-init-maker</a> invocation, +the <tt>bin/</tt> subdirectory of the target will contain a <tt>shutdown</tt> +symlink to <tt>s6-linux-init-shutdown</tt>. The <tt>bin/</tt> subdirectory +should be copied by the administrator into <tt>/sbin</tt> for full +interface compatibility with sysvinit. </li> + <li> The <tt>-f</tt> and <tt>-F</tt> options are only accepted for compatibility. +LSB says they are used to advise the system to skip or enforce a <tt>fsck</tt> +after rebooting. But they are only advisory, and for decades now systems have used +other methods of evaluating whether they should perform filesystem checks, so these +options are largely obsolete nowadays. </li> +</ul> + +</body> +</html> diff --git a/doc/s6-linux-init-shutdownd.html b/doc/s6-linux-init-shutdownd.html new file mode 100644 index 0000000..8889a9e --- /dev/null +++ b/doc/s6-linux-init-shutdownd.html @@ -0,0 +1,72 @@ +<html> + <head> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>s6-linux-init: the s6-linux-init-shutdownd program</title> + <meta name="Description" content="s6-linux-init: the s6-linux-init-shutdownd program" /> + <meta name="Keywords" content="s6 linux init administration root utilities shutdown halt poweroff reboot daemon shutdownd" /> + <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> + </head> +<body> + +<p> +<a href="index.html">s6-linux-init</a><br /> +<a href="//skarnet.org/software/">Software</a><br /> +<a href="//skarnet.org/">skarnet.org</a> +</p> + +<h1> The <tt>s6-linux-init-shutdownd</tt> program </h1> + +<p> +<tt>s6-linux-init-shutdownd</tt> is the daemon that manages the shutdown +procedure for a s6-linux-init installation. It is not meant to be called +directly by the user. +</p> + +<h2> Interface </h2> + +<pre> + s6-linux-init-shutdownd [ -c <em>basedir</em> ] [ -g <em>gracetime</em> ] <em>fifo</em> +</pre> + +<ul> + <li> <tt>s6-linux-init-shutdownd</tt> opens the <em>fifo</em> named pipe +and listens to it. This is where programs such as +<a href="s6-linux-init-shutdown.html">s6-linux-init-shutdown</a> send their +commands when they are told to trigger the shutdown procedure.</li> + <li> When it receives a command to shut down, <tt>s6-linux-init-shutdownd</tt> +first spawns the <em>rc.shutdown</em> script defined by the +<a href="s6-linux-init-maker.html">s6-linux-init-maker</a> invocation that +created the shutdownd service. </li> + <li> When this script exits, <tt>s6-linux-init-shutdownd</tt> kills all +processes, first with a SIGTERM, then (after the grace time specified by +the shutdown command) with a SIGKILL. </li> + <li> It then runs an automatically-generated script (called <em>stage 4</em>), +which unmounts the file systems and halts, powers off or reboots the +machine. </li> +</ul> + +<h2> Options </h2> + +<ul> + <li> <tt>-c <em>basedir</em></tt> : look for the +<em>rc.shutdown</em> script in the <em>basedir</em><tt>/scripts</tt> +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> +</ul> + +<h2> Notes </h2> + +<ul> + <li> The <a href="s6-linux-init-shutdownd.html">s6-linux-init-shutdownd</a> +binary is not meant to be called directly by administrators. It is run +by a <a href="//skarnet.org/software/s6/">s6</a> service that is automatically +generated by +<a href="s6-linux-init-maker.html">s6-linux-init-maker</a>. </li> +</ul> + +</body> +</html> diff --git a/doc/s6-linux-init-telinit.html b/doc/s6-linux-init-telinit.html new file mode 100644 index 0000000..2bea4e5 --- /dev/null +++ b/doc/s6-linux-init-telinit.html @@ -0,0 +1,84 @@ +<html> + <head> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>s6-linux-init: the s6-linux-init-telinit program</title> + <meta name="Description" content="s6-linux-init: the s6-linux-init-telinit program" /> + <meta name="Keywords" content="s6 linux init administration root utilities telinit" /> + <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> + </head> +<body> + +<p> +<a href="index.html">s6-linux-init</a><br /> +<a href="//skarnet.org/software/">Software</a><br /> +<a href="//skarnet.org/">skarnet.org</a> +</p> + +<h1> The <tt>s6-linux-init-telinit</tt> program </h1> + +<p> +<tt>s6-linux-init-telinit</tt> changes runlevels, i.e. changes the +system state. It is normally invoked as <tt>/sbin/telinit</tt> or +just <tt>init</tt> with an argument. +</p> + +<h2> Interface </h2> + +<pre> + s6-linux-init-telinit <tt>rl</tt> +</pre> + +<ul> + <li> <tt>s6-linux-init-telinit</tt> may be called with the same options as +<tt>s6-linux-init</tt>, but it ignores them all. </li> + <li> It calls the runleveld +<a href="//skarnet.org/software/s6/localservice.html">local service</a> with +the <em>rl</em> argument. This local service executes the user-provided +<tt>runlevel</tt> script, which changes the system state to the state +described by <em>rl</em>. </li> + <li> As a special case, if <em>rl</em> is <tt>0</tt> or <tt>6</tt>, +<tt>s6-linux-init-telinit</tt> then executes into +<a href="s6-linux-init-hpr.html">s6-linux-init-hpr</a> with the <tt>-p</tt> +or <tt>-r</tt> option respectively, +for compatibility with sysvinit's <em>0</em> and <em>6</em> runlevels +that respectively halt and reboot the machine. </li> +</ul> + +<h2> Exit codes </h2> + +<ul> + <li> 100: wrong usage </li> + <li> 111: system call failed </li> + <li> Else, <tt>s6-linux-init-telinit</tt> exits with the same exit code +as the <em>runlevel</em> script called with the <em>rl</em> argument. </li> + <li> If <em>rl</em> is 0 or 6, in case of success +<tt>s6-linux-init-telinit</tt> exits 0, but the system shuts down +immediately as it returns. </li> +</ul> + +<h2> Notes </h2> + +<ul> + <li> Traditional sysvinit only allows integer runlevels, from 0 to 6. +More advanced service managers, like OpenRC or s6-rc, allow the admin to +define alphanumerical runlevels, or <em>states</em>. <tt>s6-linux-init-telinit</tt> +does not implement policy; it only makes sure the user-provided <tt>runlevel</tt> +script is called with the <em>rl</em> argument, under a safe and reproducible +environment. The <tt>runlevel</tt> script can then change the machine state +as chosen by the user - typically by invoking the service manager. </li> + <li> The <tt>0</tt> and <tt>6</tt> special case has been added because +some legacy programs may assume that calling <tt>init 0</tt> and <tt>init 6</tt> +respectively halt and reboot the system. </li> + <li> The <tt>s6-linux-init-telinit</tt> +binary is not meant to be called directly by administrators. Instead, after a +<a href="s6-linux-init-maker.html">s6-linux-init-maker</a> invocation, +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> +</ul> + +</body> +</html> diff --git a/doc/s6-linux-init-umountall.html b/doc/s6-linux-init-umountall.html new file mode 100644 index 0000000..2d1bf99 --- /dev/null +++ b/doc/s6-linux-init-umountall.html @@ -0,0 +1,68 @@ +<html> + <head> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>s6-linux-init: the s6-linux-init-umountall program</title> + <meta name="Description" content="s6-linux-init: the s6-linux-init-umountall program" /> + <meta name="Keywords" content="s6 linux administration root linux utilities umount unmount filesystem" /> + <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> + </head> +<body> + +<p> +<a href="index.html">s6-linux-init</a><br /> +<a href="//skarnet.org/software/">Software</a><br /> +<a href="//skarnet.org/">skarnet.org</a> +</p> + +<h1> The <tt>s6-linux-init-umountall</tt> program </h1> + +<p> + <tt>s6-linux-init-umountall</tt> unmounts all filesystems. +</p> + +<h2> Interface </h2> + +<pre> + s6-linux-init-umountall +</pre> + +<ul> + <li> <tt>s6-linux-init-umountall</tt> unmounts all filesystems according to <tt>/proc/mounts</tt>. +It processes <tt>/proc/mounts</tt> in the reverse order, starting with the most recently mounted +partition and ending with the root filesystem ("unmounting" the root filesystem means remounting +it read-only). </li> + <li> <tt>s6-linux-init-umountall</tt> does not touch <tt>/etc/mtab</tt>. </li> + <li> If a filesystem fails to unmount, a warning is printed to stderr, but +<tt>s6-linux-init-umountall</tt> still attempts to unmount all the other ones. </li> +</ul> + +<h2> Exit codes </h2> + +<p> + <tt>s6-linux-init-umountall</tt> returns the number of errors it encountered +when attempting to unmount all the filesystems listed in <tt>/proc/mounts</tt>. +</p> + +<h2> Notes </h2> + +<ul> + <li> <tt>s6-linux-init-umountall</tt> is automatically called at the very end of the shutdown procedure, +in "stage 4", i.e. after a SIGKILL has been sent to all the processes on the system, and +right before the system reboots (or halts, or is powered off). By that point, there is +no possible process that could prevent real file systems from being unmounted. </li> + <li> It is likely that some filesystems will still fail to unmount, typically +<tt>/proc</tt> and <tt>/dev</tt>. That's okay: those are pseudo-filesystems, and +will not cause data loss or a fsck if the system shuts down while they are still mounted. </li> + <li> Distributions usually provide a <tt>umount</tt> command with a <tt>-a</tt> option +to unmount all filesystems. That command is usually bloated with historical artifacts +and relies on unsafe interfaces, so it was decided not to use it. The +<a href="//skarnet.org/software/s6-linux-utils/">s6-linux-utils</a> package also +provides a <a href="//skarnet.org/software/s6-linux-utils/s6-umount.html">s6-umount</a> +command with a <tt>-a</tt> option, but adding a dependency to that package would be a +higher cost than simply reimplementing the specific functionality here. </li> +</ul> + +</body> +</html> diff --git a/doc/s6-linux-init.html b/doc/s6-linux-init.html new file mode 100644 index 0000000..f57adae --- /dev/null +++ b/doc/s6-linux-init.html @@ -0,0 +1,164 @@ +<html> + <head> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>s6-linux-init: the s6-linux-init program</title> + <meta name="Description" content="s6-linux-init: the s6-linux-init program" /> + <meta name="Keywords" content="s6 linux init administration root init boot pid1 pid 1 /sbin/init" /> + <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> + </head> +<body> + +<p> +<a href="index.html">s6-linux-init</a><br /> +<a href="//skarnet.org/software/">Software</a><br /> +<a href="//skarnet.org/">skarnet.org</a> +</p> + +<h1> The <tt>s6-linux-init</tt> program </h1> + +<p> +<tt>s6-linux-init</tt> is a program that is meant to run as pid 1, +as a <em>stage 1 init</em>: it performs the necessary early system preparation +and execs into <a href="//skarnet.org/software/s6/s6-svscan.html">s6-svscan</a>. +</p> + +<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>dev_style</em> ] [ -D <em>initdefault</em> ] [ -n | -N ] [ <em>args...</em> ] +</pre> + +<ul> + <li> If <tt>s6-linux-init</tt> isn't pid 1, it execs into +<a href="s6-linux-init-telinit.html">s6-linux-init-telinit</a> with the +same arguments. </li> + </li> + <li> Else, it performs some early preparation, spawns a process that +will run the <em>rc.init</em> script, then execs into +<a href="//skarnet.org/software/s6/s6-svscan.html">s6-svscan</a>. +</ul> + +<h2> Options </h2> + +<p> + These options should exactly mirror the options with the same name that +have been given to <a href="s6-linux-init-maker.html">s6-linux-init-maker</a>. +If there is a discrepancy, the system might not boot. +</p> + +<ul> + <li> <tt>-c</tt> <em>basedir</em> : read all its initialization +data from <em>basedir</em>. If the data has not indeed been copied to +<em>basedir</em>, <strong>the system will not boot</strong>. </li> + <li> <tt>-p</tt> <em>initial_path</em> : the initial value for +the PATH environment variable. </li> + <li> <tt>-s</tt> <em>env_store</em> : the place where to dump +kernel environment variables. </li> + <li> <tt>-m</tt> <em>initial_umask</em> : the initial file umask. </li> + <li> <tt>-d</tt> <em>slashdev</em> : mount a devtmpfs on +<em>slashdev</em>. By default, no such mount is performed - it is assumed +that a devtmpfs is automounted on <tt>/dev</tt> at boot time by the kernel. </li> + <li> <tt>-D</tt> <em>initdefault</em> : the initial runlevel +to boot to, if it isn't overridden by the kernel command line. +This is only given as a first argument to <em>rc.init</em>. +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> +</ul> + +<h2> Early preparation </h2> + +<p> + When booting a system, <tt>s6-linux-init</tt> performs the following +operations: +</p> + +<ul> + <li> It prints a banner to <tt>/dev/console</tt>. </li> + <li> It chdirs to <tt>/</tt>. </li> + <li> It sets the umask to <em>initial_umask</em>. </li> + <li> It becomes a session leader. </li> + <li> It mounts a devtmpfs on <em>slashdev</em>, if requested. </li> + <li> It uses <tt>/dev/null</tt> as its stdin (instead of <tt>/dev/console</tt>). +<tt>/dev/console</tt> is still used, for now, as stdout and stderr. </li> + <li> It unmounts <tt>/run</tt> (or the directory you have given to the +<tt>--tmpfsdir</tt> configure option at package build time), just in case; +then it creates a tmpfs on it. Alternatively, it remounts <tt>/run</tt>, +or does not touch it at all. </li> + <li> It copies the whole <tt><em>basedir</em>/run-image</tt> hierarchy to +<tt>/run</tt> (or your chosen tmpfsdir). </li> + <li> It reads the initial environment from <tt><em>basedir</em>/env</tt>. </li> + <li> If required, it stores the kernel environment into <em>env_store</em>. </li> + <li> It performs "the fifo trick", i.e. it redirects its stdout to the +catch-all logger's fifo, without blocking, before the catch-all +logger is even up (because it's a service that will be spawned a bit +later, when <a href="//skarnet.org/software/s6/s6-svscan.html">s6-svscan</a> +is executed). </li> + <li> It forks a child. + <ul> + <li> The child scans the kernel command line to find a suitable runlevel +(<tt>default</tt>, <tt>2</tt>, <tt>3</tt>, <tt>4</tt>, or <tt>5</tt>). If +it doesn't find any kernel command line argument that defines a runlevel, +it uses <em>initdefault</em>. </li> + <li> The child becomes a session leader. </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 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> + <li> <a href="//skarnet.org/software/s6/s6-svscan.html">s6-svscan</a> +spawns the early services that are defined in +<tt><em>basedir</em>/run-image/service</tt>, and have been copied into +<tt>/run/service</tt> (or <em>tmpfsdir</em>/service). </li> + <li> One of those early services is <tt>s6-svscan-log</tt>, which is +the catch-all logger. When this service is up, <tt>s6-linux-init</tt>'s +child unblocks. </li> + <li> The child execs into <tt><em>basedir</em>/scripts/rc.init</tt>. +The first argument to <em>rc.init</em> is the chosen runlevel. The kernel +command line, as given by the kernel to <tt>s6-linux-init</tt> (i.e. without +the <tt>key=value</tt> arguments, which were passed into <tt>s6-linux-init</tt>'s +environment and were stored into <em>env_store</em>), makes for the rest of +the arguments given to <em>rc.init</em>. </li> + </ul> </li> +</ul> + +<p> + By the time <em>rc.init</em> runs, +<a href="//skarnet.org/software/s6/s6-svscan.html">s6-svscan</a> is running +as pid 1 and has spawned its early services - at least the catch-all logger, +and the other services, including the early getty if it has been defined, are +started in parallel and will be ready instantly. <em>rc.init</em> can then +perform <em>stage 2</em> of the initialization process, i.e. the handoff to +the service manager. +</p> + +<h2> Exit codes </h2> + +<p> + <tt>s6-linux-init</tt> never exits. It spawns the <em>rc.init</em> script +and execs into <a href="//skarnet.org/software/s6/s6-svscan.html">s6-svscan</a>, +which runs forever until the machine stops or reboots. +</p> + +<h2> Notes </h2> + +<ul> + <li> The <tt>s6-linux-init</tt> +binary is not meant to be called directly, or be linked to <tt>/sbin/init</tt> +directly, because it takes command-line options. + Instead, after a +<a href="s6-linux-init-maker.html">s6-linux-init-maker</a> invocation, +the <tt>bin/</tt> subdirectory of the target will contain a script called +<tt>init</tt>, which execs into <tt>s6-linux-init</tt> with the appropriate +command-line options, and <em>is</em> suitable as a <tt>/sbin/init</tt> program. +The <tt>bin/</tt> subdirectory +should be copied by the administrator into <tt>/sbin</tt> for full +interface compatibility with sysvinit. </li> +</ul> + +</body> +</html> diff --git a/doc/s6-poweroff.html b/doc/s6-poweroff.html deleted file mode 100644 index e215c38..0000000 --- a/doc/s6-poweroff.html +++ /dev/null @@ -1,55 +0,0 @@ -<html> - <head> - <meta name="viewport" content="width=device-width, initial-scale=1.0" /> - <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> - <meta http-equiv="Content-Language" content="en" /> - <title>s6-linux-init: the s6-poweroff program</title> - <meta name="Description" content="s6-linux-init: the s6-poweroff program" /> - <meta name="Keywords" content="s6 linux init administration root utilities shutdown halt poweroff reboot" /> - <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> - </head> -<body> - -<p> -<a href="index.html">s6-linux-init</a><br /> -<a href="//skarnet.org/software/">Software</a><br /> -<a href="//skarnet.org/">skarnet.org</a> -</p> - -<h1> The <tt>s6-poweroff</tt> program </h1> - -<p> -<tt>s6-poweroff</tt> sends a signal to process 1 in order to power off the machine; -or, with the <tt>-f</tt> option, it performs an immediate hard shutdown. -</p> - -<h2> Interface </h2> - -<pre> - s6-poweroff [ -h | -p | -r ] [ -f ] -</pre> - -<ul> - <li> s6-poweroff sends a signal to process 1. </li> - <li> It then exits 0. </li> -</ul> - -<h2> Options </h2> - -<ul> - <li> <tt>-h</tt> : halt. The command will order a halt (i.e. the system will -be shut down, but the power will remain up), which means -sending a SIGUSR2 to process 1. </li> - <li> <tt>-p</tt> : poweroff. The command will order a power off, which means -sending a SIGUSR1 to process 1. This is the default. </li> - <li> <tt>-r</tt> : reboot. The command will order a reboot, which means -sending a SIGINT to process 1. </li> - <li> <tt>-f</tt> : force. The command will not send any signal to process 1; -it will just sync the filesystems then tell the kernel to halt, poweroff or reboot. -<tt>s6-reboot -f</tt> or <tt>s6-poweroff -f</tt> should be the last program -executed in the lifetime of a machine, at the end of the shutdown script called -by process 1 when it receives a signal telling it to shut down. </li> -</ul> - -</body> -</html> diff --git a/doc/s6-reboot.html b/doc/s6-reboot.html deleted file mode 100644 index 16043c5..0000000 --- a/doc/s6-reboot.html +++ /dev/null @@ -1,55 +0,0 @@ -<html> - <head> - <meta name="viewport" content="width=device-width, initial-scale=1.0" /> - <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> - <meta http-equiv="Content-Language" content="en" /> - <title>s6-linux-init: the s6-reboot program</title> - <meta name="Description" content="s6-linux-init: the s6-reboot program" /> - <meta name="Keywords" content="s6 linux init administration root utilities shutdown halt poweroff reboot" /> - <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> - </head> -<body> - -<p> -<a href="index.html">s6-linux-init</a><br /> -<a href="//skarnet.org/software/">Software</a><br /> -<a href="//skarnet.org/">skarnet.org</a> -</p> - -<h1> The <tt>s6-reboot</tt> program </h1> - -<p> -<tt>s6-reboot</tt> sends a signal to process 1 in order to reboot the machine; -or, with the <tt>-f</tt> option, it performs an immediate reboot. -</p> - -<h2> Interface </h2> - -<pre> - s6-reboot [ -h | -p | -r ] [ -f ] -</pre> - -<ul> - <li> s6-reboot sends a signal to process 1. </li> - <li> It then exits 0. </li> -</ul> - -<h2> Options </h2> - -<ul> - <li> <tt>-h</tt> : halt. The command will order a halt (i.e. the system will -be shut down, but the power will remain up), which means -sending a SIGUSR2 to process 1. </li> - <li> <tt>-p</tt> : poweroff. The command will order a power off, which means -sending a SIGUSR1 to process 1. </li> - <li> <tt>-r</tt> : reboot. The command will order a reboot, which means -sending a SIGINT to process 1. This is the default. </li> - <li> <tt>-f</tt> : force. The command will not send any signal to process 1; -it will just sync the filesystems then tell the kernel to halt, poweroff or reboot. -<tt>s6-reboot -f</tt> or <tt>s6-poweroff -f</tt> should be the last program -executed in the lifetime of a machine, at the end of the shutdown script called -by process 1 when it receives a signal telling it to shut down. </li> -</ul> - -</body> -</html> diff --git a/doc/upgrade.html b/doc/upgrade.html index f8ea901..02aaeea 100644 --- a/doc/upgrade.html +++ b/doc/upgrade.html @@ -18,6 +18,15 @@ <h1> What has changed in s6-linux-init </h1> + +<h2> in 1.0.0.0 </h2> + +<ul> + <li> This is a complete rewrite and redesign of s6-linux-init: the +<em>lifetime</em> version number has increased. No compatibility +whatsoever is retained with previous versions. </li> +</ul> + <h2> in 0.4.0.1 </h2> <ul> @@ -48,6 +57,9 @@ anymore (stage 3 was previously the user-written <tt>/etc/rc.shutdown</tt> script). </li> <li> The default user-provided "end of stage 2, bring down services" script was named <tt>/etc/rc.tini</tt> before; now it's named <tt>/etc/rc.shutdown</tt>. </li> + <li> Everything now builds as PIC by default no matter +the toolchain's settings. Use the <tt>--disable-all-pic</tt> configure +option to build executables and static libraries as non-PIC. </li> </ul> <h2> in 0.3.1.1 </h2> diff --git a/doc/why.html b/doc/why.html new file mode 100644 index 0000000..8898cbd --- /dev/null +++ b/doc/why.html @@ -0,0 +1,139 @@ +<html> + <head> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>s6-linux-init: why?</title> + <meta name="Description" content="s6-linux-init: why?" /> + <meta name="Keywords" content="s6-linux-init why rationale s6 software stack init pid 1" /> + <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> + </head> +<body> + +<p> +<a href="index.html">s6-linux-init</a><br /> +<a href="//skarnet.org/software/">Software</a><br /> +<a href="//skarnet.org/">skarnet.org</a> +</p> + +<h1> Why s6-linux-init ? </h1> + +<h2> The s6 software stack </h2> + +<p> + The s6 ecosystem is made of several parts, which are mainly the following: +</p> + +<ul> + <li> <a href="//skarnet.org/software/skalibs/">skalibs</a>: a C system +programming library that is used in all skarnet.org software. </li> + <li> <a href="//skarnet.org/software/execline/">execline</a>: a small +scripting language that is mainly used in various parts of the s6 +ecosystem because: + <ul> + <li> It is very quick to launch, and efficient with small scripts, so it +is a good choice for s6 run scripts. </li> + <li> It is much easier to programmatically generate execline scripts than +shell scripts. execline allows programs such as +<a href="s6-linux-init-maker.html">s6-linux-init-maker</a> to generate scripts +quite easily, whereas using the shell syntax would require them to understand +the full subleties of shell quoting. </li> + </ul> + <li> <a href="//skarnet.org/software/s6/">s6</a>, the main dish: a process +supervision suite. </li> + <li> <a href="//skarnet.org/software/s6-rc/">s6-rc</a>: a service manager +for s6. </li> + <li> and <a href="//skarnet.org/software/s6-linux-init/">s6-linux-init</a>: this +package. </li> +</ul> + +<h2> Providing a complete init system </h2> + +<p> + As explained in +<a href="https://archive.fosdem.org/2017/schedule/event/s6_supervision/">this +presentation</a>, an init system is made of four parts: +</p> + +<ol> + <li> <tt>/sbin/init</tt>: the first userspace program that is run by the +kernel at boot time (not counting an initramfs). </li> + <li> <em>pid 1</em>: the program that will run as process 1 for most of +the lifetime of the machine. This is not necessarily the same executable +as <tt>/sbin/init</tt>, because <tt>/sbin/init</tt> can exec into something +else. </li> + <li> a <em>process supervisor</em>. </li> + <li> a <em>service manager</em>. </li> +</ol> + +<p> + The <a href="//skarnet.org/software/s6/">s6</a> package obviously provides +part 3. It also provides part 2, because +<a href="//skarnet.org/software/s6/s6-svscan.html">s6-svscan</a> is suitable +as being pid 1 after some small setup is performed. +</p> + +<p> + Part 4, service management, can be provided in a variety of ways. The +<a href="//skarnet.org/software/s6-rc/">s6-rc</a> service manager is the +natural complement to the s6 process supervisor, but it is not the only +possibility. The +<a href="https://jjacky.com/anopa/">anopa</a> package also provides a +service manager designed to work with s6. And, at the expense of +tight integration with the supervisor, it is possible to run a "traditional" +service manager, such as sysv-rc or OpenRC, with an s6-based init system. +This flexibility is possible because service management is one layer above +the mechanisms of init and process supervision. +</p> + +<p> + Remains part 1. And that's where s6-linux-init enters the picture. +</p> + +<h3> Portability </h3> + +<p> + Part 1 of an init system, the <tt>/sbin/init</tt> program, has been purposefully +omitted from the main s6 package, for a simple reason: s6 aims to be portable +to any flavor of Unix, and <em>it is impossible to implement <tt>/sbin/init</tt> +in a portable way</em>. +</p> + +<p> + For instance, to do its job, +<a href="//skarnet.org/software/s6/s6-svscan.html">s6-svscan</a> needs +a writable directory. Such a directory may not be available at boot time, +before mounting filesystems, because the root filesystem may be read-only. +So, at least one writable filesystem (typically a RAM-backed one) must be +mounted before s6-svscan can be executed and be pid 1. And mounting a +filesystem is a non-portable operation. +</p> + +<h3> Complexity </h3> + +<p> + Moreover, the sequence of operations that a <tt>/sbin/init</tt> program +needs to perform before executing into <tt>s6-svscan</tt> is a bit +tricky. It can be scripted, but it's not easy, and since it's so early +in the lifetime of the machine, there's no safety net at all (the +supervision tree itself, and the early getty, are supposed to be the +safety net, and they're not there yet). So it's better to automate +these operations. +</p> + +<h2> Conclusion </h2> + +<p> + <tt>s6-linux-init</tt> aims to provide a fully functional <tt>/sbin/init</tt> +program that executes into an s6 supervision tree with all the necessary +support services already in place, as well as the corresponding shutdown +commands. It also aims to be flexible enough to accommodate various needs +and be compatible with any user-chosen service manager. +</p> + +<p> +As usual, it is about <em>mechanism</em>, not <em>policy</em>. +</p> + +</body> +</html> |