From 35b102dae60e53a4be06dbe1c5d2950ee862542b Mon Sep 17 00:00:00 2001
From: Laurent Bercot <ska-skaware@skarnet.org>
Date: Thu, 30 Oct 2025 23:23:52 +0000
Subject:  Finish repo documentation; make bootdb configurable; fix install

---
 doc/s6-rc-init.html        | 30 ++++++++++++++++--------------
 doc/s6-rc-set-install.html | 15 ++++++++++++---
 doc/upgrade.html           |  3 +++
 3 files changed, 31 insertions(+), 17 deletions(-)

(limited to 'doc')

diff --git a/doc/s6-rc-init.html b/doc/s6-rc-init.html
index afe10cd..3f181a8 100644
--- a/doc/s6-rc-init.html
+++ b/doc/s6-rc-init.html
@@ -28,22 +28,22 @@ invocation of the
 <h2> Interface </h2>
 
 <pre>
-     s6-rc-init [ -c <em>compiled</em> ] [ -l <em>live</em> ] [ -p <em>prefix</em> ] [ -t <em>timeout</em> ] [ -b ] [ -d ] <em>scandir</em>
+     s6-rc-init [ -c <em>bootdb</em> ] [ -l <em>live</em> ] [ -p <em>prefix</em> ] [ -t <em>timeout</em> ] [ -b ] [ -d ] <em>scandir</em>
 </pre>
 
 <ul>
