From 087097faa52791f941daaab5c14200a470f6aebe Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Tue, 7 Jul 2015 21:11:25 +0000 Subject: - More doc! - Cosmetic fixes in s6-rc-compile --- doc/s6-rc-compile.html | 311 ++++++++++++++++++++++++++++++++-------------- doc/s6-rc-update.html | 46 +++++++ doc/s6-rc-upgrade.html | 174 -------------------------- src/s6-rc/s6-rc-compile.c | 23 +--- 4 files changed, 265 insertions(+), 289 deletions(-) create mode 100644 doc/s6-rc-update.html delete mode 100644 doc/s6-rc-upgrade.html diff --git a/doc/s6-rc-compile.html b/doc/s6-rc-compile.html index 33d8bcd..4d9aeeb 100644 --- a/doc/s6-rc-compile.html +++ b/doc/s6-rc-compile.html @@ -19,145 +19,270 @@

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. + s6-rc-compile is a service database compiler. It takes a series +of service definitions in the source format, and compiles +them into a directory, which is the compiled format. +

+ +

+ The administrator can then examine that compiled database via +s6-rc-db, put it into a place where +it will be registered at boot time as the current compiled database +by s6-rc-init, or even live update +the current service database via +s6-rc-update.

Interface

-     s6-rc [ -v verbosity ] [ servicenames... ]
+     s6-rc-compile [ -v verbosity ] compiled source...

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.
s6-rc-compile analyzes every directory source in its +arguments. For every subdirectory service in source, +it expects to find a valid service definition in service.
s6-rc-compile outputs a compiled version of the service database +into compiled. This database contains information for all the +services declared in every source argument.
s6-rc-compile exits 0.

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

+ +

Source format

+ +

+ s6-rc-compile scans every source directory to find +service definition directories in it. It ignores every +file that is not a directory, or that starts with a dot. For +every service definition directory that it finds, it creates a +service with the same name as the directory. Names cannot be +duplicated and cannot contain a slash or a newline; they can +contain spaces and tabs, but using anything else than alphanumerical +characters, underscores and dashes is discouraged - the s6-rc programs +will handle weird names just fine, but other tools, especially +shell scripts, may not. +

+ +

+ Every service +definition directory service is expected to contain the following files: +

+ +

For every service

+ +

A regular file named type, that contains only the text +oneshot, longrun or bundle, and a terminating +newline. This file declares the type of service defined by the +directory.

+ +

For bundles

+ +

A regular file named contents. This file must be a list +of service names, one per line. Whitespace at the beginning of a line +is ignored, but trailing whitespace is not. Lines starting with a # +character are ignored. The file defines the services that will be +represented by the bundle named service.

Up or down

+ It is possible to use bundle names in a contents file. +However, if s6-rc-compile detects a cycle in bundle definitions, it will +complain and exit 1. +

+ +

For atomic services

-u : selected services are interpreted -as to be brought up. This is the default.
-d : selected services are interpreted -as to be brought down.
An optional regular file named timeout-up. This file, if it exists, +must contain an integer, which is the maximum number of milliseconds +s6-rc will wait for successful completion of the service +start; if starting the service takes longer than this value, s6-rc will declare +the transition a failure. If the file does not exist, or contains 0, no timeout +is defined and s6-rc will wait indefinitely for the service to start.
An optional regular file named timeout-down. This file, if it exists, +must contain an integer, which is the maximum number of milliseconds +s6-rc will wait for successful completion of the service +stop; if stopping the service takes longer than this value, s6-rc will declare +the transition a failure. If the file does not exist, or contains 0, no timeout +is defined and s6-rc will wait indefinitely for the service to stop.
An optional regular file named dependencies. This file must be a list +of service names, one per line. Whitespace at the beginning of a line +is ignored, but trailing whitespace is not. Lines starting with a # +character are ignored. The file defines the direct dependencies of +service, i.e. the services that must be up in order for +service to work properly.

Service selection

+ It is unnecessary to manually define complete sets of dependencies in the +dependency file, because +s6-rc will properly handle dependency chains. +anyway. If A depends on B, no matter the underlying +implementation of B, and the current implementation of B +depends on C, then you should just put B in +A/dependencies; when starting the set, +s6-rc will start C first, then +B, then A. If the underlying implementation of B +changes and does not depend on C, then you will just have to +modify the dependencies for B, not for A +

+ +

+ Of course, if A depends on C anyway, you should add +both B and C to A/dependencies. +

+ +

+ If s6-rc-compile detects a cycle in dependencies across services, it will +complain and exit 1. +

+ +

For oneshots

-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.
Two mandatory regular files named up and down, which +must each contain a single Unix command line. The files will be interpreted by the +execlineb +lexer at compile time and the results will be stored into the +compiled database in an internal form. up will be run when +the service is started, and down will be executed when the service +is stopped.

Actions

+ +

