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