From 96fbd74d6d70b562f45e327eeb0f625b54899bcc Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Sat, 4 Jul 2015 01:40:10 +0000 Subject: Start of doc --- doc/index.html | 142 +++++++++++++++++++++++++ doc/overview.html | 220 ++++++++++++++++++++++++++++++++++++++ doc/s6-rc-compile.html | 163 +++++++++++++++++++++++++++++ doc/s6-rc-db.html | 134 ++++++++++++++++++++++++ doc/s6-rc-dryrun.html | 64 ++++++++++++ doc/s6-rc-init.html | 168 ++++++++++++++++++++++++++++++ doc/s6-rc-upgrade.html | 174 +++++++++++++++++++++++++++++++ doc/s6-rc.html | 2 +- doc/upgrade.html | 28 +++++ doc/why.html | 278 +++++++++++++++++++++++++++++++++++++++++++++++++ 10 files changed, 1372 insertions(+), 1 deletion(-) create mode 100644 doc/index.html create mode 100644 doc/overview.html create mode 100644 doc/s6-rc-compile.html create mode 100644 doc/s6-rc-db.html create mode 100644 doc/s6-rc-dryrun.html create mode 100644 doc/s6-rc-init.html create mode 100644 doc/s6-rc-upgrade.html create mode 100644 doc/upgrade.html create mode 100644 doc/why.html diff --git a/doc/index.html b/doc/index.html new file mode 100644 index 0000000..543b4ca --- /dev/null +++ b/doc/index.html @@ -0,0 +1,142 @@ + + + + + + s6-rc - a service manager for s6 + + + + + + +

+Software
+skarnet.org +

+ +

s6-rc

+ +

What is it ?

+ +

+ s6-rc is a service manager for +s6-based +systems, i.e. a suite of programs that can start and stop +services, both long-running daemons and one-time +initialization scripts, in the proper order according to a +dependency tree. It ensures that long-running daemons are +supervised by the s6 infrastructure, and that one-time +scripts are also run in a controlled environment. +

+ +

Why such a program ?
A high-level overview of s6-rc

+ +

Installation

+ +

Requirements

+ +

A POSIX-compliant system with a standard C development environment
GNU make, version 4.0 or later
skalibs version +2.3.5.1 or later
execline version +2.1.2.2 or later
s6 version +2.1.6.0 or later

+ +

Licensing

+ +

+ s6-rc is free software. It is available under the +ISC license. +

+ +

Download

+ +

The current released version of s6-rc is +0.0.1.0.
Alternatively, you can checkout a copy of the s6-rc git repository: +
```
 git clone git://git.skarnet.org/s6-rc 
```
There's also a +GitHub mirror +of the s6 git repository.

+ +

Compilation

+ +

See the enclosed INSTALL file for installation details.

+ +

Upgrade notes

+ +

This page lists the differences to be aware of between +the previous versions of s6-rc and the current one.

+ +

Reference

+ +

Commands

+ +

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

+ +

Offline tools: creating and managing a compiled service database

+ +

Online tools: managing your live services

+ +

Related resources

+ +

Discussion

+ +

s6-rc is discussed on the +skaware mailing-list.

+ +

Similar work

+ +

anopa is another service manager +for s6, with a similar design (but no compilation phase).
nosh +is a complete init system and service manager for Unix.

+ +

Discussion

+ +

s6-rc is discussed on the +skaware mailing-list.

+ + + diff --git a/doc/overview.html b/doc/overview.html new file mode 100644 index 0000000..fd544a7 --- /dev/null +++ b/doc/overview.html @@ -0,0 +1,220 @@ + + + + + + s6-rc: an overview + + + + + + +

+s6-rc
+Software
+skarnet.org +

+ +

An overview of s6-rc

+ +

A manager for services

+ +

+ s6-rc is a service manager, or, in other words, a +machine state manager: given a database of services, +with dependencies between them, it can safely bring the +global machine state, or live state, to +the desired point, making sure dependencies are never +broken. +

+ +

The live state

+ +

+ The live state, by definition, is the tuple of +all service states on the machine. Changing the live state +means bringing services up, or bringing services down. +

+ +

2.5 kinds of services

+ +

+ Supervision suites manage long-lived processes, a.k.a +daemons, and sometimes call them services. +With s6-rc, those things are different: a long-lived process is +also called a longrun and is a service, but a service +does not have to be a longrun. There is a second kind of service, +which is called a oneshot, and which represents a change +of system state that is not embodied by the presence of a +long-lived process. For instance, "mounting a filesystem" is a +system state change, but in most cases there is no process hanging +around while the filesystem is mounted. +

