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/s6-rc-compile.html | 118 ++++++++++++++++++++++++++++++++++++------------- 1 file changed, 87 insertions(+), 31 deletions(-) (limited to 'doc/s6-rc-compile.html') diff --git a/doc/s6-rc-compile.html b/doc/s6-rc-compile.html index a11acfb..44327ba 100644 --- a/doc/s6-rc-compile.html +++ b/doc/s6-rc-compile.html @@ -36,7 +36,7 @@ the current service database via

Interface 

-     s6-rc-compile [ -v verbosity ] [ -u uids ] [ -g gids ] compiled source...
+     s6-rc-compile [ -v verbosity ] [ -u uids ] [ -g gids ] [ -h fdhuser ] compiled source...
+ +

Exit codes

+ +

Options

@@ -64,6 +72,11 @@ numerical UIDs. use this database with s6-rc to start and stop services. gids must be a comma-separated list of numerical GIDs. +
  • -h fdhuser : arrange for the +s6-fdholder-daemon +program, which maintains the pipes for the longrun pipelines, to run +as user fdhuser. By default, it runs as the user owning +the supervision tree, i.e. most likely root.

    • @@ -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

    -- cgit v1.2.3