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