+ +

+ s6-rc handles both oneshots and longruns. +

+ +

A longrun is the exact equivalent of a service +in the supervision sense. It is defined by a +service +directory, with a run script and optional other data. The +service is considered up as long as the long-lived +process is alive and, for daemons that support it, has +notified +its readiness. It is considered down otherwise.
A oneshot, on the other hand, is totally unknown +from supervision suites, because there is no daemon to manage. +A oneshot is represented by two short-lived scripts, up +and down, used to bring the service respectively up and +down. The service is considered up when the up +program has exited successfully, and until the down +program has exited successfully.

+ +

+ Services can depend on one another. +If service A has been declared as +depending on service B, then s6-rc will make sure to +never start A until it knows that B is up, +and will make sure to never stop B until it knows that +A is down. This works whether A and B +are both oneshots, both longruns, or a oneshot and a longrun. +

+ +

+ s6-rc also handles an additional kind of service: a bundle. +A bundle is just a collection of oneshots or longruns, described +under a single name. A bundle definition can even contain other +bundles, but ultimately a bundle will always represent a set of one +or more oneshots or longruns. A oneshot or longrun is called an +atomic service. +Bundle names can be used anywhere with the s6-rc user +interface, and they will internally be converted to a set of +atomic services. An atomic service can depend on a bundle: it will +simply depend on all the atomic services represented by the bundle. +A bundle, however, cannot have dependencies. +

+ +

A two-part operation

+ +

+ Unlike other service managers such as +anopa, s6-rc separates the +work of analyzing a set of service definitions, resolving +dependencies, and so on, from the work of actually applying the +dependency graph to perform live state changes. The former is +the compilation phase, and is done offline; the latter is +the live phase, and is of course done online - it impacts +the actual state of the machine. +

+ +

The compilation phase

+ +

Users are expected to write their service definitions - be it +oneshots, longruns or bundles - in one ore more +source directories, in the s6-rc +source format. +The source format is simple to parse automatically - which is +one of the main reasons why it has been designed that way - and +it is also simple to generate automatically: it is easy to write +converters from a given service definition format to the s6-rc +source format.
Users then run the +s6-rc-compile program, that takes +a set of service definitions in one or more source directories +and makes a compiled service database, abbreviated as +compiled. This compiled should be stored by the +administrator on the root filesystem.
The s6-rc-db tool can be used +to examine compiled service databases and extract information from +them in a human-friendly format.

+ +

The live phase

+ +

+ When the machine boots up: +

+ +

First, the chosen init should make sure that a +s6 +supervision tree is up and running. s6-rc will only work +if there is an active +s6-svscan +process monitoring a +scan +directory. On Linux, for instance, it is possible to achieve such a state +by using an init created by the +s6-linux-init-maker +tool: when control reaches stage 2, s6-svscan is guaranteed to run, +so using s6-rc in the stage 2 script is the way to go.
The boot process, let's name it stage2, should then call the +s6-rc-init program. This program +will set up an area for s6-rc in a writable directory (which can +be on a RAM filesystem such as tmpfs) to host its live information +such as the machine state, a working copy of all service directories +for longruns, and a link to the current compiled state database. +s6-rc-init initializes the machine state +as "every declared service is down".
stage2 should then invoke the +s6-rc program with the names of the services that +should be brought up given as arguments. Of course, bundles can be used +for shortcuts.
That's it, the services are up and the initialization should be +over. If the service database has been properly written, a stage2 +script can actually be really short: an invocation of +s6-rc-init and an invocation of +s6-rc.

+ +

Other state changes and shutdown

+ +

+ The administrator can make changes to the live state of the machine +by manually calling s6-rc again with the +proper arguments. This is more powerful than the old +runlevels: +it is possible to change the live state to any set of +services, not only predefined ones. The only thing that s6-rc will +not allow is a state that would break service dependencies; it +will always respect the dependency graph. +

+ +

+ The s6-rc command is the central for machine state changes, and it is +also true for shutdown. When shutting a machine down, all the services +managed by s6-rc should be brought down in the proper order (via the +s6-rc -da change command). Once all those services have been +brought down successfully, the final shutdown procedure can take place; +for instance, if s6-svscan is running as process 1 with the +s6-linux-init +defaults, s6-svscanctl -t /run/service will kill the +supervision tree and call /etc/rc.shutdown reboot, which should +reboot the machine. +

+ +

