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