From 5eefb9aae5e9e88b200ff7fcc445120c5ee2998b Mon Sep 17 00:00:00 2001
From: Laurent Bercot <ska-skaware@skarnet.org>
Date: Tue, 8 Sep 2026 16:12:24 +0000
Subject:  Improve user service management

- Separate /etc/s6.conf from /etc/s6-user.conf
- Have --system|--user handled at the s6 level, not the s6-frontend level
- Also have --help rewritten at the s6 level because it's cleaner
- On --user, process the config file with sed to import XDG variables
- Do not use s6f_user_get_confdirs() anymore (can remove it if we
decide to stick with this design), --user now only changes the
conf file, and only command-line options such as --scandir can override
what is described in the conf file.
- Document the current behaviour.
---
 doc/s6-frontend.html | 20 ++++++++++++++++----
 doc/s6.conf.html     | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 doc/s6.html          | 27 +++++++++++----------------
 3 files changed, 74 insertions(+), 20 deletions(-)

(limited to 'doc')

diff --git a/doc/s6-frontend.html b/doc/s6-frontend.html
index 9d563f7..df98186 100644
--- a/doc/s6-frontend.html
+++ b/doc/s6-frontend.html
@@ -38,14 +38,26 @@ users should call <a href="s6.html">s6</a> instead.
 </p>
 
 <ul>
- <li> <a href="s6.html">s6</a> gets the name of its configuration file from the
-<tt>S6_CONF</tt> environment variable, or from the compiled-in default if
-this variable is unset. Normally this default is <tt>/etc/s6.conf</tt>. </li>
+ <li> <a href="s6.html">s6</a> reads its configuration file at
+<tt>/etc/s6.conf</tt> by default, overridable by the admin at build time
+via the <tt>--conffile</tt> configure option, also overridable by the user
+at run time via the <tt>S6_CONF</tt> environment variable.
+  <ul>
+   <li> If <a href="s6.html">s6</a> is run with the <tt>--user</tt> option,
+it looks for <tt>/etc/s6-user.conf</tt> instead, overridable by the admin at
+build time via the <tt>--userconffile</tt> configure option, also overridable
+by the user at run time via the <tt>S6_USER_CONF</tt> environment variable. </li>
+  </ul> </li>
  <li> This configuration file (let's call it <em>conf</em>) contains
 <a href="s6.conf.html">variable definitions</a> that set the default for
 all the parts of the s6 system. </li>
  <li> <a href="s6.html">s6</a> rewrites itself into
-<code>envfile -I <em>conf</em> -- s6-frontend <em>args...</em></code> </li>
+<code>envfile -I <em>conf</em> -- s6-frontend <em>args...</em></code>
+  <ul>
+   <li> If the <tt>--user</tt> flag has been given, some text transformation
+<a href="s6.conf.html#userservices">is first performed on the file</a> to substitute
+the relevant XDG variables. </li>
+  </ul> </li>
  <li> The <a href="//skarnet.org/software/execline/envfile.html">envfile</a> program
 reads and parses <em>conf</em>, and then runs <a href="s6-frontend.html">s6-frontend</a>
 with the additional environment variables defined in <em>conf</em>.
diff --git a/doc/s6.conf.html b/doc/s6.conf.html
index 8120603..9c15615 100644
--- a/doc/s6.conf.html
+++ b/doc/s6.conf.html
@@ -37,6 +37,15 @@ are located).
 what the full path to the <em>foobar</em> service directory is.
 </p>
 
+<h3> Location </h3>
+
+<p>
+The global <tt>/etc/s6.conf</tt> path for the configuration variable can be
+overridden by the admin at build time via the <tt>--conffile</tt> configure
+option, and by the user at <a href="s6.html">s6</a> run time via the
+<tt>S6_CONF</tt> environment variable.
+</p>
+
 <h2 id="description"> Description </h2>
 
 <p>
@@ -107,5 +116,43 @@ The default is <strong>root</strong> and that is fine, but distributions
 may want to set it to an unprivileged user. </dd>
 </dl>
 
+<h2 id="userservices"> User services </h2>
+
+<p>
+  If <a href="s6.html">s6</a> is invoked with the <tt>--user</tt> flag,
+the <tt>/etc/s6-user.conf</tt> file is used instead, with the same
+syntax and the same variables, but additionally, the following
+environment variables, if present, are substituted:
+</p>
+
+<ul>
+ <li> <tt>XDG_RUNTIME_DIR</tt> </li>
+ <li> <tt>XDG_DATA_HOME</tt> </li>
+ <li> <tt>XDG_CONFIG_HOME</tt> </li>
+ <li> <tt>XDG_STATE_HOME</tt> </li>
+ <li> <tt>XDG_CACHE_HOME</tt> </li>
+</ul>
+
+<p>
+ That means that a global <tt>/etc/s6-user.conf</tt> file can for instance declare
+</p>
+
+<pre>
+ scandir=${XDG_RUNTIME_DIR}/service
+</pre>
+
+<p>
+and the correct location for the <tt>scandir</tt> will be obtained, for every user.
+</p>
+
+<h3> Location </h3>
+
+<p>
+The global <tt>/etc/s6-user.conf</tt> path for the configuration variable can be
+overridden by the admin at build time via the <tt>--userconffile</tt> configure
+option, and by the user at <a href="s6.html">s6</a> run time via the
+<tt>S6_USER_CONF</tt> environment variable.
+</p>
+
 </body>
 </html>
diff --git a/doc/s6.html b/doc/s6.html
index 661bc65..9fb6038 100644
--- a/doc/s6.html
+++ b/doc/s6.html
@@ -63,17 +63,6 @@ command, and on the linked documentation page you can find the interpretation
 of its various exit codes.
 </p>
 
-<h2 id="env"> Environment variables </h2>
-
-<ul>
- <li> s6 reads the <code>S6_CONF</code> environment variable
-containing the absolute path to the
-<a href="s6.conf.html">configuration file</a> for the s6 command. </li>
- <li> If this variable is unset, the default is <tt>/etc/s6.conf</tt>,
-possibly overridden by the <tt>--conffile</tt> build-time configure option to
-s6-frontend. </li>
-</ul>
-
 <h2 id="options"> Global options </h2>
 
 <p>
@@ -129,12 +118,18 @@ 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>
 
+ <dt> <tt>-S</tt>, <tt>--system</tt> </dt>
+ <dd> Use the <tt>/etc/s6.conf</tt> system <a href="s6.conf.html">configuration file</tt>.
+This is the default.
+The location of the file can be overridden by the admin at install time via the
+<tt>--conffile</tt> configure option, or by the user at run time via the
+<tt>S6_CONF</tt> environment variable. </dd>
+
  <dt> <tt>-u</tt>, <tt>--user</tt> </dt>
- <dd> Override the variables defined in the configuration file with values
-built from XDG environment variables. This option only works if the XDG
-environment variables are present in the environment. This option is
-useful to address user services. You can see what values are used by
-running <tt>s6 -u version export</tt>. </dd>
+ <dd> Use the <tt>/etc/s6-user.conf</tt> system <a href="s6.conf.html">configuration file</tt>.
+The location of the file can be overridden by the admin at install time via the
+<tt>--userconffile</tt> configure option, or by the user at run time via the
+<tt>S6_USER_CONF</tt> environment variable. </dd>
 </dl>
 
 
-- 
cgit v1.3.1