From 3b9836248ed7f5164140d63e96ece21973fc43f7 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Tue, 21 Oct 2025 18:03:48 +0000 Subject: add getserviceflags and use it in fillset; add some doc --- doc/s6-rc-compile.html | 9 +++- doc/s6-rc-db.html | 23 +++++++++- doc/s6-rc-repo-init.html | 111 ++++++++++++++++++++++++++++++++++++++++++++++ doc/s6-rc-repo-sync.html | 100 +++++++++++++++++++++++++++++++++++++++++ doc/s6-rc-set-copy.html | 72 ++++++++++++++++++++++++++++++ doc/s6-rc-set-delete.html | 69 ++++++++++++++++++++++++++++ doc/s6-rc-set-new.html | 76 +++++++++++++++++++++++++++++++ 7 files changed, 456 insertions(+), 4 deletions(-) create mode 100644 doc/s6-rc-repo-init.html create mode 100644 doc/s6-rc-repo-sync.html create mode 100644 doc/s6-rc-set-copy.html create mode 100644 doc/s6-rc-set-delete.html create mode 100644 doc/s6-rc-set-new.html (limited to 'doc') diff --git a/doc/s6-rc-compile.html b/doc/s6-rc-compile.html index e1ad82b..11ecb38 100644 --- a/doc/s6-rc-compile.html +++ b/doc/s6-rc-compile.html @@ -109,9 +109,14 @@ directory.

An optional regular file named flag-essential. The contents of this file are irrelevant, only its presence is tested. If this file exists, the service will be marked as essential, which means that a s6-rc -d change foo -command will not stop the service. Only a s6-rc -D change foo +command will not stop the service; only a s6-rc -D change foo command will. If the service is a bundle, the flag will be propagated to all its -contents, i.e. all the services it represents will be marked as essential.

+contents, i.e. all the services it represents will be marked as essential. + +

An optional regular file named flag-recommended. The contents of this +file are irrelevant, only its presence is tested. If this file exists, the service +will be marked as recommended. This is only important for +repo commands, not when compiling the database.

For bundles

diff --git a/doc/s6-rc-db.html b/doc/s6-rc-db.html index bc527a6..4794be6 100644 --- a/doc/s6-rc-db.html +++ b/doc/s6-rc-db.html @@ -222,10 +222,29 @@ for atomic service atomicname.

- Those binary flags are currently unused, but this may change in a -future version of s6-rc. + Those binary flags are used by repo +commands:

Bit 0 is set if there's a flag-essential file in the +source directory (or if the "essential" flag was inherited from a +bundle). It means the service cannot be downed by normal means: +s6-rc -d change atomicname will not work, +the -D option to s6-rc is needed. Additionally, when +importing atomicname in a set, +it will automatically be put in the always sub, which means +it will always be enabled by default.
Bit 1 is set if there's a flag-recommended file in the +source directory (or if the "essential" flag was inherited from a +bundle). When +importing atomicname in a set, +it will automatically be put in the active sub rather than the +latent one: unless the user actively makes a change before +committing the set, atomicname will be in the default bundle +and be started at boot time.

s6-rc-db atomics servicename...

diff --git a/doc/s6-rc-repo-init.html b/doc/s6-rc-repo-init.html new file mode 100644 index 0000000..22baf52 --- /dev/null +++ b/doc/s6-rc-repo-init.html @@ -0,0 +1,111 @@ + + + + + + s6-rc: the s6-rc-repo-init program + + + + + + +

+s6-rc
+Software
+skarnet.org +

+ +

The s6-rc-repo-init program

+ +

+ s6-rc-repo-init initializes a repository +on a system, linking it to a list of stores +and ensuring that the set of all services defined in all the stores is +consistent. +

+ +

Interface

+ +

+     s6-rc-repo-init [ -v verbosity ] [ -r repo ] [ -h fdhuser ] [ -f ] [ -U ] [ -B ] stores...
+

+ +

s6-rc-repo-init creates an s6-rc repository at location repo.
It makes stores... (which must be a list of several locations in the +filesystem) the current list of stores for this repository.
It synchronizes with the list of stores, as if +s6-rc-repo-sync had been called. That means +that it imports all the services in the stores and builds the +reference database.
It exits 0.

+ +

Options

+ +

