9 "Dinit" is a service supervisor with dependency support which can also
10 act as the system "init" program.
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
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).
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).
27 See doc/COMPARISON for a comparison of Dinit with similar software packages.
29 The primary author of Dinit is Davin McCall <davmac@davmac.org>.
32 Introduction to services
33 =-=-=-=-=-=-=-=-=-=-=-=-
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).
40 Many programs that you might want to run under dinit's supervision can run
41 either "in the foreground" or as a daemon ("in the background"), and the
42 choice is dictated by a command line switch (for instance the -D and -F
43 switches to Samba's "smbd"). Although it might seem counterintuitive,
44 the "foreground" mode should be used for programs registered as process
45 services in dinit; this allows dinit to monitor the process.
47 Process services are attractive due to the ease of monitoring (and
48 restarting) the service, however, they have one inherent problem, which is
49 that dinit cannot tell when the service is truly started. Once the process
50 has been launched, dinit assumes that the service has started, but in fact
51 there will be a short delay before the process sets itself up, starts
52 listening on sockets, etc; during this time any other process (including
53 one from a service listed as dependent) which tries to contact it will not
54 be able to do so. In practice, this is not usually a problem (and external
55 solutions, like D-Bus, do exist).
59 Service Description files
60 =-=-=-=-=-=-=-=-=-=-=-=-=
62 Dinit discovers services by reading _service description files_. These files
63 reside in a directory (/etc/dinit.d is the default "system" location) and
64 their name matches the name of the service. Service descriptions are loaded
65 lazily, as needed by Dinit.
67 A service description file consists of a number of parameter settings.
68 Settings in the SDF are denoted as a parameter name followed by either an
69 equal sign or colon and then the parameter value (all on the same line).
70 Comments begin with a hash mark (#) and extend to the end of the line.
72 Parameter values are interpreted literally, except that:
73 - whitespace is collapsed to a single space
74 - double quotes can be used around all or part(s) of a parameter to prevent
75 whitespace collapse and interpretation of special characters
76 - backslash can be used to 'escape' the next character, preventing any
77 special meaning from being associated with it. It can be used to include
78 non-collapsing whitespace, double-quote marks, and backslashes in the
83 type = process | scripted | internal
85 restart = yes | true | no | false
88 depends-on = (service name)
89 waits-for = (service name)
90 termsignal = HUP | INT | QUIT | USR1 | USR2
92 command = (external script or executable and arguments)
93 For a 'process' service, this is the process to run.
94 For a 'scripted' service, this process is run both to start the service
95 (with the command-line argument "start" appended) and to stop the
96 service (with "stop").
98 onstart = (internal commands)
99 release_console - stop performing output to the console (usually used
100 when login prompt is spawned)
101 rw_ready - try again to open any logs, control socket etc that could not
102 be opened previously due to a read-only filesystem.
104 depends-on = (service name)
105 This service depends on the named service. Starting this service will
106 start the named service; the command to start this service will not be
107 executed until the named service has started. If the named service is
108 stopped then this service will also be stopped.
110 waits-for = (service name)
111 When this service is started, wait for the named service to finish
112 starting (or to fail starting) before commencing the start procedure
113 for this service. Starting this service will automatically start
116 termsignal = (signal)
117 Specifies an additional signal to send to the process when requesting it
118 to terminate (applies to 'process' services only). SIGTERM is always
119 sent along with the specified signal, unless the 'nosigterm' setting is
122 nosigterm = yes | true | no | false
123 If true, the TERM signal will not be sent to the process to kill it. (If
124 an alternate signal is specified using the "termsignal" setting, that
125 signal will be sent instead; otherwise, no signal will be sent, and the
126 process must be killed by external means).