Fix some bugs, add some doc

author: Laurent Bercot <ska-skaware@skarnet.org> 2015-06-17 18:33:06 +0000
committer: Laurent Bercot <ska-skaware@skarnet.org> 2015-06-17 18:33:06 +0000
commit: ff781adeb26caca82a717d7f1dd83c4ad94b5165 (patch)
tree: de5790b65e9249a07b04749be3ee441d32523361 /doc
parent: b7f31dafc46e772d98405e93bc21c271d8087b7e (diff)
download: s6-linux-init-ff781adeb26caca82a717d7f1dd83c4ad94b5165.tar.xz
3 files changed, 213 insertions, 16 deletions
diff --git a/doc/index.html b/doc/index.html
index ad0d3b0..c3426e0 100644
--- a/doc/index.html
+++ b/doc/index.html
@@ -20,9 +20,9 @@
 <h2> What is it&nbsp;? </h2>
 
 <p>
- s6-linux-init is a set of minimalistic tools to create and manage
-the init process on a Linux system - i.e. the first process created
-by the kernel at boot time.
+ s6-linux-init is a set of minimalistic tools to create a
+<a href="http://skarnet.org/software/s6/">s6</a>-based init
+system, including a <tt>/sbin/init</tt> binary, on a Linux kernel.
 </p>
 
 <p>
@@ -61,11 +61,12 @@ and then you can <em>boot</em> your system on that init script.
 </p>
 
 <p>
- The listed dependencies are all <em>build-time</em> dependencies and also
-<em>boot-time</em> dependencies, i.e. you need the tools installed to build
-s6-linux-init and to boot your system. There are no <em>run-time</em>
-dependencies, except skalibs if you linked against the shared version of
-the library.
+ skalibs and execline are <em>build-time</em> dependencies.
+ There are no <em>run-time</em> dependencies.
+ And every listed package, save skalibs, is a <em>boot-time</em> dependency.
+ If you are using the shared version of the skalibs library,
+then skalibs also becomes a <em>run-time</em> and a
+<em>boot-time</em> dependency.
 </p>
 
 <h3> Licensing </h3>
@@ -101,6 +102,13 @@ the previous versions of s6-linux-init and the current one. </li>
 
 <h2> Reference </h2>
 
+<h3> Quickstart guide and FAQ </h3>
+
+<p>
+ There is one,
+ <a href="quickstart.html">here</a>&nbsp;!
+</p>
+
 <h3> Commands </h3>
 
 <p>
diff --git a/doc/quickstart.html b/doc/quickstart.html
new file mode 100644
index 0000000..da47334
--- /dev/null
+++ b/doc/quickstart.html
@@ -0,0 +1,142 @@
+<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: quickstart and FAQ</title>
+    <meta name="Description" content="s6-linux-init: quickstart and FAQ" />
+    <meta name="Keywords" content="s6-linux-init installation quickstart faq" />
+    <!-- <link rel="stylesheet" type="text/css" href="http://skarnet.org/default.css" /> -->
+  </head>
+<body>
+
+<p>
+<a href="index.html">s6-linux-init</a><br />
+<a href="http://skarnet.org/software/">Software</a><br />
+<a href="http://skarnet.org/">skarnet.org</a>
+</p>
+
+<h1> Quickstart and FAQ for s6-linux-init </h1>
+
+<h2> Quickstart </h2>
+
+<ul>
+ <li> Install all the s6-linux-init dependencies:
+  <ul>
+   <li> <a href="http://skarnet.org/software/skalibs/">skalibs</a> </li>
+   <li> <a href="http://skarnet.org/software/execline/">execline</a> </li>
+   <li> <a href="http://skarnet.org/software/s6-portable-utils/">s6-portable-utils</a> </li>
+   <li> <a href="http://skarnet.org/software/s6-linux-utils/">s6-linux-utils</a> </li>
+   <li> <a href="http://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> 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 them executable. </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 &gt; /tmp/init
+     chmod 0700 /tmp/init
+     mv /tmp/s6-linux-init /etc/
+     mv /tmp/init /sbin/ </pre> </li>
+ <li> Reboot. </li>
+ <li> Congratulations! your machine is now running a s6-based init system. </li>
+</ul>
+
+<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&nbsp;? </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-linux-init-maker.html b/doc/s6-linux-init-maker.html
index cdf617e..530cd41 100644
--- a/doc/s6-linux-init-maker.html
+++ b/doc/s6-linux-init-maker.html
@@ -49,6 +49,7 @@ machine</em> - else the scripts will crash.
        [ -u <em>log_user</em> ] \
        [ -g <em>early_getty</em> ] \
        [ -2 <em>stage2</em> ] \
