From 5876e2f9e260ef46330edfa6f258c6d88b7e5d50 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Sun, 11 Jan 2026 02:54:05 +0000 Subject: Add repository_check; add basic documentation --- doc/s6-frontend.html | 101 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 101 insertions(+) create mode 100644 doc/s6-frontend.html (limited to 'doc/s6-frontend.html') diff --git a/doc/s6-frontend.html b/doc/s6-frontend.html new file mode 100644 index 0000000..0f7ff22 --- /dev/null +++ b/doc/s6-frontend.html @@ -0,0 +1,101 @@ + + + + + + s6-frontend: the s6-frontend program + + + + + + +

+ +

The `s6-frontend` internal program

+ +

+ s6-frontend is the program that does the real command dispatching behind +the s6 command line. It is not meant to be called directly; +users should call s6 instead. +

+ +

Interface

+ +

+     s6-frontend [ global_options... ] commandM/em> subcommand [ subcommand_options... ] [ args... ]
+

+ +
+
Detailed operation
+
+ +
+ What really happens when you call s6 args... is the following: +
+ +
+
s6 gets the name of its configuration file from the +S6_FRONTEND_CONF environment variable, or from the compiled-in default if +this variable is unset. Normally this default is /etc/s6-frontend.conf.
+
This configuration file (let's call it conf) contains +variable definitions that set the default for +all the parts of the s6 system.
+
s6 rewrites itself into +envfile -I conf -- s6-frontend args...
+
The envfile program +reads and parses conf, and then runs s6-frontend +with the additional environment variables defined in conf. +
s6-frontend sets its defaults according to these environment variables, then +performs the work described in the documents linked from the s6 page.
+
+ +
+ The separation between s6 and s6-frontend is really just a +trick to avoid writing an additional parser for the s6-frontend.conf +configuration file. The execline +set of tools is a dependency of s6-frontend anyway, because s6-frontend uses +some if these tools to build complex command lines calling various parts of the +s6 ecosystem; so using the +envfile tool as well +to read the configuration was a natural fit. +
+ +
+ That is why usage messages given by the various s6 foobar help +commands print Usage: s6 foobar subcommand... but error messages, if +they happen, print s6-frontend: fatal: error condition, because +the program where the error occurred is s6-frontend, not s6.
+ +
+Note that most error messages will print the name of another command, +somewhere in the s6 ecosystem. That is a command invoked by s6-frontend to perform +the task required by the user; and if it fails, its own error message will be more +informative than whatever wrapping s6-frontend could do. This might be a little +confusing at first, but a design decision was made that it was a better trade-off +to provide accurate error messages at the expense of a little predictability in the +name of the program that prepends the error messages. +
+ +
+ In summary: +
+ +
+
s6 is what the user types
+
s6-frontend is what interprets the user's command into orders to give to +various parts of the s6 ecosystem
+
Various programs from the s6 supervision +suite or the s6-rc service manager, +invoked by s6-frontend, perform the work. When they succeed, it is transparent; +when they fail, they prepend the error message with their name.
+
+ + + -- cgit v1.3.1

The s6-frontend internal program

Interface

Detailed operation

The `s6-frontend` internal program