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/index.html | 76 ++++++----- doc/quickstart.html | 26 ---- doc/s6-frontend-helper-kill.html | 54 ++++++++ doc/s6-frontend.conf.html | 125 +++++++++++++++++ doc/s6-frontend.html | 101 ++++++++++++++ doc/s6.html | 281 +++++++++++++++++++++++++++++++++++++++ 6 files changed, 607 insertions(+), 56 deletions(-) delete mode 100644 doc/quickstart.html create mode 100644 doc/s6-frontend-helper-kill.html create mode 100644 doc/s6-frontend.conf.html create mode 100644 doc/s6-frontend.html create mode 100644 doc/s6.html (limited to 'doc') diff --git a/doc/index.html b/doc/index.html index 70ca515..d7d20b3 100644 --- a/doc/index.html +++ b/doc/index.html @@ -20,45 +20,58 @@

What is it ?

- s6-frontend is still in development. + s6-frontend is a frontend to the s6 init system. It provides +the one-stop-shop s6 command, that is used +to address every part of the init system.

+

Huh?

+

- s6-frontend is a frontend to the s6 ecosystem. It is made of -several parts: + The s6 init system is made of several different parts:

- These parts are all independent from one another. But when put all together, -they implement a powerful, fast, turnkey init system that is usable on -any distribution. + The separation in different packages is purposeful: the goal is to keep the +system entirely modular, and not tie it to a particular use. s6-supervision +is often used on its own, in environments that already have an init system +(no need for s6-linux-init) and a service manager (no need for s6-rc). +For the same purpose of modularity, s6 follows an approach of "one functionality, +one tool", sometimes to the extreme: the s6-supervision package, as of +2.14.0.0, hosts 75 binaries.

-
+

+ This approach is successful in that it provides comprehensive functionality +with maximum efficiency: despite its growth, s6 remains extremely +lightweight in run-time resource usage. However, a recurring +pattern is that potential users are often rebuked by s6's apparent complexity. +

- +

+ s6-frontend is an attempt at managing users' interface expectations. It +provides one user-facing command, named s6, that +takes intuitively-named subcommands in order to control all the important +parts of an s6-based system. +

+

Installation

Requirements

@@ -131,14 +144,17 @@ the previous versions of s6-frontend and the current one.

Reference

-

Commands

+

User-facing commands

-

- All these commands exit 111 if they encounter a temporary error, and -100 if they encounter a permanent error - such as a misuse. -

+ + +

Internal programs

Related resources

diff --git a/doc/quickstart.html b/doc/quickstart.html deleted file mode 100644 index 6c99510..0000000 --- a/doc/quickstart.html +++ /dev/null @@ -1,26 +0,0 @@ - - - - - - s6-frontend: quickstart and FAQ - - - - - - -

-s6-frontend
-Software
-skarnet.org -

- -

Quickstart and FAQ for s6-frontend

- -

- (To be written.) -

- - - diff --git a/doc/s6-frontend-helper-kill.html b/doc/s6-frontend-helper-kill.html new file mode 100644 index 0000000..6c5d2b8 --- /dev/null +++ b/doc/s6-frontend-helper-kill.html @@ -0,0 +1,54 @@ + + + + + + s6-frontend: the s6-frontend-helper-kill program + + + + + + +

+s6-frontend
+Software
+skarnet.org +

+ +

The s6-frontend-helper-kill internal program

+ +

+ s6-frontend-helper-kill is a small utility to send numerical +signals to a given list of pids. It is not meant to be called directly, +although nothing bad will happen if you do. It is used in command lines crafted by +s6 process kill instead of the POSIX +kill +program, because the latter does not support sending arbitrary numerical signals. +

+ +
+

Interface

+
+ +
+     s6-frontend-helper-kill sig pids...
+
+ + + +
+

Exit codes