+ up and down are interpreted by +execlineb, but +that does not mean they have to be entirely written in the +execline language. The +execlineb +lexer is only used because it can compile a Unix command line from a text file +and store the compiled result, whereas a shell would have to be invoked +everytime the script is run. There are many ways to write up and +down scripts: +

-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.
They can be written as standard execline scripts, without the +initial shebang line or positional parameter management.
They can be written in any scripting language by invoking the interpreter +directly: for instance +/bin/sh -c "script", where script is +a shell script.
They can also just call a script that will actually be stored somewhere else: +for instance, up can contain /etc/init.d/service start +while down contains /etc/init.d/service stop, and +/etc/init.d/service is a System V-style init script.

Usage examples

+ Don't think you have to learn all the intricacies of the execline language +just because the up and down scripts get lexed by it. +You don't. +

+ +

For longruns

 s6-rc myservicebundle

- Brings up all the services represented by myservicebundle, -dependencies first. + The s6-rc service definition directory for a longrun service is similar to +a s6 service +directory, but there are a few differences:

 s6-rc -Sad

s6-rc-compile crafts the servicedir itself, based on what it +finds in the service definition directory. It does not copy everything +directly from the definition directory to the servicedir; only two +subdirectories will be copied as is, data and env. +So if you want to store service configuration data, to be used +by the run script, in the service directory, make sure it is in a +data/ or env/ subdirectory.
Definition directories cannot have a log subdirectory - +or if they do, it will be ignored. From s6-rc-compile's point of view, +logged s6 services must actually be defined as two separate +s6-rc services, one for the producer and one for the logger; there is +specific syntax to link those two services.

- Brings down all the services in an orderly manner. This is typically -run at shutdown time. + The following files must or may appear in a longrun definition directory:

 s6-rc -Au myservicebundle

A mandatory regular file named run, as well as optional files +named finish, notification-fd and nosetsid. These +files will be copied, or recreated, in the generated +service directory. +
Optional directories named data and env. These will +be copied verbatim into the generated service directory.
An optional file named logger. If this file exists, then +service will be flagged as a producer, and the file must +contain the name of another longrun service servicelog, which will +be declared as a logger for service. service must also +be declared as a producer in servicelog's definition directory.
An optional file named producer. If this file exists, then +service will be flagged as a logger, and the file must +contain the name of another longrun service serviceprod, which will +be declared as a producer for service. service must also +be declared as a logger in serviceprod's definition directory.

- Prints the names of all atomic services represented by -myservicebundle, as well as everything they depend on. + Be aware that service directories will be relocated, and copied at boot time, +so if your run or finish scripts refer to files in the service directory +(probably in the data or env subdirectories!), they should +use relative paths, not absolute ones.

 s6-rc -Ad myservicebundle

- Prints the names of all atomic services represented by -myservicebundle, as well as everything that depends on them. + Note that you cannot create a down file in a generated service +directory. Even if such a file exists in the definition directory, it will +be ignored. This is intentional: +s6-rc internally uses down files to mark longrun +services that are down.

 s6-rc -pun0 myservicebundle

- Prints what s6-rc would do to bring the state to just -myservicebundle and its dependencies. + The logger and producer files are support for logged services: +A service defined as a logger for producer p will have its s6 service +directory set to p/log. Logged service definitions must be consistent:

It is impossible to have a both a logger and a producer file +in the same definition directory: loggers cannot have loggers, producers cannot have +producers.
The logger must be declared in the logger file in its producer's +definition directory, and the producer must be declared in the producer file +in its logger's definition directory. If it sees an inconsistency, s6-rc-compile +will complain and exit 1.

+ +

A complete example

Internals

+ The examples/source subdirectory of the s6-rc package contains a set +of service definition directories, which is actually a working, valid set for a +Linux system running +busybox and the +skarnet.org packages. You can compile +it with s6-rc-compile /tmp/compiled examples/source, then examine the +resulting compiled database with +s6-rc-db -c /tmp/compiled subcommand. +

diff --git a/doc/s6-rc-update.html b/doc/s6-rc-update.html new file mode 100644 index 0000000..26ebf48 --- /dev/null +++ b/doc/s6-rc-update.html @@ -0,0 +1,46 @@ + + + + + + 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-update [ -v verbosity ]
+

+ +

Options