Live updates to the service database

+ +

+The s6-rc command is a one-stop shop for service management as long as +the compiled database doesn't change. If an administrator wishes to +make a new compiled database the current live one, without rebooting +the machine, a bit more work is needed, and that's the job of the +s6-rc-update command. This command +has been specifically written with Unix distributions in mind: when +new packages ship, they come with new service definitions, or upgraded +ones, and it is necessary to compile a new service database and update +the live state so it matches; if source definitions for s6-rc are +provided in the packages, an invocation of +s6-rc-compile followed by an invocation of +s6-rc-update should be all it takes to +keep the live state up to date. +

+ + + diff --git a/doc/s6-rc-compile.html b/doc/s6-rc-compile.html new file mode 100644 index 0000000..33d8bcd --- /dev/null +++ b/doc/s6-rc-compile.html @@ -0,0 +1,163 @@ + + + + + + s6-rc: the s6-rc-compile program + + + + + + +

+s6-rc
+Software
+skarnet.org +

+ +

The s6-rc-compile program

+ +

+ s6-rc is a machine state manager: it brings the machine to a +desired state, by starting or stopping services as needed. +

+ +

Interface

+ +

+     s6-rc [ -v verbosity ] [ servicenames... ]
+

+ +

s6-rc expects to find a compiled service database +in /etc/s6-rc/compiled and a live state in +/s6/s6-rc. If it cannot find that data, it complains and +exits. +
- The compiled service database is built offline +via the s6-rc-compile tool.
- The live state should be initialized at boot time +via the s6-rc-init tool. It is then +maintained by s6-rc itself.
The command line arguments servicenames... define a set +of selected services the user wants to act on.
s6-rc computes the necessary transitions to bring the machine +to the desired state - by default a state where all the +services listed on the command line are up. If asked to, it performs +those transitions.
s6-rc processes services as soon as they can be processed. It +will wait until a service is up to start a dependent service, but it +will start two independent services in parallel.
If every state transition completes successfully, s6-rc exits 0.
If a state transition fails, s6-rc will not perform the transitions +that depend on it. It will wait until all the other independent transitions +are done, then exit 1.

+ +

Options

+ +

s6-rc control

+ +

-v verbosity : be more or less +verbose. Default is 1: warning and error messages will be printed to +stderr. 0 silences warnings. 2 writes information messages whenever +s6-rc performs a transition. 3 or more is debug info.
-n dryruntimeout : dry run. +s6-rc will pretend to perform transitions, but will replace all its +program invocations by a call to +s6-rc-dryrun, which will do nothing but +print the command line s6-rc would have executed, then sleep for +dryruntimeout milliseconds before reporting success.
-t timeout : timeout. If s6-rc +isn't done after timeout milliseconds, it will exit, leaving +the live state as it is at exit time. It does not kill its children, so +a child may successfully complete afterwards and the live state will +not be updated; in that case, subsequent s6-rc invocations will notice +and correctly update it.
-c compiled : look for the +compiled service database in compiled. Default is +/etc/s6-rc/compiled
-l live : look for the +live state in live. Default is +/s6/s6-rc

+ +

Up or down

+ +

-u : selected services are interpreted +as to be brought up. This is the default.
-d : selected services are interpreted +as to be brought down.

+ +

Service selection

+ +

-p : prune. The state will be brought to +exactly servicenames..., plus their dependencies, and +the other services will be brought down. With the -d option, +the meaning is reversed: the state will be brought to the maximum +possible set that does not include servicenames....
-a : all. Add the current set of active services to +the selected set. This is useful to ensure consistency of the machine +state, for instance, and also at shutdown time: s6-rc -da +will stop all the currently active services.

+ +

Actions

+ +

-C : check. s6-rc will check the consistency of the +database, and exit with an error message if it finds errors.
-L : list. s6-rc will resolve the given names, then +print the list of corresponding atomic services to stdout, without taking their +dependencies into account. It will print an empty line afterwards.
-A : list all. s6-rc will print the list of selected +atomic services to stdout, after computing dependencies. Note that with +the -d option, it computes reverse dependencies instead.
-S : state change. A state change will be performed +for the selected services. +This is the default if no other action option has been given.

+ +

Usage examples

+ +

 s6-rc myservicebundle

+ Brings up all the services represented by myservicebundle, +dependencies first. +

+ +

 s6-rc -Sad

+ Brings down all the services in an orderly manner. This is typically +run at shutdown time. +

+ +

 s6-rc -Au myservicebundle

