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 --- NEWS | 2 +- README | 14 +- 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 +++++++++++++++++++++++++++++++++ package/deps.mak | 3 +- package/targets.mak | 2 +- src/s6-frontend/deps-exe/s6-frontend | 1 + src/s6-frontend/repository.help.txt | 9 ++ src/s6-frontend/repository_check.c | 53 +++++++ src/s6-frontend/s6-frontend-internal.h | 2 + src/s6-frontend/s6.c | 6 +- 15 files changed, 682 insertions(+), 73 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 create mode 100644 src/s6-frontend/repository_check.c diff --git a/NEWS b/NEWS index b662d60..0dc423a 100644 --- a/NEWS +++ b/NEWS @@ -1,4 +1,4 @@ -Changelog for s6-frontend +Changelog for s6-frontend. In 0.0.1.0 ---------- diff --git a/README b/README index dba8078..60788e0 100644 --- a/README +++ b/README @@ -1,16 +1,10 @@ s6-frontend - a s6-based init system with a friendly UI ------------------------------------------------------- -! -! s6-frontend is IN DEVELOPMENT, do not expect anything -! magical from it for some time! -! - - s6-frontend is a set of programs providing interfaces -to the s6 family of programs (s6, s6-rc, s6-linux-init) -for users who are used to different systems. It also -comes with a full set of init scripts and can be used as -a turnkey init system. + s6-frontend provides the one-stop-shop "s6" command that +serves as a friendlier user interface to the s6 family of +programs (s6, s6-rc, s6-linux-init), hiding policy details +and providing a unified view of the init system. See https://skarnet.org/software/s6-frontend/ for details. 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