+ + + diff --git a/doc/s6-rc-upgrade.html b/doc/s6-rc-upgrade.html deleted file mode 100644 index bdaa090..0000000 --- a/doc/s6-rc-upgrade.html +++ /dev/null @@ -1,174 +0,0 @@ - - - - - - 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/src/s6-rc/s6-rc-compile.c b/src/s6-rc/s6-rc-compile.c index b056f64..b2b82dd 100644 --- a/src/s6-rc/s6-rc-compile.c +++ b/src/s6-rc/s6-rc-compile.c @@ -25,13 +25,6 @@ #include #include -// #ifdef DEBUG -// # include -// # define DBG(...) do { buffer_puts(buffer_2, PROG) ; buffer_puts(buffer_2, ": debug: ") ; bprintf(buffer_2, __VA_ARGS__) ; buffer_putflush(buffer_2, "\n", 1) ; } while (0) -// #else -// # define DBG(...) -// #endif - #define USAGE "s6-rc-compile [ -v verbosity ] destdir sources..." #define dieusage() strerr_dieusage(100, USAGE) #define dienomem() strerr_dief1x(111, "out of memory") ; @@ -267,7 +260,6 @@ static int add_namelist (before_t *be, int dirfd, char const *srcdir, char const if (fd < 0) return 0 ; buffer_init(&b, &fd_readsv, fd, buf, 2048) ; *listindex = genalloc_len(unsigned int, &be->indices) ; - // DBG("add_namelist %s %s: *listindex is %u", name, list, *listindex) ; while (cont) { register int r = skagetln(&b, &satmp, '\n') ; @@ -300,7 +292,6 @@ static int add_namelist (before_t *be, int dirfd, char const *srcdir, char const } close(fd) ; *n = genalloc_len(unsigned int, &be->indices) - *listindex ; - // DBG("add_namelist %s %s: *n is %u", name, list, *n) ; return 1 ; } @@ -547,20 +538,16 @@ static void resolve_bundle_rec (bundle_recinfo_t *recinfo, unsigned int i) register nameinfo_t const *p ; avltree_search(&names_map, data.s + listindex[j], &id) ; p = genalloc_s(nameinfo_t, &nameinfo) + id ; -// DBG("resolve_bundle_rec: %s depends on %s", data.s + me->name, data.s + p->pos) ; switch (p->type) { case SVTYPE_ONESHOT : bitarray_set(recinfo->barray + i * recinfo->nbits, recinfo->nlong + p->i) ; -// DBG("resolve_bundle_rec: %s is a oneshot, setting bit %u in barray[%u]", data.s + p->pos, recinfo->nlong + p->i, i) ; break ; case SVTYPE_LONGRUN : bitarray_set(recinfo->barray + i * recinfo->nbits, p->i) ; -// DBG("resolve_bundle_rec: %s is a longrun, setting bit %u in barray[%u]", data.s + p->pos, p->i, i) ; break ; case SVTYPE_BUNDLE : resolve_bundle_rec(recinfo, p->i) ; -// DBG("resolve_bundle_rec: %s is a bundle, adding barray[%u] to barray[%u]", data.s + p->pos, p->i, i) ; bitarray_or(recinfo->barray + i * recinfo->nbits, recinfo->barray + i * recinfo->nbits, recinfo->barray + p->i * recinfo->nbits, recinfo->n) ; break ; default : @@ -604,11 +591,7 @@ static inline void flatlist_bundles (bundle_t *bundles, unsigned int nbundles, u uint32 *mydeps = bdeps + bundles[i].listindex ; unsigned int j = 0, k = 0 ; for (; k < bundles[i].n ; j++) - if (bitarray_peek(mybits, j)) - { - mydeps[k++] = j ; -// DBG("flatlist_bundles: bundle %u contains service %u", i, j) ; - } + if (bitarray_peek(mybits, j)) mydeps[k++] = j ; } } @@ -621,12 +604,10 @@ static void resolve_deps (common_t const *me, unsigned int nlong, unsigned int n register nameinfo_t const *p ; avltree_search(&names_map, data.s + indices[me->depindex + j], &id) ; p = genalloc_s(nameinfo_t, &nameinfo) + id ; -// DBG("resolve_deps: %s depends on %s", data.s + me->name, data.s + p->pos) ; switch (p->type) { case SVTYPE_ONESHOT : bitarray_set(sarray, nlong + p->i) ; -// DBG("resolve_deps: %s is a oneshot, setting bit %u in sarray for %s", data.s + p->pos, nlong + p->i, data.s + me->name) ; if (verbosity >= 4) { char fmt[UINT_FMT] ; @@ -636,7 +617,6 @@ static void resolve_deps (common_t const *me, unsigned int nlong, unsigned int n break ; case SVTYPE_LONGRUN : bitarray_set(sarray, p->i) ; -// DBG("resolve_deps: %s is a longrun, setting bit %u in sarray for %s", data.s + p->pos, p->i, data.s + me->name) ; if (verbosity >= 4) { char fmt[UINT_FMT] ; @@ -646,7 +626,6 @@ static void resolve_deps (common_t const *me, unsigned int nlong, unsigned int n break ; case SVTYPE_BUNDLE : bitarray_or(sarray, sarray, barray + p->i * nbits, n) ; -// DBG("resolve_deps: %s is a bundle, ORing barray[%u] into sarray for %s", data.s + p->pos, p->i, data.s + me->name) ; if (verbosity >= 4) { char fmt[UINT_FMT] ; -- cgit v1.2.3