README

   1 Dinit
   2 -----
   3 v0.05 (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, and restarting them when their
  20 dependencies are satisfied.
  21
  22 Dinit includes a tool ("dinitctl") to issue commands to the main Dinit
  23 process, and a "shutdown" program (with scripts "halt" and "reboot") to
  24 manage shutting down and restarting the system.
  25
  26 Dinit is designed to work on POSIXy operating systems such as Linux and
  27 OpenBSD. It is written in C++ and uses the "Dasynq" event handling library,
  28 which was written especially to support Dinit.
  29
  30 Development goals include clean design, robustness, portability, and
  31 avoiding feature bloat (whilst still handling a variety of use cases).
  32
  33 See doc/COMPARISON for a comparison of Dinit with similar software packages.
  34
  35 Dinit is licensed under the Apache License, version 2.0. A copy of this
  36 license can be found in the LICENSE file.
  37
  38 Dinit was written by Davin McCall <davmac@davmac.org>.
  39
  40 See BUILD for information on how to build Dinit.
  41
  42
  43 Introduction to services
  44 =-=-=-=-=-=-=-=-=-=-=-=-
  45
  46 A "service" is nominally a persistent process or system state. The two main
  47 types of service are a _process_ service (represented by a an actual process)
  48 and a _scripted_ service (which is started and stopped by running a process -
  49 often a shell script - to completion). There are also _bgprocess_ services
  50 and _internal_services.
  51
  52 Many programs that you might want to run under dinit's supervision can run
  53 either "in the foreground" or as a daemon ("in the background"), and the
  54 choice is dictated by a command line switch (for instance the -D and -F
  55 switches to Samba's "smbd"). Although it might seem counterintuitive,
  56 the "foreground" mode should be used for programs registered as process
  57 services in dinit; this allows dinit to monitor the process.
  58
  59 Process services are attractive due to the ease of monitoring (and
  60 restarting) the service, however, they have one inherent problem, which is
  61 that dinit cannot tell when the service is truly started. Once the process
  62 has been launched, dinit assumes that the service has started, but in fact
  63 there will be a short delay before the process sets itself up, starts
  64 listening on sockets, etc; during this time any other process (including
  65 one from a service listed as dependent) which tries to contact it will not
  66 be able to do so. In practice, this is not usually a problem (and external
  67 solutions, like D-Bus, do exist).
  68
  69 A _scripted_ service has separate commands for startup and (optional)
  70 shutdown. Scripted services can be used for tasks such as mounting file
  71 systems that don't need a persisten process, and in some cases can be used
  72 for daemon processes (although Dinit will not be able to supervise a
  73 process that is registered as a scripted service).
  74
  75 A _bgprocess_ service is a mix between a process service and a scripted
  76 service. A command is used to start the service, and once started, the
  77 process ID is expected to be available in a file which Dinit can then
  78 read. Many existing daemons can operate in this way. The process can only be
  79 supervised if Dinit runs as the system "init" (PID 1) - otherwise Dinit can
  80 not reliably know when the process has terminated.
  81
  82 (Note, use of bgprocess services type requires care. The file from which the
  83 PID is read is trusted; Dinit may send signals to the specified PID. It
  84 should not be possible for unauthorised users to modify the file contents!)
  85
  86 An _internal_ service is just a placeholder service that can be used to
  87 describe a set of dependencies. An internal service has no corresponding
  88 process.
  89
  90
  91 Service Hiearchy and states
  92 =-=-=-=-=-=-=-=-=-=-=-=-=-=
  93
  94 Services can depend on other services for operation, and so form a
  95 dependency hierarchy. Starting a service which depends on another
  96 causes that other service to start (and the first service waits until
  97 the latter has started before its process is launched and it is itself
  98 considered started).
  99
 100 Services are considered _active_ when they are not stopped. Services
 101 can also be explicitly marked as active (this normally happens when you
 102 explicitly start a service). Finally, a service with an active dependent
 103 is also considered active.
 104
 105 If a service stops and becomes inactive (i.e. it is not explicitly marked
 106 active and has no active dependents) then any services it depends on will
 107 also be marked inactive and stopped unless they have other active
 108 dependents, or were explicitly started and marked active.
 109
 110 What this means is that, in general, starting an (inactive, stopped)
 111 service and then stopping it will return the system to its prior state -
 112 no dependencies which were started automatically will be left running.
 113
 114
 115 Service Description files
 116 =-=-=-=-=-=-=-=-=-=-=-=-=
 117
 118 Dinit discovers services by reading _service description files_. These files
 119 reside in a directory (/etc/dinit.d is the default "system" location) and
 120 their name matches the name of the service. Service descriptions are loaded
 121 lazily, as needed by Dinit.
 122
 123 A service description file consists of a number of parameter settings.
 124 Settings in the SDF are denoted as a parameter name followed by either an
 125 equal sign or colon and then the parameter value (all on the same line).
 126 Comments begin with a hash mark (#) and extend to the end of the line (they
 127 must be separated from setting values by at least one whitespace character).
 128
 129 Parameter values are interpreted literally, except that:
 130  - whitespace is collapsed to a single space
 131  - double quotes can be used around all or part(s) of a parameter to prevent
 132    whitespace collapse and interpretation of special characters
 133  - backslash can be used to 'escape' the next character, preventing any
 134    special meaning from being associated with it. It can be used to include
 135    non-collapsing whitespace, double-quote marks, and backslashes in the
 136    parameter value.
 137
 138 Parameters are:
 139
 140 type = process | bgprocess | scripted | internal
 141 command = ...
 142 logfile = ...
 143 options = ...
 144 depends-on = (service name)
 145 depends-ms = (service name)
 146 waits-for = (service name)
 147
 148 command = (external script or executable, and arguments)
 149    For a 'process' service, this is the process to run.
 150    For a 'scripted' service, this command is run to start the service.
 151
 152 stop-command = (external script or executable, and arguments)
 153    For a 'scripted' service, this command is run to stop the service.
 154
 155 restart = yes | true | no | false
 156    Specifies whether the service should automatically restart if it becomes
 157    stopped (for any reason, including being explicitly requested to stop).
 158    Only active services will restart automatically.
 159
 160 smooth-recovery = yes | true | no | false
 161    For process services only. Specifies that, should the process die, it
 162    can be restarted without bringing the service itself down. This means that
 163    any dependent services do not need to be stopped/restarted. Such recovery
 164    happens regardless of the "restart" setting (if smooth-recovery is enabled,
 165    the service does not reach the stopped state when the process terminates
 166    unexpectedly).
 167
 168 restart-delay = XXX.YYYY
 169    Specifies the minimum time in seconds between automatic restarts. The
 170    default is 0.2 (i.e. 200ms). This prevents Dinit from consuming processor
 171    cycles when a process continuously fails immediately after it starts.
 172
 173 restart-limit-interval = XXX.YYYY
 174    Specifies the interval, in seconds, over which restarts are limited. If a
 175    process automatically restarts more than a certain number of times (default
 176    3) in this time interval, it will not restart again. The default value is
 177    10 seconds. Use this to prevent broken services from continuously
 178    restarting ad infinitum.
 179
 180 restart-limit-count = NNN
 181    Specifies the maximum number of times that a service can automatically
 182    restart over the interval specified by restart-limit-interval (default of
 183    10 seconds). Specify a value of 0 to disable the restart limit.
 184
 185 stop-timeout = XXX.YYYY
 186    Specifies the time in seconds allowed for the service to stop. If the
 187    service takes longer than this, its process group is sent a SIGKILL signal
 188    which should cause it to terminate immediately. The timeout period begins
 189    only when all dependent services have already stopped. The default stop
 190    timeout is 10 seconds.
 191
 192 pid-file = (path to file)
 193    For "bgprocess" type services only; specifies the path of the file where
 194    daemon will write its process ID before detaching.
 195
 196 depends-on = (service name)
 197    This service depends on the named service. Starting this service will
 198    start the named service; the command to start this service will not be
 199    executed until the named service has started. If the named service is
 200    stopped then this service will also be stopped.
 201
 202 depends-ms = (service name)
 203    Indicates a "milestone dependency" on the named service. This service
 204    requires the named service to start before it starts itself. Once the
 205    named service has started, it remains active due to the dependency, but if
 206    it stops for any reason then the dependency link is broken until the next
 207    time this service is started.
 208
 209 waits-for = (service name)
 210    When this service is started, wait for the named service to finish
 211    starting (or to fail starting) before commencing the start procedure
 212    for this service. Starting this service will automatically start
 213    the named service.
 214
 215 socket-listen = (socket path)
 216    Pre-open a socket for the service and pass it to the service using the
 217    Systemd activation protocol. This by itself does not give so called
 218    "socket activation", but does allow that any process trying to connect
 219    to the specified socket will be able to do so, even before the service
 220    is properly prepared to accept connections.
 221
 222 socket-permissions = (octal permissions mask)
 223    Gives the permissions for the socket specified using socket-listen.
 224    Normally this will be 600 (user access only), 660 (user and group
 225    access), or 666 (all users).
 226
 227 socket-uid = (numeric user id or username)
 228    Specifies the user that should own the activation socket. If socket-uid
 229    is specified without also specifying socket-gid, then the socket group
 230    is the primary group of the specified user (as found in the system user
 231    database, normally /etc/passwd). If the socket owner is not specified,
 232    the socket will be owned by the user id of the Dinit process.
 233
 234 socket-gid = (numeric group id or group name)
 235    Specifies the group of the activation socket. See discussion of
 236    socket-uid.
 237
 238 termsignal = HUP | INT | QUIT | USR1 | USR2
 239    Specifies an additional signal to send to the process when requesting it
 240    to terminate (applies to 'process' services only). SIGTERM is always
 241    sent along with the specified signal, unless the 'nosigterm' setting is
 242    set true.
 243
 244 options = ( runs-on-console | nosigterm | starts-rwfs | starts-log ) ...
 245   Specifies various options for this service:
 246
 247   no-sigterm : specifies that the TERM signal should not be send to the
 248               process to terminate it. (Another signal can be specified using
 249               the "termsignal" setting; if no other signal is specified, NO
 250               signal will be sent).
 251
 252   runs-on-console : specifies that this service uses the console; its input
 253               and output should be directed to the console. A service running
 254               on the console prevents other services from running on the
 255               console (they will queue for the console).
 256
 257               The "interrupt" key (normally control-C) will be active for
 258               process / scripted services that run on the console. Handling
 259               of an interrupt is determined by the service process, but
 260               typically will cause it to terminate.
 261
 262   starts-on-console : specifies that this service uses the console during
 263               service startup. This is implied by runs-on-console, but can
 264               be specified separately for services that need the console
 265               while they start but not afterwards.
 266
 267               This setting is not applicable to regular "process" services,
 268               but can be used for "scripted" and "bgprocess" services. It
 269               allows for interrupting startup via the "interrupt" key
 270               (normally control-C). This is useful to allow filesystem checks
 271               to be interrupted/skipped.
 272
 273   starts-rwfs : this service mounts the root filesystem read/write (or at
 274               least mounts the normal writable filesystems for the system).
 275               This prompts Dinit to create its control socket, if it has not
 276               already managed to do so.
 277
 278   starts-log : this service starts the system log daemon. Dinit will begin
 279               logging via the /dev/log socket.
 280
 281   pass-cs-fd : pass an open Dinit control socket to the process when launching
 282               it (the DINIT_CS_FD environment variable will be set to the file
 283               descriptor of the socket). This allows the service to issue
 284               commands to Dinit even if the regular control socket is not
 285               available yet.
 286
 287               Using this option has security implications! The service which
 288               receives the control socket must close it before launching any
 289               untrusted processes. You should not use this option unless the
 290               service is designed to receive a Dinit control socket.
 291
 292 logfile = (log file path)
 293    Specifies the log file for the service. Output from the service process
 294    will go this file.
 295
 296
 297 Controlling services
 298 =-=-=-=-=-=-=-=-=-=-
 299
 300 You can use the "dinitctl" to start and stop services. Typical invocations
 301 are:
 302
 303     dinitctl start <service-name>
 304     dinitctl stop <service-name>
 305     dinitctl release <service-name>
 306
 307 Note that a "start" markes the service active, as well as starting it if it is
 308 not already started; the opposite of this is actually "release", which clears
 309 the active mark and stops it if it has no active dependent services. The "stop"
 310 command by default acts as a "release" which also forces the service to stop
 311 (although it may then immediately restart, depending on how it and its
 312 dependents are configured).
 313
 314 Use the "-s" switch to talk the "system" instance of dinit, rather than a
 315 personal instance, e.g:
 316
 317     dinitctl -s start mysql   # start system mysql service
 318
 319 For complete details on the command line, use:
 320
 321     dinitctl --help
 322
 323 You can "pin" a service in either the stopped or started state, which prevents
 324 it from changing state either due to a dependency/dependent or a direct
 325 command:
 326
 327     dinitctl -s start --pin mysql  # start mysql service, pin it as "started"
 328     dinitctl -s stop mysql  # issues stop, but doesn't take effect due to pin
 329     dinitctl -s unpin mysql # release pin; service will now stop
 330
 331 You can pin a service in the stopped state in order to make sure it doesn't
 332 get started accidentally (either via a dependency or directly). You can also
 333 use it to temporarily keep stopped a service that would otherwise restart
 334 immediately when you stopped it (because it, or a dependent, is configured
 335 to restart automatically).
 336
 337 Finally, you can list the state of all loaded services:
 338
 339     dinitctl -s list
 340
 341 This may result in something like the following:
 342
 343     [{+}     ] boot
 344     [{+}     ] tty1
 345     [{+}     ] tty2
 346     [{+}     ] tty3
 347     [{+}     ] tty4
 348     [{+}     ] loginready
 349     [{+}     ] rcboot
 350     [{+}     ] filesystems
 351     [{+}     ] udevd
 352     [     {-}] mysql
 353
 354 The above represents a number of started services and one stopped service
 355 (mysql). Services transitioning state (starting or stopping) are displayed
 356 with an arrow indicating the transition direction:
 357
 358     [   <<{-}] mysql     # starting
 359     [{+}>>   ] mysql     # stopping
 360
 361 Remember that a "starting" service may be waiting for its dependencies to
 362 start, and a "stopping" service may be waiting for its dependencies to stop.