cc13bff7550f6ca7fb456eaaadb29049c00aa6f4
[thirdparty/systemd.git] / man / systemd.service.xml
1 <?xml version='1.0'?>
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
5
6 <refentry id="systemd.service">
7 <refentryinfo>
8 <title>systemd.service</title>
9 <productname>systemd</productname>
10 </refentryinfo>
11
12 <refmeta>
13 <refentrytitle>systemd.service</refentrytitle>
14 <manvolnum>5</manvolnum>
15 </refmeta>
16
17 <refnamediv>
18 <refname>systemd.service</refname>
19 <refpurpose>Service unit configuration</refpurpose>
20 </refnamediv>
21
22 <refsynopsisdiv>
23 <para><filename><replaceable>service</replaceable>.service</filename></para>
24 </refsynopsisdiv>
25
26 <refsect1>
27 <title>Description</title>
28
29 <para>A unit configuration file whose name ends in
30 <literal>.service</literal> encodes information about a process
31 controlled and supervised by systemd.</para>
32
33 <para>This man page lists the configuration options specific to
34 this unit type. See
35 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
36 for the common options of all unit configuration files. The common
37 configuration items are configured in the generic
38 [Unit] and [Install]
39 sections. The service specific configuration options are
40 configured in the [Service] section.</para>
41
42 <para>Additional options are listed in
43 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
44 which define the execution environment the commands are executed
45 in, and in
46 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
47 which define the way the processes of the service are terminated,
48 and in
49 <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
50 which configure resource control settings for the processes of the
51 service.</para>
52
53 <para>If a service is requested under a certain name but no unit
54 configuration file is found, systemd looks for a SysV init script
55 by the same name (with the <filename>.service</filename> suffix
56 removed) and dynamically creates a service unit from that script.
57 This is useful for compatibility with SysV. Note that this
58 compatibility is quite comprehensive but not 100%. For details
59 about the incompatibilities, see the <ulink
60 url="https://www.freedesktop.org/wiki/Software/systemd/Incompatibilities">Incompatibilities
61 with SysV</ulink> document.</para>
62
63 <para>The <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>
64 command allows creating <filename>.service</filename> and <filename>.scope</filename> units dynamically
65 and transiently from the command line.</para>
66 </refsect1>
67
68 <refsect1>
69 <title>Service Templates</title>
70
71 <para>It is possible for <command>systemd</command> services to take a single argument via the
72 <literal><replaceable>service</replaceable>@<replaceable>argument</replaceable>.service</literal>
73 syntax. Such services are called "instantiated" services, while the unit definition without the
74 <replaceable>argument</replaceable> parameter is called a "template". An example could be a
75 <filename>dhcpcd@.service</filename> service template which takes a network interface as a
76 parameter to form an instantiated service. Within the service file, this parameter or "instance
77 name" can be accessed with %-specifiers. See
78 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
79 for details.</para>
80 </refsect1>
81
82 <refsect1>
83 <title>Automatic Dependencies</title>
84
85 <refsect2>
86 <title>Implicit Dependencies</title>
87
88 <para>The following dependencies are implicitly added:</para>
89
90 <itemizedlist>
91 <listitem><para>Services with <varname>Type=dbus</varname> set automatically
92 acquire dependencies of type <varname>Requires=</varname> and
93 <varname>After=</varname> on
94 <filename>dbus.socket</filename>.</para></listitem>
95
96 <listitem><para>Socket activated services are automatically ordered after
97 their activating <filename>.socket</filename> units via an
98 automatic <varname>After=</varname> dependency.
99 Services also pull in all <filename>.socket</filename> units
100 listed in <varname>Sockets=</varname> via automatic
101 <varname>Wants=</varname> and <varname>After=</varname> dependencies.</para></listitem>
102 </itemizedlist>
103
104 <para>Additional implicit dependencies may be added as result of
105 execution and resource control parameters as documented in
106 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
107 and
108 <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
109 </refsect2>
110
111 <refsect2>
112 <title>Default Dependencies</title>
113
114 <para>The following dependencies are added unless <varname>DefaultDependencies=no</varname> is set:</para>
115
116 <itemizedlist>
117 <listitem><para>Service units will have dependencies of type <varname>Requires=</varname> and
118 <varname>After=</varname> on <filename>sysinit.target</filename>, a dependency of type <varname>After=</varname> on
119 <filename>basic.target</filename> as well as dependencies of type <varname>Conflicts=</varname> and
120 <varname>Before=</varname> on <filename>shutdown.target</filename>. These ensure that normal service units pull in
121 basic system initialization, and are terminated cleanly prior to system shutdown. Only services involved with early
122 boot or late system shutdown should disable this option.</para></listitem>
123
124 <listitem><para>Instanced service units (i.e. service units with an <literal>@</literal> in their name) are assigned by
125 default a per-template slice unit (see
126 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>), named after the
127 template unit, containing all instances of the specific template. This slice is normally stopped at shutdown,
128 together with all template instances. If that is not desired, set <varname>DefaultDependencies=no</varname> in the
129 template unit, and either define your own per-template slice unit file that also sets
130 <varname>DefaultDependencies=no</varname>, or set <varname>Slice=system.slice</varname> (or another suitable slice)
131 in the template unit. Also see
132 <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
133 </para></listitem>
134 </itemizedlist>
135 </refsect2>
136 </refsect1>
137
138 <refsect1>
139 <title>Options</title>
140
141 <para>Service files must include a [Service]
142 section, which carries information about the service and the
143 process it supervises. A number of options that may be used in
144 this section are shared with other unit types. These options are
145 documented in
146 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
147 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
148 and
149 <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
150 The options specific to the [Service] section
151 of service units are the following:</para>
152
153 <variablelist class='unit-directives'>
154 <varlistentry>
155 <term><varname>Type=</varname></term>
156
157 <listitem>
158 <para>Configures the process start-up type for this service unit. One of <option>simple</option>,
159 <option>exec</option>, <option>forking</option>, <option>oneshot</option>, <option>dbus</option>,
160 <option>notify</option> or <option>idle</option>:</para>
161
162 <itemizedlist>
163 <listitem><para>If set to <option>simple</option> (the default if <varname>ExecStart=</varname> is
164 specified but neither <varname>Type=</varname> nor <varname>BusName=</varname> are), the service manager
165 will consider the unit started immediately after the main service process has been forked off. It is
166 expected that the process configured with <varname>ExecStart=</varname> is the main process of the
167 service. In this mode, if the process offers functionality to other processes on the system, its
168 communication channels should be installed before the service is started up (e.g. sockets set up by
169 systemd, via socket activation), as the service manager will immediately proceed starting follow-up units,
170 right after creating the main service process, and before executing the service's binary. Note that this
171 means <command>systemctl start</command> command lines for <option>simple</option> services will report
172 success even if the service's binary cannot be invoked successfully (for example because the selected
173 <varname>User=</varname> doesn't exist, or the service binary is missing).</para></listitem>
174
175 <listitem><para>The <option>exec</option> type is similar to <option>simple</option>, but the service
176 manager will consider the unit started immediately after the main service binary has been executed. The service
177 manager will delay starting of follow-up units until that point. (Or in other words:
178 <option>simple</option> proceeds with further jobs right after <function>fork()</function> returns, while
179 <option>exec</option> will not proceed before both <function>fork()</function> and
180 <function>execve()</function> in the service process succeeded.) Note that this means <command>systemctl
181 start</command> command lines for <option>exec</option> services will report failure when the service's
182 binary cannot be invoked successfully (for example because the selected <varname>User=</varname> doesn't
183 exist, or the service binary is missing).</para></listitem>
184
185 <listitem><para>If set to <option>forking</option>, it is expected that the process configured with
186 <varname>ExecStart=</varname> will call <function>fork()</function> as part of its start-up. The parent
187 process is expected to exit when start-up is complete and all communication channels are set up. The child
188 continues to run as the main service process, and the service manager will consider the unit started when
189 the parent process exits. This is the behavior of traditional UNIX services. If this setting is used, it is
190 recommended to also use the <varname>PIDFile=</varname> option, so that systemd can reliably identify the
191 main process of the service. systemd will proceed with starting follow-up units as soon as the parent
192 process exits.</para></listitem>
193
194 <listitem><para>Behavior of <option>oneshot</option> is similar to <option>simple</option>;
195 however, the service manager will consider the unit up after the main process exits. It will then
196 start follow-up units. <varname>RemainAfterExit=</varname> is particularly useful for this type
197 of service. <varname>Type=</varname><option>oneshot</option> is the implied default if neither
198 <varname>Type=</varname> nor <varname>ExecStart=</varname> are specified. Note that if this
199 option is used without <varname>RemainAfterExit=</varname> the service will never enter
200 <literal>active</literal> unit state, but directly transition from <literal>activating</literal>
201 to <literal>deactivating</literal> or <literal>dead</literal> since no process is configured that
202 shall run continuously. In particular this means that after a service of this type ran (and which
203 has <varname>RemainAfterExit=</varname> not set) it will not show up as started afterwards, but
204 as dead.</para></listitem>
205
206 <listitem><para>Behavior of <option>dbus</option> is similar to <option>simple</option>; however, it is
207 expected that the service acquires a name on the D-Bus bus, as configured by
208 <varname>BusName=</varname>. systemd will proceed with starting follow-up units after the D-Bus bus name
209 has been acquired. Service units with this option configured implicitly gain dependencies on the
210 <filename>dbus.socket</filename> unit. This type is the default if <varname>BusName=</varname> is
211 specified.</para></listitem>
212
213 <listitem><para>Behavior of <option>notify</option> is similar to <option>exec</option>; however, it is
214 expected that the service sends a notification message via
215 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> or an
216 equivalent call when it has finished starting up. systemd will proceed with starting follow-up units after
217 this notification message has been sent. If this option is used, <varname>NotifyAccess=</varname> (see
218 below) should be set to open access to the notification socket provided by systemd. If
219 <varname>NotifyAccess=</varname> is missing or set to <option>none</option>, it will be forcibly set to
220 <option>main</option></para></listitem>.
221
222 <listitem><para>Behavior of <option>idle</option> is very similar to <option>simple</option>; however,
223 actual execution of the service program is delayed until all active jobs are dispatched. This may be used
224 to avoid interleaving of output of shell services with the status output on the console. Note that this
225 type is useful only to improve console output, it is not useful as a general unit ordering tool, and the
226 effect of this service type is subject to a 5s timeout, after which the service program is invoked
227 anyway.</para></listitem>
228 </itemizedlist>
229
230 <para>It is generally recommended to use <varname>Type=</varname><option>simple</option> for long-running
231 services whenever possible, as it is the simplest and fastest option. However, as this service type won't
232 propagate service start-up failures and doesn't allow ordering of other units against completion of
233 initialization of the service (which for example is useful if clients need to connect to the service through
234 some form of IPC, and the IPC channel is only established by the service itself — in contrast to doing this
235 ahead of time through socket or bus activation or similar), it might not be sufficient for many cases. If so,
236 <option>notify</option> or <option>dbus</option> (the latter only in case the service provides a D-Bus
237 interface) are the preferred options as they allow service program code to precisely schedule when to
238 consider the service started up successfully and when to proceed with follow-up units. The
239 <option>notify</option> service type requires explicit support in the service codebase (as
240 <function>sd_notify()</function> or an equivalent API needs to be invoked by the service at the appropriate
241 time) — if it's not supported, then <option>forking</option> is an alternative: it supports the traditional
242 UNIX service start-up protocol. Finally, <option>exec</option> might be an option for cases where it is
243 enough to ensure the service binary is invoked, and where the service binary itself executes no or little
244 initialization on its own (and its initialization is unlikely to fail). Note that using any type other than
245 <option>simple</option> possibly delays the boot process, as the service manager needs to wait for service
246 initialization to complete. It is hence recommended not to needlessly use any types other than
247 <option>simple</option>. (Also note it is generally not recommended to use <option>idle</option> or
248 <option>oneshot</option> for long-running services.)</para>
249 </listitem>
250 </varlistentry>
251
252 <varlistentry>
253 <term><varname>RemainAfterExit=</varname></term>
254
255 <listitem><para>Takes a boolean value that specifies whether
256 the service shall be considered active even when all its
257 processes exited. Defaults to <option>no</option>.</para>
258 </listitem>
259 </varlistentry>
260
261 <varlistentry>
262 <term><varname>GuessMainPID=</varname></term>
263
264 <listitem><para>Takes a boolean value that specifies whether
265 systemd should try to guess the main PID of a service if it
266 cannot be determined reliably. This option is ignored unless
267 <option>Type=forking</option> is set and
268 <option>PIDFile=</option> is unset because for the other types
269 or with an explicitly configured PID file, the main PID is
270 always known. The guessing algorithm might come to incorrect
271 conclusions if a daemon consists of more than one process. If
272 the main PID cannot be determined, failure detection and
273 automatic restarting of a service will not work reliably.
274 Defaults to <option>yes</option>.</para>
275 </listitem>
276 </varlistentry>
277
278 <varlistentry>
279 <term><varname>PIDFile=</varname></term>
280
281 <listitem><para>Takes a path referring to the PID file of the service. Usage of this option is recommended for
282 services where <varname>Type=</varname> is set to <option>forking</option>. The path specified typically points
283 to a file below <filename>/run/</filename>. If a relative path is specified it is hence prefixed with
284 <filename>/run/</filename>. The service manager will read the PID of the main process of the service from this
285 file after start-up of the service. The service manager will not write to the file configured here, although it
286 will remove the file after the service has shut down if it still exists. The PID file does not need to be owned
287 by a privileged user, but if it is owned by an unprivileged user additional safety restrictions are enforced:
288 the file may not be a symlink to a file owned by a different user (neither directly nor indirectly), and the
289 PID file must refer to a process already belonging to the service.</para></listitem>
290 </varlistentry>
291
292 <varlistentry>
293 <term><varname>BusName=</varname></term>
294
295 <listitem><para>Takes a D-Bus bus name that this service is
296 reachable as. This option is mandatory for services where
297 <varname>Type=</varname> is set to
298 <option>dbus</option>.</para>
299 </listitem>
300 </varlistentry>
301
302 <varlistentry>
303 <term><varname>ExecStart=</varname></term>
304 <listitem><para>Commands with their arguments that are
305 executed when this service is started. The value is split into
306 zero or more command lines according to the rules described
307 below (see section "Command Lines" below).
308 </para>
309
310 <para>Unless <varname>Type=</varname> is <option>oneshot</option>, exactly one command must be given. When
311 <varname>Type=oneshot</varname> is used, zero or more commands may be specified. Commands may be specified by
312 providing multiple command lines in the same directive, or alternatively, this directive may be specified more
313 than once with the same effect. If the empty string is assigned to this option, the list of commands to start
314 is reset, prior assignments of this option will have no effect. If no <varname>ExecStart=</varname> is
315 specified, then the service must have <varname>RemainAfterExit=yes</varname> and at least one
316 <varname>ExecStop=</varname> line set. (Services lacking both <varname>ExecStart=</varname> and
317 <varname>ExecStop=</varname> are not valid.)</para>
318
319 <para>For each of the specified commands, the first argument must be either an absolute path to an executable
320 or a simple file name without any slashes. Optionally, this filename may be prefixed with a number of special
321 characters:</para>
322
323 <table>
324 <title>Special executable prefixes</title>
325
326 <tgroup cols='2'>
327 <colspec colname='prefix'/>
328 <colspec colname='meaning'/>
329
330 <thead>
331 <row>
332 <entry>Prefix</entry>
333 <entry>Effect</entry>
334 </row>
335 </thead>
336 <tbody>
337 <row>
338 <entry><literal>@</literal></entry>
339 <entry>If the executable path is prefixed with <literal>@</literal>, the second specified token will be passed as <literal>argv[0]</literal> to the executed process (instead of the actual filename), followed by the further arguments specified.</entry>
340 </row>
341
342 <row>
343 <entry><literal>-</literal></entry>
344 <entry>If the executable path is prefixed with <literal>-</literal>, an exit code of the command normally considered a failure (i.e. non-zero exit status or abnormal exit due to signal) is recorded, but has no further effect and is considered equivalent to success.</entry>
345 </row>
346
347 <row>
348 <entry><literal>:</literal></entry>
349 <entry>If the executable path is prefixed with <literal>:</literal>, environment variable substitution (as described by the "Command Lines" section below) is not applied.</entry>
350 </row>
351
352 <row>
353 <entry><literal>+</literal></entry>
354 <entry>If the executable path is prefixed with <literal>+</literal> then the process is executed with full privileges. In this mode privilege restrictions configured with <varname>User=</varname>, <varname>Group=</varname>, <varname>CapabilityBoundingSet=</varname> or the various file system namespacing options (such as <varname>PrivateDevices=</varname>, <varname>PrivateTmp=</varname>) are not applied to the invoked command line (but still affect any other <varname>ExecStart=</varname>, <varname>ExecStop=</varname>, … lines).</entry>
355 </row>
356
357 <row>
358 <entry><literal>!</literal></entry>
359
360 <entry>Similar to the <literal>+</literal> character discussed above this permits invoking command lines with elevated privileges. However, unlike <literal>+</literal> the <literal>!</literal> character exclusively alters the effect of <varname>User=</varname>, <varname>Group=</varname> and <varname>SupplementaryGroups=</varname>, i.e. only the stanzas that affect user and group credentials. Note that this setting may be combined with <varname>DynamicUser=</varname>, in which case a dynamic user/group pair is allocated before the command is invoked, but credential changing is left to the executed process itself.</entry>
361 </row>
362
363 <row>
364 <entry><literal>!!</literal></entry>
365
366 <entry>This prefix is very similar to <literal>!</literal>, however it only has an effect on systems lacking support for ambient process capabilities, i.e. without support for <varname>AmbientCapabilities=</varname>. It's intended to be used for unit files that take benefit of ambient capabilities to run processes with minimal privileges wherever possible while remaining compatible with systems that lack ambient capabilities support. Note that when <literal>!!</literal> is used, and a system lacking ambient capability support is detected any configured <varname>SystemCallFilter=</varname> and <varname>CapabilityBoundingSet=</varname> stanzas are implicitly modified, in order to permit spawned processes to drop credentials and capabilities themselves, even if this is configured to not be allowed. Moreover, if this prefix is used and a system lacking ambient capability support is detected <varname>AmbientCapabilities=</varname> will be skipped and not be applied. On systems supporting ambient capabilities, <literal>!!</literal> has no effect and is redundant.</entry>
367 </row>
368 </tbody>
369 </tgroup>
370 </table>
371
372 <para><literal>@</literal>, <literal>-</literal>, <literal>:</literal>, and one of
373 <literal>+</literal>/<literal>!</literal>/<literal>!!</literal> may be used together and they can appear in any
374 order. However, only one of <literal>+</literal>, <literal>!</literal>, <literal>!!</literal> may be used at a
375 time. Note that these prefixes are also supported for the other command line settings,
376 i.e. <varname>ExecStartPre=</varname>, <varname>ExecStartPost=</varname>, <varname>ExecReload=</varname>,
377 <varname>ExecStop=</varname> and <varname>ExecStopPost=</varname>.</para>
378
379 <para>If more than one command is specified, the commands are
380 invoked sequentially in the order they appear in the unit
381 file. If one of the commands fails (and is not prefixed with
382 <literal>-</literal>), other lines are not executed, and the
383 unit is considered failed.</para>
384
385 <para>Unless <varname>Type=forking</varname> is set, the
386 process started via this command line will be considered the
387 main process of the daemon.</para>
388 </listitem>
389 </varlistentry>
390
391 <varlistentry>
392 <term><varname>ExecStartPre=</varname></term>
393 <term><varname>ExecStartPost=</varname></term>
394 <listitem><para>Additional commands that are executed before
395 or after the command in <varname>ExecStart=</varname>,
396 respectively. Syntax is the same as for
397 <varname>ExecStart=</varname>, except that multiple command
398 lines are allowed and the commands are executed one after the
399 other, serially.</para>
400
401 <para>If any of those commands (not prefixed with
402 <literal>-</literal>) fail, the rest are not executed and the
403 unit is considered failed.</para>
404
405 <para><varname>ExecStart=</varname> commands are only run after
406 all <varname>ExecStartPre=</varname> commands that were not prefixed
407 with a <literal>-</literal> exit successfully.</para>
408
409 <para><varname>ExecStartPost=</varname> commands are only run after the commands specified in
410 <varname>ExecStart=</varname> have been invoked successfully, as determined by <varname>Type=</varname>
411 (i.e. the process has been started for <varname>Type=simple</varname> or <varname>Type=idle</varname>, the last
412 <varname>ExecStart=</varname> process exited successfully for <varname>Type=oneshot</varname>, the initial
413 process exited successfully for <varname>Type=forking</varname>, <literal>READY=1</literal> is sent for
414 <varname>Type=notify</varname>, or the <varname>BusName=</varname> has been taken for
415 <varname>Type=dbus</varname>).</para>
416
417 <para>Note that <varname>ExecStartPre=</varname> may not be
418 used to start long-running processes. All processes forked
419 off by processes invoked via <varname>ExecStartPre=</varname> will
420 be killed before the next service process is run.</para>
421
422 <para>Note that if any of the commands specified in <varname>ExecStartPre=</varname>,
423 <varname>ExecStart=</varname>, or <varname>ExecStartPost=</varname> fail (and are not prefixed with
424 <literal>-</literal>, see above) or time out before the service is fully up, execution continues with commands
425 specified in <varname>ExecStopPost=</varname>, the commands in <varname>ExecStop=</varname> are skipped.</para>
426
427 <para>Note that the execution of <varname>ExecStartPost=</varname> is taken into account for the purpose of
428 <varname>Before=</varname>/<varname>After=</varname> ordering constraints.</para>
429 </listitem>
430 </varlistentry>
431
432 <varlistentry>
433 <term><varname>ExecCondition=</varname></term>
434 <listitem><para>Optional commands that are executed before the command(s) in <varname>ExecStartPre=</varname>.
435 Syntax is the same as for <varname>ExecStart=</varname>, except that multiple command lines are allowed and the
436 commands are executed one after the other, serially.</para>
437
438 <para>The behavior is like an <varname>ExecStartPre=</varname> and condition check hybrid: when an
439 <varname>ExecCondition=</varname> command exits with exit code 1 through 254 (inclusive), the remaining
440 commands are skipped and the unit is <emphasis>not</emphasis> marked as failed. However, if an
441 <varname>ExecCondition=</varname> command exits with 255 or abnormally (e.g. timeout, killed by a
442 signal, etc.), the unit will be considered failed (and remaining commands will be skipped). Exit code of 0 or
443 those matching <varname>SuccessExitStatus=</varname> will continue execution to the next command(s).</para>
444
445 <para>The same recommendations about not running long-running processes in <varname>ExecStartPre=</varname>
446 also applies to <varname>ExecCondition=</varname>. <varname>ExecCondition=</varname> will also run the commands
447 in <varname>ExecStopPost=</varname>, as part of stopping the service, in the case of any non-zero or abnormal
448 exits, like the ones described above.</para>
449 </listitem>
450 </varlistentry>
451
452 <varlistentry>
453 <term><varname>ExecReload=</varname></term>
454 <listitem><para>Commands to execute to trigger a configuration
455 reload in the service. This argument takes multiple command
456 lines, following the same scheme as described for
457 <varname>ExecStart=</varname> above. Use of this setting is
458 optional. Specifier and environment variable substitution is
459 supported here following the same scheme as for
460 <varname>ExecStart=</varname>.</para>
461
462 <para>One additional, special environment variable is set: if
463 known, <varname>$MAINPID</varname> is set to the main process
464 of the daemon, and may be used for command lines like the
465 following:</para>
466
467 <programlisting>ExecReload=kill -HUP $MAINPID</programlisting>
468
469 <para>Note however that reloading a daemon by sending a signal
470 (as with the example line above) is usually not a good choice,
471 because this is an asynchronous operation and hence not
472 suitable to order reloads of multiple services against each
473 other. It is strongly recommended to set
474 <varname>ExecReload=</varname> to a command that not only
475 triggers a configuration reload of the daemon, but also
476 synchronously waits for it to complete. For example,
477 <citerefentry project='mankier'><refentrytitle>dbus-broker</refentrytitle><manvolnum>1</manvolnum></citerefentry>
478 uses the following:</para>
479
480 <programlisting>ExecReload=busctl call org.freedesktop.DBus \
481 /org/freedesktop/DBus org.freedesktop.DBus \
482 ReloadConfig
483 </programlisting>
484 </listitem>
485 </varlistentry>
486
487 <varlistentry>
488 <term><varname>ExecStop=</varname></term>
489 <listitem><para>Commands to execute to stop the service started via
490 <varname>ExecStart=</varname>. This argument takes multiple command lines, following the same scheme
491 as described for <varname>ExecStart=</varname> above. Use of this setting is optional. After the
492 commands configured in this option are run, it is implied that the service is stopped, and any
493 processes remaining for it are terminated according to the <varname>KillMode=</varname> setting (see
494 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
495 If this option is not specified, the process is terminated by sending the signal specified in
496 <varname>KillSignal=</varname> or <varname>RestartKillSignal=</varname> when service stop is
497 requested. Specifier and environment variable substitution is supported (including
498 <varname>$MAINPID</varname>, see above).</para>
499
500 <para>Note that it is usually not sufficient to specify a command for this setting that only asks the
501 service to terminate (for example, by sending some form of termination signal to it), but does not
502 wait for it to do so. Since the remaining processes of the services are killed according to
503 <varname>KillMode=</varname> and <varname>KillSignal=</varname> or
504 <varname>RestartKillSignal=</varname> as described above immediately after the command exited, this
505 may not result in a clean stop. The specified command should hence be a synchronous operation, not an
506 asynchronous one.</para>
507
508 <para>Note that the commands specified in <varname>ExecStop=</varname> are only executed when the service
509 started successfully first. They are not invoked if the service was never started at all, or in case its
510 start-up failed, for example because any of the commands specified in <varname>ExecStart=</varname>,
511 <varname>ExecStartPre=</varname> or <varname>ExecStartPost=</varname> failed (and weren't prefixed with
512 <literal>-</literal>, see above) or timed out. Use <varname>ExecStopPost=</varname> to invoke commands when a
513 service failed to start up correctly and is shut down again. Also note that the stop operation is always
514 performed if the service started successfully, even if the processes in the service terminated on their
515 own or were killed. The stop commands must be prepared to deal with that case. <varname>$MAINPID</varname>
516 will be unset if systemd knows that the main process exited by the time the stop commands are called.</para>
517
518 <para>Service restart requests are implemented as stop operations followed by start operations. This
519 means that <varname>ExecStop=</varname> and <varname>ExecStopPost=</varname> are executed during a
520 service restart operation.</para>
521
522 <para>It is recommended to use this setting for commands that communicate with the service requesting
523 clean termination. For post-mortem clean-up steps use <varname>ExecStopPost=</varname> instead.
524 </para></listitem>
525 </varlistentry>
526
527 <varlistentry>
528 <term><varname>ExecStopPost=</varname></term>
529 <listitem><para>Additional commands that are executed after the service is stopped. This includes cases where
530 the commands configured in <varname>ExecStop=</varname> were used, where the service does not have any
531 <varname>ExecStop=</varname> defined, or where the service exited unexpectedly. This argument takes multiple
532 command lines, following the same scheme as described for <varname>ExecStart=</varname>. Use of these settings
533 is optional. Specifier and environment variable substitution is supported. Note that – unlike
534 <varname>ExecStop=</varname> – commands specified with this setting are invoked when a service failed to start
535 up correctly and is shut down again.</para>
536
537 <para>It is recommended to use this setting for clean-up operations that shall be executed even when the
538 service failed to start up correctly. Commands configured with this setting need to be able to operate even if
539 the service failed starting up half-way and left incompletely initialized data around. As the service's
540 processes have been terminated already when the commands specified with this setting are executed they should
541 not attempt to communicate with them.</para>
542
543 <para>Note that all commands that are configured with this setting are invoked with the result code of the
544 service, as well as the main process' exit code and status, set in the <varname>$SERVICE_RESULT</varname>,
545 <varname>$EXIT_CODE</varname> and <varname>$EXIT_STATUS</varname> environment variables, see
546 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
547 details.</para>
548
549 <para>Note that the execution of <varname>ExecStopPost=</varname> is taken into account for the purpose of
550 <varname>Before=</varname>/<varname>After=</varname> ordering constraints.</para></listitem>
551 </varlistentry>
552
553 <varlistentry>
554 <term><varname>RestartSec=</varname></term>
555 <listitem><para>Configures the time to sleep before restarting
556 a service (as configured with <varname>Restart=</varname>).
557 Takes a unit-less value in seconds, or a time span value such
558 as "5min 20s". Defaults to 100ms.</para></listitem>
559 </varlistentry>
560
561 <varlistentry>
562 <term><varname>TimeoutStartSec=</varname></term>
563 <listitem><para>Configures the time to wait for start-up. If a daemon service does not signal start-up
564 completion within the configured time, the service will be considered failed and will be shut down again. The
565 precise action depends on the <varname>TimeoutStartFailureMode=</varname> option. Takes a unit-less value in
566 seconds, or a time span value such as "5min 20s". Pass <literal>infinity</literal> to disable the timeout logic.
567 Defaults to <varname>DefaultTimeoutStartSec=</varname> from the manager configuration file, except when
568 <varname>Type=oneshot</varname> is used, in which case the timeout is disabled by default (see
569 <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
570 </para>
571
572 <para>If a service of <varname>Type=notify</varname> sends <literal>EXTEND_TIMEOUT_USEC=…</literal>, this may cause
573 the start time to be extended beyond <varname>TimeoutStartSec=</varname>. The first receipt of this message
574 must occur before <varname>TimeoutStartSec=</varname> is exceeded, and once the start time has extended beyond
575 <varname>TimeoutStartSec=</varname>, the service manager will allow the service to continue to start, provided
576 the service repeats <literal>EXTEND_TIMEOUT_USEC=…</literal> within the interval specified until the service
577 startup status is finished by <literal>READY=1</literal>. (see
578 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>).
579 </para></listitem>
580 </varlistentry>
581
582 <varlistentry>
583 <term><varname>TimeoutStopSec=</varname></term>
584 <listitem><para>This option serves two purposes. First, it configures the time to wait for each
585 <varname>ExecStop=</varname> command. If any of them times out, subsequent <varname>ExecStop=</varname> commands
586 are skipped and the service will be terminated by <constant>SIGTERM</constant>. If no <varname>ExecStop=</varname>
587 commands are specified, the service gets the <constant>SIGTERM</constant> immediately. This default behavior
588 can be changed by the <varname>TimeoutStopFailureMode=</varname> option. Second, it configures the time
589 to wait for the service itself to stop. If it doesn't terminate in the specified time, it will be forcibly terminated
590 by <constant>SIGKILL</constant> (see <varname>KillMode=</varname> in
591 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
592 Takes a unit-less value in seconds, or a time span value such
593 as "5min 20s". Pass <literal>infinity</literal> to disable the
594 timeout logic. Defaults to
595 <varname>DefaultTimeoutStopSec=</varname> from the manager
596 configuration file (see
597 <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
598 </para>
599
600 <para>If a service of <varname>Type=notify</varname> sends <literal>EXTEND_TIMEOUT_USEC=…</literal>, this may cause
601 the stop time to be extended beyond <varname>TimeoutStopSec=</varname>. The first receipt of this message
602 must occur before <varname>TimeoutStopSec=</varname> is exceeded, and once the stop time has extended beyond
603 <varname>TimeoutStopSec=</varname>, the service manager will allow the service to continue to stop, provided
604 the service repeats <literal>EXTEND_TIMEOUT_USEC=…</literal> within the interval specified, or terminates itself
605 (see <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>).
606 </para></listitem>
607 </varlistentry>
608
609 <varlistentry>
610 <term><varname>TimeoutAbortSec=</varname></term>
611 <listitem><para>This option configures the time to wait for the service to terminate when it was aborted due to a
612 watchdog timeout (see <varname>WatchdogSec=</varname>). If the service has a short <varname>TimeoutStopSec=</varname>
613 this option can be used to give the system more time to write a core dump of the service. Upon expiration the service
614 will be forcibly terminated by <constant>SIGKILL</constant> (see <varname>KillMode=</varname> in
615 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>). The core file will
616 be truncated in this case. Use <varname>TimeoutAbortSec=</varname> to set a sensible timeout for the core dumping per
617 service that is large enough to write all expected data while also being short enough to handle the service failure
618 in due time.
619 </para>
620
621 <para>Takes a unit-less value in seconds, or a time span value such as "5min 20s". Pass an empty value to skip
622 the dedicated watchdog abort timeout handling and fall back <varname>TimeoutStopSec=</varname>. Pass
623 <literal>infinity</literal> to disable the timeout logic. Defaults to <varname>DefaultTimeoutAbortSec=</varname> from
624 the manager configuration file (see
625 <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
626 </para>
627
628 <para>If a service of <varname>Type=notify</varname> handles <constant>SIGABRT</constant> itself (instead of relying
629 on the kernel to write a core dump) it can send <literal>EXTEND_TIMEOUT_USEC=…</literal> to
630 extended the abort time beyond <varname>TimeoutAbortSec=</varname>. The first receipt of this message
631 must occur before <varname>TimeoutAbortSec=</varname> is exceeded, and once the abort time has extended beyond
632 <varname>TimeoutAbortSec=</varname>, the service manager will allow the service to continue to abort, provided
633 the service repeats <literal>EXTEND_TIMEOUT_USEC=…</literal> within the interval specified, or terminates itself
634 (see <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>).
635 </para></listitem>
636 </varlistentry>
637
638 <varlistentry>
639 <term><varname>TimeoutSec=</varname></term>
640 <listitem><para>A shorthand for configuring both
641 <varname>TimeoutStartSec=</varname> and
642 <varname>TimeoutStopSec=</varname> to the specified value.
643 </para></listitem>
644 </varlistentry>
645
646 <varlistentry>
647 <term><varname>TimeoutStartFailureMode=</varname></term>
648 <term><varname>TimeoutStopFailureMode=</varname></term>
649
650 <listitem><para>These options configure the action that is taken in case a daemon service does not signal
651 start-up within its configured <varname>TimeoutStartSec=</varname>, respectively if it does not stop within
652 <varname>TimeoutStopSec=</varname>. Takes one of <option>terminate</option>, <option>abort</option> and
653 <option>kill</option>. Both options default to <option>terminate</option>.</para>
654
655 <para>If <option>terminate</option> is set the service will be gracefully terminated by sending the signal
656 specified in <varname>KillSignal=</varname> (defaults to <constant>SIGTERM</constant>, see
657 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>). If the
658 service does not terminate the <varname>FinalKillSignal=</varname> is sent after
659 <varname>TimeoutStopSec=</varname>. If <option>abort</option> is set, <varname>WatchdogSignal=</varname> is sent
660 instead and <varname>TimeoutAbortSec=</varname> applies before sending <varname>FinalKillSignal=</varname>.
661 This setting may be used to analyze services that fail to start-up or shut-down intermittently.
662 By using <option>kill</option> the service is immediately terminated by sending
663 <varname>FinalKillSignal=</varname> without any further timeout. This setting can be used to expedite the
664 shutdown of failing services.
665 </para></listitem>
666 </varlistentry>
667
668 <varlistentry>
669 <term><varname>RuntimeMaxSec=</varname></term>
670
671 <listitem><para>Configures a maximum time for the service to run. If this is used and the service has been
672 active for longer than the specified time it is terminated and put into a failure state. Note that this setting
673 does not have any effect on <varname>Type=oneshot</varname> services, as they terminate immediately after
674 activation completed. Pass <literal>infinity</literal> (the default) to configure no runtime
675 limit.</para>
676
677 <para>If a service of <varname>Type=notify</varname> sends <literal>EXTEND_TIMEOUT_USEC=…</literal>, this may cause
678 the runtime to be extended beyond <varname>RuntimeMaxSec=</varname>. The first receipt of this message
679 must occur before <varname>RuntimeMaxSec=</varname> is exceeded, and once the runtime has extended beyond
680 <varname>RuntimeMaxSec=</varname>, the service manager will allow the service to continue to run, provided
681 the service repeats <literal>EXTEND_TIMEOUT_USEC=…</literal> within the interval specified until the service
682 shutdown is achieved by <literal>STOPPING=1</literal> (or termination). (see
683 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>).
684 </para></listitem>
685 </varlistentry>
686
687 <varlistentry>
688 <term><varname>WatchdogSec=</varname></term>
689 <listitem><para>Configures the watchdog timeout for a service.
690 The watchdog is activated when the start-up is completed. The
691 service must call
692 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
693 regularly with <literal>WATCHDOG=1</literal> (i.e. the
694 "keep-alive ping"). If the time between two such calls is
695 larger than the configured time, then the service is placed in
696 a failed state and it will be terminated with
697 <constant>SIGABRT</constant> (or the signal specified by
698 <varname>WatchdogSignal=</varname>). By setting
699 <varname>Restart=</varname> to <option>on-failure</option>,
700 <option>on-watchdog</option>, <option>on-abnormal</option> or
701 <option>always</option>, the service will be automatically
702 restarted. The time configured here will be passed to the
703 executed service process in the
704 <varname>WATCHDOG_USEC=</varname> environment variable. This
705 allows daemons to automatically enable the keep-alive pinging
706 logic if watchdog support is enabled for the service. If this
707 option is used, <varname>NotifyAccess=</varname> (see below)
708 should be set to open access to the notification socket
709 provided by systemd. If <varname>NotifyAccess=</varname> is
710 not set, it will be implicitly set to <option>main</option>.
711 Defaults to 0, which disables this feature. The service can
712 check whether the service manager expects watchdog keep-alive
713 notifications. See
714 <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
715 for details.
716 <citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
717 may be used to enable automatic watchdog notification support.
718 </para></listitem>
719 </varlistentry>
720
721 <varlistentry>
722 <term><varname>Restart=</varname></term>
723 <listitem><para>Configures whether the service shall be
724 restarted when the service process exits, is killed, or a
725 timeout is reached. The service process may be the main
726 service process, but it may also be one of the processes
727 specified with <varname>ExecStartPre=</varname>,
728 <varname>ExecStartPost=</varname>,
729 <varname>ExecStop=</varname>,
730 <varname>ExecStopPost=</varname>, or
731 <varname>ExecReload=</varname>. When the death of the process
732 is a result of systemd operation (e.g. service stop or
733 restart), the service will not be restarted. Timeouts include
734 missing the watchdog "keep-alive ping" deadline and a service
735 start, reload, and stop operation timeouts.</para>
736
737 <para>Takes one of
738 <option>no</option>,
739 <option>on-success</option>,
740 <option>on-failure</option>,
741 <option>on-abnormal</option>,
742 <option>on-watchdog</option>,
743 <option>on-abort</option>, or
744 <option>always</option>.
745 If set to <option>no</option> (the default), the service will
746 not be restarted. If set to <option>on-success</option>, it
747 will be restarted only when the service process exits cleanly.
748 In this context, a clean exit means an exit code of 0, or one
749 of the signals
750 <constant>SIGHUP</constant>,
751 <constant>SIGINT</constant>,
752 <constant>SIGTERM</constant> or
753 <constant>SIGPIPE</constant>, and
754 additionally, exit statuses and signals specified in
755 <varname>SuccessExitStatus=</varname>. If set to
756 <option>on-failure</option>, the service will be restarted
757 when the process exits with a non-zero exit code, is
758 terminated by a signal (including on core dump, but excluding
759 the aforementioned four signals), when an operation (such as
760 service reload) times out, and when the configured watchdog
761 timeout is triggered. If set to <option>on-abnormal</option>,
762 the service will be restarted when the process is terminated
763 by a signal (including on core dump, excluding the
764 aforementioned four signals), when an operation times out, or
765 when the watchdog timeout is triggered. If set to
766 <option>on-abort</option>, the service will be restarted only
767 if the service process exits due to an uncaught signal not
768 specified as a clean exit status. If set to
769 <option>on-watchdog</option>, the service will be restarted
770 only if the watchdog timeout for the service expires. If set
771 to <option>always</option>, the service will be restarted
772 regardless of whether it exited cleanly or not, got terminated
773 abnormally by a signal, or hit a timeout.</para>
774
775 <table>
776 <title>Exit causes and the effect of the <varname>Restart=</varname> settings on them</title>
777
778 <tgroup cols='2'>
779 <colspec colname='path' />
780 <colspec colname='expl' />
781 <thead>
782 <row>
783 <entry>Restart settings/Exit causes</entry>
784 <entry><option>no</option></entry>
785 <entry><option>always</option></entry>
786 <entry><option>on-success</option></entry>
787 <entry><option>on-failure</option></entry>
788 <entry><option>on-abnormal</option></entry>
789 <entry><option>on-abort</option></entry>
790 <entry><option>on-watchdog</option></entry>
791 </row>
792 </thead>
793 <tbody>
794 <row>
795 <entry>Clean exit code or signal</entry>
796 <entry/>
797 <entry>X</entry>
798 <entry>X</entry>
799 <entry/>
800 <entry/>
801 <entry/>
802 <entry/>
803 </row>
804 <row>
805 <entry>Unclean exit code</entry>
806 <entry/>
807 <entry>X</entry>
808 <entry/>
809 <entry>X</entry>
810 <entry/>
811 <entry/>
812 <entry/>
813 </row>
814 <row>
815 <entry>Unclean signal</entry>
816 <entry/>
817 <entry>X</entry>
818 <entry/>
819 <entry>X</entry>
820 <entry>X</entry>
821 <entry>X</entry>
822 <entry/>
823 </row>
824 <row>
825 <entry>Timeout</entry>
826 <entry/>
827 <entry>X</entry>
828 <entry/>
829 <entry>X</entry>
830 <entry>X</entry>
831 <entry/>
832 <entry/>
833 </row>
834 <row>
835 <entry>Watchdog</entry>
836 <entry/>
837 <entry>X</entry>
838 <entry/>
839 <entry>X</entry>
840 <entry>X</entry>
841 <entry/>
842 <entry>X</entry>
843 </row>
844 </tbody>
845 </tgroup>
846 </table>
847
848 <para>As exceptions to the setting above, the service will not
849 be restarted if the exit code or signal is specified in
850 <varname>RestartPreventExitStatus=</varname> (see below) or
851 the service is stopped with <command>systemctl stop</command>
852 or an equivalent operation. Also, the services will always be
853 restarted if the exit code or signal is specified in
854 <varname>RestartForceExitStatus=</varname> (see below).</para>
855
856 <para>Note that service restart is subject to unit start rate
857 limiting configured with <varname>StartLimitIntervalSec=</varname>
858 and <varname>StartLimitBurst=</varname>, see
859 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
860 for details. A restarted service enters the failed state only
861 after the start limits are reached.</para>
862
863 <para>Setting this to <option>on-failure</option> is the
864 recommended choice for long-running services, in order to
865 increase reliability by attempting automatic recovery from
866 errors. For services that shall be able to terminate on their
867 own choice (and avoid immediate restarting),
868 <option>on-abnormal</option> is an alternative choice.</para>
869 </listitem>
870 </varlistentry>
871
872 <varlistentry>
873 <term><varname>SuccessExitStatus=</varname></term>
874
875 <listitem><para>Takes a list of exit status definitions that, when returned by the main service
876 process, will be considered successful termination, in addition to the normal successful exit status
877 0 and the signals <constant>SIGHUP</constant>, <constant>SIGINT</constant>,
878 <constant>SIGTERM</constant>, and <constant>SIGPIPE</constant>. Exit status definitions can be
879 numeric termination statuses, termination status names, or termination signal names, separated by
880 spaces. See the Process Exit Codes section in
881 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
882 a list of termination status names (for this setting only the part without the
883 <literal>EXIT_</literal> or <literal>EX_</literal> prefix should be used). See <citerefentry
884 project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
885 a list of signal names.</para>
886
887 <para>Note that this setting does not change the mapping between numeric exit statuses and their
888 names, i.e. regardless how this setting is used 0 will still be mapped to <literal>SUCCESS</literal>
889 (and thus typically shown as <literal>0/SUCCESS</literal> in tool outputs) and 1 to
890 <literal>FAILURE</literal> (and thus typically shown as <literal>1/FAILURE</literal>), and so on. It
891 only controls what happens as effect of these exit statuses, and how it propagates to the state of
892 the service as a whole.</para>
893
894 <para>This option may appear more than once, in which case the list of successful exit statuses is
895 merged. If the empty string is assigned to this option, the list is reset, all prior assignments of
896 this option will have no effect.</para>
897
898 <example>
899 <title>A service with the <varname>SuccessExitStatus=</varname> setting</title>
900
901 <programlisting>SuccessExitStatus=TEMPFAIL 250 SIGUSR1</programlisting>
902
903 <para>Exit status 75 (<constant>TEMPFAIL</constant>), 250, and the termination signal
904 <constant>SIGUSR1</constant> are considered clean service terminations.</para>
905 </example>
906
907 <para>Note: <command>systemd-analyze exit-status</command> may be used to list exit statuses and
908 translate between numerical status values and names.</para></listitem>
909 </varlistentry>
910
911 <varlistentry>
912 <term><varname>RestartPreventExitStatus=</varname></term>
913
914 <listitem><para>Takes a list of exit status definitions that, when returned by the main service
915 process, will prevent automatic service restarts, regardless of the restart setting configured with
916 <varname>Restart=</varname>. Exit status definitions can either be numeric exit codes or termination
917 signal names, and are separated by spaces. Defaults to the empty list, so that, by default, no exit
918 status is excluded from the configured restart logic. For example:
919
920 <programlisting>RestartPreventExitStatus=1 6 SIGABRT</programlisting>
921
922 ensures that exit codes 1 and 6 and the termination signal <constant>SIGABRT</constant> will not
923 result in automatic service restarting. This option may appear more than once, in which case the list
924 of restart-preventing statuses is merged. If the empty string is assigned to this option, the list is
925 reset and all prior assignments of this option will have no effect.</para>
926
927 <para>Note that this setting has no effect on processes configured via
928 <varname>ExecStartPre=</varname>, <varname>ExecStartPost=</varname>, <varname>ExecStop=</varname>,
929 <varname>ExecStopPost=</varname> or <varname>ExecReload=</varname>, but only on the main service
930 process, i.e. either the one invoked by <varname>ExecStart=</varname> or (depending on
931 <varname>Type=</varname>, <varname>PIDFile=</varname>, …) the otherwise configured main
932 process.</para></listitem>
933 </varlistentry>
934
935 <varlistentry>
936 <term><varname>RestartForceExitStatus=</varname></term>
937 <listitem><para>Takes a list of exit status definitions that,
938 when returned by the main service process, will force automatic
939 service restarts, regardless of the restart setting configured
940 with <varname>Restart=</varname>. The argument format is
941 similar to
942 <varname>RestartPreventExitStatus=</varname>.</para></listitem>
943 </varlistentry>
944
945 <varlistentry>
946 <term><varname>RootDirectoryStartOnly=</varname></term>
947 <listitem><para>Takes a boolean argument. If true, the root
948 directory, as configured with the
949 <varname>RootDirectory=</varname> option (see
950 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
951 for more information), is only applied to the process started
952 with <varname>ExecStart=</varname>, and not to the various
953 other <varname>ExecStartPre=</varname>,
954 <varname>ExecStartPost=</varname>,
955 <varname>ExecReload=</varname>, <varname>ExecStop=</varname>,
956 and <varname>ExecStopPost=</varname> commands. If false, the
957 setting is applied to all configured commands the same way.
958 Defaults to false.</para></listitem>
959 </varlistentry>
960
961 <varlistentry>
962 <term><varname>NonBlocking=</varname></term>
963 <listitem><para>Set the <constant>O_NONBLOCK</constant> flag for all file descriptors passed via socket-based
964 activation. If true, all file descriptors >= 3 (i.e. all except stdin, stdout, stderr), excluding those passed
965 in via the file descriptor storage logic (see <varname>FileDescriptorStoreMax=</varname> for details), will
966 have the <constant>O_NONBLOCK</constant> flag set and hence are in non-blocking mode. This option is only
967 useful in conjunction with a socket unit, as described in
968 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> and has no
969 effect on file descriptors which were previously saved in the file-descriptor store for example. Defaults to
970 false.</para></listitem>
971 </varlistentry>
972
973 <varlistentry>
974 <term><varname>NotifyAccess=</varname></term>
975 <listitem><para>Controls access to the service status notification socket, as accessible via the
976 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> call. Takes one
977 of <option>none</option> (the default), <option>main</option>, <option>exec</option> or
978 <option>all</option>. If <option>none</option>, no daemon status updates are accepted from the service
979 processes, all status update messages are ignored. If <option>main</option>, only service updates sent from the
980 main process of the service are accepted. If <option>exec</option>, only service updates sent from any of the
981 main or control processes originating from one of the <varname>Exec*=</varname> commands are accepted. If
982 <option>all</option>, all services updates from all members of the service's control group are accepted. This
983 option should be set to open access to the notification socket when using <varname>Type=notify</varname> or
984 <varname>WatchdogSec=</varname> (see above). If those options are used but <varname>NotifyAccess=</varname> is
985 not configured, it will be implicitly set to <option>main</option>.</para>
986
987 <para>Note that <function>sd_notify()</function> notifications may be attributed to units correctly only if
988 either the sending process is still around at the time PID 1 processes the message, or if the sending process
989 is explicitly runtime-tracked by the service manager. The latter is the case if the service manager originally
990 forked off the process, i.e. on all processes that match <option>main</option> or
991 <option>exec</option>. Conversely, if an auxiliary process of the unit sends an
992 <function>sd_notify()</function> message and immediately exits, the service manager might not be able to
993 properly attribute the message to the unit, and thus will ignore it, even if
994 <varname>NotifyAccess=</varname><option>all</option> is set for it.</para>
995
996 <para>Hence, to eliminate all race conditions involving lookup of the client's unit and attribution of notifications
997 to units correctly, <function>sd_notify_barrier()</function> may be used. This call acts as a synchronization point
998 and ensures all notifications sent before this call have been picked up by the service manager when it returns
999 successfully. Use of <function>sd_notify_barrier()</function> is needed for clients which are not invoked by the
1000 service manager, otherwise this synchronization mechanism is unnecessary for attribution of notifications to the
1001 unit.</para></listitem>
1002 </varlistentry>
1003
1004 <varlistentry>
1005 <term><varname>Sockets=</varname></term>
1006 <listitem><para>Specifies the name of the socket units this
1007 service shall inherit socket file descriptors from when the
1008 service is started. Normally, it should not be necessary to use
1009 this setting, as all socket file descriptors whose unit shares
1010 the same name as the service (subject to the different unit
1011 name suffix of course) are passed to the spawned
1012 process.</para>
1013
1014 <para>Note that the same socket file descriptors may be passed
1015 to multiple processes simultaneously. Also note that a
1016 different service may be activated on incoming socket traffic
1017 than the one which is ultimately configured to inherit the
1018 socket file descriptors. Or, in other words: the
1019 <varname>Service=</varname> setting of
1020 <filename>.socket</filename> units does not have to match the
1021 inverse of the <varname>Sockets=</varname> setting of the
1022 <filename>.service</filename> it refers to.</para>
1023
1024 <para>This option may appear more than once, in which case the list of socket units is merged. Note
1025 that once set, clearing the list of sockets again (for example, by assigning the empty string to this
1026 option) is not supported.</para></listitem>
1027 </varlistentry>
1028
1029 <varlistentry>
1030 <term><varname>FileDescriptorStoreMax=</varname></term>
1031 <listitem><para>Configure how many file descriptors may be stored in the service manager for the service using
1032 <citerefentry><refentrytitle>sd_pid_notify_with_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>'s
1033 <literal>FDSTORE=1</literal> messages. This is useful for implementing services that can restart after an
1034 explicit request or a crash without losing state. Any open sockets and other file descriptors which should not
1035 be closed during the restart may be stored this way. Application state can either be serialized to a file in
1036 <filename>/run</filename>, or better, stored in a
1037 <citerefentry><refentrytitle>memfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry> memory file
1038 descriptor. Defaults to 0, i.e. no file descriptors may be stored in the service manager. All file descriptors
1039 passed to the service manager from a specific service are passed back to the service's main process on the next
1040 service restart. Any file descriptors passed to the service manager are automatically closed when
1041 <constant>POLLHUP</constant> or <constant>POLLERR</constant> is seen on them, or when the service is fully
1042 stopped and no job is queued or being executed for it. If this option is used, <varname>NotifyAccess=</varname>
1043 (see above) should be set to open access to the notification socket provided by systemd. If
1044 <varname>NotifyAccess=</varname> is not set, it will be implicitly set to
1045 <option>main</option>.</para></listitem>
1046 </varlistentry>
1047
1048 <varlistentry>
1049 <term><varname>USBFunctionDescriptors=</varname></term>
1050 <listitem><para>Configure the location of a file containing
1051 <ulink
1052 url="https://www.kernel.org/doc/Documentation/usb/functionfs.txt">USB
1053 FunctionFS</ulink> descriptors, for implementation of USB
1054 gadget functions. This is used only in conjunction with a
1055 socket unit with <varname>ListenUSBFunction=</varname>
1056 configured. The contents of this file are written to the
1057 <filename>ep0</filename> file after it is
1058 opened.</para></listitem>
1059 </varlistentry>
1060
1061 <varlistentry>
1062 <term><varname>USBFunctionStrings=</varname></term>
1063 <listitem><para>Configure the location of a file containing
1064 USB FunctionFS strings. Behavior is similar to
1065 <varname>USBFunctionDescriptors=</varname>
1066 above.</para></listitem>
1067 </varlistentry>
1068
1069 <varlistentry>
1070 <term><varname>OOMPolicy=</varname></term>
1071
1072 <listitem><para>Configure the Out-Of-Memory (OOM) killer policy. On Linux, when memory becomes scarce
1073 the kernel might decide to kill a running process in order to free up memory and reduce memory
1074 pressure. This setting takes one of <constant>continue</constant>, <constant>stop</constant> or
1075 <constant>kill</constant>. If set to <constant>continue</constant> and a process of the service is
1076 killed by the kernel's OOM killer this is logged but the service continues running. If set to
1077 <constant>stop</constant> the event is logged but the service is terminated cleanly by the service
1078 manager. If set to <constant>kill</constant> and one of the service's processes is killed by the OOM
1079 killer the kernel is instructed to kill all remaining processes of the service, too. Defaults to the
1080 setting <varname>DefaultOOMPolicy=</varname> in
1081 <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
1082 is set to, except for services where <varname>Delegate=</varname> is turned on, where it defaults to
1083 <constant>continue</constant>.</para>
1084
1085 <para>Use the <varname>OOMScoreAdjust=</varname> setting to configure whether processes of the unit
1086 shall be considered preferred or less preferred candidates for process termination by the Linux OOM
1087 killer logic. See
1088 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
1089 details.</para></listitem>
1090 </varlistentry>
1091
1092 </variablelist>
1093
1094 <para>Check
1095 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
1096 and
1097 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
1098 for more settings.</para>
1099
1100 </refsect1>
1101
1102 <refsect1>
1103 <title>Command lines</title>
1104
1105 <para>This section describes command line parsing and
1106 variable and specifier substitutions for
1107 <varname>ExecStart=</varname>,
1108 <varname>ExecStartPre=</varname>,
1109 <varname>ExecStartPost=</varname>,
1110 <varname>ExecReload=</varname>,
1111 <varname>ExecStop=</varname>, and
1112 <varname>ExecStopPost=</varname> options.</para>
1113
1114 <para>Multiple command lines may be concatenated in a single
1115 directive by separating them with semicolons (these semicolons
1116 must be passed as separate words). Lone semicolons may be escaped
1117 as <literal>\;</literal>.</para>
1118
1119 <para>Each command line is split on whitespace, with the first item being the command to
1120 execute, and the subsequent items being the arguments. Double quotes ("…") and single quotes
1121 ('…') may be used to wrap a whole item (the opening quote may appear only at the beginning or
1122 after whitespace that is not quoted, and the closing quote must be followed by whitespace or the
1123 end of line), in which case everything until the next matching quote becomes part of the same
1124 argument. Quotes themselves are removed. C-style escapes are also supported. The table below
1125 contains the list of known escape patterns. Only escape patterns which match the syntax in the
1126 table are allowed; other patterns may be added in the future and unknown patterns will result in
1127 a warning. In particular, any backslashes should be doubled. Finally, a trailing backslash
1128 (<literal>\</literal>) may be used to merge lines.</para>
1129
1130 <para>This syntax is inspired by shell syntax, but only the meta-characters and expansions
1131 described in the following paragraphs are understood, and the expansion of variables is
1132 different. Specifically, redirection using
1133 <literal>&lt;</literal>,
1134 <literal>&lt;&lt;</literal>,
1135 <literal>&gt;</literal>, and
1136 <literal>&gt;&gt;</literal>, pipes using
1137 <literal>|</literal>, running programs in the background using
1138 <literal>&amp;</literal>, and <emphasis>other elements of shell
1139 syntax are not supported</emphasis>.</para>
1140
1141 <para>The command to execute may contain spaces, but control characters are not allowed.</para>
1142
1143 <para>The command line accepts <literal>%</literal> specifiers as described in
1144 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
1145
1146 <para>Basic environment variable substitution is supported. Use
1147 <literal>${FOO}</literal> as part of a word, or as a word of its
1148 own, on the command line, in which case it will be erased and replaced
1149 by the exact value of the environment variable (if any) including all
1150 whitespace it contains, always resulting in exactly a single argument.
1151 Use <literal>$FOO</literal> as a separate word on the command line, in
1152 which case it will be replaced by the value of the environment
1153 variable split at whitespace, resulting in zero or more arguments.
1154 For this type of expansion, quotes are respected when splitting
1155 into words, and afterwards removed.</para>
1156
1157 <para>If the command is not a full (absolute) path, it will be resolved to a full path using a
1158 fixed search path determinted at compilation time. Searched directories include
1159 <filename>/usr/local/bin/</filename>, <filename>/usr/bin/</filename>, <filename>/bin/</filename>
1160 on systems using split <filename>/usr/bin/</filename> and <filename>/bin/</filename>
1161 directories, and their <filename>sbin/</filename> counterparts on systems using split
1162 <filename>bin/</filename> and <filename>sbin/</filename>. It is thus safe to use just the
1163 executable name in case of executables located in any of the "standard" directories, and an
1164 absolute path must be used in other cases. Using an absolute path is recommended to avoid
1165 ambiguity. Hint: this search path may be queried using
1166 <command>systemd-path search-binaries-default</command>.</para>
1167
1168 <para>Example:</para>
1169
1170 <programlisting>Environment="ONE=one" 'TWO=two two'
1171 ExecStart=echo $ONE $TWO ${TWO}</programlisting>
1172
1173 <para>This will execute <command>/bin/echo</command> with four
1174 arguments: <literal>one</literal>, <literal>two</literal>,
1175 <literal>two</literal>, and <literal>two two</literal>.</para>
1176
1177 <para>Example:</para>
1178 <programlisting>Environment=ONE='one' "TWO='two two' too" THREE=
1179 ExecStart=/bin/echo ${ONE} ${TWO} ${THREE}
1180 ExecStart=/bin/echo $ONE $TWO $THREE</programlisting>
1181 <para>This results in <filename>/bin/echo</filename> being
1182 called twice, the first time with arguments
1183 <literal>'one'</literal>,
1184 <literal>'two two' too</literal>, <literal></literal>,
1185 and the second time with arguments
1186 <literal>one</literal>, <literal>two two</literal>,
1187 <literal>too</literal>.
1188 </para>
1189
1190 <para>To pass a literal dollar sign, use <literal>$$</literal>.
1191 Variables whose value is not known at expansion time are treated
1192 as empty strings. Note that the first argument (i.e. the program
1193 to execute) may not be a variable.</para>
1194
1195 <para>Variables to be used in this fashion may be defined through
1196 <varname>Environment=</varname> and
1197 <varname>EnvironmentFile=</varname>. In addition, variables listed
1198 in the section "Environment variables in spawned processes" in
1199 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1200 which are considered "static configuration", may be used (this
1201 includes e.g. <varname>$USER</varname>, but not
1202 <varname>$TERM</varname>).</para>
1203
1204 <para>Note that shell command lines are not directly supported. If
1205 shell command lines are to be used, they need to be passed
1206 explicitly to a shell implementation of some kind. Example:</para>
1207 <programlisting>ExecStart=sh -c 'dmesg | tac'</programlisting>
1208
1209 <para>Example:</para>
1210
1211 <programlisting>ExecStart=echo one ; echo "two two"</programlisting>
1212
1213 <para>This will execute <command>echo</command> two times,
1214 each time with one argument: <literal>one</literal> and
1215 <literal>two two</literal>, respectively. Because two commands are
1216 specified, <varname>Type=oneshot</varname> must be used.</para>
1217
1218 <para>Example:</para>
1219
1220 <programlisting>ExecStart=echo / &gt;/dev/null &amp; \; \
1221 ls</programlisting>
1222
1223 <para>This will execute <command>echo</command>
1224 with five arguments: <literal>/</literal>,
1225 <literal>&gt;/dev/null</literal>,
1226 <literal>&amp;</literal>, <literal>;</literal>, and
1227 <literal>ls</literal>.</para>
1228
1229 <table>
1230 <title>C escapes supported in command lines and environment variables</title>
1231 <tgroup cols='2'>
1232 <colspec colname='escape' />
1233 <colspec colname='meaning' />
1234 <thead>
1235 <row>
1236 <entry>Literal</entry>
1237 <entry>Actual value</entry>
1238 </row>
1239 </thead>
1240 <tbody>
1241 <row>
1242 <entry><literal>\a</literal></entry>
1243 <entry>bell</entry>
1244 </row>
1245 <row>
1246 <entry><literal>\b</literal></entry>
1247 <entry>backspace</entry>
1248 </row>
1249 <row>
1250 <entry><literal>\f</literal></entry>
1251 <entry>form feed</entry>
1252 </row>
1253 <row>
1254 <entry><literal>\n</literal></entry>
1255 <entry>newline</entry>
1256 </row>
1257 <row>
1258 <entry><literal>\r</literal></entry>
1259 <entry>carriage return</entry>
1260 </row>
1261 <row>
1262 <entry><literal>\t</literal></entry>
1263 <entry>tab</entry>
1264 </row>
1265 <row>
1266 <entry><literal>\v</literal></entry>
1267 <entry>vertical tab</entry>
1268 </row>
1269 <row>
1270 <entry><literal>\\</literal></entry>
1271 <entry>backslash</entry>
1272 </row>
1273 <row>
1274 <entry><literal>\"</literal></entry>
1275 <entry>double quotation mark</entry>
1276 </row>
1277 <row>
1278 <entry><literal>\'</literal></entry>
1279 <entry>single quotation mark</entry>
1280 </row>
1281 <row>
1282 <entry><literal>\s</literal></entry>
1283 <entry>space</entry>
1284 </row>
1285 <row>
1286 <entry><literal>\x<replaceable>xx</replaceable></literal></entry>
1287 <entry>character number <replaceable>xx</replaceable> in hexadecimal encoding</entry>
1288 </row>
1289 <row>
1290 <entry><literal>\<replaceable>nnn</replaceable></literal></entry>
1291 <entry>character number <replaceable>nnn</replaceable> in octal encoding</entry>
1292 </row>
1293 </tbody>
1294 </tgroup>
1295 </table>
1296 </refsect1>
1297
1298 <refsect1>
1299 <title>Examples</title>
1300
1301 <example>
1302 <title>Simple service</title>
1303
1304 <para>The following unit file creates a service that will
1305 execute <filename>/usr/sbin/foo-daemon</filename>. Since no
1306 <varname>Type=</varname> is specified, the default
1307 <varname>Type=</varname><option>simple</option> will be assumed.
1308 systemd will assume the unit to be started immediately after the
1309 program has begun executing.</para>
1310
1311 <programlisting>[Unit]
1312 Description=Foo
1313
1314 [Service]
1315 ExecStart=/usr/sbin/foo-daemon
1316
1317 [Install]
1318 WantedBy=multi-user.target</programlisting>
1319
1320 <para>Note that systemd assumes here that the process started by
1321 systemd will continue running until the service terminates. If
1322 the program daemonizes itself (i.e. forks), please use
1323 <varname>Type=</varname><option>forking</option> instead.</para>
1324
1325 <para>Since no <varname>ExecStop=</varname> was specified,
1326 systemd will send SIGTERM to all processes started from this
1327 service, and after a timeout also SIGKILL. This behavior can be
1328 modified, see
1329 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
1330 for details.</para>
1331
1332 <para>Note that this unit type does not include any type of
1333 notification when a service has completed initialization. For
1334 this, you should use other unit types, such as
1335 <varname>Type=</varname><option>notify</option> if the service
1336 understands systemd's notification protocol,
1337 <varname>Type=</varname><option>forking</option> if the service
1338 can background itself or
1339 <varname>Type=</varname><option>dbus</option> if the unit
1340 acquires a DBus name once initialization is complete. See
1341 below.</para>
1342 </example>
1343
1344 <example>
1345 <title>Oneshot service</title>
1346
1347 <para>Sometimes, units should just execute an action without
1348 keeping active processes, such as a filesystem check or a
1349 cleanup action on boot. For this,
1350 <varname>Type=</varname><option>oneshot</option> exists. Units
1351 of this type will wait until the process specified terminates
1352 and then fall back to being inactive. The following unit will
1353 perform a cleanup action:</para>
1354
1355 <programlisting>[Unit]
1356 Description=Cleanup old Foo data
1357
1358 [Service]
1359 Type=oneshot
1360 ExecStart=/usr/sbin/foo-cleanup
1361
1362 [Install]
1363 WantedBy=multi-user.target</programlisting>
1364
1365 <para>Note that systemd will consider the unit to be in the
1366 state "starting" until the program has terminated, so ordered
1367 dependencies will wait for the program to finish before starting
1368 themselves. The unit will revert to the "inactive" state after
1369 the execution is done, never reaching the "active" state. That
1370 means another request to start the unit will perform the action
1371 again.</para>
1372
1373 <para><varname>Type=</varname><option>oneshot</option> are the
1374 only service units that may have more than one
1375 <varname>ExecStart=</varname> specified. For units with multiple
1376 commands (<varname index="false">Type=oneshot</varname>), all commands will be run again.</para>
1377 <para> For <varname index="false">Type=oneshot</varname>, <varname>Restart=</varname><option>always</option>
1378 and <varname>Restart=</varname><option>on-success</option> are <emphasis>not</emphasis> allowed.</para>
1379 </example>
1380
1381 <example>
1382 <title>Stoppable oneshot service</title>
1383
1384 <para>Similarly to the oneshot services, there are sometimes
1385 units that need to execute a program to set up something and
1386 then execute another to shut it down, but no process remains
1387 active while they are considered "started". Network
1388 configuration can sometimes fall into this category. Another use
1389 case is if a oneshot service shall not be executed each time
1390 when they are pulled in as a dependency, but only the first
1391 time.</para>
1392
1393 <para>For this, systemd knows the setting
1394 <varname>RemainAfterExit=</varname><option>yes</option>, which
1395 causes systemd to consider the unit to be active if the start
1396 action exited successfully. This directive can be used with all
1397 types, but is most useful with
1398 <varname>Type=</varname><option>oneshot</option> and
1399 <varname>Type=</varname><option>simple</option>. With
1400 <varname>Type=</varname><option>oneshot</option>, systemd waits
1401 until the start action has completed before it considers the
1402 unit to be active, so dependencies start only after the start
1403 action has succeeded. With
1404 <varname>Type=</varname><option>simple</option>, dependencies
1405 will start immediately after the start action has been
1406 dispatched. The following unit provides an example for a simple
1407 static firewall.</para>
1408
1409 <programlisting>[Unit]
1410 Description=Simple firewall
1411
1412 [Service]
1413 Type=oneshot
1414 RemainAfterExit=yes
1415 ExecStart=/usr/local/sbin/simple-firewall-start
1416 ExecStop=/usr/local/sbin/simple-firewall-stop
1417
1418 [Install]
1419 WantedBy=multi-user.target</programlisting>
1420
1421 <para>Since the unit is considered to be running after the start
1422 action has exited, invoking <command>systemctl start</command>
1423 on that unit again will cause no action to be taken.</para>
1424 </example>
1425
1426 <example>
1427 <title>Traditional forking services</title>
1428
1429 <para>Many traditional daemons/services background (i.e. fork,
1430 daemonize) themselves when starting. Set
1431 <varname>Type=</varname><option>forking</option> in the
1432 service's unit file to support this mode of operation. systemd
1433 will consider the service to be in the process of initialization
1434 while the original program is still running. Once it exits
1435 successfully and at least a process remains (and
1436 <varname>RemainAfterExit=</varname><option>no</option>), the
1437 service is considered started.</para>
1438
1439 <para>Often, a traditional daemon only consists of one process.
1440 Therefore, if only one process is left after the original
1441 process terminates, systemd will consider that process the main
1442 process of the service. In that case, the
1443 <varname>$MAINPID</varname> variable will be available in
1444 <varname>ExecReload=</varname>, <varname>ExecStop=</varname>,
1445 etc.</para>
1446
1447 <para>In case more than one process remains, systemd will be
1448 unable to determine the main process, so it will not assume
1449 there is one. In that case, <varname>$MAINPID</varname> will not
1450 expand to anything. However, if the process decides to write a
1451 traditional PID file, systemd will be able to read the main PID
1452 from there. Please set <varname>PIDFile=</varname> accordingly.
1453 Note that the daemon should write that file before finishing
1454 with its initialization. Otherwise, systemd might try to read the
1455 file before it exists.</para>
1456
1457 <para>The following example shows a simple daemon that forks and
1458 just starts one process in the background:</para>
1459
1460 <programlisting>[Unit]
1461 Description=Some simple daemon
1462
1463 [Service]
1464 Type=forking
1465 ExecStart=/usr/sbin/my-simple-daemon -d
1466
1467 [Install]
1468 WantedBy=multi-user.target</programlisting>
1469
1470 <para>Please see
1471 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
1472 for details on how you can influence the way systemd terminates
1473 the service.</para>
1474 </example>
1475
1476 <example>
1477 <title>DBus services</title>
1478
1479 <para>For services that acquire a name on the DBus system bus,
1480 use <varname>Type=</varname><option>dbus</option> and set
1481 <varname>BusName=</varname> accordingly. The service should not
1482 fork (daemonize). systemd will consider the service to be
1483 initialized once the name has been acquired on the system bus.
1484 The following example shows a typical DBus service:</para>
1485
1486 <programlisting>[Unit]
1487 Description=Simple DBus service
1488
1489 [Service]
1490 Type=dbus
1491 BusName=org.example.simple-dbus-service
1492 ExecStart=/usr/sbin/simple-dbus-service
1493
1494 [Install]
1495 WantedBy=multi-user.target</programlisting>
1496
1497 <para>For <emphasis>bus-activatable</emphasis> services, do not
1498 include a [Install] section in the systemd
1499 service file, but use the <varname>SystemdService=</varname>
1500 option in the corresponding DBus service file, for example
1501 (<filename>/usr/share/dbus-1/system-services/org.example.simple-dbus-service.service</filename>):</para>
1502
1503 <programlisting>[D-BUS Service]
1504 Name=org.example.simple-dbus-service
1505 Exec=/usr/sbin/simple-dbus-service
1506 User=root
1507 SystemdService=simple-dbus-service.service</programlisting>
1508
1509 <para>Please see
1510 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
1511 for details on how you can influence the way systemd terminates
1512 the service.</para>
1513 </example>
1514
1515 <example>
1516 <title>Services that notify systemd about their initialization</title>
1517
1518 <para><varname>Type=</varname><option>simple</option> services
1519 are really easy to write, but have the major disadvantage of
1520 systemd not being able to tell when initialization of the given
1521 service is complete. For this reason, systemd supports a simple
1522 notification protocol that allows daemons to make systemd aware
1523 that they are done initializing. Use
1524 <varname>Type=</varname><option>notify</option> for this. A
1525 typical service file for such a daemon would look like
1526 this:</para>
1527
1528 <programlisting>[Unit]
1529 Description=Simple notifying service
1530
1531 [Service]
1532 Type=notify
1533 ExecStart=/usr/sbin/simple-notifying-service
1534
1535 [Install]
1536 WantedBy=multi-user.target</programlisting>
1537
1538 <para>Note that the daemon has to support systemd's notification
1539 protocol, else systemd will think the service has not started yet
1540 and kill it after a timeout. For an example of how to update
1541 daemons to support this protocol transparently, take a look at
1542 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
1543 systemd will consider the unit to be in the 'starting' state
1544 until a readiness notification has arrived.</para>
1545
1546 <para>Please see
1547 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
1548 for details on how you can influence the way systemd terminates
1549 the service.</para>
1550 </example>
1551 </refsect1>
1552
1553 <refsect1>
1554 <title>See Also</title>
1555 <para>
1556 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1557 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1558 <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1559 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1560 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1561 <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1562 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1563 <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1564 <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>
1565 </para>
1566 </refsect1>
1567
1568 </refentry>