- <li> <em>compiled</em> (if the <tt>-d</tt> option hasn't been given),
+ <li> <em>bootdb</em> (if the <tt>-d</tt> option hasn't been given),
 <em>live</em> and <em>scandir</em> must be absolute paths. </li>
  <li> s6-rc-init expects to find a <em>compiled service database</em>
-in <em>compiled</em>. It expects to be able to create a directory
+in <em>bootdb</em>. It expects to be able to create a directory
 named <em>live</em>. It also expects that an instance of
 <a href="//skarnet.org/software/s6/s6-svscan.html">s6-svscan</a>
 is running on <em>scandir</em>. </li>
  <li> s6-rc-init initializes the live state in <em>live</em>. It
-declares <em>compiled</em> as the current service database and
+declares <em>bootdb</em> as the current service database and
 sets the state as "all services down". </li>
  <li> It then copies verbatim all
-the service directories declared by <em>compiled</em> into a
+the service directories declared by <em>bootdb</em> into a
 subdirectory of <em>live</em>, adds <tt>./down</tt> files to the live copies
 and links those live copies into <em>scandir</em>. It then triggers
 <a href="//skarnet.org/software/s6/s6-svscan.html">s6-svscan</a>,
@@ -64,9 +64,12 @@ milliseconds, s6-rc-init will complain and exit 111. This is a
 safety feature so s6-rc-init doesn't hang indefinitely on a
 nonworking installation; normally this initialization should not take
 more than a few milliseconds. </li>
- <li> <tt>-c&nbsp;<em>compiled</em></tt>&nbsp;: declare <em>compiled</em>
+ <li> <tt>-c&nbsp;<em>bootdb</em></tt>&nbsp;: declare <em>bootdb</em>
 as the current compiled service database for the upcoming live state.
-Default is <tt>/etc/s6-rc/compiled</tt>. </li>
+Default is <tt>/etc/s6-rc/compiled/current</tt>. Note that <em>bootdb</em>
+should always be a symlink pointing to the real compiled database: that
+is how databases can be live switched without modifying the boot
+process that invokes s6-rc-init. </li>
  <li> <tt>-l&nbsp;<em>live</em></tt>&nbsp;: Store the live state into
 the <em>live</em> directory, which should not exist prior to running
 s6-rc-init, but should be under a writable filesystem - likely a RAM
@@ -91,11 +94,10 @@ being used by another program, s6-rc-init will wait until that
 other program has released its lock on the database, then proceed.
 By default, s6-rc-init fails with an error message if the database
 is currently in use. </li>
- <li><tt>-d</tt>&nbsp;: dereference <em>compiled</em>. Fully resolve
-the <em>compiled</em> path before declaring it as the current
-compiled service database for the upcoming live state. This allows
-<em>compiled</em> to be a symlink that can be updated later without
-impacting the current live state. Using this flag in your init scripts'
+ <li><tt>-d</tt>&nbsp;: dereference <em>bootdb</em>. Fully resolve
+the <em>bootdb</em> path before declaring it as the current
+compiled service database for the upcoming live state.
+Using this flag in your init scripts'
 <tt>s6-rc-init</tt> invocation means that it's possible to boot on a
 compiled service database whose validity has not previously been
 guaranteed by a successful <a href="s6-rc-update.html">s6-rc-update</a>
@@ -137,11 +139,11 @@ and updates the live state by atomically changing the target of the
 the real directory may. </li>
  <li> Similarly, it is recommended that administrators store their
 compiled service databases into some versioned directory, and that
-<em>compiled</em> be a symbolic link to the database currently in
+<em>bootdb</em> be a symbolic link to the database currently in
 use. This will make it easier to create new compiled databases and
 switch them with <a href="s6-rc-update.html">s6-rc-update</a>
 without having to change the s6-rc-init invocation in boot scripts. </li>
- <li> After s6-rc-init runs, <em>compiled</em> has become the
+ <li> After s6-rc-init runs, <em>bootdb</em> has become the
 "live compiled database", and must not be tampered with or deleted.
 The only way to free it for deletion is to replace it with another
 database, via a call to <a href="s6-rc-update.html">s6-rc-update</a>. </li>
diff --git a/doc/s6-rc-set-install.html b/doc/s6-rc-set-install.html
index 02b01f8..c3051f4 100644
--- a/doc/s6-rc-set-install.html
+++ b/doc/s6-rc-set-install.html
@@ -5,7 +5,7 @@
     <meta http-equiv="Content-Language" content="en" />
     <title>s6-rc: the s6-rc-set-install program</title>
     <meta name="Description" content="s6-rc: the s6-rc-set-install program" />
-    <meta name="Keywords" content="s6-rc s6-rc-set-install repo set installation update s6-rc-update boot" />
+    <meta name="Keywords" content="s6-rc s6-rc-set-install repo set installation update s6-rc-update boot bootdb" />
     <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
   </head>
 <body>
@@ -31,16 +31,18 @@ the <em>live database</em> of the currently running system.
 <h2> Interface </h2>
 
 <pre>
-     s6-rc-set-install [ -v <em>verbosity</em> ] [ -r <em>repo</em> ] [ -l <em>livedir</em> ] [ -f <em>convfile</em> ] [ -b ] [ -K ] <em>set</em> <em>bootdbdir</em>
+     s6-rc-set-install [ -v <em>verbosity</em> ] [ -r <em>repo</em> ] [ -c <em>bootdb</em> ] [ -l <em>livedir</em> ] [ -f <em>convfile</em> ] [ -b ] [ -K ] <em>set</em>
 </pre>
 
 <ul>
  <li> s6-rc-set-install checks that the <a href="repodefs.html#set">set</a> of services <em>set</em>
 has been <a href="repodefs.html#commit">committed</a> and that no changes have occurred since. </li>
- <li> It takes the corresponding service database and copies it to <em>bootdbdir</em>. </li>
+ <li> It takes the corresponding service database and copies it to the same directory as <em>bootdb</em>. </li>
  <li> It calls <a href="s6-rc-update.html">s6-rc-update</a> on that copy of the compiled service
 database, which makes it the new <em>live</em> database. Some services may be stopped, and
 other started, in the process. </li>
+ <li> It updates the <em>bootdb</em> link to point to the new database, so that
+next boot uses it. </li>
 </ul>
 
 <h2> Options </h2>
@@ -55,6 +57,13 @@ error messages will be written, and 2 or more adds informational messages. </dd>
  <dd> Use the repository in <em>repo</em>, which must exist. Default is
 <strong>/var/lib/s6-rc/repository</strong>. </dd>
 
+ <dt> -c <em>bootdb</em>, --bootdb=<em>bootdb</em> </dt>
+ <dd> Use <em>bootdb</em> as the path to the boot-time database. This must be
+the same path that is given to the <tt>-c</tt> option of
+<a href="s6-rc-init.html">s6-rc-init</a> at boot time. The default is
+<strong><tt>/etc/s6-rc/compiled/current</tt></strong>. Note that <em>bootdb</em>
+must always be a symlink, pointing to the real compiled database at any time. </dd>
+
  <dt> -l <em>livedir</em>, --livedir=<em>livedir</em> </dt>
  <dd> Assume the <em>live directory</em> of the machine, as created by
 <a href="s6-rc-init.html">s6-rc-init</a>, is <em>livedir</em>. The default
diff --git a/doc/upgrade.html b/doc/upgrade.html
index dba10f9..ddc5e3b 100644
--- a/doc/upgrade.html
+++ b/doc/upgrade.html
@@ -39,6 +39,9 @@ dependency bumped to 2.14.5.0. </li>
 dependency bumped to 2.9.8.0. </li>
  <li> <a href="//skarnet.org/software/s6/">s6</a>
 dependency bumped to 2.13.3.0. </li>
+ <li> The macros in <tt>s6-rc/config.h</tt> have changed.
+<tt>S6RC_LIVE_BASE</tt> is now named <tt>S6RC_LIVEDIR</tt>, in
+addition to the new <tt>S6RC_REPODIR</tt> and <tt>S6RC_BOOTDB</tt>. </li>
 </ul>
 
 <h2> in 0.5.6.0 </h2>
-- 
cgit v1.3.1