+ Prints the names of all atomic services represented by +myservicebundle, as well as everything they depend on. +

+ +

 s6-rc -Ad myservicebundle

+ Prints the names of all atomic services represented by +myservicebundle, as well as everything that depends on them. +

+ +

 s6-rc -pun0 myservicebundle

+ Prints what s6-rc would do to bring the state to just +myservicebundle and its dependencies. +

+ + +

Internals

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

+s6-rc
+Software
+skarnet.org +

+ +

The s6-rc-db program

+ +

+ s6-rc-db is a tool to analyze a compiled service database +and extract information from it, and print it in a user-friendly +format. +

+ +

+ It is an offline tool, i.e. you can run it on any +compiled service database without actually having a live set +of services managed by s6-rc. However, if you do have a live +set, you can still run s6-rc-db on the current database (and +it is the default); it won't interfere with your normal service +operation. +

+ +

Interface

+ +

+     s6-rc-db help
+     s6-rc-db [ -l live ] [ -c compiled ] check
+     s6-rc-db [ -l live ] [ -c compiled ] list all|services|oneshots|longruns|bundles
+     s6-rc-db [ -l live ] [ -c compiled ] type servicename
+     s6-rc-db [ -l live ] [ -c compiled ] [ -u | -d ] timeout atomicname
+     s6-rc-db [ -l live ] [ -c compiled ] contents bundlename
+     s6-rc-db [ -l live ] [ -c compiled ] [ -u | -d ] dependencies servicename
+     s6-rc-db [ -l live ] [ -c compiled ] servicedir longrunname
+     s6-rc-db [ -l live ] [ -c compiled ] [ -u | -d ] script oneshotname
+     s6-rc-db [ -l live ] [ -c compiled ] flags atomicname
+     s6-rc-db [ -l live ] [ -c compiled ] atomics servicename...
+     s6-rc-db [ -l live ] [ -c compiled ] [ -u | -d ] all-dependencies servicename...
+

+ +

s6-rc-db expects to find a compiled service database +in compiled; by default it uses the service database +used by the live state in live. +It reads and parses the compiled database it finds. If the +database is invalid, it exits 4.
Depending on the arguments given, it prints the requested +information to stdout, then exits 0.

+ +

Options

+ +

-c compiled : examine a +compiled service database in compiled instead of +the current live one.
-l live : assume the live +state is in live. Default is +/run/s6-rc. This option is ignored if the +-c option has been given.
-u : for commands that use different data +depending on whether it's about bringing the service up or down, +select the "up" data. This option is ignored when it is irrelevant.
-d : for commands that use different data +depending on whether it's about bringing the service up or down, +select the "down" data. This option is ignored when it is irrelevant.

+ +

Subcommands

+ +

s6-rc-db help

+ +

+ Prints a help message on stdout. +

+ +

s6-rc-db check

+ +

+ Checks the database consistency. Exits 4 with an error message if +it finds a problem, such as a mismatch in the direct and reverse +dependency tables, or a dependency cycle. +

+ + +

Usage examples

+ +

 s6-rc myservicebundle

+ Brings up all the services represented by myservicebundle, +dependencies first. +

+ +

 s6-rc -Sad

+ Brings down all the services in an orderly manner. This is typically +run at shutdown time. +

+ +

 s6-rc -Au myservicebundle

+ Prints the names of all atomic services represented by +myservicebundle, as well as everything they depend on. +

+ +

 s6-rc -Ad myservicebundle

+ Prints the names of all atomic services represented by +myservicebundle, as well as everything that depends on them. +

+ +

 s6-rc -pun0 myservicebundle

+ Prints what s6-rc would do to bring the state to just +myservicebundle and its dependencies. +

+ + +

Internals

+ + + diff --git a/doc/s6-rc-dryrun.html b/doc/s6-rc-dryrun.html new file mode 100644 index 0000000..0a55fa6 --- /dev/null +++ b/doc/s6-rc-dryrun.html @@ -0,0 +1,64 @@ + + + + + + s6-rc: the s6-rc-dryrun program + + + + + + +

+s6-rc
+Software
+skarnet.org +

+ +

The s6-rc-dryrun internal program

+ +

+ s6-rc-dryrun is a command wrapper and nullifier, roughly +equivalent to the Unix echo command. When run, it +simply prints its arguments to stdout. +

+ +

+ s6-rc-dryrun is not meant to be used directly; it is +internally called by +s6-rc when given the -n +option. When a dry-running s6-rc instance wants to change the +system state by spawning a command cmd, it spawns +s6-rc-dryrun cmd instead, which allows the user +to see what would have been done without actually running the +command. +

