add getserviceflags and use it in fillset; add some doc

author: Laurent Bercot <ska-skaware@skarnet.org> 2025-10-21 18:03:48 +0000
committer: Laurent Bercot <ska-skaware@skarnet.org> 2025-10-21 18:03:48 +0000
commit: 3b9836248ed7f5164140d63e96ece21973fc43f7 (patch)
tree: 193242a4b634c84d712d8260e7707eae1be53601 /doc
parent: d71f18b44e4168e2d942b503110af5b5314364b5 (diff)
download: s6-rc-3b9836248ed7f5164140d63e96ece21973fc43f7.tar.gz
7 files changed, 456 insertions, 4 deletions
diff --git a/doc/s6-rc-compile.html b/doc/s6-rc-compile.html
index e1ad82b..11ecb38 100644
--- a/doc/s6-rc-compile.html
+++ b/doc/s6-rc-compile.html
@@ -109,9 +109,14 @@ directory. </li>
  <li> An optional regular file named <tt>flag-essential</tt>. The contents of this
 file are irrelevant, only its presence is tested. If this file exists, the service
 will be marked as essential, which means that a <tt>s6-rc -d change <em>foo</em></tt>
-command will not stop the service. Only a <tt>s6-rc -D change <em>foo</em></tt>
+command will not stop the service; only a <tt>s6-rc -D change <em>foo</em></tt>
 command will. If the service is a bundle, the flag will be propagated to all its
-contents, i.e. all the services it represents will be marked as essential. </li>
+contents, i.e. all the services it represents will be marked as essential.
+ </li>
+ <li> An optional regular file named <tt>flag-recommended</tt>. The contents of this
+file are irrelevant, only its presence is tested. If this file exists, the service
+will be marked as recommended. This is only important for
+<a href="repodefs.html">repo</a> commands, not when compiling the database. </li>
 </ul>
 
 <h3> For bundles </h3>
diff --git a/doc/s6-rc-db.html b/doc/s6-rc-db.html
index bc527a6..4794be6 100644
--- a/doc/s6-rc-db.html
+++ b/doc/s6-rc-db.html
@@ -222,10 +222,29 @@ for atomic service <em>atomicname</em>.
 </p>
 
 <p>
- Those binary flags are currently unused, but this may change in a
-future version of s6-rc.
+ Those binary flags are used by <a href="repodefs.html">repo</a>
+commands:
 </p>
 
+<ul>
+ <li> Bit 0 is set if there's a <tt>flag-essential</tt> file in the
+source directory (or if the "essential" flag was inherited from a
+bundle). It means the service cannot be downed by normal means:
+<code>s6-rc -d change <em>atomicname</em></code> will not work,
+the <tt>-D</tt> option to s6-rc is needed. Additionally, when
+importing <em>atomicname</em> in a <a href="repodefs.html#set">set</a>,
+it will automatically be put in the <tt>always</tt> sub, which means
+it will always be enabled by default. </li>
+ <li> Bit 1 is set if there's a <tt>flag-recommended</tt> file in the
+source directory (or if the "essential" flag was inherited from a
+bundle). When
+importing <em>atomicname</em> in a <a href="repodefs.html#set">set</a>,
+it will automatically be put in the <tt>active</tt> sub rather than the
+<tt>latent</tt> one: unless the user actively makes a change before
+committing the set, <em>atomicname</em> will be in the default bundle
+and be started at boot time. </li>
+</ul>
+
 <h3> s6-rc-db atomics <em>servicename...</em> </h3>
 
 <p>