+
+ +
+
0
Success
+
100
Wrong usage
+
+ + + diff --git a/doc/s6-frontend.conf.html b/doc/s6-frontend.conf.html new file mode 100644 index 0000000..9a83e2d --- /dev/null +++ b/doc/s6-frontend.conf.html @@ -0,0 +1,125 @@ + + + + + + s6-frontend: the s6-frontend.conf configuration file + + + + + + +

+s6-frontend
+Software
+skarnet.org +

+ +

The /etc/s6-frontend.conf configuration file

+ +
+

Goal and usage

+
+ +

+ /etc/s6-frontend.conf is a configuration file provided by the +distribution, or written by the system administrator, defining various +settings for the s6 commands, as well as the default +policies of an s6-based system (i.e. where various directories and files +are located). +

+ +

+ This is, for instance, what allows the +s6 process restart foobar command to send +s6-svc -r to the +foobar service without the user needing to type, or even remember, +what the full path to the foobar service directory is. +

+ +
+

Description

+
+ +

+The /etc/s6-frontend.conf file follows the syntax of the +envfile command: +simple key = value lines, comments permitted. +

+ +

+ If a value is left empty, the compiled-in default is used. +

+ +

+ The variables that can be set are the following: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Name Contents Default
scandir The directory where s6-svscan +is running. /run/service (possibly overridden by the --scandir build-time configure option to + or to +s6-frontend)
livedir The directory hosting the live service database managed by +s6-rc /run/s6-rc (possibly overridden by the --livedir build-time configure option to + or to +s6-frontend)
repodir The directory hosting the repository of service sets managed by the +s6-rc repo commands /var/lib/s6-rc/repository (possibly overridden by the --repodir build-time configure option to + or to +s6-frontend)
bootdb The path to the boot-time compiled service database /etc/s6-rc/compiled/current (possibly overridden by the --bootdb build-time configure option to + or to +s6-frontend)
stmpdir A directory suitable for root-only runtime data and temporary files for s6-frontend /run/s6-frontend (possibly overridden by the --stmpdir build-time configure option to +s6-frontend)
storelist A colon-separated (:) list of directories containing the +stores of s6-rc service +definition directories /usr/share/s6-frontend/s6-rc/sources:/etc/s6-frontend/s6-rc/sources +(possibly overridden by the --storelist build-time configure option to +s6-frontend)
verbosity The default verbosity for s6 and its invoked commands. 0 is +terse (only print fatal error messages), 1 is normal (print error messages and warnings), +over 1 is increasingly verbose (print informational messages, up to tracing and debug +messages at level 4-5) 1
+ + + 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 + + + + + + +

+s6-frontend
+Software
+skarnet.org +

+ +

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: +

+ + + +

+ 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: +

+ + + + + diff --git a/doc/s6.html b/doc/s6.html new file mode 100644 index 0000000..8f1012f --- /dev/null +++ b/doc/s6.html @@ -0,0 +1,281 @@ + + + + + + s6-frontend: the s6 program + + + + + + +

+s6-frontend
+Software
+skarnet.org +

+ +

The s6 program

+ +

+ s6 is a generic command-line utility that can be used to +interact with a system managed by the +s6 process supervision system, the +s6-rc service manager, and optionally the +s6-linux-init boot program. +

+ +
+

Interface

+
+ +
+     s6 [ global_options... ] command subcommand [ subcommand_options... ] [ args... ]
+
+ + + +
+

Common usage

+
+ +

+

+ +
+

Exit codes

+
+ +

+ s6 always exits 0 on success, 100 on bad usage, and 111 on a system call +failure. +

+ +

+ Since it can exec into a wide variety of commands belonging to various +parts of the s6 family of programs, it is difficult to list all its possible +exit codes exhaustively. However, in case of an error, the name of the +subprogram where the error occurred is always printed on stderr; you can then +consult the documentation for said subprogram, which will have the explanation +for all its exit codes. For instance, if an invocation of s6 prints +a message such as s6-rc: fatal: unable to start service foobar, +it means that s6 invoked the s6-rc +command, and on the linked documentation page, you can find the interpretation +of its various exit codes. +

