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