diff --git a/doc/s6-rc-repo-init.html b/doc/s6-rc-repo-init.html
new file mode 100644
index 0000000..22baf52
--- /dev/null
+++ b/doc/s6-rc-repo-init.html
@@ -0,0 +1,111 @@
+<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-rc: the s6-rc-repo-init program</title>
+    <meta name="Description" content="s6-rc: the s6-rc-repo-init program" />
+    <meta name="Keywords" content="s6-rc repo init initialisation update setup repository" />
+    <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
+  </head>
+<body>
+
+<p>
+<a href="index.html">s6-rc</a><br />
+<a href="//skarnet.org/software/">Software</a><br />
+<a href="//skarnet.org/">skarnet.org</a>
+</p>
+
+<h1> The s6-rc-repo-init program </h1>
+
+<p>
+ s6-rc-repo-init initializes a <a href="repodefs.html#repository">repository</a>
+on a system, linking it to a list of <a href="repodefs.html#store">stores</a>
+and ensuring that the set of all services defined in all the stores is
+consistent.
+</p>
+
+<h2> Interface </h2>
+
+<pre>
+     s6-rc-repo-init [ -v <em>verbosity</em> ] [ -r <em>repo</em> ] [ -h <em>fdhuser</em> ] [ -f ] [ -U ] [ -B ] <em>stores...</em>
+</pre>
+
+<ul>
+ <li> s6-rc-repo-init creates an s6-rc repository at location <em>repo</em>. </li>
+ <li> It makes <em>stores...</em> (which must be a list of several locations in the
+filesystem) the current list of stores for this repository. </li>
+ <li> It synchronizes with the list of stores, as if
+<a href="s6-rc-repo-sync.html">s6-rc-repo-sync</a> had been called. That means
+that it imports all the services in the stores and builds the
+<a href="repodefs.html#refdb">reference database</a>. </li>
+ <li> It exits 0. </li>
+</ul>
+
+<h2> Options </h2>
+
+<dl>
+ <dt> -v <em>verbosity</em>, --verbosity=<em>verbosity</em> </dt>
+ <dd> Be more or less verbose. The default is <strong>1</strong>, which means
+that error messages and warnings will be written to stderr. 0 means that only
+error messages will be written, and 2 or more adds informational messages.
+The option is also passed to commands that s6-rc-repo-init may call, such
+as <a href="s6-rc-compile.html">s6-rc-compile</a>, so their verbosity will
+be similarly adjusted. </dd>
+
+ <dt> -r <em>repo</em>, --repository=<em>repo</em> </dt>
+ <dd> Create the repository in <em>repo</em>. Default is
+<strong>/var/lib/s6-rc/repository</strong>. Unless the <tt>-U</tt> option is
+given, <em>repo</em> must not previously exist in the filesystem.
+ </dd>
+
+ <dt> -h <em>fdhuser</em>, --fdholder-user=<em>fdhuser</em> </dt>
+ <dd> You can safely ignore this option and forget about it. What it does
+is ensure that if a supervision tree is started as root on a compiled
+database produced by this command (this will never happen to the reference
+database, so it is only ever useful together with the <tt>-U</tt>
+option when there are sets to update), the fd-holder daemon in that
+supervision tree runs as <em>fdhuser</em> rather than root. Told you:
+you can safely forget about that option. </dd>
+
+ <dt> -f, --force </dt>
+ <dd> Make a new repository at <em>repo</em> even if one already exists.
+This is dangerous, use of this option is not recommended. </dd>
+
+ <dt> -U, --update-stores </dt>
+ <dd> Rather than create a new repository, change the list of stores in an
+existing one. This is useful, for instance, when a distribution's policies
+change and local stores are added, moved, or removed. It is not an operation
+that should be done frequently, however. </dd>
+
+ <dt> -B, --bare </dt>
+ <dd> Do not synchronize the repository with the stores. This is
+useful if you are going to call
+<a href="s6-rc-repo-sync.html">s6-rc-repo-sync</a> afterwards anyway. </dd>
+</dl>
+
+<h2> Exit codes </h2>
+
+<dl>
+ <dt> 0 </dt> <dd> Success. </dd>
+ <dt> 1 </dt> <dd> Failure. The services in the listed stores do not make a
+consistent reference database. With a nonzero <em>verbosity</em>, the error
+messages from <a href="s6-rc-compile.html">s6-rc-compile</a> will be displayed
+and detail exactly what went wrong. </dd>
+ <dt> 100 </dt> <dd> Incorrect usage. </dd>
+ <dt> 111 </dt> <dd> System call failed. This usually signals an issue with the
+underlying operating system. </dd>
+</dl>
+
+<h2> Notes </h2>
+
+<ul>
+ <li> s6-rc-repo-init is the first command to invoke when creating a repository,
+or when a change occurs within the stores. </li>
+ <li> There is generally only one repository per system, but non-root users
+who would want to run their own tree of s6-rc services can do so by specifying
+an alternative <em>repo</em>. </li>
+</ul>
+
+</body>
+</html>
diff --git a/doc/s6-rc-repo-sync.html b/doc/s6-rc-repo-sync.html
new file mode 100644
index 0000000..cc2501b
--- /dev/null
+++ b/doc/s6-rc-repo-sync.html
@@ -0,0 +1,100 @@
+<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-rc: the s6-rc-repo-sync program</title>
+    <meta name="Description" content="s6-rc: the s6-rc-repo-sync program" />
+    <meta name="Keywords" content="s6-rc repo sync synchronization update set store repository" />
+    <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
+  </head>
+<body>
+
+<p>
+<a href="index.html">s6-rc</a><br />
+<a href="//skarnet.org/software/">Software</a><br />
+<a href="//skarnet.org/">skarnet.org</a>
+</p>
+
+<h1> The s6-rc-repo-sync program </h1>
+
+<p>
+ s6-rc-repo-sync synchronizes a <a href="repodefs.html#repository">repository</a>,
+which means making an up-to-date <a href="repodefs.html#refdb">reference
+database</a>, and ensuring that all defined
+<a href="repodefs.html#set">sets</a> include all the services in the
+repository's stores, and only them.
+</p>
+
+<h2> Interface </h2>
+
+<pre>
+     s6-rc-repo-sync [ -v <em>verbosity</em> ] [ -r <em>repo</em> ] [ -h <em>fdhuser</em> ]
+</pre>
+
+<ul>
+ <li> s6-rc-repo-sync looks at all the services defined in the repository's
+<a href="repodefs.html#store">stores</a>, and compiles them into a
+<a href="repodefs.html#refdb">reference database</a>. </li>
+ <li> It then looks at all the <a href="repodefs.html#set">sets</a>
+and synchronizes them with the services in all the stores:
+  <ul>
+   <li> Existing services are preserved as they are. </li>
+   <li> If a service doesn't appear in the stores, it is removed from all sets. </li>
+   <li> If a new service is defined in the stores, it is added to all sets. Services
+with the <em>essential</em> flag are added to the <tt>always</tt>
+<a href="repodefs.html#sub">sub</a>; services with
+the <em>recommended</em> flag are added to the <tt>active</tt> sub; others are added
+to the <tt>usable</tt> sub. </li>
+  </ul> </li>
+ <li> It exits 0. </li>
+</ul>
+
+<h2> Options </h2>
+
+<dl>
+ <dt> -v <em>verbosity</em>, --verbosity=<em>verbosity</em> </dt>
+ <dd> Be more or less verbose. The default is <strong>1</strong>, which means
+that error messages and warnings will be written to stderr. 0 means that only
+error messages will be written, and 2 or more adds informational messages.
+The option is also passed to commands that s6-rc-repo-sync may call, such
+as <a href="s6-rc-compile.html">s6-rc-compile</a>, so their verbosity will
+be similarly adjusted. </dd>
+
+ <dt> -r <em>repo</em>, --repository=<em>repo</em> </dt>
+ <dd> Use the repository in <em>repo</em>, which must exist. Default is
+<strong>/var/lib/s6-rc/repository</strong>.
+ </dd>
+
+ <dt> -h <em>fdhuser</em>, --fdholder-user=<em>fdhuser</em> </dt>
+ <dd> You can safely ignore this option and forget about it. What it does
+is ensure that if a supervision tree is started as root on a compiled
+database produced by this command, the fd-holder daemon in that
+supervision tree runs as <em>fdhuser</em> rather than root. (It is okay
+to run that daemon as root.) </dd>
+</dl>
+
+<h2> Exit codes </h2>
+
+<dl>
+ <dt> 0 </dt> <dd> Success. </dd>
+ <dt> 1 </dt> <dd> Failure. Either the services in the listed stores do not make a
+consistent reference database, or some set is inconsistent.
+With a nonzero <em>verbosity</em>, the error messages from
+<a href="s6-rc-compile.html">s6-rc-compile</a> will be displayed
+and detail exactly what went wrong. </dd>
+ <dt> 100 </dt> <dd> Incorrect usage. </dd>
+ <dt> 111 </dt> <dd> System call failed. This usually signals an issue with the
+underlying operating system. </dd>
+</dl>
+
+<h2> Notes </h2>
+
+<ul>
+ <li> s6-rc-repo-sync should be called when the contents of the stores have
+changed, for instance when the package manager has added packages that define
+new services. </li>
+</ul>
+
+</body>
+</html>
diff --git a/doc/s6-rc-set-copy.html b/doc/s6-rc-set-copy.html
new file mode 100644
index 0000000..9d0681c
--- /dev/null
+++ b/doc/s6-rc-set-copy.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-rc: the s6-rc-set-copy program</title>
+    <meta name="Description" content="s6-rc: the s6-rc-set-copy program" />
+    <meta name="Keywords" content="s6-rc s6-rc-set-copy repo set sub copy services" />
+    <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
+  </head>
+<body>
+
+<p>
+<a href="index.html">s6-rc</a><br />
+<a href="//skarnet.org/software/">Software</a><br />
+<a href="//skarnet.org/">skarnet.org</a>
+</p>
+
+<h1> The s6-rc-set-copy program </h1>
+
+<p>
+ s6-rc-set-copy makes a copy of a <a href="repodefs.html#set">set</a> under a
+different name, in a <a href="repodefs.html#repository">repository</a>.
+</p>
+
+<h2> Interface </h2>
+
+<pre>
+     s6-rc-set-copy [ -v <em>verbosity</em> ] [ -r <em>repo</em> ] [ -f ] <em>src</em> <em>dst</em>
+</pre>
+
+<ul>
+ <li> s6-rc-set-copy makes an exact copy of set <em>src</em> and names it <em>dst</em>. </li>
+ <li> It exits 0. </li>
+</ul>
+
+<h2> Options </h2>
+
+<dl>
+ <dt> -v <em>verbosity</em>, --verbosity=<em>verbosity</em> </dt>
+ <dd> Be more or less verbose. The default is <strong>1</strong>, which means
+that error messages and warnings will be written to stderr. 0 means that only
+error messages will be written, and 2 or more adds informational messages. </dd>
+
+ <dt> -r <em>repo</em>, --repository=<em>repo</em> </dt>
+ <dd> Use the repository in <em>repo</em>, which must exist. Default is
+<strong>/var/lib/s6-rc/repository</strong>.
+ </dd>
+
+ <dt> -f, --force </dt>
+ <dd> Overwrite set <em>dst</em> if it exists. </dd>
+</dl>
+
+<h2> Exit codes </h2>
+
+<dl>
+ <dt> 0 </dt> <dd> Success. </dd>
+ <dt> 1 </dt> <dd> Set <em>dst</em> already exists and the <tt>-f</tt> option has not been given. </dd>
+ <dt> 100 </dt> <dd> Incorrect usage. </dd>
+ <dt> 102 </dt> <dd> Inconsistent repository. </dd>
+ <dt> 111 </dt> <dd> System call failed. </dd>
+</dl>
+
+<h2> Notes </h2>
+
+<ul>
+ <li> s6-rc-set-copy can be used to create a dynamic working set, to be copied back
+to its source when the user is happy with the changes. </li>
+</ul>
+
+</body>
+</html>
diff --git a/doc/s6-rc-set-delete.html b/doc/s6-rc-set-delete.html
new file mode 100644
index 0000000..efb1820
--- /dev/null
+++ b/doc/s6-rc-set-delete.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-rc: the s6-rc-set-delete program</title>
+    <meta name="Description" content="s6-rc: the s6-rc-set-delete program" />
+    <meta name="Keywords" content="s6-rc s6-rc-set-delete repo set sub deletion services" />
+    <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
+  </head>
+<body>
+
+<p>
+<a href="index.html">s6-rc</a><br />
+<a href="//skarnet.org/software/">Software</a><br />
+<a href="//skarnet.org/">skarnet.org</a>
+</p>
+
+<h1> The s6-rc-set-delete program </h1>
+
+<p>
+ s6-rc-set-delete deletes a whole <a href="repodefs.html#set">set</a>
+from a <a href="repodefs.html#repository">repository</a>.
+</p>
+
+<h2> Interface </h2>
+
+<pre>
+     s6-rc-set-delete [ -v <em>verbosity</em> ] [ -r <em>repo</em> ] <em>setname...</em>
+</pre>
+
+<ul>
+ <li> For every argument in <em>setname...</em>, s6-rc-set-delete deletes that
+<a href="repodefs.html#set">set</a> from the repository.
+ <li> It exits 0. </li>
+</ul>
+
+<h2> Options </h2>
+
+<dl>
+ <dt> -v <em>verbosity</em>, --verbosity=<em>verbosity</em> </dt>
+ <dd> Be more or less verbose. The default is <strong>1</strong>, which means
+that error messages and warnings will be written to stderr. 0 means that only
+error messages will be written, and 2 or more adds informational messages. </dd>
+
+ <dt> -r <em>repo</em>, --repository=<em>repo</em> </dt>
+ <dd> Use the repository in <em>repo</em>, which must exist. Default is
+<strong>/var/lib/s6-rc/repository</strong>.
+ </dd>
+</dl>
+
+<h2> Exit codes </h2>
+
+<dl>
+ <dt> 0 </dt> <dd> Success. </dd>
+ <dt> 100 </dt> <dd> Incorrect usage. </dd>
+ <dt> 111 </dt> <dd> System call failed. </dd>
+</dl>
+
+<h2> Notes </h2>
+
+<ul>
+ <li> An error in one of the arguments (e.g. if the user specifies a non-existent
+set) will prevent processing the rest of the command line. The user should
+double-check the set names in case of multiple deletions. </li>
+</ul>
+
+</body>
+</html>
diff --git a/doc/s6-rc-set-new.html b/doc/s6-rc-set-new.html
new file mode 100644
index 0000000..8cdc2f7
--- /dev/null
+++ b/doc/s6-rc-set-new.html
@@ -0,0 +1,76 @@
+<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-rc: the s6-rc-set-new program</title>
+    <meta name="Description" content="s6-rc: the s6-rc-set-new program" />
+    <meta name="Keywords" content="s6-rc s6-rc-set-new repo set sub new services" />
+    <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
+  </head>
+<body>
+
+<p>
+<a href="index.html">s6-rc</a><br />
+<a href="//skarnet.org/software/">Software</a><br />
+<a href="//skarnet.org/">skarnet.org</a>
+</p>
+
+<h1> The s6-rc-set-new program </h1>
+
+<p>
+ s6-rc-set-new creates new <a href="repodefs.html#sets">sets</a>
+in a <a href="repodefs.html#repository">repository</a>.
+</p>
+
+<h2> Interface </h2>
+
+<pre>
+     s6-rc-set-delete [ -v <em>verbosity</em> ] [ -r <em>repo</em> ] <em>setname...</em>
+</pre>
+
+<ul>
+ <li> For every argument in <em>setname...</em>, s6-rc-set-new creates a
+<a href="repodefs.html#set">set</a> with that name, in the repository
+<em>repo</em>. Under that set name, it attributes a default
+<a href="repodefs.html#sub">sub</a> to every service listed in the
+<a href="repodefs.html#store">stores</a>:
+  <ul>
+   <li> Services with the <em>essential</em> flag are added to the <tt>always</tt> sub </li>
+   <li> Services with the <em>recommended</em> flag are added to the <tt>active</tt> sub </li>
+   <li> Others are added to the <tt>usable</tt> sub. </li>
+  </ul> </li>
+ <li> It exits 0. </li>
+</ul>
+
+<h2> Options </h2>
+
+<dl>
+ <dt> -v <em>verbosity</em>, --verbosity=<em>verbosity</em> </dt>
+ <dd> Be more or less verbose. The default is <strong>1</strong>, which means
+that error messages and warnings will be written to stderr. 0 means that only
+error messages will be written, and 2 or more adds informational messages. </dd>
+
+ <dt> -r <em>repo</em>, --repository=<em>repo</em> </dt>
+ <dd> Use the repository in <em>repo</em>, which must exist. Default is
+<strong>/var/lib/s6-rc/repository</strong>.
+ </dd>
+</dl>
+
+<h2> Exit codes </h2>
+
+<dl>
+ <dt> 0 </dt> <dd> Success. </dd>
+ <dt> 100 </dt> <dd> Incorrect usage. </dd>
+ <dt> 111 </dt> <dd> System call failed. </dd>
+</dl>
+
+<h2> Notes </h2>
+
+<ul>
+ <li> s6-rc-set-new can be called at the user's convenience, but in a typical
+installation, two sets are enough: a stable committed set and a working set. </li>
+</ul>
+
+</body>
+</html>
author	Laurent Bercot <ska-skaware@skarnet.org>	2025-10-21 18:03:48 +0000
committer	Laurent Bercot <ska-skaware@skarnet.org>	2025-10-21 18:03:48 +0000
commit	3b9836248ed7f5164140d63e96ece21973fc43f7 (patch)
tree	193242a4b634c84d712d8260e7707eae1be53601 /doc
parent	d71f18b44e4168e2d942b503110af5b5314364b5 (diff)
download	s6-rc-3b9836248ed7f5164140d63e96ece21973fc43f7.tar.gz