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, and restarting them when their
20 dependencies are satisfied.
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.
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.
30 Development goals include clean design, robustness, portability, and
31 avoiding feature bloat (whilst still handling a variety of use cases).
33 See doc/COMPARISON for a comparison of Dinit with similar software packages.
35 Dinit is licensed under the Apache License, version 2.0. A copy of this
36 license can be found in the LICENSE file.
38 Dinit was written by Davin McCall <davmac@davmac.org>.
40 See BUILD for information on how to build Dinit.
43 Introduction to services
44 =-=-=-=-=-=-=-=-=-=-=-=-
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.
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.
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).
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 persistent 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).
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), or can otherwise mark
80 itself as a subreaper (which is possible on Linux, FreeBSD and DragonFlyBSD) -
81 otherwise Dinit can not reliably know when the process has terminated.
83 (Note, use of bgprocess services type requires care. The file from which the
84 PID is read is trusted; Dinit may send signals to the specified PID. It
85 should not be possible for unauthorised users to modify the file contents!)
87 An _internal_ service is just a placeholder service that can be used to
88 describe a set of dependencies. An internal service has no corresponding
92 Service Hiearchy and states
93 =-=-=-=-=-=-=-=-=-=-=-=-=-=
95 Services can depend on other services for operation, and so form a
96 dependency hierarchy. Starting a service which depends on another
97 causes that other service to start (and the first service waits until
98 the latter has started before its process is launched and it is itself
101 Services are considered _active_ when they are not stopped. Services
102 can also be explicitly marked as active (this normally happens when you
103 explicitly start a service). Finally, a service with an active dependent
104 is also considered active.
106 If a service stops and becomes inactive (i.e. it is not explicitly marked
107 active and has no active dependents) then any services it depends on will
108 also be marked inactive and stopped unless they have other active
109 dependents, or were explicitly started and marked active.
111 What this means is that, in general, starting an (inactive, stopped)
112 service and then stopping it will return the system to its prior state -
113 no dependencies which were started automatically will be left running.
116 Service Description files
117 =-=-=-=-=-=-=-=-=-=-=-=-=
119 Dinit discovers services by reading _service description files_. These files
120 reside in a directory (/etc/dinit.d is the default "system" location, with
121 "/usr/local/lib/dinit.d" and "/lib/dinit.d" also searched) and their name
122 matches the name of the service. Service descriptions are loaded lazily, as
125 A service description file consists of a number of parameter settings.
126 Settings in the SDF are denoted as a parameter name followed by either an
127 equal sign or colon and then the parameter value (all on the same line).
128 Comments begin with a hash mark (#) and extend to the end of the line (they
129 must be separated from setting values by at least one whitespace character).
131 Parameter values are interpreted literally, except that:
132 - whitespace is collapsed to a single space
133 - double quotes can be used around all or part(s) of a parameter to prevent
134 whitespace collapse and interpretation of special characters
135 - backslash can be used to 'escape' the next character, preventing any
136 special meaning from being associated with it. It can be used to include
137 non-collapsing whitespace, double-quote marks, and backslashes in the
140 Some available parameters are:
142 type = process | bgprocess | scripted | internal
147 smooth-recovery = (boolean)
151 depends-on = (service name)
152 depends-ms = (service name)
153 waits-for = (service name)
155 command = (external script or executable, and arguments)
156 For a 'process' service, this is the process to run.
157 For a 'scripted' service, this command is run to start the service.
159 stop-command = (external script or executable, and arguments)
160 For a 'scripted' service, this command is run to stop the service.
163 Specifies which user to run the process(es) for this service as. The group
164 id for the process will also be set to the primary group of the specified
167 restart = yes | true | no | false
168 Specifies whether the service should automatically restart if it becomes
169 stopped (for any reason, including being explicitly requested to stop).
170 Only active services will restart automatically.
172 smooth-recovery = yes | true | no | false
173 For process services only. Specifies that, should the process die, it
174 can be restarted without bringing the service itself down. This means that
175 any dependent services do not need to be stopped/restarted. Such recovery
176 happens regardless of the "restart" setting (if smooth-recovery is enabled,
177 the service does not reach the stopped state when the process terminates
180 logfile = (log file path)
181 Specifies the log file for the service. Output from the service process
184 pid-file = (path to file)
185 For "bgprocess" type services only; specifies the path of the file where
186 daemon will write its process ID before detaching.
188 depends-on = (service name)
189 This service depends on the named service. Starting this service will
190 start the named service; the command to start this service will not be
191 executed until the named service has started. If the named service is
192 stopped then this service will also be stopped.
194 depends-ms = (service name)
195 Indicates a "milestone dependency" on the named service. This service
196 requires the named service to start before it starts itself. Once the
197 named service has started, it remains active due to the dependency, but if
198 it stops for any reason then the dependency link is broken until the next
199 time this service is started.
201 waits-for = (service name)
202 When this service is started, wait for the named service to finish
203 starting (or to fail starting) before commencing the start procedure
204 for this service. Starting this service will automatically start
207 options = ( runs-on-console | nosigterm | starts-rwfs | starts-log ) ...
208 Specifies various options for this service:
210 no-sigterm : specifies that the TERM signal should not be send to the
211 process to terminate it. (Another signal can be specified using
212 the "termsignal" setting; if no other signal is specified, NO
213 signal will be sent).
215 runs-on-console : specifies that this service uses the console; its input
216 and output should be directed to the console. A service running
217 on the console prevents other services from running on the
218 console (they will queue for the console).
220 The "interrupt" key (normally control-C) will be active for
221 process / scripted services that run on the console. Handling
222 of an interrupt is determined by the service process, but
223 typically will cause it to terminate.
225 starts-on-console : specifies that this service uses the console during
226 service startup. This is implied by runs-on-console, but can
227 be specified separately for services that need the console
228 while they start but not afterwards.
230 This setting is not applicable to regular "process" services,
231 but can be used for "scripted" and "bgprocess" services. It
232 allows for interrupting startup via the "interrupt" key
233 (normally control-C). This is useful to allow filesystem checks
234 to be interrupted/skipped.
236 starts-rwfs : this service mounts the root filesystem read/write (or at
237 least mounts the normal writable filesystems for the system).
238 This prompts Dinit to create its control socket, if it has not
239 already managed to do so.
241 starts-log : this service starts the system log daemon. Dinit will begin
242 logging via the /dev/log socket.
244 pass-cs-fd : pass an open Dinit control socket to the process when launching
245 it (the DINIT_CS_FD environment variable will be set to the file
246 descriptor of the socket). This allows the service to issue
247 commands to Dinit even if the regular control socket is not
250 Using this option has security implications! The service which
251 receives the control socket must close it before launching any
252 untrusted processes. You should not use this option unless the
253 service is designed to receive a Dinit control socket.
255 start-interruptible : this service can have its startup interrupted
256 (cancelled) if it becomes inactive while still starting.
257 The SIGINT signal will be sent to the signal to cancel its
258 startup. This is meaningful only for scripted and bgprocess
261 Please see the manual page for a full list of service parameters and options.
267 You can use the "dinitctl" to start and stop services. Typical invocations
270 dinitctl start <service-name>
271 dinitctl stop <service-name>
272 dinitctl release <service-name>
274 Note that a "start" markes the service active, as well as starting it if it is
275 not already started; the opposite of this is actually "release", which clears
276 the active mark and stops it if it has no active dependent services. The "stop"
277 command by default acts as a "release" which also forces the service to stop
278 (although it may then immediately restart, depending on how it and its
279 dependents are configured).
281 Use the "-s" switch to talk the "system" instance of dinit, rather than a
282 personal instance, e.g:
284 dinitctl -s start mysql # start system mysql service
286 For complete details on the command line, use:
290 You can "pin" a service in either the stopped or started state, which prevents
291 it from changing state either due to a dependency/dependent or a direct
294 dinitctl -s start --pin mysql # start mysql service, pin it as "started"
295 dinitctl -s stop mysql # issues stop, but doesn't take effect due to pin
296 dinitctl -s unpin mysql # release pin; service will now stop
298 You can pin a service in the stopped state in order to make sure it doesn't
299 get started accidentally (either via a dependency or directly). You can also
300 use it to temporarily keep stopped a service that would otherwise restart
301 immediately when you stopped it (because it, or a dependent, is configured
302 to restart automatically).
304 Finally, you can list the state of all loaded services:
308 This may result in something like the following:
321 The above represents a number of started services and one stopped service
322 (mysql). Services transitioning state (starting or stopping) are displayed
323 with an arrow indicating the transition direction:
325 [{ }<< ] mysql # starting
326 [ >>{ }] mysql # stopping
328 The curly brackets indicate the desired state, which may not be the state to
329 which the service is currently transitioning. For example:
331 [ <<{ }] mysql # starting, but will stop after starting
332 [{ }>> ] mysql # stopping, but will restart once stopped
334 Remember that a "starting" service may be waiting for its dependencies to
335 start, and a "stopping" service may be waiting for its dependencies to stop.