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