Add repository_check; add basic documentation

author: Laurent Bercot <ska-skaware@skarnet.org> 2026-01-11 02:54:05 +0000
committer: Laurent Bercot <ska-skaware@skarnet.org> 2026-01-11 02:54:05 +0000
commit: 5876e2f9e260ef46330edfa6f258c6d88b7e5d50 (patch)
tree: 4e56a24bdbcfd9bf9bc39cbb1a4d6fc5fec74a74 /doc/s6.html
parent: e135a92c11f1fe1e13c1c17df6616bae56d215e8 (diff)
download: s6-frontend-5876e2f9e260ef46330edfa6f258c6d88b7e5d50.tar.gz
1 files changed, 281 insertions, 0 deletions
diff --git a/doc/s6.html b/doc/s6.html
new file mode 100644
index 0000000..8f1012f
--- /dev/null
+++ b/doc/s6.html
@@ -0,0 +1,281 @@
+<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: the s6 program</title>
+    <meta name="Description" content="s6-frontend: the s6 program" />
+    <meta name="Keywords" content="s6 ecosystem supervision service manager user interface init skarnet.org skarnet software" />
+    <!-- <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> The <tt>s6</tt> program </h1>
+
+<p>
+ <tt>s6</tt> is a generic command-line utility that can be used to
+interact with a system managed by the
+<a href="//skarnet.org/software/s6/">s6 process supervision system</a>, the
+<a href="//skarnet.org/software/s6-rc/">s6-rc service manager</a>, and optionally the
+<a href="//skarnet.org/software/s6-linux-init/">s6-linux-init boot program</a>.
+</p>
+
+<div id="interface">
+<h2> Interface </h2>
+</div>
+
+<pre>
+     s6 [ <em>global_options...</em> ] <em>command</em> <em>subcommand</em> [ <em>subcommand_options...</em> ] [ <em>args...</em> ]
+</pre>
+
+<ul>
+ <li> s6 reads its configuration file. </li>
+ <li> It reads from the command line, in this order: global options,
+a command, a subcommand, potentially subcommand options, and potentially
+arguments to the command and subcommand. </li>
+ <li> It performs various operations, typically invoking binaries from
+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>
+
+<p>
+ s6 always exits 0 on success, 100 on bad usage, and 111 on a system call
+failure.
+</p>
+
+<p>
+ Since it can exec into a wide variety of commands belonging to various
+parts of the s6 family of programs, it is difficult to list all its possible
+exit codes exhaustively. However, in case of an error, the name of the
+subprogram where the error occurred is always printed on stderr; you can then
+consult the documentation for said subprogram, which will have the explanation
+for all its exit codes. For instance, if an invocation of <tt>s6</tt> prints
+a message such as <code>s6-rc: fatal: unable to start service foobar</code>,
+it means that s6 invoked the <a href="//skarnet.org/software/s6-rc/s6-rc.html">s6-rc</a>
+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>
+
+<ul>
+ <li> s6 reads the <code>S6_FRONTEND_CONF</code> environment variable. This
+variable contains the absolute path to the
+<a href="s6-frontend.conf.html">configuration file</a> for the s6 command. </li>
+ <li> If this variable is unset, the default is <tt>/etc/s6-frontend.conf</tt>
+possibly overridden by the <tt>--conffile</tt> build-time configure option to
+s6-frontend. </li>
+</ul>
+
+<div id="options">
+<h2> Global options </h2>
+</div>
+
+<p>
+ <em>global_options...</em> is a list of options that modify s6's behaviour
+and policies. They should generally not be used; instead, the behaviour should
+be set in the <a href="s6-frontend.conf.html">configuration file</a>.
+Nevertheless, if you need to override the configuration file settings for some
+reason, here you go.
+</p>
+
+<dl>
+ <dt> -h, --help </dt>
+ <dd> Run the <a href="#s6_help"><tt>s6 help</tt></aa> command.
+Any given command or subcommand is ignored. </dd>
+
+ <dt> -V, --version </dt>
+ <dd> Run the <a href="#s6_version"><tt>s6 version</tt></aa> command.
+ <dd> Any given command or subcommand is ignored. </dd>
+
+ <dt> -s <em>scandir</em>, --scandir=<em>scandir</em> </dt>
+ <dd> Use <em>scandir</em> as scan directory (i.e. the directory where
+<a href="//skarnet.org/software/s6/s6-svscan.html">s6-svscan</a> runs
+and supervises service directories),
+overriding the value of <em>scandir</em>
+defined in <a href="s6-frontend.conf.html">s6-frontend.conf</a>. </dd>
+
+ <dt> -l <em>livedir</em>, --livedir=<em>livedir</em> </dt>
+ <dd> Use <em>livedir</em> as live directory (i.e. the directory where
+<a href="//skarnet.org/software/s6-rc/s6-rc.html">s6-rc</a> keeps tabs
+on the machine state and stores its runtime information),
+and supervises service directories),
+overriding the value of <em>livedir</em>
+defined in <a href="s6-frontend.conf.html">s6-frontend.conf</a>. </dd>
+
+ <dt> -r <em>repodir</em>, --repodir=<em>repodir</em> </dt>
+ <dd> Use <em>repodir</em> as s6-rc repository (i.e. the directory where
+the <a href="//skarnet.org/software/s6-rc/repodefs.html">repo</a> commands
+of the <a href="//skarnet.org/software/s6-rc/">s6-rc</a> package store
+and manipulate their service sets),
+overriding the value of <em>repodir</em>
+defined in <a href="s6-frontend.conf.html">s6-frontend.conf</a>. </dd>
+
+ <dt> -c <em>bootdb</em>, --bootdb=<em>bootdb</em> </dt>
+ <dd> Use <em>bootdb</em> as the name of the compiled service database
+used by s6-rc at boot time (i.e. the directory where
+the <a href="//skarnet.org/software/s6-rc/s6-rc.html">s6-rc</a> reads
+information on how to start all the wanted services)
+overriding the value of <em>bootdb</em>
+defined in <a href="s6-frontend.conf.html">s6-frontend.conf</a>. </dd>
+
+ <dt> --stmpdir=<em>stmpdir</em> </dt>
+ <dd> Use <em>stmpdir</em> to store runtime s6-frontend data and
+temporary files,
+overriding the value of <em>stmpdir</em>
+defined in <a href="s6-frontend.conf.html">s6-frontend.conf</a>. </dd>
+
+ <dt> --storelist=<em>storelist</em> </dt>
+ <dd> Use <em>storelist</em> as list of
+<a href="//skarnet.org/software/s6-rc/repodefs.html#store">stores</a>,
+overriding the value of <em>storelist</em>
+defined in <a href="s6-frontend.conf.html">s6-frontend.conf</a>. </dd>
+
+ <dt> -v <em>verbosity</em>, --verbosity=<em>verbosity</em> </dt>
+ <dd> Use <em>verbosity</em> as numerical verbosity value,
+overriding the value of <em>verbosity</em>
+defined in <a href="s6-frontend.conf.html">s6-frontend.conf</a>. </dd>
+
+ <dt> --color=yes|no|auto </dt>
+ <dd> Use fancy output (which may or may not involve color): always if
+<tt>yes</tt>, never if <tt>no</tt>, and only when stdout is a terminal
+if <tt>auto</tt>. Not all commands and subcommands will use this
+setting. Also, for pretty-printing of columns, it is recommended to
+have built s6-frontend with util-linux support. </dd>
+</dl>
+
+
+<div id="commands">
+<h2> Commands </h2>
+</div>
+
+<div id="s6_help">
+<h3> help </h3>
+</div>
+
+<p>
+ <tt>s6 help</tt> prints a short help message summarizing the options
+and usage of the s6 command. It is not as detailed as this page.
+</p>
+
+<p>
+ No subcommands are defined.
+</p>
+
+<div id="s6_version">
+<h3> version </h3>
+</div>
+
+<p>
+ <tt>s6 version</tt> prints the current version of s6-frontend, on one line.
+</p>
+
+<p>
+ No subcommands are defined.
+</p>
+
+<div id="s6_process">
+<h3> process </h3>
+</div>
+
+<p>
+ <tt>s6 process</tt> sends commands to long-running processes supervised by the
+<a href="//skarnet.org/software/s6/">s6 supervision suite</a>. The details are
+available <a href="s6_process.html">here</a>.
+</p>
+
+<p>
+ <a href="s6_process.html"><tt>s6 process</tt></a> is typically used when a daemon
+needs to be restarted or otherwise addressed without involvement from the service
+manager, i.e. without having to start or stop dependencies.
+</p>
+
+<div id="s6_live">
+<h3> live </h3>
+</div>
+
+<p>
+ <tt>s6 live</tt> controls the live state of the machine, starting and stopping
+services, installing a new set of services, etc. It is mostly an interface
+around the 
+<a href="//skarnet.org/software/s6-rc/">s6-rc service manager</a>. The details are
+available <a href="s6_live.html">here</a>.
+</p>
+
+<div id="s6_repository">
+<h3> repository </h3>
+</div>
+
+<p>
+ <tt>s6 repository</tt> regroups administrative tasks related to the repository
+of service sets, typically synchronization with the service stores when the
+package manager updates service definitions. It is not often directly used by
+sysadmins, but is an essential part of distribution scripts, when they create
+the initial layout, run their package manager, etc.
+</p>
+
+<p>
+The details are available <a href="s6_repository.html">here</a>.
+</p>
+
+<div id="s6_set">
+<h3> set </h3>
+</div>
+
+<p>
+ <tt>s6 set</tt> is the interface to the creation and manipulation of service sets by
+the user. It is how they define what service will be enabled or disabled at boot
+time. This manipulation occurs <em>offline</em>: service sets being worked on are distinct from
+the live state of the machine, accessible via <a href="#s6_live"><tt>s6 live</tt></a> commands.
+
+<p>
+The details are available <a href="s6_set.html">here</a>.
+</p>
+
+<div id="s6_system">
+<h3> system </h3>
+</div>
+
+<p>
+ <tt>s6 system</tt> provides commands to run at boot and, on systems fully managed by s6,
+to shut the system down.
+The details are available <a href="s6_system.html">here</a>.
+</p>
+
+<div id="notes">
+<h2> Notes </h2>
+</div>
+
+<ul>
+ <li> <tt>s6</tt> does not perform real operations itself. Instead, after
+finding the path to its <a href="s6-frontend.conf.html">configuration file</a>
+<em>conf</em>, it rewrites itself into <code>envfile -I <em>conf</em></code> -- s6-frontend
+<em>global_options...</em> <em>command</em> <em>subcommand</em> <em>subcommand_options...</em> <em>args...</em></code>
+  <ul>
+   <li> <a href="//skarnet.org/software/execline/envfile.html">envfile</a> reads and parses <em>conf</em> </li>
+   <li> <a href="s6-frontend.html">s6-frontend</a> is the binary that does the real work of
+parsing options, command, subcommand, etc. and dispatching orders. </li>
+  </ul>
+</ul>
+
+</body>
+</html>
author	Laurent Bercot <ska-skaware@skarnet.org>	2026-01-11 02:54:05 +0000
committer	Laurent Bercot <ska-skaware@skarnet.org>	2026-01-11 02:54:05 +0000
commit	5876e2f9e260ef46330edfa6f258c6d88b7e5d50 (patch)
tree	4e56a24bdbcfd9bf9bc39cbb1a4d6fc5fec74a74 /doc/s6.html
parent	e135a92c11f1fe1e13c1c17df6616bae56d215e8 (diff)
download	s6-frontend-5876e2f9e260ef46330edfa6f258c6d88b7e5d50.tar.gz