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 Dinit is designed to work on POSIXy operating systems such as Linux and
  23 OpenBSD. It is written in C++ and uses the "libev" event handling library.
  24 Development goals include clean design, robustness, portability, and
  25 avoiding feature bloat (whilst still handling a variety of use cases).
  26
  27 See doc/COMPARISON for a comparison of Dinit with similar software packages.
  28
  29 The primary author of Dinit is Davin McCall <davmac@davmac.org>.
  30
  31
  32 Introduction to services
  33 =-=-=-=-=-=-=-=-=-=-=-=-
  34
  35 A "service" is nominally a persistent process or system state. The two main
  36 types of service are a _process_ service (represented by a an actual process)
  37 and a _scripted_ service (which is started and stopped by running a process -
  38 often a shell script - to completion). There are also _bgprocess_ services
  39 and _internal_services.
  40
  41 Many programs that you might want to run under dinit's supervision can run
  42 either "in the foreground" or as a daemon ("in the background"), and the
  43 choice is dictated by a command line switch (for instance the -D and -F
  44 switches to Samba's "smbd"). Although it might seem counterintuitive,
  45 the "foreground" mode should be used for programs registered as process
  46 services in dinit; this allows dinit to monitor the process.
  47
  48 Process services are attractive due to the ease of monitoring (and
  49 restarting) the service, however, they have one inherent problem, which is
  50 that dinit cannot tell when the service is truly started. Once the process
  51 has been launched, dinit assumes that the service has started, but in fact
  52 there will be a short delay before the process sets itself up, starts
  53 listening on sockets, etc; during this time any other process (including
  54 one from a service listed as dependent) which tries to contact it will not
  55 be able to do so. In practice, this is not usually a problem (and external
  56 solutions, like D-Bus, do exist).
  57
  58 A _scripted_ service has separate commands for startup and (optional)
  59 shutdown. Scripted services can be used for tasks such as mounting file
  60 systems that don't need a persisten process, and in some cases can be used
  61 for daemon processes (although Dinit will not be able to supervise a
  62 process that is registered as a scripted service).
  63
  64 A _bgprocess_ service is a mix between a process service and a scripted
  65 service. A command is used to start the service, and once started, the
  66 process ID is expected to be available in a file which Dinit can then
  67 read. Many existing daemons can operate in this way. Dinit can only
  68 supervise the process if it runs as the system "init" (PID 1),
  69
  70 An _internal_ service is just a placeholder service that can be used to
  71 describe a set of dependencies. An internal service has no corresponding
  72 process.
  73
  74
  75 Service Description files
  76 =-=-=-=-=-=-=-=-=-=-=-=-=
  77
  78 Dinit discovers services by reading _service description files_. These files
  79 reside in a directory (/etc/dinit.d is the default "system" location) and
  80 their name matches the name of the service. Service descriptions are loaded
  81 lazily, as needed by Dinit.
  82
  83 A service description file consists of a number of parameter settings.
  84 Settings in the SDF are denoted as a parameter name followed by either an
  85 equal sign or colon and then the parameter value (all on the same line).
  86 Comments begin with a hash mark (#) and extend to the end of the line.
  87
  88 Parameter values are interpreted literally, except that:
  89  - whitespace is collapsed to a single space
  90  - double quotes can be used around all or part(s) of a parameter to prevent
  91    whitespace collapse and interpretation of special characters
  92  - backslash can be used to 'escape' the next character, preventing any
  93    special meaning from being associated with it. It can be used to include
  94    non-collapsing whitespace, double-quote marks, and backslashes in the
  95    parameter value.
  96
  97 Parameters are:
  98
  99 type = process | bgprocess | scripted | internal
 100 command = ...
 101 logfile = ...
 102 onstart = ...
 103 depends-on = (service name)
 104 waits-for = (service name)
 105
 106 command = (external script or executable, and arguments)
 107    For a 'process' service, this is the process to run.
 108    For a 'scripted' service, this command is run to start the service.
 109
 110 stop-command = (external script or executable, and arguments)
 111    For a 'scripted' service, this command is run to stop the service.
 112
 113 restart = yes | true | no | false
 114    Specifies whether the service should automatically restart if it becomes
 115    stopped (for any reason, including being explicitly requested to stop).
 116
 117 smooth-recovery = yes | true | no | false
 118    For process services only. Specifies that, should the process die, it
 119    can be restarted without bringing the service itself down. This means that
 120    any dependent services do not need to be stopped/restarted. Such recovery
 121    happens regardless of the "restart" setting (if smooth-recovery is enabled,
 122    the service does not reach the stopped state when the process terminates
 123    unexpectedly).
 124
 125 onstart = (internal commands)
 126    rw_ready - try again to open any logs, control socket etc that could not
 127               be opened previously due to a read-only filesystem.
 128
 129 depends-on = (service name)
 130    This service depends on the named service. Starting this service will
 131    start the named service; the command to start this service will not be
 132    executed until the named service has started. If the named service is
 133    stopped then this service will also be stopped.
 134
 135 waits-for = (service name)
 136    When this service is started, wait for the named service to finish
 137    starting (or to fail starting) before commencing the start procedure
 138    for this service. Starting this service will automatically start
 139    the named service.
 140
 141 termsignal = HUP | INT | QUIT | USR1 | USR2
 142    Specifies an additional signal to send to the process when requesting it
 143    to terminate (applies to 'process' services only). SIGTERM is always
 144    sent along with the specified signal, unless the 'nosigterm' setting is
 145    set true.
 146
 147 nosigterm = yes | true | no | false
 148    If true, the TERM signal will not be sent to the process to kill it. (If
 149    an alternate signal is specified using the "termsignal" setting, that
 150    signal will be sent instead; otherwise, no signal will be sent, and the
 151    process must be killed by external means).
 152
 153 runs-on-console = yes | no | true | false
 154   If true, the service runs on the console; its input and output are
 155   directed to the console (actually, to the terminal on which Dinit is
 156   running) and Dinit's own output will be suppressed during this time.
 157   Control signals (^C) may be used to control a service running on the
 158   console.
 159
 160   This is useful to allow a "login" master service to prevent Dinit output
 161   once terminal sessions are spawned, or to make fsck display its progress
 162   on the terminal (and be interruptible).
 163
 164   Only one service can run on the console at a time (services will queue
 165   in order to gain access to the console).
 166
 167   For scripted services, only the start command runs on the console.
 168   Process services and internal services take the console for the entire
 169   time that they are active (and cannot release it).
 170