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