README

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