From 9473830ad612dcb674f6048a9a17e372ff9d9ec3 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Wed, 12 Aug 2015 20:00:17 +0000 Subject: Intermediary commit; working on source dir format change. Should work, but untested as for now. --- doc/index.html | 11 ++--- doc/s6-rc-compile.html | 118 ++++++++++++++++++++++++++++++++++++------------- doc/s6-rc-db.html | 50 +++++++++++---------- doc/s6-rc.html | 12 +++++ 4 files changed, 129 insertions(+), 62 deletions(-) (limited to 'doc') diff --git a/doc/index.html b/doc/index.html index c889800..de0d23d 100644 --- a/doc/index.html +++ b/doc/index.html @@ -47,11 +47,11 @@ scripts are also run in a controlled environment.
  • A POSIX-compliant system with a standard C development environment
  • GNU make, version 4.0 or later
  • skalibs version -2.3.6.0 or later
    • +2.3.6.1 or later
  • execline version -2.1.3.0 or later
    • +2.1.3.1 or later
  • s6 version -2.2.0.0 or later
    • +2.2.0.1 or later

    Licensing

    @@ -92,11 +92,6 @@ the previous versions of s6-rc and the current one.

    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

    @@ -85,7 +98,8 @@ 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. +shell scripts, may not. Names are also forbidden to use the reserved +s6rc- and s6-rc- prefixes.

    @@ -221,15 +235,16 @@ directory, but there are a few differences:

  • 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. +subdirectories will be copied verbatim, 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.
    • +s6-rc services, one defined as a producer and one defined as a consumer, +making a pipeline of just two services; see below for more information +about pipelines.

    @@ -243,16 +258,23 @@ 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.
    • +
  • An optional file named producer-for. If this file exists, then +it must contain the name of another longrun service servicelog; +service is then declared as a producer for servicelog. +servicelog must also, in its own definition directory, +be declared as a consumer for service.
    • +
  • An optional file named consumer-for. If this file exists, then +it must contain the name of another longrun service serviceprod; +service is then declared as a consumer for serviceprod. +serviceprod must also, in its own definition directory, +be declared as a producer for service.
    • +
  • An optional file named pipeline-name. If this file exists +along with a producer-for file, and there is no +consumer-for file, then a bundle will automatically be +created, named with the content of the pipeline-name file, and +containing all the services in the pipeline that starts at service. +See below for more about pipelining. The pipeline-name file +is ignored if service is not a first producer.

    • @@ -271,26 +293,60 @@ services that are down.

    - 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: + The producer-for, consumer-for and pipeline-name +files are used to set up automatic longrun pipelining. +

    + +

    Longrun pipelining

    + +

    + Users of supervision suites know about logged services: a service acts +as a producer, and is coupled with another service, its logger; the +supervision system automatically maintains an open pipe between the +producer's stdout and the logger's stdin. +

    + +

    + s6-rc comes with an extension of this mechanism. Rather than only +allowing two longrun services to be pipelined, it can set up an +indefinite number of longrun services this way.

    +

    + s6-rc-compile will detect pipelines, and set up the service directories +so that every producer's stdout is connected to its consumer's stdin, and +that the pipes are not broken whenever one element in the chain dies. +

    + +

    + s6-rc-compile checks for pipeline consistency. It must see a +producer-for file in the producer's definition that is consistent +with the consumer-for file in the consumer's definition. It will +detect and reject cycles as well as collisions. +

    + +

    + The pipe linking a producer and a consumer is created by an automatically +generated oneshot service that both the producer and consumer depend on, +and stored in a +s6-fdholder-daemon +instance created by an automatically generated longrun service. +

    +

    A complete example

    diff --git a/doc/s6-rc-db.html b/doc/s6-rc-db.html index 280f98a..a60658e 100644 --- a/doc/s6-rc-db.html +++ b/doc/s6-rc-db.html @@ -43,7 +43,7 @@ operation. 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 ] pipeline 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... @@ -54,9 +54,8 @@ operation.

  • 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 +It reads and parses the compiled database it finds; depending on +its arguments, it prints the requested information to stdout, then exits 0.
    • @@ -78,6 +77,17 @@ depending on whether it's about bringing the service up or down, select the "down" data. This option is ignored when it is irrelevant. +

    Exit codes

    + + +

    Subcommands

    s6-rc-db help

    @@ -134,8 +144,7 @@ dependency tables, or a dependency cycle.

    Prints the type of servicename: oneshot, longrun -or bundle. Exits 1 if -servicename is not a valid identifier in the database. +or bundle.

    s6-rc-db timeout atomicname

    @@ -143,8 +152,8 @@ or bundle. Exits 1 if

    Prints the timeout value, in milliseconds, after which bringing atomicname up or down is considered a failure if the -called script still has not succeeded. Exits 1 if atomicname -isn't a valid atomic service. By default, or if the -u +called script still has not succeeded. +By default, or if the -u option has been given to s6-rc-db, the timeout for up is printed; the timeout for down is printed instead if the -d option has been given. @@ -154,14 +163,12 @@ printed; the timeout for down is printed instead if the

    Lists the atomic services represented by bundle bundlename. -Exits 1 if bundlename is not a valid bundle.

    s6-rc-db dependencies servicename

    - Prints the list of direct dependencies for servicename. -Exits 1 if servicename isn't a valid identifier. If + Prints the list of direct dependencies for servicename. If servicename is a bundle, its set of direct dependencies is the union of the direct dependencies of all the atomic services contained in the bundle. @@ -174,12 +181,13 @@ depend on servicename, or on one of its components if it is a bundle.

    -

    s6-rc-db servicedir longrunname

    +

    s6-rc-db pipeline longrunname

    - Prints the service directory for longrun service longrunname; -this value is relative to the scandir. Exits 1 if -longrunname is not a valid longrun. + Prints the longrun service pipeline longrunname is a +part of, one service per line, producers before consumers. +If longrunname isn't +part of a pipeline, only longrunname is printed.

    s6-rc-db script oneshotname

    @@ -190,8 +198,7 @@ an argv, i.e. a Unix command line. Each component of this command line is terminated by a null character, so to print it in a human-readable format, pipe the output into something like -xargs -0 echo. The command exits 1 if oneshotname -is not a valid oneshot. +xargs -0 echo.

    @@ -203,8 +210,7 @@ is not a valid oneshot.

    Prints a hexadecimal number that is the list of all binary flags -for atomic service atomicname. Exits 1 if atomicname -is not a valid atomic service. +for atomic service atomicname.

    @@ -219,8 +225,7 @@ future version of s6-rc. servicename... arguments, i.e. the union of all atomic services contained in servicename.... Each argument in servicename... can be an atomic service or -a bundle. If an argument isn't a valid identifier, the command -exits 1. +a bundle.

    s6-rc-db all-dependencies servicename...

    @@ -232,8 +237,7 @@ dependencies, recursively. In other words: for servicename... to be up, every single service listed in the output will need to be up. The output includes the atomic services represented by the -servicename... arguments themselves. If one of those -arguments isn't a valid identifier, the command exits 1. +servicename... arguments themselves.

    diff --git a/doc/s6-rc.html b/doc/s6-rc.html index ae3e469..75dba9a 100644 --- a/doc/s6-rc.html +++ b/doc/s6-rc.html @@ -59,6 +59,18 @@ information to stdout, then exits 0; or it performs a machine state change. +

    Exit codes

    + + +

    Service selection

    -- cgit v1.2.3