+
+ + + + + diff --git a/package/deps.mak b/package/deps.mak index 3293ada..a715f1c 100644 --- a/package/deps.mak +++ b/package/deps.mak @@ -22,6 +22,7 @@ src/s6-frontend/process_restart.o src/s6-frontend/process_restart.lo: src/s6-fro src/s6-frontend/process_startstop.o src/s6-frontend/process_startstop.lo: src/s6-frontend/process_startstop.c src/s6-frontend/s6-frontend-internal.h src/s6-frontend/process_status.o src/s6-frontend/process_status.lo: src/s6-frontend/process_status.c src/s6-frontend/s6-frontend-internal.h src/s6-frontend/repository.o src/s6-frontend/repository.lo: src/s6-frontend/repository.c src/s6-frontend/s6-frontend-internal.h +src/s6-frontend/repository_check.o src/s6-frontend/repository_check.lo: src/s6-frontend/repository_check.c src/s6-frontend/s6-frontend-internal.h src/include/s6-frontend/config.h src/s6-frontend/repository_init.o src/s6-frontend/repository_init.lo: src/s6-frontend/repository_init.c src/s6-frontend/s6-frontend-internal.h src/include/s6-frontend/config.h src/s6-frontend/repository_list.o src/s6-frontend/repository_list.lo: src/s6-frontend/repository_list.c src/s6-frontend/s6-frontend-internal.h src/s6-frontend/repository_sync.o src/s6-frontend/repository_sync.lo: src/s6-frontend/repository_sync.c src/s6-frontend/s6-frontend-internal.h @@ -48,5 +49,5 @@ endif s6: EXTRA_LIBS := s6: src/s6-frontend/s6.o -lskarnet s6-frontend: EXTRA_LIBS := ${MAYBEPTHREAD_LIB} -s6-frontend: src/s6-frontend/s6-frontend.o src/s6-frontend/live.o src/s6-frontend/live_help.o src/s6-frontend/live_install.o src/s6-frontend/live_startstop.o src/s6-frontend/live_status.o src/s6-frontend/live_start_everything.o src/s6-frontend/live_stop_everything.o src/s6-frontend/main_help.o src/s6-frontend/main_version.o src/s6-frontend/process.o src/s6-frontend/process_help.o src/s6-frontend/process_kill.o src/s6-frontend/process_restart.o src/s6-frontend/process_startstop.o src/s6-frontend/process_status.o src/s6-frontend/repository.o src/s6-frontend/repository_help.o src/s6-frontend/repository_init.o src/s6-frontend/repository_list.o src/s6-frontend/repository_sync.o src/s6-frontend/set.o src/s6-frontend/set_change.o src/s6-frontend/set_check.o src/s6-frontend/set_commit.o src/s6-frontend/set_copy.o src/s6-frontend/set_help.o src/s6-frontend/set_list.o src/s6-frontend/set_status.o src/s6-frontend/system.o src/s6-frontend/system_boot.o src/s6-frontend/system_help.o src/s6-frontend/system_hpr.o libs6f.a.xyzzy ${LIBNSSS} -ls6rc -ls6 -lskarnet +s6-frontend: src/s6-frontend/s6-frontend.o src/s6-frontend/live.o src/s6-frontend/live_help.o src/s6-frontend/live_install.o src/s6-frontend/live_startstop.o src/s6-frontend/live_status.o src/s6-frontend/live_start_everything.o src/s6-frontend/live_stop_everything.o src/s6-frontend/main_help.o src/s6-frontend/main_version.o src/s6-frontend/process.o src/s6-frontend/process_help.o src/s6-frontend/process_kill.o src/s6-frontend/process_restart.o src/s6-frontend/process_startstop.o src/s6-frontend/process_status.o src/s6-frontend/repository.o src/s6-frontend/repository_check.o src/s6-frontend/repository_help.o src/s6-frontend/repository_init.o src/s6-frontend/repository_list.o src/s6-frontend/repository_sync.o src/s6-frontend/set.o src/s6-frontend/set_change.o src/s6-frontend/set_check.o src/s6-frontend/set_commit.o src/s6-frontend/set_copy.o src/s6-frontend/set_help.o src/s6-frontend/set_list.o src/s6-frontend/set_status.o src/s6-frontend/system.o src/s6-frontend/system_boot.o src/s6-frontend/system_help.o src/s6-frontend/system_hpr.o libs6f.a.xyzzy ${LIBNSSS} -ls6rc -ls6 -lskarnet INTERNAL_LIBS := libs6f.a.xyzzy diff --git a/package/targets.mak b/package/targets.mak index 8b2a86a..bc266f5 100644 --- a/package/targets.mak +++ b/package/targets.mak @@ -1,8 +1,8 @@ BIN_TARGETS := \ s6 \ -s6-frontend LIBEXEC_TARGETS := \ +s6-frontend \ s6-frontend-helper-kill \ EXTRA_TARGETS := \ diff --git a/src/s6-frontend/deps-exe/s6-frontend b/src/s6-frontend/deps-exe/s6-frontend index 14038f5..9f08747 100644 --- a/src/s6-frontend/deps-exe/s6-frontend +++ b/src/s6-frontend/deps-exe/s6-frontend @@ -14,6 +14,7 @@ process_restart.o process_startstop.o process_status.o repository.o +repository_check.o repository_help.o repository_init.o repository_list.o diff --git a/src/s6-frontend/repository.help.txt b/src/s6-frontend/repository.help.txt index 7a07296..3a9ee1e 100644 --- a/src/s6-frontend/repository.help.txt +++ b/src/s6-frontend/repository.help.txt @@ -5,6 +5,8 @@ Subcommands: init initialize a service repository sync synchronize repository with stores list list names of saved service sets + check check all sets and fix inconsistencies + s6 repository init options: -f --force Overwrite existing repository @@ -16,3 +18,10 @@ s6 repository sync options: s6 repository list options: none +s6 repository check options: + -E --no-force-essential do not allow manual changes to essential services (default) + -e --force-essential allow manual changes to essential services + -f --fix try to fix inconsistencies automatically + -d --down fix by disabling or masking services if necessary (default) + -u --up fix by enabling services if necessary + diff --git a/src/s6-frontend/repository_check.c b/src/s6-frontend/repository_check.c new file mode 100644 index 0000000..a0e7737 --- /dev/null +++ b/src/s6-frontend/repository_check.c @@ -0,0 +1,53 @@ +/* ISC license. */ + +#include +#include +#include + +#include + +#include + +#include +#include "s6-frontend-internal.h" + +enum golb_e +{ + GOLB_FIXUP = 0x01, + GOLB_FORCE_ESSENTIAL = 0x02, + GOLB_FIX = 0x04, +} ; + +void repository_check (char const *const *argv) +{ + static gol_bool const rgolb[] = + { + { .so = 'E', .lo = "no-force-essential", .clear = GOLB_FORCE_ESSENTIAL, .set = 0 }, + { .so = 'e', .lo = "force-essential", .clear = 0, .set = GOLB_FORCE_ESSENTIAL }, + { .so = 'd', .lo = "down", .clear = GOLB_FIXUP, .set = 0 }, + { .so = 'u', .lo = "up", .clear = 0, .set = GOLB_FIXUP }, + { .so = 'f', .lo = "fix", .clear = 0, .set = GOLB_FIX }, + } ; + uint64_t wgolb = 0 ; + unsigned int m = 0 ; + char const *newargv[9] ; + char fmtv[UINT_FMT] = " " ; + + argv += gol_argv(argv, rgolb, 4, 0, 0, &wgolb, 0) ; + + newargv[m++] = S6RC_EXTBINPREFIX "s6-rc-set-fix" ; + if (g->verbosity != 1) + { + fmtv[uint_fmt(fmtv, g->verbosity)] = 0 ; + newargv[m++] = "-v" ; + newargv[m++] = fmtv ; + } + newargv[m++] = "-r" ; + newargv[m++] = g->dirs.repo ; + newargv[m++] = wgolb & GOLB_FORCE_ESSENTIAL ? "--force-essential" : "--no-force-essential" ; + newargv[m++] = wgolb & GOLB_FIXUP ? "--fix-up" : "--fix-down" ; + if (!(wgolb & GOLB_FIX)) newargv[m++] = "--dry-run" ; + newargv[m++] = 0 ; + + xmexec_n(newargv, cleanup_modif.s, cleanup_modif.len, cleanup_modif.n) ; +} diff --git a/src/s6-frontend/s6-frontend-internal.h b/src/s6-frontend/s6-frontend-internal.h index ddd3b69..fdacb2b 100644 --- a/src/s6-frontend/s6-frontend-internal.h +++ b/src/s6-frontend/s6-frontend-internal.h @@ -61,6 +61,8 @@ extern void repository_init (char const *const *) gccattr_noreturn ; extern void repository_sync (char const *const *) gccattr_noreturn ; extern void repository_list (char const *const *) gccattr_noreturn ; +extern void repository_check (char const *const *) gccattr_noreturn ; + /* set */ diff --git a/src/s6-frontend/s6.c b/src/s6-frontend/s6.c index f19fd56..8777b8d 100644 --- a/src/s6-frontend/s6.c +++ b/src/s6-frontend/s6.c @@ -2,9 +2,7 @@ #include -#include -#include -#include +#include #include @@ -24,7 +22,7 @@ int main (int argc, char const *const *argv) newargv[m++] = "-I" ; newargv[m++] = "--" ; newargv[m++] = conffile ; - newargv[m++] = S6_FRONTEND_BINPREFIX "s6-frontend" ; + newargv[m++] = S6_FRONTEND_LIBEXECPREFIX "s6-frontend" ; while (argc--) newargv[m++] = *argv++ ; newargv[m++] = 0 ; xexec(newargv) ; -- cgit v1.3.1