Add s6-rc-set-install, repodefs page

author: Laurent Bercot <ska-skaware@skarnet.org> 2025-10-06 02:27:38 +0000
committer: Laurent Bercot <ska-skaware@skarnet.org> 2025-10-06 02:27:38 +0000
commit: 0ea45c6552010c36e4718542db759ec6cdfce58a (patch)
tree: 273f222c2d108e9daa687d5f4ea2a068a75dc550 /doc/repodefs.html
parent: 399184cad0c0dd63a39de775130a2a73d0325913 (diff)
download: s6-rc-0ea45c6552010c36e4718542db759ec6cdfce58a.tar.gz
1 files changed, 259 insertions, 0 deletions
diff --git a/doc/repodefs.html b/doc/repodefs.html
new file mode 100644
index 0000000..ff2bd32
--- /dev/null
+++ b/doc/repodefs.html
@@ -0,0 +1,259 @@
+<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 "repo" subset of commands: definitions and concepts</title>
+    <meta name="Description" content="s6-rc: an overview" />
+    <meta name="Keywords" content="s6-rc overview" />
+    <!-- <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 <em>repo</em> subset of s6-rc commands: management of source definition directories </h1>
+
+<p>
+ s6-rc commands such as
+<a href="s6-rc.html">s6-rc</a>,
+<a href="s6-rc-compile.html">s6-rc-compile</a>, or
+<a href="s6-rc-db.html">s6-rc-db</a>, implement pure <em>mechanism</em>, and
+leave all the burden of <em>policy</em>, i.e. how to organize source files,
+when to compile a service database, etc., to the user. This is on purpose, but
+does not make it easy to integrate s6-rc in a distribution, where service
+files are provided by packages installed by a package manager, and where the
+user wants to be able to easily define which services start at boot time and
+which do not, etc.
+</p>
+
+<p>
+ The solution to this conundrum is the high-level user interface to s6-rc
+(and more generally to the s6 ecosystem) named
+<a href="//skarnet.org/software/s6-frontend/">s6-frontend</a> (currently
+in development). But in order for
+<a href="//skarnet.org/software/s6-frontend/">s6-frontend</a> to be a
+<em>user interface</em> and not a whole engine in its own right, some
+stepping stones are in order: intermediary-level helpers to manage s6-rc
+source definition directories in a way that maps better to the way that
+distributions work than just the raw <a href="s6-rc-compile.html">s6-rc-compile</a>.
+</p>
+
+<p>
+ These intermediary-level helpers made their appearance in version 0.6.0.0
+of s6-rc, and they're collectively known as <em>repo</em> commands &mdash;
+simply because they manage a <em>repository</em> of services.
+</p>
+
+<h2> Definitions </h2>
+
+<div id="repository">
+<h3> Repository </h3>
+</div>
+
+<p>
+ An s6-rc <em>repository</em> is a place in the filesystem where the
+<em>repo</em> commands perform their work and store their data. It
+is made of hierarchies of symlinks (lots and lots of symlinks), that
+ultimately point to source definition directories in the
+<a href="#store">stores</a>, as well as several compiled databases:
+the <a href="#refdb">reference database</a>, and the compiled databases
+made of the <a href="#set">sets</a> you have
+<a href="#commit">committed</a>, including the one you will eventually
+<a href="#install">install</a>.
+</p>
+
+<p>
+ A <em>repository</em> is where <strong>offline</strong> work on
+services happens. It must be located on a read-write filesystem, but
+that filesystem does not need to be accessible during the early boot.
+The default repository is located in <tt>/var/lib/s6-rc/repository</tt>
+(configurable at build-time). Other repositories can be created and
+used at will, typically by non-root users who want to manage their own
+sets of services.
+</p>
+
+<div id="store">
+<h3> Store </h3>
+</div>
+
+<p>
+ A service <em>store</em> is a place in the filesystem where source
+definition directories are written by the package manager or the
+user, where you can find the real contents of the services (instead
+of just symlinks), as in, source definition directories that are
+processed by <a href="s6-rc-compile.html">s6-rc-compile</a>.
+A repository will typically link to several stores: one provided by
+the package manager, and one &mdash; or more &mdash; provided locally
+by the admin. No s6-rc command will ever write to a store, but most
+repo commands read from all the stores.
+</p>
+
+<p>
+ The location of the stores is entirely determined by distribution
+policy, and s6-rc hardcodes no default for them. A good place to
+host service definition directories installed by a package manager
+could be, for instance, <tt>/usr/lib/s6-rc/sources</tt>. A good
+place to host local service definition directories managed by
+an administrator could be <tt>/etc/s6-rc/sources</tt>.
+</p>
+
+<div id="refdb">
+<h3> Reference database </h3>
+</div>
+
+<p>
+ When a repository is created or updated, the list of all services
+defined in all the <a href="#store">stores</a> used by this repository
+is analyzed, and all these services are automatically compiled into a
+<em>reference database</em>, stored in the repository. The reference
+database is never meant to be installed or go live in any way; its
+purpose is mainly to give repo commands access to the full dependency
+graph of all the services in the store. Additionally, compiling this
+reference database ensures that the whole set of services defined
+in all the used stores is consistent: if not, the initialization fails,
+so the problem is reported as early as possible.
+</p>
+
+<div id="set">
+<h3> Set </h3>
+</div>
+
+<p>
+ Inside a repository, a <em>set</em> is the fundamental unit of operation,
+and what users will interact the most with. A set is a map associating
+each service contained in the <a href="#refdb">reference database</a>
+(so, each service listed in all the <a href="#store">stores</a> used by the
+repository) to a given state that the user wants this service in when
+booting the system. This target state is also called a
+<a href="#sub">sub</a>, because target states are implemented by
+subdirectories of the directory holding a set.
+</p>
+
+<p>
+ The idea is that the user can work on a set, making modifications to
+the target states as they see fit; the repo commands always ensure that
+the set will be consistent, i.e. that dependencies will be respected and
+target states are reachable. When satisfied with the states, the user
+can <a href="#commit">commit</a> the set, then <a href="#install">install</a> it.
+</p>
+
+<div id="sub">
+<h3> Subs </h3>
+</div>
+
+<p>
+ A <em>sub</em> is the target state for every service in a set. At all times,
+each service is in one and only one sub. The list of subs the service can be in
+is the following:
+</p>
+
+<ul>
+ <li> <em>masked</em>: when the set is committed, masked services <em>will not</em>
+be included in the compiled set database. They will be completely absent; if
+the set database is installed, <a href="s6-rc.html">s6-rc</a> will not know them.
+A service in another sub cannot depend on a masked service. </li>
+ <li> <em>disabled</em>, aka <em>unmasked</em>, aka <em>active</em> (yes, the
+naming may seem inconsistent, but bear with me): these services will appear in
+the compiled set database, and be startable by <a href="s6-rc.html">s6-rc</a> if
+the database is installed. However, they will not be included in the default
+bundle, i.e. they will not be automatically started at boot time. </li>
+ <li> <em>enabled</em>: these services will appear in the compiled set database,
+<em>and</em> in the default bundle. They will be started at boot time. </li>
+ <li> <em>essential</em>, aka <em>always</em>: these services have been marked
+as essential in their source definition directories, so they will always be
+enabled. They cannot be disabled or masked. They cannot depend on non-essential
+services. This sub is typically used by early boot services that should always
+be run. </li>
+</ul>
+
+<p>
+ Working on a set basically means moving services from one of these subs to
+another, mostly choosing what services you will enable or disable, and sometimes
+masking services you don't want to see at all. And once you are happy with a set,
+you can commit it.
+</p>
+
+<div id="commit">
+<h3> Commit </h3>
+</div>
+
+<p>
+ <em>Committing</em> a set means assembling a subset of all the source
+definition directories in the set and compiling them into a
+<em>set database</em>, replacing any previous database for the same
+set. This set database can then be <em>installed</em>.
+</p>
+
+<div id="install">
+<h3> Install </h3>
+</div>
+
+<p>
+ <em>Installing</em> a committed set means copying the compiled set
+database to the place (defined by policy distribution) where it can be
+used as a <em>live database</em>, i.e. booted on, and then switching
+the live database to it. In other words: making the set database into
+the new live database.
+</p>
+
+<h2> Workflow </h2>
+
+<ul>
+ <li> <strong>At distribution installation time</strong>:
+  <ul>
+   <li> The installer creates a repository with
+<a href="s6-rc-repo-init.html">s6-rc-repo-init</a>, linking to stores
+according to distribution policy. </li>
+   <li> The installer also sets a default live service database up. </li>
+  </ul> </li>
+ <li> <strong>Whenever distribution policies change</strong>, for instance
+when declaring an additional local store:
+  <ul>
+   <li> The admin updates the list of stores with
+<a href="s6-rc-repo-init.html">s6-rc-repo-init -U</a>. </li>
+  </ul> </li>
+ <li> <strong>Whenever service files change</strong>, typically when the
+package manager installs/updates/deletes packages that provide daemons,
+or admins modify services in local stores:
+  <ul>
+   <li> The package manager, or the admin, invokes
+<a href="s6-rc-repo-sync.html">s6-rc-repo-sync</a> to keep the sets in the
+repository in sync with the stores. </li>
+   <li> It may also be necessary to commit the live set again with
+<a href="s6-rc-set-commit.html">s6-rc-set-commit</a>, and to install it with
+<a href="s6-rc-repo-set-install.html">s6-rc-repo-set-install</a>, so the live
+database is also kept in sync with the machine state. (Failure to do so may
+prevent the machine from booting next time.)
+  </ul> </li>
+ <li> <strong>Whenever the admin wants to customize their startup process</strong>:
+  <ul>
+   <li> They can create new sets (with default subs coming from policy that's
+hardcoded in the stores) with <a href="s6-rc-set-new.html">s6-rc-set-new</a>,
+make a copy of an existing set with <a href="s6-rc-set-copy.html">s6-rc-set-copy</a>,
+or delete sets with <a href="s6-rc-set-delete.html">s6-rc-set-delete</a>. </li>
+   <li> They mask, unmask, enable or disable services in their favorite set with
+<a href="s6-rc-set-change.html">s6-rc-set-change</a>. </li>
+   <li> They commit the set with <a href="s6-rc-set-commit.html">s6-rc-set-commit</a>. </li>
+   <li> They install the set with <a href="s6-rc-set-install.html">s6-rc-set-install</a>.
+This action potentially modifies the current state of the machine! </li>
+  </ul> </li>
+ <li> <strong>At boot time</strong>:
+  <ul>
+   <li> The system boots on the installed live database. None of the <em>repo</em>
+commands are involved. </li>
+  </ul> </li>
+</ul>
+
+<p>
+ Note that all these steps will be made easier in the near future by the higher-level
+user interface provided by
+<a href="s6-frontend.html">s6-frontend</a>.
+</p>
+
+</body>
+</html>
author	Laurent Bercot <ska-skaware@skarnet.org>	2025-10-06 02:27:38 +0000
committer	Laurent Bercot <ska-skaware@skarnet.org>	2025-10-06 02:27:38 +0000
commit	0ea45c6552010c36e4718542db759ec6cdfce58a (patch)
tree	273f222c2d108e9daa687d5f4ea2a068a75dc550 /doc/repodefs.html
parent	399184cad0c0dd63a39de775130a2a73d0325913 (diff)
download	s6-rc-0ea45c6552010c36e4718542db759ec6cdfce58a.tar.gz