s6-rc is a service manager, a.k.a machine state manager: a program to manage the live state of a machine - what services are currently up and what services are currently down. It can list active services, or change the live state.
s6-rc is meant to be the one-stop shop of service management: once service definitions have been made into a compiled service database via s6-rc-compile, and the machine state has been initialized via s6-rc-init, any state change - be it initial startup, shutdown, or anything else - should be achieved by a single s6-rc change invocation.
s6-rc should only be run as root, especially when asking for a state change.
s6-rc help
s6-rc [ -l live ] [ -a ] [ -u | -d ] list servicenames...
s6-rc [ -l live ] [ -a ] [ -u | -d ] listall servicenames...
s6-rc [ -l live ] [ -a ] [ -u | -d ] [ -p ] [ -v verbosity ] [ -n dryrunthrottle ] [ -t timeout ] change [ servicenames... ]
The arguments servicenames... may be atomic services or bundles; they are resolved into a set of atomic services, which is called the selection. If the -a option is present, the current set of up services is added to the selection. The s6-rc command operates on the selection.
These options control what is to be done: bring selected services up or down (for s6-rc change) or whether to use the forward or reverse dependency graph (for s6-rc listall). Default is up.
Prints a short help message.
Prints the selection. If the -d option has been given, the selection is inverted before it is printed, i.e. all the services but servicenames... will be printed.
This is mostly useful as s6-rc -a list, which simply prints the list of currently active services. s6-rc -da list will print the list of currently down services.
s6-rc change is the service state engine. It will bring the machine to a state where:
To do so:
Transitions for longrun services are simple: s6-rc removes or create a down file, then sends a command to the supervision tree to start or stop the service. (A service that is considered down by s6-rc will have a down file in its live service directory; a service that is considered up by s6-rc will not.) The transition is considered successful as soon as the daemon dies (for down transitions), or becomes up and ready (for up transitions). If a longrun service does not support readiness notification, the s6-svc command that is invoked by s6-rc will print a warning message, and the transition will be considered successful as soon as the daemon is up, i.e. as soon as the run script is executed by s6-supervise.
When a longrun service supports readiness notification, unless a nonzero timeout has been declared in the timeout-up file in the service definition directory, s6-rc will wait forever on an "up" transition for the notification to arrive. The transition will fail if a timeout occurs.
Transitions are supposed to be idempotent, but it is a general rule of supervision that run and finish scripts must be idempotent, so a properly designed service directory should work with s6-rc with no additional effort.
Transitions for oneshot services involve running the up or down script for the service; those scripts are stored in the compiled service database that is linked from the live state. The transition is considered successful if the script exits zero, and unsuccessful otherwise.
s6-rc performs some black magic so that up and down scripts are always run in a reproducible way, no matter when or how s6-rc change is invoked. That black magic involves a special longrun service, s6rc-oneshot-runner, that every oneshot service automatically depends on, and that is actually used to fork the up or down scripts as scions of the s6 supervision tree, instead of children of the s6-rc process.
Transitions should be ideally transactional, or at the very least idempotent. If a transition fails, it should leave the machine in the same state as before the transition was attempted; at the very least, it should not prevent a subsequent run of the same transition from completing successfully. If an s6-rc change invocation fails because some transition experienced a temporary failure, it should be possible to run the exact same s6-rc change invocation later, and be met with success.
This is important: it means that oneshot scripts should be treated as atoms, and that some care should be taken when writing them.
For any manual change, is it recommended to perform a dry run before the state change itself: add the -n dryrunthrottle option to the s6-rc command line. s6-rc will then simulate all the transitions, but not actually perform them or change the real live state. The command lines that s6-rc would have run will be printed to stdout instead, and each simulated transition will take dryrunthrottle milliseconds to complete successfully.
s6-rc change myservicebundle
Brings up all the services represented by myservicebundle, bringing up all its dependencies first (recursively).
s6-rc -ad change
Brings down all the currently running services in an orderly manner. This is typically run at shutdown time.
s6-rc -l /zork -ua listall myservicebundle
Prints the names of all atomic services represented by myservicebundle plus the current live services, as well as everything they depend on, recursively. Assumes the live state is stored in the /zork directory instead of /run/s6-rc.
s6-rc -d listall 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 exactly the contents of myservicebundle as well as its recursive dependencies, and pruning all the rest. Do not wait any extra time between simulated transitions.