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