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