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