4 This is the README for Dinit, the service manager and init system. It is
5 intended to provide an overview; For full documentation please check the manual pages.
9 1. [Introduction](#introduction)
10 2. [Configuring services](#configuring-services)
11 1. [Service types](#service-types)
12 2. [Service description files](#service-description-files)
13 3. [Running Dinit](#running-dinit)
14 4. [Controlling services](#controlling-services)
15 1. [Service hierarchy and states](#service-hierarchy-and-states)
16 2. [Using dinitctl](#using-dinitctl)
20 "Dinit" is a service supervisor with dependency support which can also
21 act as the system "init" program. It was created with the intention of
22 providing a portable init system that could serve as a lighter-weight
23 alternative to the Linux-only Systemd.
25 Specifically, Dinit can launch multiple services in parallel, with dependency
26 management (i.e. if one service's operation depends on another, the latter
27 service will be started first). It can monitor the process corresponding to a
28 service, and re-start it if it dies, and it can do this in an intelligent way,
29 first "rolling back" all dependent services, and restarting them when their
30 dependencies are satisfied. However, the precise nature of dependency
31 relations between services is highly configurable. The "dinitctl" tool can
32 be used to start or stop services and check their state (by issuing commands
33 to the "dinit" daemon).
35 Dinit is designed to run as either as a system service manager (runs as root,
36 uses system paths for configuration etc) or a user process (runs as a user,
37 uses paths in the user's home directory by default).
39 Dinit is designed to work on POSIXy operating systems such as Linux and
40 OpenBSD. It is written in C++ and uses the [Dasynq](http://davmac.org/projects/dasynq/)
41 event handling library, which was written especially to support Dinit. (Note
42 that a copy of Dasynq is bundled with Dinit, so a separate copy is not
43 required for compilation; however, the bundled copy does not include the
44 documentation or test suite).
46 Development goals include clean design, robustness, portability, and
47 avoiding feature bloat (whilst still handling a variety of use cases).
49 See [doc/COMPARISON](doc/COMPARISON) for a comparison of Dinit with similar
52 Dinit is licensed under the Apache License, version 2.0. A copy of this
53 license can be found in the LICENSE file.
55 Dinit was written by Davin McCall <davmac@davmac.org>.
57 See BUILD.txt for information on how to build Dinit.
60 ## Configuring services
64 A "service" is nominally a persistent process or system state. The two main
65 types of service are a _process_ service (represented by a an actual process)
66 and a _scripted_ service (which is started and stopped by running a process -
67 often a shell script - to completion). There are also _bgprocess_ services
68 and _internal_ services.
70 Many programs that you might want to run under Dinit's supervision can run
71 either "in the foreground" or as a daemon ("in the background"), and the
72 choice is dictated by a command line switch (for instance the -D and -F
73 switches to Samba's "smbd"). Although it might seem counterintuitive,
74 the "foreground" mode should be used for programs registered as process
75 services in Dinit; this allows Dinit to monitor the process.
77 Process services are attractive due to the ease of monitoring (and
78 restarting) the service, however, they have one inherent problem, which is
79 that Dinit cannot tell when the service is truly started. Once the process
80 has been launched, Dinit assumes that the service has started, but in fact
81 there will be a short delay before the process sets itself up, starts
82 listening on sockets, etc; during this time any other process (including
83 one from a service listed as dependent) which tries to contact it will not
84 be able to do so. In practice, this is not usually a problem (and external
85 solutions, like D-Bus, do exist).
87 A _scripted_ service has separate commands for startup and (optional)
88 shutdown. Scripted services can be used for tasks such as mounting file
89 systems that don't need a persistent process, and in some cases can be used
90 for daemon processes (although Dinit will not be able to supervise a
91 process that is registered as a scripted service).
93 A _bgprocess_ service is a mix between a process service and a scripted
94 service. A command is used to start the service, and once started, the
95 process ID is expected to be available in a file which Dinit can then
96 read. Many existing daemons can operate in this way. The process can only be
97 supervised if Dinit runs as the system "init" (PID 1), or can otherwise mark
98 itself as a subreaper (which is possible on Linux, FreeBSD and DragonFlyBSD) -
99 otherwise Dinit can not reliably know when the process has terminated.
101 (Note, use of bgprocess services type requires care. The file from which the
102 PID is read is trusted; Dinit may send signals to the specified PID. It
103 should not be possible for unauthorised users to modify the file contents!)
105 An _internal_ service is just a placeholder service that can be used to
106 describe a set of dependencies. An internal service has no corresponding
110 ### Service description files
112 Dinit discovers services by reading _service description files_. These files
113 reside in a directory (/etc/dinit.d is the default "system" location, with
114 "/usr/local/lib/dinit.d" and "/lib/dinit.d" also searched; the default user
115 location is "$HOME/dinit.d") and the name of a service description file
116 matches the name of the service they configure. Service descriptions are
117 loaded lazily, as needed by Dinit.
119 (An example of a complete set of system service descriptions can be found in
120 the [doc/linux/services](doc/linux/services) directory).
122 A service description file consists of a number of parameter settings.
123 Settings in the SDF are denoted as a parameter name followed by either an
124 equal sign or colon and then the parameter value (all on the same line).
125 Comments begin with a hash mark (#) and extend to the end of the line (they
126 must be separated from setting values by at least one whitespace character).
128 Parameter values are interpreted literally, except that:
129 - whitespace is collapsed to a single space
130 - double quotes can be used around all or part(s) of a parameter to prevent
131 whitespace collapse and interpretation of special characters
132 - backslash can be used to 'escape' the next character, preventing any
133 special meaning from being associated with it. It can be used to include
134 non-collapsing whitespace, double-quote marks, and backslashes in the
137 Some examples of the available parameters are:
139 type = process | bgprocess | scripted | internal
144 smooth-recovery = (boolean)
148 depends-on = (service name)
149 depends-ms = (service name)
150 waits-for = (service name)
152 Descriptions of individual parameters follows:
154 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)
161 For a 'scripted' service, this command is run to stop the service.
165 Specifies which user to run the process(es) for this service as. The group
166 id for the process will also be set to the primary group of the specified
169 restart = yes | true | no | false
171 Specifies whether the service should automatically restart if it becomes
172 stopped (for any reason, including being explicitly requested to stop).
173 Only active services will restart automatically.
175 smooth-recovery = yes | true | no | false
177 For process services only. Specifies that, should the process die, it
178 can be restarted without bringing the service itself down. This means that
179 any dependent services do not need to be stopped/restarted. Such recovery
180 happens regardless of the "restart" setting (if smooth-recovery is enabled,
181 the service does not reach the stopped state when the process terminates
184 logfile = (log file path)
186 Specifies the log file for the service. Output from the service process
189 pid-file = (path to file)
191 For "bgprocess" type services only; specifies the path of the file where
192 daemon will write its process ID before detaching.
194 depends-on = (service name)
196 This service depends on the named service. Starting this service will
197 start the named service; the command to start this service will not be
198 executed until the named service has started. If the named service is
199 stopped then this service will also be stopped.
201 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.
209 waits-for = (service name)
211 When this service is started, wait for the named service to finish
212 starting (or to fail starting) before commencing the start procedure
213 for this service. Starting this service will automatically start
216 options = ( runs-on-console | nosigterm | starts-rwfs | starts-log ) ...
218 Specifies various options for this service:
220 `no-sigterm` : specifies that the TERM signal should not be send to the
221 process to terminate it. (Another signal can be specified using
222 the "termsignal" setting; if no other signal is specified, NO
223 signal will be sent).
225 `runs-on-console` : specifies that this service uses the console; its input
226 and output should be directed to the console. A service running
227 on the console prevents other services from running on the
228 console (they will queue for the console).
229 The "interrupt" key (normally control-C) will be active for
230 process / scripted services that run on the console. Handling
231 of an interrupt is determined by the service process, but
232 typically will cause it to terminate.
234 `starts-on-console` : specifies that this service uses the console during
235 service startup. This is implied by runs-on-console, but can
236 be specified separately for services that need the console
237 while they start but not afterwards.
238 This setting is not applicable to regular "process" services,
239 but can be used for "scripted" and "bgprocess" services. It
240 allows for interrupting startup via the "interrupt" key
241 (normally control-C). This is useful to allow filesystem checks
242 to be interrupted/skipped.
244 `start-interruptible` : this service can have its startup interrupted
245 (cancelled) if it becomes inactive while still starting.
246 The SIGINT signal will be sent to the signal to cancel its
247 startup. This is meaningful only for scripted and bgprocess
250 Please see the manual page for a full list of service parameters and options.
254 Dinit can run as the system "init" - the first process started by the kernel
255 on boot - which is normally done by linking or copying it to `/sbin/init`.
256 This is currently supported only on Linux. It requires having suitable service
257 descriptions in place and should be attempted only by those comfortable
258 with low-level system administration and recovery. See doc/linux directory for
261 Dinit can also run as a normal process, and can be started in this case by a
264 By default, regardless of whether it runs as a system or user process, Dinit
265 will look for and start the service named "boot". This service should be
266 configured with dependencies which will cause any other desired services to
267 start. You can specify alternative services to start via the `dinit` command
268 line (consult the man page for more information).
270 ## Controlling services
272 ### Service hierarchy and states
274 Services can depend on other services for operation, and so form a
275 dependency hierarchy. Starting a service which depends on another
276 causes that other service to start (and the first service waits until
277 the latter has started before its process is launched and it is itself
280 Services are considered _active_ when they are not stopped. Services
281 can also be explicitly marked as active (this normally happens when you
282 explicitly start a service). Finally, a service with an active dependent
283 is also considered active.
285 If a service stops and becomes inactive (i.e. it is not explicitly marked
286 active and has no active dependents) then any services it depends on will
287 also be marked inactive and stopped unless they have other active
288 dependents, or were explicitly started and marked active.
290 What this means is that, in general, starting an (inactive, stopped)
291 service and then stopping it will return the system to its prior state -
292 no dependencies which were started automatically will be left running.
296 You can use the "dinitctl" utility to start and stop services. Typical invocations
299 dinitctl start <service-name>
300 dinitctl stop <service-name>
301 dinitctl release <service-name>
303 Note that a "start" marks the service active, as well as starting it if it is
304 not already started; the opposite of this is actually "release", which clears
305 the active mark and stops it if it has no active dependent services. The "stop"
306 command by default acts as a "release" that also forces the service to stop
307 (although it may then immediately restart, depending on how it and its
308 dependents are configured).
310 Use the "-s" switch to talk the "system" instance of Dinit, rather than a
311 personal instance, e.g:
313 dinitctl -s start mysql # start system mysql service
315 For complete details on the command line, use:
319 You can "pin" a service in either the stopped or started state, which prevents
320 it from changing state either due to a dependency/dependent or a direct
323 dinitctl -s start --pin mysql # start mysql service, pin it as "started"
324 dinitctl -s stop mysql # issues stop, but doesn't take effect due to pin
325 dinitctl -s unpin mysql # release pin; service will now stop
327 You can pin a service in the stopped state in order to make sure it doesn't
328 get started accidentally (either via a dependency or directly). You can also
329 use it to temporarily keep stopped a service that would otherwise restart
330 immediately when you stopped it (because it, or a dependent, is configured
331 to restart automatically).
333 Finally, you can list the state of all loaded services:
337 This may result in something like the following:
340 [{+} ] tty1 (pid: 300)
341 [{+} ] tty2 (pid: 301)
342 [{+} ] tty3 (pid: 302)
343 [{+} ] tty4 (pid: 303)
344 [{+} ] loginready (has console)
347 [{+} ] udevd (pid: 4)
350 The above represents a number of started services and one stopped service
351 (mysql). Services transitioning state (starting or stopping) are displayed
352 with an arrow indicating the transition direction:
354 [{ }<< ] mysql # starting
355 [ >>{ }] mysql # stopping
357 The curly brackets indicate the desired state, which may not be the state to
358 which the service is currently transitioning. For example:
360 [ <<{ }] mysql # starting, but will stop after starting
361 [{ }>> ] mysql # stopping, but will restart once stopped
363 Remember that a "starting" service may be waiting for its dependencies to
364 start, and a "stopping" service may be waiting for its dependencies to stop.