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 Dinit is licensed under the Apache License, version 2.0. A copy of this
  30 license can be found in the LICENSE file.
  31
  32 Dinit was written by Davin McCall <davmac@davmac.org>.
  33
  34
  35 Introduction to services
  36 =-=-=-=-=-=-=-=-=-=-=-=-
  37
  38 A "service" is nominally a persistent process or system state. The two main
  39 types of service are a _process_ service (represented by a an actual process)
  40 and a _scripted_ service (which is started and stopped by running a process -
  41 often a shell script - to completion). There are also _bgprocess_ services
  42 and _internal_services.
  43
  44 Many programs that you might want to run under dinit's supervision can run
  45 either "in the foreground" or as a daemon ("in the background"), and the
  46 choice is dictated by a command line switch (for instance the -D and -F
  47 switches to Samba's "smbd"). Although it might seem counterintuitive,
  48 the "foreground" mode should be used for programs registered as process
  49 services in dinit; this allows dinit to monitor the process.
  50
  51 Process services are attractive due to the ease of monitoring (and
  52 restarting) the service, however, they have one inherent problem, which is
  53 that dinit cannot tell when the service is truly started. Once the process
  54 has been launched, dinit assumes that the service has started, but in fact
  55 there will be a short delay before the process sets itself up, starts
  56 listening on sockets, etc; during this time any other process (including
  57 one from a service listed as dependent) which tries to contact it will not
  58 be able to do so. In practice, this is not usually a problem (and external
  59 solutions, like D-Bus, do exist).
  60
  61 A _scripted_ service has separate commands for startup and (optional)
  62 shutdown. Scripted services can be used for tasks such as mounting file
  63 systems that don't need a persisten process, and in some cases can be used
  64 for daemon processes (although Dinit will not be able to supervise a
  65 process that is registered as a scripted service).
  66
  67 A _bgprocess_ service is a mix between a process service and a scripted
  68 service. A command is used to start the service, and once started, the
  69 process ID is expected to be available in a file which Dinit can then
  70 read. Many existing daemons can operate in this way. Dinit can only
  71 supervise the process if it runs as the system "init" (PID 1),
  72
  73 An _internal_ service is just a placeholder service that can be used to
  74 describe a set of dependencies. An internal service has no corresponding
  75 process.
  76
  77
  78 Service Hiearchy and states
  79 =-=-=-=-=-=-=-=-=-=-=-=-=-=
  80
  81 Services can depend on other services for operation, and so form a
  82 dependency hierarchy. Starting a service which depends on another
  83 causes that other service to start (and the first service waits until
  84 the latter has started before its process is launched and it is itself
  85 considered started).
  86
  87 Services are considered _active_ when they are not stopped. Services
  88 can also be explicitly marked as active (this normally happens when you
  89 explicitly start a service). Finally, a service with an active dependent
  90 is also considered active.
  91
  92 If a service stops and becomes inactive (i.e. it is not explicitly marked
  93 active and has no active dependents) then any services it depends on will
  94 also be marked inactive and stopped unless they have other active
  95 dependents (or are explicitly active).
  96
  97 What this means is that, in general, starting an (inactive, stopped)
  98 service and then stopping it will return the system to its prior state -
  99 no dependencies which were started automatically will be left running.
 100
 101
 102 Service Description files
 103 =-=-=-=-=-=-=-=-=-=-=-=-=
 104
 105 Dinit discovers services by reading _service description files_. These files
 106 reside in a directory (/etc/dinit.d is the default "system" location) and
 107 their name matches the name of the service. Service descriptions are loaded
 108 lazily, as needed by Dinit.
 109
 110 A service description file consists of a number of parameter settings.
 111 Settings in the SDF are denoted as a parameter name followed by either an
 112 equal sign or colon and then the parameter value (all on the same line).
 113 Comments begin with a hash mark (#) and extend to the end of the line.
 114
 115 Parameter values are interpreted literally, except that:
 116  - whitespace is collapsed to a single space
 117  - double quotes can be used around all or part(s) of a parameter to prevent
 118    whitespace collapse and interpretation of special characters
 119  - backslash can be used to 'escape' the next character, preventing any
 120    special meaning from being associated with it. It can be used to include
 121    non-collapsing whitespace, double-quote marks, and backslashes in the
 122    parameter value.
 123
 124 Parameters are:
 125
 126 type = process | bgprocess | scripted | internal
 127 command = ...
 128 logfile = ...
 129 onstart = ...
 130 depends-on = (service name)
 131 waits-for = (service name)
 132
 133 command = (external script or executable, and arguments)
 134    For a 'process' service, this is the process to run.
 135    For a 'scripted' service, this command is run to start the service.
 136
 137 stop-command = (external script or executable, and arguments)
 138    For a 'scripted' service, this command is run to stop the service.
 139
 140 restart = yes | true | no | false
 141    Specifies whether the service should automatically restart if it becomes
 142    stopped (for any reason, including being explicitly requested to stop).
 143    Only active services will restart automatically.
 144
 145 smooth-recovery = yes | true | no | false
 146    For process services only. Specifies that, should the process die, it
 147    can be restarted without bringing the service itself down. This means that
 148    any dependent services do not need to be stopped/restarted. Such recovery
 149    happens regardless of the "restart" setting (if smooth-recovery is enabled,
 150    the service does not reach the stopped state when the process terminates
 151    unexpectedly).
 152
 153 onstart = (internal commands)
 154    rw_ready - try again to open any logs, control socket etc that could not
 155               be opened previously due to a read-only filesystem.
 156
 157 depends-on = (service name)
 158    This service depends on the named service. Starting this service will
 159    start the named service; the command to start this service will not be
 160    executed until the named service has started. If the named service is
 161    stopped then this service will also be stopped.
 162
 163 waits-for = (service name)
 164    When this service is started, wait for the named service to finish
 165    starting (or to fail starting) before commencing the start procedure
 166    for this service. Starting this service will automatically start
 167    the named service.
 168
 169 socket-listen = (socket path)
 170    Pre-open a socket for the service and pass it to the service using the
 171    Systemd activation protocol. This by itself does not give so called
 172    "socket activation", but does allow that any process trying to connect
 173    to the specified socket will be able to do so, even before the service
 174    is properly prepared to accept connections.
 175
 176 socket-permissions = (octal permissions mask)
 177    Gives the permissions for the socket specified using socket-listen.
 178    Normally this will be 600 (user access only), 660 (user and group
 179    access), or 666 (all users).
 180
 181 socket-uid = (numeric user id or username)
 182    Specifies the user that should own the activation socket. If socket-uid
 183    is specified without also specifying socket-gid, then the socket group
 184    is the primary group of the specified user (as found in the system user
 185    database, normally /etc/passwd). If the socket owner is not specified,
 186    the socket will be owned by the user id of the Dinit process.
 187
 188 socket-gid = (numeric group id or group name)
 189    Specifies the group of the activation socket. See discussion of
 190    socket-uid.
 191
 192 termsignal = HUP | INT | QUIT | USR1 | USR2
 193    Specifies an additional signal to send to the process when requesting it
 194    to terminate (applies to 'process' services only). SIGTERM is always
 195    sent along with the specified signal, unless the 'nosigterm' setting is
 196    set true.
 197
 198 nosigterm = yes | true | no | false
 199    If true, the TERM signal will not be sent to the process to kill it. (If
 200    an alternate signal is specified using the "termsignal" setting, that
 201    signal will be sent instead; otherwise, no signal will be sent, and the
 202    process must be killed by external means).
 203
 204 runs-on-console = yes | no | true | false
 205   If true, the service runs on the console; its input and output are
 206   directed to the console (actually, to the terminal on which Dinit is
 207   running) and Dinit's own output will be suppressed during this time.
 208   Control signals (^C) may be used to control a service running on the
 209   console.
 210
 211   This is useful to allow a "login" master service to prevent Dinit output
 212   once terminal sessions are spawned, or to make fsck display its progress
 213   on the terminal (and be interruptible).
 214
 215   Only one service can run on the console at a time (services will queue
 216   in order to gain access to the console).
 217
 218   For scripted services, only the start command runs on the console.
 219   Process services and internal services take the console for the entire
 220   time that they are active (and cannot release it).
 221