aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorLaurent Bercot <ska-skaware@skarnet.org>2026-01-18 02:50:51 +0000
committerLaurent Bercot <ska-skaware@skarnet.org>2026-01-18 02:50:51 +0000
commitc2740b983f6bb4baf0d5a1772fa3682cc66aa5f9 (patch)
treeeb17ec96fa0ff5b7bd6c5290edb9293ff1e8453d
parent6203378b6b6731a938eebdd60d99fecb429a849f (diff)
downloads6-frontend-c2740b983f6bb4baf0d5a1772fa3682cc66aa5f9.tar.gz
Add s6 live install --init ; finish and fix documentation
Diffstat
-rw-r--r--doc/index.html6
-rw-r--r--doc/overview.html316
-rw-r--r--doc/s6-frontend-helper-kill.html8
-rw-r--r--doc/s6-frontend.conf.html9
-rw-r--r--doc/s6-frontend.html8
-rw-r--r--doc/s6.html59
-rw-r--r--doc/s6_live.html52
-rw-r--r--doc/s6_process.html32
-rw-r--r--doc/s6_repository.html28
-rw-r--r--doc/s6_set.html46
-rw-r--r--doc/s6_system.html68
-rw-r--r--src/s6-frontend/live.help.txt1
-rw-r--r--src/s6-frontend/live_install.c5
13 files changed, 434 insertions, 204 deletions
diff --git a/doc/index.html b/doc/index.html
index d7d20b3..2d408b9 100644
--- a/doc/index.html
+++ b/doc/index.html
@@ -72,6 +72,12 @@ parts of an s6-based system.
<hr />
+<ul>
+ <li> An <a href="overview.html">overview</a> of s6-frontend </li>
+</ul>
+
+<hr />
+
<h2> Installation </h2>
<h3> Requirements </h3>
diff --git a/doc/overview.html b/doc/overview.html
new file mode 100644
index 0000000..f4d16f7
--- /dev/null
+++ b/doc/overview.html
@@ -0,0 +1,316 @@
+<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-frontend: overview</title>
+ <meta name="Description" content="s6-frontend: overview" />
+ <meta name="Keywords" content="s6 ecosystem supervision service manager user interface init skarnet.org skarnet software overview" />
+ <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" />
+ </head>
+<body>
+
+<p>
+<a href="index.html">s6-frontend</a><br />
+<a href="//skarnet.org/software/">Software</a><br />
+<a href="//skarnet.org/">skarnet.org</a>
+</p>
+
+<h1> s6-frontend: an overview </h1>
+
+<h2 id="contents"> Contents of the s6-frontend package </h2>
+
+<p>
+ The <tt>s6-frontend</tt> package does not itself contain much. The only binary
+that users will interact with directly is the
+<a href="s6.html"><tt>s6</tt></a> binary, which is a wrapper around the
+<a href="s6-frontend.html"><tt>s6-frontend</tt></a> binary (which users
+should not have to call directly), which is itself a wrapper around
+various commands of the s6 ecosystem that users also need to have
+installed in order for s6-frontend to work. That means:
+</p>
+
+<ul>
+ <li> <a href="//skarnet.org/software/s6/">s6</a>, the <em>package</em>,
+not the <em>command</em>: a process supervisor. Yes, the
+<a href="s6.html"><tt>s6</tt></a> binary is provided by the s6-frontend
+package (this package) and not the s6 package. Because the "s6" name,
+which was originally meant for "the supervision system", evolved to mean
+"the skarnet.org ecosystem of programs", and <tt>s6</tt> was the natural
+name to use for a command interfacing with all of it. </li>
+ <li> <a href="//skarnet.org/software/s6-rc/">s6-rc</a>: a service manager
+working on top of the s6 process supervisor. </li>
+ <li> optionally, <a href="//skarnet.org/software/s6-linux-init/">s6-linux-init</a>:
+a set of programs to make a Linux system <em>boot</em> and use
+<a href="//skarnet.org/software/s6/s6-svscan.html">s6-svscan</a>, the cornerstone
+of the s6 process supervisor, as pid 1. This makes s6 a full init system, by
+eliminating the need to pair s6 with something like busybox init, sysvinit,
+openrc-init or systemd, which provide a pid 1. </li>
+ <li> Future packages may be added to the ecosystem to add functionality,
+for instance: a package with turnkey essential service definitions that downstream
+can use, a package to handle namespaces and cgroups, a package to handle
+capabilities, etc. </li>
+</ul>
+
+<h2 id="installation"> Installing s6-frontend </h2>
+
+<p>
+ In addition to the s6-frontend package and its dependencies, in order to
+make use of the <a href="s6.html"><tt>s6</tt></a> command, you will need
+<em>service definitions</em>: a set of directories, in a format understandable
+by <a href="//skarnet.org/software/s6-rc/s6-rc-compile.html">s6-rc-compile</a>,
+describing various services that can run on a machine &mdash; long-running
+daemons, one-shot scripts, and "bundles" aliasing to a group of these services.
+</p>
+
+<p>
+ If you are running s6-frontend from a distribution, the packages that provide
+these services should already have them defined, and the service definition
+directories should already made available in some pre-configured
+<a href="//skarnet.org/software/s6-rc/repodefs#store">stores</a>. Your
+distribution should also have pre-installed everything you need in order
+for yo to be able to use the <a href="s6.html"><tt>s6</tt></a> command to
+control the system. But if you are installing s6-frontend manually, or are
+the person <em>building</em> the distribution, here is what you need to do:
+</p>
+
+<ul>
+ <li> Define one or more places where your service directories will
+be hosted: it's the equivalent of <tt>/etc/init.d</tt> for OpenRC or sysv-rc,
+the place where they store their scripts; or the equivalent of the places where
+systemd looks for its unit files, namely:
+<tt>/etc/systemd/system.control</tt>,
+<tt>/run/systemd/system.control</tt>,
+<tt>/run/systemd/transient</tt>,
+<tt>/run/systemd/generator.early</tt>,
+<tt>/etc/systemd/system</tt>,
+<tt>/etc/systemd/system.attached</tt>,
+<tt>/run/systemd/system</tt>,
+<tt>/run/systemd/system.attached</tt>,
+<tt>/run/systemd/generator</tt>,
+<tt>/usr/local/lib/systemd/system</tt>,
+<tt>/usr/lib/systemd/system</tt>, and
+<tt>/run/systemd/generator.late</tt>.
+ <ul>
+ <li> Yes, we think systemd <em>might</em> be overdoing it just a little.
+But who are we to criticize if it works for them? &#x1F92D; </li>
+ <li> We recommend having <em>two or three</em> stores: one for packages
+installed by the package manager, one for local modifications, and possibly
+one that is managed by the distribution outside of any package. The default
+<em>store list</em> for s6-frontend is
+<tt>/usr/share/s6-frontend/s6-rc/sources:/etc/s6-frontend/s6-rc/sources</tt>,
+which means that the package manager should install service definition
+directories in <tt>/usr/share/s6-frontend/s6-rc/sources</tt>, and that
+administrators should do their local modifications in
+<tt>/etc/s6-frontend/s6-rc/sources</tt>. You can modify this store list
+in the configuration file, see below. </li>
+ </ul> </li>
+ <li> And then you need the service definitions themselves.
+ <ul>
+ <li> Service definitions for a given daemon such as e.g. sshd should
+be written by the distribution that packages sshd and provided by the
+package manager when it installs sshd. Alternatively, they
+could be provided by the sshd upstream, but service definitions are
+<em>policy</em>, not <em>mechanism</em>, and we think policy is the realm
+of distributions, not of software authors. </li>
+ <li> Essential services, i.e. how to boot a machine and bring it to
+the state where it can accept logins and run services provided by packages,
+should be provided by the distribution in a specific package. </li>
+ <ul>
+ <li> systemd comes with a big list of unit files: it provides some policy
+itself. </li>
+ <li> OpenRC also comes with a set of basic services: it provides some policy
+itself as well. </li>
+ <li> s6-frontend <em>does not</em> provides policy, but since basic service
+files is essential for people to use it, work is underway to write these. They
+will be provided in a separate package. In the meantime, you can find service
+definitions contributed by the community pretty much everywhere s6-rc is used.
+The s6-rc package comes with some
+<a href="https://git.skarnet.org/cgi-bin/cgit.cgi/s6-rc/tree/examples/source">example
+service definitions</a>. </li>
+ </ul> </li>
+ </ul> </li>
+ <li> Define a <a href="s6-frontend.conf.html">configuration file</a>,
+located at <tt>/etc/s6-frontend.conf</tt> unless you modified the default at
+build time. If you go with all the defaults for all the packages in the s6
+ecosystem, the configuration file can basically be empty; but you will probably
+at least want to define the <tt>storelist</tt> variable. </li>
+ <li> Once your configuration file is ready, and all your services are in the
+store, you need to initialize the repository:
+<a href="s6_repository.html#init"><tt>s6 repository init</tt></a>. This command
+will create the repository and make a reference database with all the services
+in your stores. If it succeeds, congratulations! Your stores are <em>consistent</em>,
+i.e. they define a full set of services that can be used by the s6-rc service manager. </li>
+ <li> Check that the default states of the service are what you want, with
+<a href="s6_set.html#status"><tt>s6 set status</tt></a>. If they're not, make the
+changes you need with various <a href="s6_set.html#enable"><tt>s6 set</tt></a> commands. </li>
+ <li> Once you're happy with the set, commit your changes with
+<a href="s6_set.html#commit"><tt>s6 set commit</tt></a>. This will make an s6-rc
+compiled service database. </li>
+ <li> Install this service database as the one that will be run at boot time.
+This is done by <a href="s6_live.html#install"><tt>s6 live install --init</tt></a>.
+Note that the <tt>--init</tt> option should only be given for this first installation
+when the machine isn't managed by s6-rc yet. </li>
+ <li> Make sure your init system will actually boot the service database you have
+just installed. The command that should be run at boot time is:
+<a href="s6_system.html#boot"><tt>s6 system boot</tt></a>. Check the link to see
+how to configure your init system to run it. </li>
+ <li> If everything is ready, reboot the machine. Congratulations! It is now
+running under a full s6 init system. </li>
+ <li> If you are using <a href="//skarnet.org/software/s6-linux-init/">s6-linux-init</a>,
+the way to reboot your system will be
+<a href="s6_system.html#reboot"><tt>s6 system reboot</tt></a> from now on. </li>
+</ul>
+
+
+<h2 id="concepts"> Concepts </h2>
+
+<p>
+ s6-frontend does not come with any innovating concepts &mdash; it's just a series
+of user-friendly wrappers around various commands in the s6 ecosystem, hiding
+the details of various options and installation directories. For instance:
+</p>
+
+<ul>
+ <li> Instead of running <tt>s6-svc -r /run/service/foobar</tt>, you run
+<tt>s6 process restart foobar</tt> </li>
+ <li> Instead of running <tt>s6-rc -d change foobar</tt>, you run
+<tt>s6 live stop foobar</tt> </li>
+ <li> Instead of running <tt>s6-rc-init /run/service &amp;&amp; s6-rc change default</tt>
+at boot time, you run <tt>s6 system boot</tt> </li>
+</ul>
+
+<p>
+ The most innovating change comes from the
+<a href="//skarnet.org/software/s6-rc/repodefs.html">repo</a> commands, in the
+version of <a href="//skarnet.org/software/s6-rc/">s6-rc</a> that is released at the
+same time as the first release of s6-frontend. The goals of the <em>repo</em> commands, which
+are wrapped by the <a href="s6_repository.html"><tt>s6 repository</tt></a> and
+<a href="s6_set.html"><tt>s6 set</tt></a> commands, are:
+</p>
+
+<ul>
+ <li> To provide a framework for distributions and system administrators to organize their
+text-format source definition directories, by defining places where service definitions
+should be stored </li>
+ <li> To allow local administrators to tailor what services they want to see in their
+live database, by providing an intermediary between the stores and the live database:
+offline sets. With <a href="s6_set.html#mask"><tt>s6 set mask</tt></a>, an administrator
+can make it so a service, though defined in a store, will not appear in the service
+database at all. <em>Unmasked</em> services appear in the live database, but are only started
+at boot time when they are <em>enabled</em> (or <em>essential</em>, but that property
+is best set in the service definition itself and never overridden). </li>
+ <li> To allow easy replacement of the current live database by a set that has been
+worked on. </li>
+</ul>
+
+<h2 id="openrc"> Comparison with OpenRC </h2>
+
+<p>
+ One of the design goals of s6-frontend is to provide a user interface to service
+management that is comparable to the one provided by OpenRC.
+</p>
+
+<p>
+ A fundamental difference between s6-frontend and OpenRC is that OpenRC always
+works on <em>live services</em>, the ones that are currently running on the
+user's machine. It only has one <em>live database</em>, comprising several
+"runlevels" (sets of services meant to be run together), and manages its
+dependency tree dynamically.
+</p>
+
+<p>
+ s6-frontend, on the other hand (and more accurately, this is the domain of
+the <a href="//skarnet.org/software/s6-rc/">s6-rc</a> service manager and its
+<a href="//skarnet.org/software/s6-rc/repodefs.html">repo</a> commands),
+separates the notion of <em>live database</em> and of <em>working set</em>
+entirely. The <em>working set</em> is worked on <em>offline</em>, without
+impacting the current machine state. You can <em>start</em> and <em>stop</em>
+live services, but you can only <em>enable</em> or <em>disable</em>
+&mdash; or <em>mask</em> &mdash; services on the working set. Enabling a
+service means that <em>next time you boot on the service database you are
+working on</em>, that service will be automatically started. <br>
+ Once you have worked on a set of services, you can replace the live
+database with it; the old live database disappears entirely, and your
+working set (well, a copy of it) is now <em>live</em>.
+</p>
+
+<p>
+ A corollary of that is that s6-frontend does not have runlevels. It does
+not need them. The <em>default bundle</em> specifies what services should
+be started at boot; other bundles (in the sense of s6-rc) can be defined
+in the stores, and the user can start and stop them at will, as well as
+start and stop individual services, dependencies notwithstanding. By
+default, all the services are accessible in the live database, but the
+user can choose to exclude certain services by <em>masking them</em> in
+a working set and then installing that set.
+</p>
+
+<p>
+ These differences being given, s6-frontend should be very comparable to
+OpenRC in its everyday usage. Here is a table showing some correspondences;
+it is not meant to be exhaustive, but to show a representative enough sample
+of the kind of commands that can be worked with.
+</p>
+
+<table>
+ <thead>
+ <tr>
+ <th> OpenRC command </th>
+ <th> s6-frontend equivalent </th>
+ <th> Notes </th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td> <tt>rc-service foobar start</tt> </td>
+ <td> <tt>s6 live start foobar</tt> </td>
+ <td> Starts a service in the live database. </td>
+ </tr>
+ <tr>
+ <td> <tt>rc-service foobar status</tt> </td>
+ <td> <tt>s6 live status foobar</tt> or <tt>s6 process status foobar</tt> </td>
+ <td> <tt>s6 process status foobar</tt> only works if foobar is a longrun,
+in which case it will give detailed information on its supervised instance. </td>
+ </tr>
+ <tr>
+ <td> <tt>rc-status default</tt> </td>
+ <td> <tt>s6 live status</tt> or <tt>s6 set status</tt> </td>
+ <td> <tt>s6 live status</tt> shows the status of the current live database,
+<tt>s6 set status</tt> the status of the offline working set. </td>
+ </tr>
+ <tr>
+ <td> <tt>rc-update add foobar</tt> </td>
+ <td> <tt>s6 set enable foobar</tt> </td>
+ <td> See below. </td>
+ </tr>
+ <tr>
+ <td> <tt>rc-update del foobar</tt> </td>
+ <td> <tt>s6 set disable foobar</tt> </td>
+ <td> See below. </td>
+ </tr>
+ <tr>
+ <td> <tt>rc-update show</tt> </td>
+ <td> <tt>s6 set status</tt> </td>
+ <td> Shows the enabled, disabled and masked services, but to make the
+changes effective, the user needs to run <tt>s6 set commit</tt> then
+<tt>s6 live install</tt>. </td>
+ </tr>
+ <tr>
+ <td> <tt>openrc sysinit &amp;&amp; openrc boot &amp;&amp; openrc default</tt> </td>
+ <td> <tt>s6 system boot</tt> </td>
+ <td> The existence of the <tt>sysinit</tt> and <tt>boot</tt> runlevels are a
+historical wart that OpenRC still has to deal with; s6-frontend does not. </td>
+ </tr>
+ <tr>
+ <td> <tt>reboot</tt> </td>
+ <td> <tt>reboot</tt> or <tt>s6 system reboot</tt> </td>
+ <td> Just like OpenRC's <tt>reboot</tt> command will only work if the system
+is using <tt>openrc-init</tt>, <tt>s6 system reboot</tt> command will only work
+if the system is using <a href="//skarnet.org/software/s6-linux-init/">s6-linux-init</a>. </td>
+ </tr>
+ </tbody>
+</table>
+
+</body>
+</html>
diff --git a/doc/s6-frontend-helper-kill.html b/doc/s6-frontend-helper-kill.html
index 6c5d2b8..e32840c 100644
--- a/doc/s6-frontend-helper-kill.html
+++ b/doc/s6-frontend-helper-kill.html
@@ -27,9 +27,7 @@ although nothing bad will happen if you do. It is used in command lines crafted
program, because the latter does not support sending arbitrary numerical signals.
</p>
-<div id="interface">
-<h2> Interface </h2>
-</div>
+<h2 id="interface"> Interface </h2>
<pre>
s6-frontend-helper-kill <em>sig</em> <em>pids...</em>
@@ -41,9 +39,7 @@ of one or more integers, <em>pids...</em>, on its command line. </li>
<li> It sends signal number <em>sig</em> to all the processes listed as <em>pids...</em>. </li>
</ul>
-<div id="exitcodes">
-<h2> Exit codes </h2>
-</div>
+<h2 id="exitcodes"> Exit codes </h2>
<dl>
<dt> 0 </dt> <dd> Success </dd>
diff --git a/doc/s6-frontend.conf.html b/doc/s6-frontend.conf.html
index fbf284c..6d06601 100644
--- a/doc/s6-frontend.conf.html
+++ b/doc/s6-frontend.conf.html
@@ -18,9 +18,7 @@
<h1> The <tt>/etc/s6-frontend.conf</tt> configuration file </h1>
-<div id="goal">
-<h2> Goal and usage </h2>
-</div>
+<h2 id="goal"> Goal and usage </h2>
<p>
<tt>/etc/s6-frontend.conf</tt> is a configuration file provided by the
@@ -38,9 +36,7 @@ are located).
what the full path to the <em>foobar</em> service directory is.
</p>
-<div id="description">
-<h2> Description </h2>
-</div>
+<h2 id="description"> Description </h2>
<p>
The <tt>/etc/s6-frontend.conf</tt> file follows the syntax of the
@@ -57,7 +53,6 @@ simple <code>key = value</code> lines, comments permitted.
</p>
<dl>
-
<dt> scandir </dt>
<dd> The directory where <a href="//skarnet.org/software/s6/s6-svscan.html">s6-svscan</a>
is running.
diff --git a/doc/s6-frontend.html b/doc/s6-frontend.html
index e8d8f56..df6b913 100644
--- a/doc/s6-frontend.html
+++ b/doc/s6-frontend.html
@@ -24,17 +24,13 @@ the <a href="s6.html">s6</a> command line. It is not meant to be called directly
users should call <a href="s6.html">s6</a> instead.
</p>
-<div id="interface">
-<h2> Interface </h2>
-</div>
+<h2 id="interface"> Interface </h2>
<pre>
s6-frontend [ <em>global_options...</em> ] <em>command</em> <em>subcommand</em> [ <em>subcommand_options...</em> ] [ <em>args...</em> ]
</pre>
-<div id="details">
-<h2> Detailed operation </h2>
-</div>
+<h2 id="details"> Detailed operation </h2>
<p>
What really happens when you call <code>s6 <em>args...</em></code> is the following:
diff --git a/doc/s6.html b/doc/s6.html
index 775a09d..8aec603 100644
--- a/doc/s6.html
+++ b/doc/s6.html
@@ -26,9 +26,7 @@ interact with a system managed by the
<a href="//skarnet.org/software/s6-linux-init/">s6-linux-init boot program</a>.
</p>
-<div id="interface">
-<h2> Interface </h2>
-</div>
+<h2 id="interface"> Interface </h2>
<pre>
s6 [ <em>global_options...</em> ] <em>command</em> <em>subcommand</em> [ <em>subcommand_options...</em> ] [ <em>args...</em> ]
@@ -44,16 +42,7 @@ various parts of the s6 ecosystem, depending on the given command and
subcommand. </li>
</ul>
-<div id="commonusage">
-<h2> Common usage </h2>
-</div>
-
-<p>
-</p>
-
-<div id="exitcodes">
-<h2> Exit codes </h2>
-</div>
+<h2 id="exitcodes"> Exit codes </h2>
<p>
s6 always exits 0 on success, 100 on bad usage, and 111 on a system call
@@ -73,9 +62,7 @@ command, and on the linked documentation page, you can find the interpretation
of its various exit codes.
</p>
-<div id="environment">
-<h2> Environment variables </h2>
-</div>
+<h2 id="env"> Environment variables </h2>
<ul>
<li> s6 reads the <code>S6_FRONTEND_CONF</code> environment variable. This
@@ -86,9 +73,7 @@ possibly overridden by the <tt>--conffile</tt> build-time configure option to
s6-frontend. </li>
</ul>
-<div id="options">
-<h2> Global options </h2>
-</div>
+<h2 id="options"> Global options </h2>
<p>
<em>global_options...</em> is a list of options that modify s6's behaviour
@@ -164,13 +149,9 @@ have built s6-frontend with util-linux support. </dd>
</dl>
-<div id="commands">
-<h2> Commands </h2>
-</div>
+<h2 id="commands"> Commands </h2>
-<div id="s6_help">
-<h3> help </h3>
-</div>
+<h3 id="help"> help </h3>
<p>
<tt>s6 help</tt> prints a short help message summarizing the options
@@ -181,9 +162,7 @@ and usage of the s6 command. It is not as detailed as this page.
No subcommands are defined.
</p>
-<div id="s6_version">
-<h3> version </h3>
-</div>
+<h3 id="version"> version </h3>
<p>
<tt>s6 version</tt> prints the current version of s6-frontend, on one line.
@@ -193,9 +172,7 @@ and usage of the s6 command. It is not as detailed as this page.
No subcommands are defined.
</p>
-<div id="s6_process">
-<h3> process </h3>
-</div>
+<h3 id="process"> process </h3>
<p>
<tt>s6 process</tt> sends commands to long-running processes supervised by the
@@ -209,9 +186,7 @@ needs to be restarted or otherwise addressed without involvement from the servic
manager, i.e. without having to start or stop dependencies.
</p>
-<div id="s6_live">
-<h3> live </h3>
-</div>
+<h3 id="live"> live </h3>
<p>
<tt>s6 live</tt> controls the live state of the machine, starting and stopping
@@ -221,9 +196,7 @@ around the
available <a href="s6_live.html">here</a>.
</p>
-<div id="s6_repository">
-<h3> repository </h3>
-</div>
+<h3 id="repository"> repository </h3>
<p>
<tt>s6 repository</tt> regroups administrative tasks related to the repository
@@ -237,9 +210,7 @@ the initial layout, run their package manager, etc.
The details are available <a href="s6_repository.html">here</a>.
</p>
-<div id="s6_set">
-<h3> set </h3>
-</div>
+<h3 id="set"> set </h3>
<p>
<tt>s6 set</tt> is the interface to the creation and manipulation of service sets by
@@ -251,9 +222,7 @@ the live state of the machine, accessible via <a href="#s6_live"><tt>s6 live</tt
The details are available <a href="s6_set.html">here</a>.
</p>
-<div id="s6_system">
-<h3> system </h3>
-</div>
+<h3 id="system"> system </h3>
<p>
<tt>s6 system</tt> provides commands to run at boot and, on systems fully managed by s6,
@@ -261,9 +230,7 @@ to shut the system down.
The details are available <a href="s6_system.html">here</a>.
</p>
-<div id="notes">
-<h2> Notes </h2>
-</div>
+<h2 id="notes"> Notes </h2>
<ul>
<li> <tt>s6</tt> does not perform real operations itself. Instead, after
diff --git a/doc/s6_live.html b/doc/s6_live.html
index cd6aeac..3e121ec 100644
--- a/doc/s6_live.html
+++ b/doc/s6_live.html
@@ -33,30 +33,22 @@ without knowledge of the service manager, and thus can only address longruns,
as well as longruns, and always respects the dependency graph.
</p>
-<div id="interface">
-<h2> Interface </h2>
-</div>
+<h2 id="interface"> Interface </h2>
<pre>
s6 live <em>subcommand</em> [ <em>subcommand_options...</em> ] [ <em>args...</em> ]
</pre>
-<div id="subcommands">
-<h2> Subcommands </h2>
-</div>
+<h2 id="subcommands"> Subcommands </h2>
-<div id="help">
-<h3> help </h3>
-</div>
+<h3 id="help"> help </h3>
<p>
<tt>s6 live help</tt> prints a short help message summarizing the options
and usage of the <tt>s6 live</tt> command. It is not as detailed as this page.
</p>
-<div id="status">
-<h3> status </h3>
-</div>
+<h3 id="status"> status </h3>
<h4> Interface </h4>
@@ -89,9 +81,7 @@ This is the default. </dd>
<dd> List all services, including essential ones. </dd>
</dl>
-<div id="start">
-<h3> start </h3>
-</div>
+<h3 id="start"> start </h3>
<h4> Interface </h4>
@@ -118,9 +108,7 @@ transitions. By default, <em>timeout</em> is 0, meaning infinite: the
command can wait forever. </dd>
</dl>
-<div id="stop">
-<h3> stop </h3>
-</div>
+<h3 id="stop"> stop </h3>
<h4> Interface </h4>
@@ -147,9 +135,7 @@ transitions. By default, <em>timeout</em> is 0, meaning infinite: the
command can wait forever. </dd>
</dl>
-<div id="restart">
-<h3> restart </h3>
-</div>
+<h3 id="restart"> restart </h3>
<h4> Interface </h4>
@@ -180,9 +166,7 @@ transitions. By default, <em>timeout</em> is 0, meaning infinite: the
command can wait forever. </dd>
</dl>
-<div id="start_everything">
-<h3> start_everything </h3>
-</div>
+<h3 id="start_everything"> start_everything </h3>
<h4> Interface </h4>
@@ -217,9 +201,7 @@ The default is <tt>default</tt>, possibly overridden by the
<a href="//skarnet.org/software/s6-frontend/">s6-frontend</a>. </dd>
</dl>
-<div id="stop_everything">
-<h3> stop_everything </h3>
-</div>
+<h3 id="stop_everything"> stop_everything </h3>
<h4> Interface </h4>
@@ -259,14 +241,12 @@ transitions. By default, <em>timeout</em> is 0, meaning infinite: the
command can wait forever. </dd>
</dl>
-<div id="install">
-<h3> install </h3>
-</div>
+<h3 id="install"> install </h3>
<h4> Interface </h4>
<pre>
- s6 live install [ -b ] [ -K ] [ -f <em>convfile</em> ]
+ s6 live install [ -b ] [ -K ] [ -f <em>convfile</em> ] [ --init ]
</pre>
<ul>
@@ -297,6 +277,16 @@ Instead, print its path to stdout. </dd>
invocation, i.e. a file translating service names and states between
the old service database and the one being installed. This option should
never be necessary if the services in the stores are properly managed. </dd>
+
+<dt> --init </dt>
+<dd>
+ Copy the compiled database of the current working set to the place where it
+can be booted on, but do not call
+<a href="//skarnet.org/software/s6-rc/s6-rc-update.html">s6-rc-update</a>.
+This is only useful for a <em>first</em> installation of s6-frontend, when
+s6-rc is not managing the live services yet. Once a reboot has been done
+and the machine is successfully running with s6-rc, this option should
+never be used again. </dd>
</dl>
</body>
diff --git a/doc/s6_process.html b/doc/s6_process.html
index a00793a..179d8c2 100644
--- a/doc/s6_process.html
+++ b/doc/s6_process.html
@@ -25,30 +25,22 @@ by an instance of <a href="//skarnet.org/software/s6/s6-svscan.html">s6-svscan</
running on the <a href="s6-frontend.conf.html">configured</a> <em>scandir</em>.
</p>
-<div id="interface">
-<h2> Interface </h2>
-</div>
+<h2 id="interface"> Interface </h2>
<pre>
s6 process <em>subcommand</em> [ <em>subcommand_options...</em> ] [ <em>args...</em> ]
</pre>
-<div id="subcommands">
-<h2> Subcommands </h2>
-</div>
+<h2 id="subcommands"> Subcommands </h2>
-<div id="help">
-<h3> help </h3>
-</div>
+<h3 id="help"> help </h3>
<p>
<tt>s6 process help</tt> prints a short help message summarizing the options
and usage of the <tt>s6 process</tt> command. It is not as detailed as this page.
</p>
-<div id="kill">
-<h3> kill </h3>
-</div>
+<h3 id="kill"> kill </h3>
<h4> Interface </h4>
@@ -91,9 +83,7 @@ command can wait forever. This option is only effective when paired with the
</dl>
-<div id="status">
-<h3> status </h3>
-</div>
+<h3 id="status"> status </h3>
<h4> Interface </h4>
@@ -130,9 +120,7 @@ only useful with old-style logged s6 services that are not managed by
s6-rc. </dd>
</dl>
-<div id="start">
-<h3> start </h3>
-</div>
+<h3 id="start"> start </h3>
<h4> Interface </h4>
@@ -181,9 +169,7 @@ command can wait forever. This option is only effective when paired with the
<tt>--wait</tt> option. </dd>
</dl>
-<div id="stop">
-<h3> stop </h3>
-</div>
+<h3 id="stop"> stop </h3>
<h4> Interface </h4>
@@ -232,9 +218,7 @@ command can wait forever. This option is only effective when paired with the
<tt>--wait</tt> option. </dd>
</dl>
-<div id="restart">
-<h3> restart </h3>
-</div>
+<h3 id="restart"> restart </h3>
<h4> Interface </h4>
diff --git a/doc/s6_repository.html b/doc/s6_repository.html
index d992a1b..93f2bdc 100644
--- a/doc/s6_repository.html
+++ b/doc/s6_repository.html
@@ -34,30 +34,22 @@ they are likely to be a part of automated procedures written by the distribution
and triggered by specific events like installation or package updates.
</p>
-<div id="interface">
-<h2> Interface </h2>
-</div>
+<h2 id="interface"> Interface </h2>
<pre>
s6 repository <em>subcommand</em> [ <em>subcommand_options...</em> ] [ <em>args...</em> ]
</pre>
-<div id="subcommands">
-<h2> Subcommands </h2>
-</div>
+<h2 id="subcommands"> Subcommands </h2>
-<div id="help">
-<h3> help </h3>
-</div>
+<h3 id="help"> help </h3>
<p>
<tt>s6 repository help</tt> prints a short help message summarizing the options
and usage of the <tt>s6 repository</tt> command. It is not as detailed as this page.
</p>
-<div id="init">
-<h3> init </h3>
-</div>
+<h3 id="init"> init </h3>
<h4> Interface </h4>
@@ -93,9 +85,7 @@ has changed. </dd>
no impact whatsoever and this option can safely be ignored. </dd>
</dl>
-<div id="list">
-<h3> list </h3>
-</div>
+<h3 id="list"> list </h3>
<h4> Interface </h4>
@@ -110,9 +100,7 @@ the current working set, which always exists. </li>
<li> No options are defined. </li>
</ul>
-<div id="check">
-<h3> check </h3>
-</div>
+<h3 id="check"> check </h3>
<h4> Interface </h4>
@@ -156,9 +144,7 @@ depends on service <tt>B</tt> and <tt>A</tt> is unmasked or enabled,
change <tt>B</tt> to be unmasked or enabled as well. </dd>
</dl>
-<div id="sync">
-<h3> sync </h3>
-</div>
+<h3 id="sync"> sync </h3>
<h4> Interface </h4>
diff --git a/doc/s6_set.html b/doc/s6_set.html
index 83cf9f7..fd20775 100644
--- a/doc/s6_set.html
+++ b/doc/s6_set.html
@@ -21,8 +21,8 @@
<p>
<tt>s6 set</tt> regroups actions on
-<a href="//skarnet.org/software/s6-rc/repodefs.html#set>service sets</a>,
-telling the service manager what service should be enabled or disabled
+<a href="//skarnet.org/software/s6-rc/repodefs.html#set">service sets</a>,
+telling the service manager what services should be enabled or disabled
at boot time, or even should be masked, i.e. should not even appear in
the list of services available at next boot.
</p>
@@ -40,30 +40,22 @@ which is internally named <tt>current</tt>. It is not the set that is
currently live; it is the set that is currently worked on.
</p>
-<div id="interface">
-<h2> Interface </h2>
-</div>
+<h2 id="interface"> Interface </h2>
<pre>
s6 set <em>subcommand</em> [ <em>subcommand_options...</em> ] [ <em>args...</em> ]
</pre>
-<div id="subcommands">
-<h2> Subcommands </h2>
-</div>
+<h2 id="subcommands"> Subcommands </h2>
-<div id="help">
-<h3> help </h3>
-</div>
+<h3 id="help"> help </h3>
<p>
<tt>s6 set help</tt> prints a short help message summarizing the options
and usage of the <tt>s6 set</tt> command. It is not as detailed as this page.
</p>
-<div id="save">
-<h3> save </h3>
-</div>
+<h3 id="save"> save </h3>
<h4> Interface </h4>
@@ -74,7 +66,7 @@ and usage of the <tt>s6 set</tt> command. It is not as detailed as this page.
<ul>
<li> <tt>s6 set save</tt> saves a copy of the current working set into a
set named <em>name</em>. </li>
- <li> <em>name</em> can be loaded by <a href="#load"><tt>s6 set load <em>name</em></a>. </li>
+ <li> <em>name</em> can be loaded by <a href="#load"><tt>s6 set load <em>name</em></tt></a>. </li>
</ul>
<h4> Options </h4>
@@ -85,9 +77,7 @@ set named <em>name</em>. </li>
of the current working set. By default, the command exits with an error
instead of overwriting. </dd>
-<div id="load">
-<h3> load </h3>
-</div>
+<h3 id="load"> load </h3>
<h4> Interface </h4>
@@ -101,9 +91,7 @@ as <em>name</em>. </li>
<li> No options are defined. </li>
</ul>
-<div id="list">
-<h3> list </h3>
-</div>
+<h3 id="list"> list </h3>
<h4> Interface </h4>
@@ -128,9 +116,7 @@ default. </dd>
<dd> Do not list essential services. </dd>
</dl>
-<div id="status">
-<h3> list </h3>
-</div>
+<h3 id="status"> status </h3>
<h4> Interface </h4>
@@ -188,7 +174,7 @@ default. </dd>
<div id="mask">
<div id="unmask">
<div id="make-essential">
-<h3> enable, disable, mask, unmask, make-essential </h3>
+<h3 id="change"> enable, disable, mask, unmask, make-essential </h3>
</div></div></div></div></div>
<h4> Interface </h4>
@@ -223,7 +209,7 @@ make the set inconsistent. </li>
<dd> Do not perform the change; only show what would be done and check whether the set
would be made inconsistent. </dd>
-<dt> -I <em>what</tt>, --if-dependencies-found=<em>what</em> </dt>
+<dt> -I <em>what</em>, --if-dependencies-found=<em>what</em> </dt>
<dd> What to do when services have dependencies, or reverse dependencies, that are not
listed in <em>services...</em>. <em>what</em> can be <tt>fail</tt>, <tt>warn</tt>,
or <tt>pull</tt>.
@@ -248,9 +234,7 @@ allow the user to tailor the boot sequence to their needs without touching the
currently running database.
</p>
-<div id="check">
-<h3> check </h3>
-</div>
+<h3 id="check"> check </h3>
<h4> Interface </h4>
@@ -294,9 +278,7 @@ depends on service <tt>B</tt> and <tt>A</tt> is unmasked or enabled,
change <tt>B</tt> to be unmasked or enabled as well. </dd>
</dl>
-<div id="commit">
-<h3> commit </h3>
-</div>
+<h3 id="commit"> commit </h3>
<h4> Interface </h4>
diff --git a/doc/s6_system.html b/doc/s6_system.html
index 10d52d7..a226a27 100644
--- a/doc/s6_system.html
+++ b/doc/s6_system.html
@@ -24,9 +24,7 @@
the system.
</p>
-<div id="interface">
-<h2> Interface </h2>
-</div>
+<h2 id="interface"> Interface </h2>
<pre>
s6 system <em>subcommand</em>
@@ -36,22 +34,16 @@ the system.
<li> No subcommand takes any options. </li>
</ul>
-<div id="subcommands">
-<h2> Subcommands </h2>
-</div>
+<h2 id="subcommands"> Subcommands </h2>
-<div id="help">
-<h3> help </h3>
-</div>
+<h3 id="help"> help </h3>
<p>
<tt>s6 system help</tt> prints a short help message summarizing the options
and usage of the <tt>s6 system</tt> command. It is not as detailed as this page.
</p>
-<div id="boot">
-<h3> boot </h3>
-</div>
+<h3 id="boot"> boot </h3>
<h4> Interface </h4>
@@ -68,18 +60,40 @@ a state where everything the user wants is running. </li>
program hands off duties.
<ul>
<li> On a system making use of
-<a href="//skarnet.org/software/s6-linux-init/">s6-linux-init/a>,
-<tt>s6 system boot</tt> should be the sole command defined in the
-<tt>/etc/rc.init</tt> script. </li>
- <li> On a system using <tt>/etc/inittab</tt>, the first line
-of the inittab should be: <tt>::wait:/usr/bin/s6 system boot</tt> </li>
+<a href="//skarnet.org/software/s6-linux-init/">s6-linux-init</a>,
+<tt>s6 system boot</tt> should be run by the
+<tt>/etc/rc.init</tt> script. No other command needs to appear in
+that script. </li>
+ <li> On a system using <tt>/etc/inittab</tt>, you need to add
+two lines at the beginning of <tt>/etc/inittab</tt>:
+ <ul>
+ <li> The first line should be a command that runs and respawns
+<a href="//skarnet.org/software/s6/s6-svscan.html">s6-svscan</a>,
+ideally with a catch-all logger. This could be something like
+<tt>::respawn:/usr/lib/s6/s6-svscanboot</tt>, with <tt>/usr/lib/s6/s6-svscanboot</tt>
+being similar to the script used
+<a href="https://gitlab.alpinelinux.org/alpine/aports/-/blob/master/main/s6/s6-svscanboot?ref_type=heads">in
+Alpine Linux</a> to start an instance of s6-svscan supervising its own
+catch-all logger. </li>
+ <li> The second line should be <tt>::wait:/usr/bin/s6 system boot</tt>. </li>
+ <li> For complete safety, there should be a synchronization mechanism so
+that the second line never starts before s6-svscan is ready. A quick and (very) dirty
+way to synchronize is polling on s6-svscan before running the
+command: <tt>::wait:until s6-svscanctl /run/service 2&gt;/dev/null; do :; done &amp;&amp; exec /usr/bin/s6 system boot</tt> </li>
+ </ul> </li>
+ <li> It is also possible to run a complete s6 ecosystem under systemd, but it is redundant,
+so it's unlikely that anyone would want to do it. For the sake of completeness,
+the way would be to define two unit files: the first one to launch s6-svscan, as
+documented <a href="//skarnet.org/software/s6/s6-svscan-not-1.html">here</a>,
+and the second one, specified to run <em>after</em> the first one, to run
+the <tt>s6 system boot</tt> command as a one-shot. </li>
</ul> </li>
</ul>
<p>
The rest of the subcommands are shutdown subcommands, and they
only work if the machine makes use of
-<a href="//skarnet.org/software/s6-linux-init/">s6-linux-init/a> and
+<a href="//skarnet.org/software/s6-linux-init/">s6-linux-init</a> and
s6-frontend has been configured to support it. On a machine that
does not boot via s6-linux-init, a shutdown should be executed via
the shutdown commands provided by your init system. In order for
@@ -90,9 +104,7 @@ following line should appear in <tt>/etc/inittab</tt>:
<code>::shutdown:/usr/bin/s6 live stop_everything -E</code>
</p>
-<div id="reboot">
-<h3> reboot </h3>
-</div>
+<h3 id="reboot"> reboot </h3>
<h4> Interface </h4>
@@ -103,13 +115,11 @@ following line should appear in <tt>/etc/inittab</tt>:
<ul>
<li> <tt>s6 system reboot</tt> reboots the machine.
<li> This only works if the machine makes use of
-<a href="//skarnet.org/software/s6-linux-init/">s6-linux-init/a> and
+<a href="//skarnet.org/software/s6-linux-init/">s6-linux-init</a> and
s6-frontend has been configured to support it. </li>
</ul>
-<div id="poweroff">
-<h3> poweroff </h3>
-</div>
+<h3 id="poweroff"> poweroff </h3>
<h4> Interface </h4>
@@ -121,13 +131,11 @@ s6-frontend has been configured to support it. </li>
<li> <tt>s6 system poweroff</tt> halts the system and turns the
power off. </li>
<li> This only works if the machine makes use of
-<a href="//skarnet.org/software/s6-linux-init/">s6-linux-init/a> and
+<a href="//skarnet.org/software/s6-linux-init/">s6-linux-init</a> and
s6-frontend has been configured to support it. </li>
</ul>
-<div id="halt">
-<h3> halt </h3>
-</div>
+<h3 id="halt"> halt </h3>
<h4> Interface </h4>
@@ -139,7 +147,7 @@ s6-frontend has been configured to support it. </li>
<li> <tt>s6 system halt</tt> halts the system without turning
the power off. </li>
<li> This only works if the machine makes use of
-<a href="//skarnet.org/software/s6-linux-init/">s6-linux-init/a> and
+<a href="//skarnet.org/software/s6-linux-init/">s6-linux-init</a> and
s6-frontend has been configured to support it. </li>
</ul>
diff --git a/src/s6-frontend/live.help.txt b/src/s6-frontend/live.help.txt
index 88d51ca..3d4a9aa 100644
--- a/src/s6-frontend/live.help.txt
+++ b/src/s6-frontend/live.help.txt
@@ -22,6 +22,7 @@ s6 live install options:
-b --block on contention, wait rather than fail
-K --keep-old keep the old db and write its path to stdout
-f FILE --conversion-file=FILE use a conversion file from current to new set
+ --init install the initial db. DO NOT USE WHEN LIVE.
s6 live start-everything options:
-n --dry-run only show what would be done, don't do it
diff --git a/src/s6-frontend/live_install.c b/src/s6-frontend/live_install.c
index 6c85b96..7da1759 100644
--- a/src/s6-frontend/live_install.c
+++ b/src/s6-frontend/live_install.c
@@ -12,6 +12,7 @@ enum golb_e
{
GOLB_BLOCK = 0x01,
GOLB_KEEPOLD = 0x02,
+ GOLB_INIT = 0x04,
} ;
enum gola_e
@@ -26,6 +27,7 @@ void live_install (char const *const *argv)
{
{ .so = 'b', .lo = "block", .clear = 0, .set = GOLB_BLOCK },
{ .so = 'K', .lo = "keep-old", .clear = 0, .set = GOLB_KEEPOLD },
+ { .so = 0, .lo = "init", .clear = 0, .set = GOLA_INIT },
} ;
static gol_arg const rgola[] =
{
@@ -34,7 +36,7 @@ void live_install (char const *const *argv)
uint64_t wgolb = 0 ;
unsigned int m = 0 ;
char const *wgola[GOLA_N] = { 0 } ;
- char const *newargv[16] ;
+ char const *newargv[17] ;
char fmtv[UINT_FMT] ;
argv += GOL_argv(argv, rgolb, rgola, &wgolb, wgola) ;
@@ -60,6 +62,7 @@ void live_install (char const *const *argv)
newargv[m++] = "-f" ;
newargv[m++] = wgola[GOLA_CONVFILE] ;
}
+ if (wgolb & GOLB_INIT) newargv[m++] = "--no-update" ;
newargv[m++] = "--" ;
newargv[m++] = "current" ;
newargv[m++] = 0 ;
generated by cgit v1.3.1 (git 2.54.0) at 2026-06-26 22:20:54 +0000