+       [ -r ] \
        [ -3 <em>stage3</em> ] \
        [ -p <em>initial_path</em> ] \
        [ -m <em>initial_umask</em> ] \
@@ -74,7 +75,7 @@ declared as <em>basedir</em>. 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="http://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> command.
+tool can do it, as well as the GNU or busybox <tt>cp -a</tt> or <tt>mv</tt> commands.
 </p>
 
 <p>
@@ -133,11 +134,10 @@ system. When <em>stage2</em> is executed, the machine state is as follows:
 
 <ul>
  <li> <em>stage2</em>'s working directory is <tt>/</tt> and its stdin
-is <tt>/dev/null</tt>. <em>stage2</em>'s
-stdout and stderr both point to the pipe to the catch-all logger, so
-unless redirected, <em>stage2</em>'s output will be logged into the
-<tt><em>tmpfsdir/uncaught-logs</em></tt> directory. </li>
- <li> The system has a valid device directory mounted on <tt>/dev</tt>.
+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>
@@ -227,6 +227,14 @@ 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>&nbsp;: 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>-3</tt>&nbsp;<em>stage3</em>&nbsp;: <em>stage3</em> is
 the location of the stage 3 script that will be run at the end of
 the machine lifetime, when s6-svscan is told to terminate.
@@ -235,8 +243,14 @@ It must be absolute. Default is
 
  <li> <tt>-p</tt>&nbsp;<em>initial_path</em>&nbsp;: the value to
 set the PATH environment variable to, for all the starting processes.
-This will be done as early as possible in <em>stage1</em>. Default is
-the value that has been compiled in
+This will be done as early as possible in <em>stage1</em>. It is
+absolutely necessary for
+<a href="http://skarnet.org/software/execline/">execline</a>,
+<a href="http://skarnet.org/software/s6/">s6</a>,
+<a href="http://skarnet.org/software/s6-portable-utils/">s6-portable-utils</a> and
+<a href="http://skarnet.org/software/s6-linux-utils/">s6-linux-utils</a>
+binaries to be accessible via <em>initial_path</em>, else the machine
+will not boot. Default is the value that has been compiled in
 <a href="http://skarnet.org/software/skalibs/">skalibs</a> via the
 <tt>--with-default-path</tt> configure option, i.e. by default
 <strong><tt>/usr/bin:/bin</tt></strong>. </li> <p />
@@ -272,5 +286,38 @@ The TZ variable, for instance, is a good candidate to be set in
 the global environment. </li> <p />
 </ul>
 
+<h2> Notes </h2>
+
+<p>
+ The difficult parts of
+<a href="http://skarnet.org/software/s6/s6-svscan-1.html">running
+s6-svscan as process 1</a> are:
+</p>
+
+<ul>
+ <li> The fact that the supervision tree requires writable directories,
+so in order to accommodate read-only root filesystems, there needs to
+be a tmpfs mounted before s6-svscan is run. </li>
+ <li> The catch-22 coming for the need to redirect the supervision
+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>
+</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:
+you could probably invoke
+<a href="http://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.
+</p>
+
 </body>
 </html>
author	Laurent Bercot <ska-skaware@skarnet.org>	2015-06-17 18:33:06 +0000
committer	Laurent Bercot <ska-skaware@skarnet.org>	2015-06-17 18:33:06 +0000
commit	ff781adeb26caca82a717d7f1dd83c4ad94b5165 (patch)
tree	de5790b65e9249a07b04749be3ee441d32523361 /doc
parent	b7f31dafc46e772d98405e93bc21c271d8087b7e (diff)
download	s6-linux-init-ff781adeb26caca82a717d7f1dd83c4ad94b5165.tar.xz