+ +

Interface

+ +

+     s6-rc-dryrun [ -v verbosity ] [ -t timeout ] cmd...
+

+ +

s6-rc-dryrun prints its name, a colon, a space, and +the space-separated list of its arguments to stdout.
It then waits for timeout milliseconds, then +exits 0.

+ +

Options

+ +

-v verbosity : if verbosity +is 0, s6-rc-dryrun will not print anything to stdout. Default is 1.
-t timeout : sleep for timeout +milliseconds before exiting. Default is 1000, but when invoked by +s6-rc, it will be the value of the +dryruntimeout argument to the -n option. This is +used to simulate a non-immediate startup or shutdown script.

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

+s6-rc
+Software
+skarnet.org +

+ +

The s6-rc-init program

+ +

+ s6-rc-init is an initialization tool for the s6-rc +system. It must be run at boot time, prior to any +invocation of the +s6-rc binary. +

+ +

Requirements

+ + +

Interface

+ +

+     s6-rc-init [ -v verbosity ] [ servicenames... ]
+

+ +

s6-rc expects to find a compiled service database +in /etc/s6-rc/compiled and a live state in +/s6/s6-rc. If it cannot find that data, it complains and +exits. +
- The compiled service database is built offline +via the s6-rc-compile tool.
- The live state should be initialized at boot time +via the s6-rc-init tool. It is then +maintained by s6-rc itself.
The command line arguments servicenames... define a set +of selected services the user wants to act on.
s6-rc computes the necessary transitions to bring the machine +to the desired state - by default a state where all the +services listed on the command line are up. If asked to, it performs +those transitions.
s6-rc processes services as soon as they can be processed. It +will wait until a service is up to start a dependent service, but it +will start two independent services in parallel.
If every state transition completes successfully, s6-rc exits 0.
If a state transition fails, s6-rc will not perform the transitions +that depend on it. It will wait until all the other independent transitions +are done, then exit 1.

+ +

Options

+ +

s6-rc control

+ +

-v verbosity : be more or less +verbose. Default is 1: warning and error messages will be printed to +stderr. 0 silences warnings. 2 writes information messages whenever +s6-rc performs a transition. 3 or more is debug info.
-n dryruntimeout : dry run. +s6-rc will pretend to perform transitions, but will replace all its +program invocations by a call to +s6-rc-dryrun, which will do nothing but +print the command line s6-rc would have executed, then sleep for +dryruntimeout milliseconds before reporting success.
-t timeout : timeout. If s6-rc +isn't done after timeout milliseconds, it will exit, leaving +the live state as it is at exit time. It does not kill its children, so +a child may successfully complete afterwards and the live state will +not be updated; in that case, subsequent s6-rc invocations will notice +and correctly update it.
-c compiled : look for the +compiled service database in compiled. Default is +/etc/s6-rc/compiled
-l live : look for the +live state in live. Default is +/s6/s6-rc

+ +

Up or down

+ +

-u : selected services are interpreted +as to be brought up. This is the default.
-d : selected services are interpreted +as to be brought down.

+ +

Service selection

+ +

-p : prune. The state will be brought to +exactly servicenames..., plus their dependencies, and +the other services will be brought down. With the -d option, +the meaning is reversed: the state will be brought to the maximum +possible set that does not include servicenames....
-a : all. Add the current set of active services to +the selected set. This is useful to ensure consistency of the machine +state, for instance, and also at shutdown time: s6-rc -da +will stop all the currently active services.

+ +

Actions

+ +

-C : check. s6-rc will check the consistency of the +database, and exit with an error message if it finds errors.
-L : list. s6-rc will resolve the given names, then +print the list of corresponding atomic services to stdout, without taking their +dependencies into account. It will print an empty line afterwards.
-A : list all. s6-rc will print the list of selected +atomic services to stdout, after computing dependencies. Note that with +the -d option, it computes reverse dependencies instead.
-S : state change. A state change will be performed +for the selected services. +This is the default if no other action option has been given.

+ +

Usage examples

+ +

 s6-rc myservicebundle

+ Brings up all the services represented by myservicebundle, +dependencies first. +

+ +

 s6-rc -Sad

+ Brings down all the services in an orderly manner. This is typically +run at shutdown time. +

+ +

 s6-rc -Au myservicebundle

+ Prints the names of all atomic services represented by +myservicebundle, as well as everything they depend on. +

