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 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).
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. Dinit can only supervise
79 the process if it runs as the system "init" (PID 1) - otherwise Dinit will
80 not know when the process has terminated.
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!)
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
91 Service Hiearchy and states
92 =-=-=-=-=-=-=-=-=-=-=-=-=-=
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
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.
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.
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.
115 Service Description files
116 =-=-=-=-=-=-=-=-=-=-=-=-=
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.
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.
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
139 type = process | bgprocess | scripted | internal
143 depends-on = (service name)
144 waits-for = (service name)
146 command = (external script or executable, and arguments)
147 For a 'process' service, this is the process to run.
148 For a 'scripted' service, this command is run to start the service.
150 stop-command = (external script or executable, and arguments)
151 For a 'scripted' service, this command is run to stop the service.
153 restart = yes | true | no | false
154 Specifies whether the service should automatically restart if it becomes
155 stopped (for any reason, including being explicitly requested to stop).
156 Only active services will restart automatically.
158 smooth-recovery = yes | true | no | false
159 For process services only. Specifies that, should the process die, it
160 can be restarted without bringing the service itself down. This means that
161 any dependent services do not need to be stopped/restarted. Such recovery
162 happens regardless of the "restart" setting (if smooth-recovery is enabled,
163 the service does not reach the stopped state when the process terminates
166 pid-file = (path to file)
167 For "bgprocess" type services only; specifies the path of the file where
168 daemon will write its process ID before detaching.
170 depends-on = (service name)
171 This service depends on the named service. Starting this service will
172 start the named service; the command to start this service will not be
173 executed until the named service has started. If the named service is
174 stopped then this service will also be stopped.
176 waits-for = (service name)
177 When this service is started, wait for the named service to finish
178 starting (or to fail starting) before commencing the start procedure
179 for this service. Starting this service will automatically start
182 socket-listen = (socket path)
183 Pre-open a socket for the service and pass it to the service using the
184 Systemd activation protocol. This by itself does not give so called
185 "socket activation", but does allow that any process trying to connect
186 to the specified socket will be able to do so, even before the service
187 is properly prepared to accept connections.
189 socket-permissions = (octal permissions mask)
190 Gives the permissions for the socket specified using socket-listen.
191 Normally this will be 600 (user access only), 660 (user and group
192 access), or 666 (all users).
194 socket-uid = (numeric user id or username)
195 Specifies the user that should own the activation socket. If socket-uid
196 is specified without also specifying socket-gid, then the socket group
197 is the primary group of the specified user (as found in the system user
198 database, normally /etc/passwd). If the socket owner is not specified,
199 the socket will be owned by the user id of the Dinit process.
201 socket-gid = (numeric group id or group name)
202 Specifies the group of the activation socket. See discussion of
205 termsignal = HUP | INT | QUIT | USR1 | USR2
206 Specifies an additional signal to send to the process when requesting it
207 to terminate (applies to 'process' services only). SIGTERM is always
208 sent along with the specified signal, unless the 'nosigterm' setting is
211 options = ( runs-on-console | nosigterm | starts-rwfs | starts-log ) ...
212 Specifies various options for this service:
214 no-sigterm : specifies that the TERM signal should not be send to the
215 process to terminate it. (Another signal can be specified using
216 the "termsignal" setting; if no other signal is specified, NO
217 signal will be sent).
219 runs-on-console : specifies that this service uses the console; its input
220 and output should be directed to the console. A service running
221 on the console prevents other services from running on the
222 console (they will queue for the console). For scripted services
223 "runs-on-console" applies only during execution of the start
226 The "interrupt" key (normally control-C) will be active for
227 process / scripted services that run on the console. This is
228 useful to allow filesystem checks to be interrupted/skipped.
230 starts-rwfs : this service mounts the root filesystem read/write (or at
231 least mounts the normal writable filesystems for the system).
232 This prompts Dinit to create its control socket, if it has not
233 already managed to do so.
235 starts-log : this service starts the system log daemon. Dinit will begin
236 logging via the /dev/log socket.