+ +
+

Environment variables

+
+ + + +
+

Global options

+
+ +

+ global_options... is a list of options that modify s6's behaviour +and policies. They should generally not be used; instead, the behaviour should +be set in the configuration file. +Nevertheless, if you need to override the configuration file settings for some +reason, here you go. +

+ +
+
-h, --help
+
Run the s6 help command. +Any given command or subcommand is ignored.
+ +
-V, --version
+
Run the s6 version command. +
Any given command or subcommand is ignored.
+ +
-s scandir, --scandir=scandir
+
Use scandir as scan directory (i.e. the directory where +s6-svscan runs +and supervises service directories), +overriding the value of scandir +defined in s6-frontend.conf.
+ +
-l livedir, --livedir=livedir
+
Use livedir as live directory (i.e. the directory where +s6-rc keeps tabs +on the machine state and stores its runtime information), +and supervises service directories), +overriding the value of livedir +defined in s6-frontend.conf.
+ +
-r repodir, --repodir=repodir
+
Use repodir as s6-rc repository (i.e. the directory where +the repo commands +of the s6-rc package store +and manipulate their service sets), +overriding the value of repodir +defined in s6-frontend.conf.
+ +
-c bootdb, --bootdb=bootdb
+
Use bootdb as the name of the compiled service database +used by s6-rc at boot time (i.e. the directory where +the s6-rc reads +information on how to start all the wanted services) +overriding the value of bootdb +defined in s6-frontend.conf.
+ +
--stmpdir=stmpdir
+
Use stmpdir to store runtime s6-frontend data and +temporary files, +overriding the value of stmpdir +defined in s6-frontend.conf.
+ +
--storelist=storelist
+
Use storelist as list of +stores, +overriding the value of storelist +defined in s6-frontend.conf.
+ +
-v verbosity, --verbosity=verbosity
+
Use verbosity as numerical verbosity value, +overriding the value of verbosity +defined in s6-frontend.conf.
+ +
--color=yes|no|auto
+
Use fancy output (which may or may not involve color): always if +yes, never if no, and only when stdout is a terminal +if auto. 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.
+
+ + +
+

Commands

+
+ +
+

help

+
+ +

+ s6 help prints a short help message summarizing the options +and usage of the s6 command. It is not as detailed as this page. +

+ +

+ No subcommands are defined. +

+ +
+

version

+
+ +

+ s6 version prints the current version of s6-frontend, on one line. +

+ +

+ No subcommands are defined. +

+ +
+

process

+
+ +

+ s6 process sends commands to long-running processes supervised by the +s6 supervision suite. The details are +available here. +

+ +

+ s6 process is typically used when a daemon +needs to be restarted or otherwise addressed without involvement from the service +manager, i.e. without having to start or stop dependencies. +

+ +
+

live

+
+ +

+ s6 live controls the live state of the machine, starting and stopping +services, installing a new set of services, etc. It is mostly an interface +around the +s6-rc service manager. The details are +available here. +

+ +
+

repository

+
+ +

+ s6 repository regroups administrative tasks related to the repository +of service sets, typically synchronization with the service stores when the +package manager updates service definitions. It is not often directly used by +sysadmins, but is an essential part of distribution scripts, when they create +the initial layout, run their package manager, etc. +

+ +

+The details are available here. +

+ +
+

set

+
+ +

+ s6 set is the interface to the creation and manipulation of service sets by +the user. It is how they define what service will be enabled or disabled at boot +time. This manipulation occurs offline: service sets being worked on are distinct from +the live state of the machine, accessible via s6 live commands. + +

+The details are available here. +

+ +
+

system

+
+ +

+ s6 system provides commands to run at boot and, on systems fully managed by s6, +to shut the system down. +The details are available here. +

+ +
+

Notes

+
+ + + + + -- cgit v1.3.1