+ +

 s6-rc -Ad myservicebundle

+ Prints the names of all atomic services represented by +myservicebundle, as well as everything that depends on them. +

+ +

 s6-rc -pun0 myservicebundle

+ Prints what s6-rc would do to bring the state to just +myservicebundle and its dependencies. +

+ + +

Internals

+ + + diff --git a/doc/s6-rc-upgrade.html b/doc/s6-rc-upgrade.html new file mode 100644 index 0000000..bdaa090 --- /dev/null +++ b/doc/s6-rc-upgrade.html @@ -0,0 +1,174 @@ + + + + + + s6-rc: the s6-rc-update program + + + + + + +

+s6-rc
+Software
+skarnet.org +

+ +

The s6-rc-update program

+ +

+ s6-rc-update is an online service database switcher: +it will replace your compiled service database with another +one, and adjust the live state accordingly. +

+ +

+ Live upgrading a service database is no small feat, and no +fully automated system can get it right in all cases. +s6-rc-update will do its best on its own, but it lets you +give it instructions to handle +difficult cases; and rather than implement doubtful +heuristics, it will fail with an error message in +situations it really cannot solve. +

+ +

Interface

+ +

+     s6-rc [ -v verbosity ] [ servicenames... ]
+

+ +

s6-rc expects to find a compiled service database +in /etc/s6-rc/compiled and a live state in +/s6/s6-rc. If it cannot find that data, it complains and +exits. +
- The compiled service database is built offline +via the s6-rc-compile tool.
- The live state should be initialized at boot time +via the s6-rc-init tool. It is then +maintained by s6-rc itself.
The command line arguments servicenames... define a set +of selected services the user wants to act on.
s6-rc computes the necessary transitions to bring the machine +to the desired state - by default a state where all the +services listed on the command line are up. If asked to, it performs +those transitions.
s6-rc processes services as soon as they can be processed. It +will wait until a service is up to start a dependent service, but it +will start two independent services in parallel.
If every state transition completes successfully, s6-rc exits 0.
If a state transition fails, s6-rc will not perform the transitions +that depend on it. It will wait until all the other independent transitions +are done, then exit 1.

+ +

Options

+ +

s6-rc control

+ +

-v verbosity : be more or less +verbose. Default is 1: warning and error messages will be printed to +stderr. 0 silences warnings. 2 writes information messages whenever +s6-rc performs a transition. 3 or more is debug info.
-n dryruntimeout : dry run. +s6-rc will pretend to perform transitions, but will replace all its +program invocations by a call to +s6-rc-dryrun, which will do nothing but +print the command line s6-rc would have executed, then sleep for +dryruntimeout milliseconds before reporting success.
-t timeout : timeout. If s6-rc +isn't done after timeout milliseconds, it will exit, leaving +the live state as it is at exit time. It does not kill its children, so +a child may successfully complete afterwards and the live state will +not be updated; in that case, subsequent s6-rc invocations will notice +and correctly update it.
-c compiled : look for the +compiled service database in compiled. Default is +/etc/s6-rc/compiled
-l live : look for the +live state in live. Default is +/s6/s6-rc

+ +

Up or down

+ +

-u : selected services are interpreted +as to be brought up. This is the default.
-d : selected services are interpreted +as to be brought down.

+ +

Service selection

+ +

-p : prune. The state will be brought to +exactly servicenames..., plus their dependencies, and +the other services will be brought down. With the -d option, +the meaning is reversed: the state will be brought to the maximum +possible set that does not include servicenames....
-a : all. Add the current set of active services to +the selected set. This is useful to ensure consistency of the machine +state, for instance, and also at shutdown time: s6-rc -da +will stop all the currently active services.

+ +

Actions

+ +

-C : check. s6-rc will check the consistency of the +database, and exit with an error message if it finds errors.
-L : list. s6-rc will resolve the given names, then +print the list of corresponding atomic services to stdout, without taking their +dependencies into account. It will print an empty line afterwards.
-A : list all. s6-rc will print the list of selected +atomic services to stdout, after computing dependencies. Note that with +the -d option, it computes reverse dependencies instead.
-S : state change. A state change will be performed +for the selected services. +This is the default if no other action option has been given.

+ +

Usage examples

+ +

 s6-rc myservicebundle

+ Brings up all the services represented by myservicebundle, +dependencies first. +

+ +

 s6-rc -Sad

+ Brings down all the services in an orderly manner. This is typically +run at shutdown time. +

+ +

 s6-rc -Au myservicebundle