-v verbosity, --verbosity=verbosity: Be more or less verbose. The default is 1, which means +that error messages and warnings will be written to stderr. 0 means that only +error messages will be written, and 2 or more adds informational messages. +The option is also passed to commands that s6-rc-repo-init may call, such +as s6-rc-compile, so their verbosity will +be similarly adjusted.
-r repo, --repository=repo: Create the repository in repo. Default is +/var/lib/s6-rc/repository. Unless the -U option is +given, repo must not previously exist in the filesystem. +
-h fdhuser, --fdholder-user=fdhuser: You can safely ignore this option and forget about it. What it does +is ensure that if a supervision tree is started as root on a compiled +database produced by this command (this will never happen to the reference +database, so it is only ever useful together with the -U +option when there are sets to update), the fd-holder daemon in that +supervision tree runs as fdhuser rather than root. Told you: +you can safely forget about that option.
-f, --force: Make a new repository at repo even if one already exists. +This is dangerous, use of this option is not recommended.
-U, --update-stores: Rather than create a new repository, change the list of stores in an +existing one. This is useful, for instance, when a distribution's policies +change and local stores are added, moved, or removed. It is not an operation +that should be done frequently, however.
-B, --bare: Do not synchronize the repository with the stores. This is +useful if you are going to call +s6-rc-repo-sync afterwards anyway.

+ +

Exit codes

+ +

0: Success.
1: Failure. The services in the listed stores do not make a +consistent reference database. With a nonzero verbosity, the error +messages from s6-rc-compile will be displayed +and detail exactly what went wrong.
100: Incorrect usage.
111: System call failed. This usually signals an issue with the +underlying operating system.

+ +

Notes

+ +

s6-rc-repo-init is the first command to invoke when creating a repository, +or when a change occurs within the stores.
There is generally only one repository per system, but non-root users +who would want to run their own tree of s6-rc services can do so by specifying +an alternative repo.

+ + + diff --git a/doc/s6-rc-repo-sync.html b/doc/s6-rc-repo-sync.html new file mode 100644 index 0000000..cc2501b --- /dev/null +++ b/doc/s6-rc-repo-sync.html @@ -0,0 +1,100 @@ + + + + + + s6-rc: the s6-rc-repo-sync program + + + + + + +

+s6-rc
+Software
+skarnet.org +

+ +

The s6-rc-repo-sync program

+ +

+ s6-rc-repo-sync synchronizes a repository, +which means making an up-to-date reference +database, and ensuring that all defined +sets include all the services in the +repository's stores, and only them. +

+ +

Interface

+ +

+     s6-rc-repo-sync [ -v verbosity ] [ -r repo ] [ -h fdhuser ]
+

+ +

s6-rc-repo-sync looks at all the services defined in the repository's +stores, and compiles them into a +reference database.
It then looks at all the sets +and synchronizes them with the services in all the stores: +
- Existing services are preserved as they are.
- If a service doesn't appear in the stores, it is removed from all sets.
- If a new service is defined in the stores, it is added to all sets. Services +with the essential flag are added to the always +sub; services with +the recommended flag are added to the active sub; others are added +to the usable sub.
It exits 0.

+ +

Options

+ +

-v verbosity, --verbosity=verbosity: Be more or less verbose. The default is 1, which means +that error messages and warnings will be written to stderr. 0 means that only +error messages will be written, and 2 or more adds informational messages. +The option is also passed to commands that s6-rc-repo-sync may call, such +as s6-rc-compile, so their verbosity will +be similarly adjusted.
-r repo, --repository=repo: Use the repository in repo, which must exist. Default is +/var/lib/s6-rc/repository. +
-h fdhuser, --fdholder-user=fdhuser: You can safely ignore this option and forget about it. What it does +is ensure that if a supervision tree is started as root on a compiled +database produced by this command, the fd-holder daemon in that +supervision tree runs as fdhuser rather than root. (It is okay +to run that daemon as root.)

+ +

Exit codes

+ +

0: Success.
1: Failure. Either the services in the listed stores do not make a +consistent reference database, or some set is inconsistent. +With a nonzero verbosity, the error messages from +s6-rc-compile will be displayed +and detail exactly what went wrong.
100: Incorrect usage.
111: System call failed. This usually signals an issue with the +underlying operating system.

+ +

Notes

+ +

s6-rc-repo-sync should be called when the contents of the stores have +changed, for instance when the package manager has added packages that define +new services.

