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