+ Prints the names of all atomic services represented by +myservicebundle, as well as everything they depend on. +

+ +

 s6-rc -Ad myservicebundle

+ Prints the names of all atomic services represented by +myservicebundle, as well as everything that depends on them. +

+ +

 s6-rc -pun0 myservicebundle

+ Prints what s6-rc would do to bring the state to just +myservicebundle and its dependencies. +

+ + +

Internals

+ + + diff --git a/doc/s6-rc.html b/doc/s6-rc.html index eeefe7a..34dfc59 100644 --- a/doc/s6-rc.html +++ b/doc/s6-rc.html @@ -26,7 +26,7 @@ desired state, by starting or stopping services as needed.

Interface

-     s6-rc [ -v verbosity ] [servicenames...
+     s6-rc [ -v verbosity ] [ servicenames... ]

s6-rc: how to upgrade

+s6-rc
+Software
+skarnet.org +

What has changed in s6-rc

in 0.0.1.0

Initial release.

s6-rc: why?

+s6-rc
+Software
+skarnet.org +

Why s6-rc ?

The limits of supervision suites

+ Supervision suites such as +s6, +runit, +perp or +daemontools +define a service as a long-lived process, a.k.a a +daemon. They provide tools to run the daemon in a reproducible +way in a controlled environment and keep it alive if it dies; +they also provide daemon management tools to, among others, +send signals to the daemon without knowing its PID. They can +control individual long-lived process perfectly well, and +s6 also provides +tools to manage a whole supervision tree. +

+ However, a supervision suite is not a service manager. +

+ Relying on a supervision suite to handle all the service +management is doable on simple systems, where there aren't +many dependencies, and where most of the one-time initialization +can take place in stage 1, before any daemons are launched. +On embedded systems, for instance, this is perfectly reasonable. +

+ On bigger systems, though, it is more problematic. Here are a few +issues encountered: +

With a pure supervision tree, all daemons are launched in +parallel; if their dependencies are not met, daemons just die, and +are restarted by the supervisors, and so on; so eventually everything +is brought up. This is okay with lightweight daemons that do not take +up too many resources when starting; but with heavyweight daemons, +bringing them up at the wrong time can significantly expend CPU and +increase the total booting time.
The runit model of +separating one-time initialization (stage 1) and daemon management +(stage 2) does not always work: some one-time initialization may +depend on a daemon being up. Example: udevd on Linux. Such daemons +then need to be run in stage 1, unsupervised - which defeats the +purpose of having a supervision suite.
More generally, supervision suites do not perform +dependency management. Their job is to maintain daemons +alive and ease their administration; dependency across those +daemons is not their concern, and one-time initialization scripts +are entirely foreign to them. So a situation like udevd +where it is necessary to interleave daemons and one-time scripts +is very badly handled by them.

+ To manage complex systems, pure supervision suites are insufficient, +and real service managers, starting and stopping services +in the proper order and handling both oneshots (one-time +initialization scripts) and longruns (daemons), are needed. +

Previous alternatives

+ Unix distributions usually come with their own init systems and +service managers; all of those have flaws one way or another. No +widely spread init system gets things right, which is the main +reason for the recent "init wars" - there are strong, valid reasons +to support such or such init system, but also strong, valid +reason to dislike it. +

+ Non-supervision init systems usually fall in one of two categories, +both with pros and cons. +

Traditional, sequential starters

+ Those are either the historical Unix init systems, or newer systems +that still favor simplicity. Among them, for instance: +

sysvinit, +the historical GNU/Linux init system, and its companion set of +/etc/rc.d init scripts that some distributions like to +call sysv-rc. Note that sysvinit does have +supervision capabilities, but nobody ever bothered to use them +for anything else than gettys, and all the machine +initialization, including longruns, is done by the sysv-rc +scripts, in a less than elegant way.
BSD +init, which is very similar to sysvinit - including the +supervision abilities that are only ever used for gettys. +The /etc/rc script takes care of all the initialization.
OpenRC, +an alternative, dependency-based rc system.

+ All these systems run sequentially: they will start services, either +oneshots or longruns, one by one, even when the dependency graph says +that some services could be started in parallel. Also, the daemons +they start are always unsupervised, even when the underlying init +system provides supervision features. There usually is no +readiness +notification support on daemons either, daemons are fire-and-forget +(but that's more on the +scripts themselves than on the frameworks). Another common criticism +of those systems is that the amount of shell scripting is so huge +that it has a significant performance impact. +

+ Another, less obvious, but important drawback is that service-launching +scripts run as scions of the shell that invoked the command, and so +they may exhibit different behaviours when they're run automatically at +boot time and when they're run manually by an admin, because the +environment is different. Scripts usually try to run in a clean +environment, but it's hard to think of everything (open file +descriptors!) and every script must protect itself with a gigantic +boilerplate, which adds to the inefficiency problem. +

Monolithic init behemoths

+ The other category of service managers is made of attempts to cover +the flaws of traditional service starters, and provide supervision, +dependency management and sometimes readiness notification, while +reducing the amount of scripting needed. +Unfortunately, the results were tightly integrated, monolithic init +systems straying very far away from Unix core principles, with +design flaws that make the historical inits' design flaws look like +a joke. +

Upstart was the first +one. On the front page, in the "feature highlights" section: +"Tasks and Services are started and stopped +by events. Events are generated as tasks and services are started +and stopped." Do you understand what that means? I don't.
launchd, +Darwin's init and service manager. The wikipedia page (linked here +because Apple doesn't see fit to provide a documentation page for +launchd) is very clear: it replaces init, rc, init.d/rc.d, +SystemStarter, inetd, crontd, atd and watchdogd. It does all of this +in process 1. And it uses XML for daemon configuration, so process 1 +has to link in a XML parsing library.
systemd, +the main protagonist (or antagonist) in the "init wars". It has the same +problems as launchd, up by an order of magnitude; +here is why. +systemd avowedly aims to replace the whole low-level user-space of +Linux systems, but its design is horrendous. It doesn't even +get readiness notification right.

+ The problem of integrated init systems is that: +

They have been developed by companies and associations, not +individuals, and despite the licensing, they are for all intents and +purposes closer to proprietary software than free software; they also +suffer from many of the technical flaws of enterprise software +design.
As a result, and despite being backed by tremendous manpower, +they have been very poorly thought out. The manpower goes into the +coding of features, not into architecture conception; and the +architects were obviously not Unix experts, which is a shame when +it's about creating a process 1 for Unix. This is apparent because:
They have been designed like application software, not +system software, which requires a fairly different set of +skills, and careful attention to details - such as minimal software +dependencies and shortness of code paths - that are not as important +in application software.

+ Pages and pages could be written about the shortcomings of integrated +init systems; one fact remains - they are not a satisfying solution +to the problem of service management under Unix. +

The best of both worlds

+ s6-rc aims to be such a solution: it is small and modular, but offers +full functionality. Parallel service startup and shutdown with +correct dependency management (none of the systemd nonsense where +services are started before their dependencies are met), correct +readiness notification support, reproducible script execution, and +short code paths. +

s6-rc is a service manager, i.e. the equivalent of +sysv-rc or OpenRC. It is not an init system. +You can run s6-rc with any init system of your choosing. +Of course, s6-rc requires a s6 supervision tree to be running on +the system, since it delegates the management of longrun services +to that supervision tree, but it does not require that s6 be the +init system itself. s6-rc will work +when s6-svscan +runs as process 1 (on Linux, such a setup can be easily achieved +via the help of the +s6-linux-init +package), and it will also work +when +s6-svscan runs under another init process.
The service manager runs on top of a supervision +suite. It does not try to make it perform boot/shutdown operations or +dependency management itself; and it does not substitute itself to it. +s6-rc uses the functionality provided by s6, but it is still possible +to run s6 without s6-rc for systems that do not need a service manager. +It would also be theoretically possible to run s6-rc on top of another +supervision suite, if said supervision suite provided the hooks that +s6-rc needs.
A significantly time-consuming part of a service manager is +the analysis of a set of services and computation of a dependency graph +for that set. At the time of writing this document, s6-rc is the only +service manager that performs that work offline, eliminating +the dependency analysis overhead from boot time, shutdown time, or +any other time where the machine state changes.
The source format for the +s6-rc-compile tool is purposefully +simple, in order to allow external tools to automatically write +service definitions for s6-rc - for instance for conversions between +service manager formats.
Like every +skarnet.org tool, s6-rc +is made of very little code, that does its job and nothing else. +The binaries are small, it is very light in memory usage, and the +code paths are extremely short.

+ The combination of s6 and s6-rc makes a complete, full-featured and +performant init system and service manager, with probably the lowest +total memory footprint of any service manager out there, and all the +reliability and ease of administration that a supervision suite can +provide. It is a real, viable alternative to integrated init +behemoths, providing equivalent functionality while being much +smaller and much, much more maintainable. +