+ + + diff --git a/doc/s6-rc-set-copy.html b/doc/s6-rc-set-copy.html new file mode 100644 index 0000000..9d0681c --- /dev/null +++ b/doc/s6-rc-set-copy.html @@ -0,0 +1,72 @@ + + + + + + s6-rc: the s6-rc-set-copy program + + + + + + +

+s6-rc
+Software
+skarnet.org +

+ +

The s6-rc-set-copy program

+ +

+ s6-rc-set-copy makes a copy of a set under a +different name, in a repository. +

+ +

Interface

+ +

+     s6-rc-set-copy [ -v verbosity ] [ -r repo ] [ -f ] src dst
+

+ +

s6-rc-set-copy makes an exact copy of set src and names it dst.
It exits 0.

+ +

Options

+ +

-v verbosity, --verbosity=verbosity: Be more or less verbose. The default is 1, which means +that error messages and warnings will be written to stderr. 0 means that only +error messages will be written, and 2 or more adds informational messages.
-r repo, --repository=repo: Use the repository in repo, which must exist. Default is +/var/lib/s6-rc/repository. +
-f, --force: Overwrite set dst if it exists.

+ +

Exit codes

+ +

0: Success.
1: Set dst already exists and the -f option has not been given.
100: Incorrect usage.
102: Inconsistent repository.
111: System call failed.

+ +

Notes

+ +

s6-rc-set-copy can be used to create a dynamic working set, to be copied back +to its source when the user is happy with the changes.

+ + + diff --git a/doc/s6-rc-set-delete.html b/doc/s6-rc-set-delete.html new file mode 100644 index 0000000..efb1820 --- /dev/null +++ b/doc/s6-rc-set-delete.html @@ -0,0 +1,69 @@ + + + + + + s6-rc: the s6-rc-set-delete program + + + + + + +

+s6-rc
+Software
+skarnet.org +

+ +

The s6-rc-set-delete program

+ +

+ s6-rc-set-delete deletes a whole set +from a repository. +

+ +

Interface

+ +

+     s6-rc-set-delete [ -v verbosity ] [ -r repo ] setname...
+

+ +

For every argument in setname..., s6-rc-set-delete deletes that +set from the repository. +
It exits 0.

+ +

Options

+ +

-v verbosity, --verbosity=verbosity: Be more or less verbose. The default is 1, which means +that error messages and warnings will be written to stderr. 0 means that only +error messages will be written, and 2 or more adds informational messages.
-r repo, --repository=repo: Use the repository in repo, which must exist. Default is +/var/lib/s6-rc/repository. +

+ +

Exit codes

+ +

0: Success.
100: Incorrect usage.
111: System call failed.

+ +

Notes

+ +

An error in one of the arguments (e.g. if the user specifies a non-existent +set) will prevent processing the rest of the command line. The user should +double-check the set names in case of multiple deletions.

+ + + diff --git a/doc/s6-rc-set-new.html b/doc/s6-rc-set-new.html new file mode 100644 index 0000000..8cdc2f7 --- /dev/null +++ b/doc/s6-rc-set-new.html @@ -0,0 +1,76 @@ + + + + + + s6-rc: the s6-rc-set-new program + + + + + + +

+s6-rc
+Software
+skarnet.org +

+ +

The s6-rc-set-new program

+ +

+ s6-rc-set-new creates new sets +in a repository. +

+ +

Interface

+ +

+     s6-rc-set-delete [ -v verbosity ] [ -r repo ] setname...
+

+ +

For every argument in setname..., s6-rc-set-new creates a +set with that name, in the repository +repo. Under that set name, it attributes a default +sub to every service listed in the +stores: +
- Services with the essential flag are added to the always sub
- Services with the recommended flag are added to the active sub
- Others are added to the usable sub.
It exits 0.

+ +

Options

+ +

-v verbosity, --verbosity=verbosity: Be more or less verbose. The default is 1, which means +that error messages and warnings will be written to stderr. 0 means that only +error messages will be written, and 2 or more adds informational messages.
-r repo, --repository=repo: Use the repository in repo, which must exist. Default is +/var/lib/s6-rc/repository. +

+ +

Exit codes

+ +

0: Success.
100: Incorrect usage.
111: System call failed.

+ +

Notes

+ +

s6-rc-set-new can be called at the user's convenience, but in a typical +installation, two sets are enough: a stable committed set and a working set.

+ + + -- cgit v1.3.1