From a491c627e09aa1149196dd40cb377d181db0580a Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Tue, 7 Jul 2015 14:39:16 +0000 Subject: - Minor fixes to s6-rc - More doc --- doc/s6-rc.html | 304 ++++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 228 insertions(+), 76 deletions(-) (limited to 'doc/s6-rc.html') diff --git a/doc/s6-rc.html b/doc/s6-rc.html index 34dfc59..ff18362 100644 --- a/doc/s6-rc.html +++ b/doc/s6-rc.html @@ -19,46 +19,85 @@

The s6-rc program

- s6-rc is a machine state manager: it brings the machine to a -desired state, by starting or stopping services as needed. + 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.

Interface 

-     s6-rc [ -v verbosity ] [ servicenames... ]
+     s6-rc help
+     s6-rc [ -l live ] [ -a ] 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... ]
+

Service selection

+ +

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

+

Options

-

s6-rc control

+

General options

+ + + +

Up or down

+ +

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

+ + + +

s6-rc change control

-

Up or down

+

Subcommands

+ +

s6-rc help

+ +

+ Prints a short help message. +

+ +

s6-rc list servicenames...

+ +

+ Prints the selection. +

+ +

+ This is mostly useful as s6-rc -a list, which simply prints +the list of currently active services. +

+ +

s6-rc listall servicenames...

-

Service selection

+

s6-rc change

+ +

+ s6-rc change is the service state engine. It will bring the +machine to a state where: +

-

Actions

+

+ To do so: +

+

Longrun transitions

+ +

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

+ +

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

+ +

Oneshot transitions

+ +

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

+ +

Dry runs

+ +

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

+

Usage examples

-
 s6-rc myservicebundle
+
 s6-rc change myservicebundle

Brings up all the services represented by myservicebundle, -dependencies first. +bringing up all its dependencies first (recursively).

-
 s6-rc -Sad
+
 s6-rc -ad change

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

-
 s6-rc -Au myservicebundle
+
 s6-rc -l /zork -ua listall myservicebundle

Prints the names of all atomic services represented by -myservicebundle, as well as everything they depend on. +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 -Ad myservicebundle
+
 s6-rc -d listall myservicebundle

Prints the names of all atomic services represented by myservicebundle, as well as everything that depends on them. @@ -152,12 +305,11 @@ run at shutdown time. 

 s6-rc -pun0 myservicebundle

- Prints what s6-rc would do to bring the state to just -myservicebundle and its dependencies. + 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.

- -

Internals

- -- cgit v1.2.3