README

   1 Dinit
   2 -----
   3 v0.1 (pre-release)
   4
   5
   6 What is it?
   7 =-=-=-=-=-=
   8
   9 "Dinit" is a service supervisor with dependency support which can also
  10 act as the system "init" program.
  11
  12 Specifically it can launch multiple services (generally, "daemon" processes,
  13 but see notes below) in parallel, with dependency management (i.e. if one
  14 service's operation depends on another, the latter service will be started
  15 first).
  16
  17 For "process" services dinit can monitor the process corresponding to the
  18 service, and re-start it if it dies. It does this in an intelligent way,
  19 first "rolling back" all dependent services (which it will later re-start,
  20 if configured to do so).
  21
  22
  23 Introduction to services
  24 =-=-=-=-=-=-=-=-=-=-=-=-
  25
  26 A "service" is nominally a persistent process or system state. The two main
  27 types of service are a _process_ service (represented by a an actual process)
  28 and a _scripted_ service (which is started and stopped by running a process -
  29 often a shell script - to completion).
  30
  31 Many programs that you might want to run under dinit's supervision can run
  32 either "in the foreground" or as a daemon ("in the background"), and the
  33 choice is dictated by a command line switch (for instance the -D and -F
  34 switches to Samba's "smbd"). Although it might seem counterintuitive,
  35 the "foreground" mode should be used for programs registered as process
  36 services in dinit; this allows dinit to monitor the process.
  37
  38 Process services are attractive due to the ease of monitoring (and
  39 restarting) the service, however, they have one inherent problem, which is
  40 that dinit cannot tell when the service is truly started. Once the process
  41 has been launched, dinit assumes that the service has started, but in fact
  42 there will be a short delay before the process sets itself up, starts
  43 listening on sockets, etc; during this time any other process (including
  44 one from a service listed as dependent) which tries to contact it will not
  45 be able to do so. In practice, this is not usually a problem (and external
  46 solutions, like D-Bus, do exist).
  47
  48
  49
  50 Service Description files
  51 =-=-=-=-=-=-=-=-=-=-=-=-=
  52
  53 Dinit discovers services by reading _service description files_. These files
  54 reside in a directory (/etc/dinit.d is the default "system" location) and
  55 their name matches the name of the service. Service descriptions are loaded
  56 lazily, as needed by Dinit.
  57
  58 A service description file consists of a number of parameter settings.
  59 Settings in the SDF are denoted as a parameter name followed by either an
  60 equal sign or colon and then the parameter value (all on the same line).
  61 Comments begin with a hash mark (#) and extend to the end of the line.
  62
  63 Parameter values are interpreted literally, except that:
  64  - whitespace is collapsed to a single space
  65  - double quotes can be used around all or part(s) of a parameter to prevent
  66    whitespace collapse and interpretation of special characters
  67  - backslash can be used to 'escape' the next character, preventing any
  68    special meaning from being associated with it. It can be used to include
  69    non-collapsing whitespace, double-quote marks, and backslashes in the
  70    parameter value.
  71
  72 Parameters are:
  73
  74 type = process | scripted | internal
  75 command = ...
  76 restart = yes | true | no | false
  77 logfile = ...
  78 onstart = ...
  79 depends-on = (service name)
  80 waits-for = (service name)
  81
  82 command = (external script or executable and arguments)
  83    For a 'process' service, this is the process to run.
  84    For a 'scripted' service, this process is run both to start the service
  85    (with the command-line argument "start" appended) and to stop the
  86    service (with "stop").
  87
  88 onstart = (internal commands)
  89    release_console - stop performing output to the console (usually used
  90               when login prompt is spawned)
  91    rw_ready - try again to open any logs, control socket etc that could not
  92               be opened previously due to a read-only filesystem.
  93
  94 depends-on = (service name)
  95    This service depends on the named service. Starting this service will
  96    start the named service; the command to start this service will not be
  97    executed until the named service has started. If the named service is
  98    stopped then this service will also be stopped.
  99
 100 waits-for = (service name)
 101    When this service is started, wait for the named service to finish
 102    starting (or to fail starting) before commencing the start procedure
 103    for this service. Starting this service will automatically start
 104    the named service.