1 <?xml version='1.0'?> <!--*-nxml-*-->
2 <?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?>
3 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
4 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
7 This file is part of systemd.
9 Copyright 2010 Lennart Poettering
11 systemd is free software; you can redistribute it and/or modify it
12 under the terms of the GNU Lesser General Public License as published by
13 the Free Software Foundation; either version 2.1 of the License, or
14 (at your option) any later version.
16 systemd is distributed in the hope that it will be useful, but
17 WITHOUT ANY WARRANTY; without even the implied warranty of
18 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 Lesser General Public License for more details.
21 You should have received a copy of the GNU Lesser General Public License
22 along with systemd; If not, see <http://www.gnu.org/licenses/>.
25 <refentry id="systemd.service">
27 <title>systemd.service</title>
28 <productname>systemd</productname>
32 <contrib>Developer</contrib>
33 <firstname>Lennart</firstname>
34 <surname>Poettering</surname>
35 <email>lennart@poettering.net</email>
41 <refentrytitle>systemd.service</refentrytitle>
42 <manvolnum>5</manvolnum>
46 <refname>systemd.service</refname>
47 <refpurpose>Service unit configuration</refpurpose>
51 <para><filename><replaceable>service</replaceable>.service</filename></para>
55 <title>Description</title>
57 <para>A unit configuration file whose name ends in
58 <filename>.service</filename> encodes information
59 about a process controlled and supervised by
62 <para>This man page lists the configuration options
63 specific to this unit type. See
64 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
65 for the common options of all unit configuration
66 files. The common configuration items are configured
67 in the generic <literal>[Unit]</literal> and
68 <literal>[Install]</literal> sections. The service
69 specific configuration options are configured in the
70 <literal>[Service]</literal> section.</para>
72 <para>Additional options are listed in
73 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
74 which define the execution environment the commands
75 are executed in, and in
76 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
77 which define the way the processes of the service are
79 <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
80 which configure resource control settings for the
81 processes of the service.</para>
83 <para>Unless <varname>DefaultDependencies=</varname>
84 is set to <option>false</option>, service units will
85 implicitly have dependencies of type
86 <varname>Requires=</varname> and
87 <varname>After=</varname> on
88 <filename>basic.target</filename> as well as
89 dependencies of type <varname>Conflicts=</varname> and
90 <varname>Before=</varname> on
91 <filename>shutdown.target</filename>. These ensure
92 that normal service units pull in basic system
93 initialization, and are terminated cleanly prior to
94 system shutdown. Only services involved with early
95 boot or late system shutdown should disable this
98 <para>If a service is requested under a certain name
99 but no unit configuration file is found, systemd looks
100 for a SysV init script by the same name (with the
101 <filename>.service</filename> suffix removed) and
102 dynamically creates a service unit from that
103 script. This is useful for compatibility with
104 SysV. Note that this compatibility is quite
105 comprehensive but not 100%. For details about the
106 incompatibilities, see the <ulink
107 url="http://www.freedesktop.org/wiki/Software/systemd/Incompatibilities">Incompatibilities
108 with SysV</ulink> document.
113 <title>Options</title>
115 <para>Service files must include a
116 <literal>[Service]</literal> section, which carries
117 information about the service and the process it
118 supervises. A number of options that may be used in
119 this section are shared with other unit types. These
120 options are documented in
121 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
123 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
124 options specific to the <literal>[Service]</literal>
125 section of service units are the following:</para>
127 <variablelist class='unit-directives'>
129 <term><varname>Type=</varname></term>
131 <listitem><para>Configures the process
132 start-up type for this service
133 unit. One of <option>simple</option>,
134 <option>forking</option>,
135 <option>oneshot</option>,
136 <option>dbus</option>,
137 <option>notify</option> or
138 <option>idle</option>.</para>
141 <option>simple</option> (the default
143 <varname>Type=</varname> nor
144 <varname>BusName=</varname>, but
145 <varname>ExecStart=</varname> are
146 specified), it is expected that the
147 process configured with
148 <varname>ExecStart=</varname> is the
149 main process of the service. In this
150 mode, if the process offers
151 functionality to other processes on
152 the system, its communication channels
153 should be installed before the daemon
154 is started up (e.g. sockets set up by
155 systemd, via socket activation), as
156 systemd will immediately proceed
157 starting follow-up units.</para>
160 <option>forking</option>, it is
161 expected that the process configured
162 with <varname>ExecStart=</varname>
163 will call <function>fork()</function>
164 as part of its start-up. The parent process is
165 expected to exit when start-up is
166 complete and all communication
167 channels are set up. The child continues
168 to run as the main daemon
169 process. This is the behavior of
170 traditional UNIX daemons. If this
171 setting is used, it is recommended to
173 <varname>PIDFile=</varname> option, so
174 that systemd can identify the main
175 process of the daemon. systemd will
176 proceed with starting follow-up units
177 as soon as the parent process
181 <option>oneshot</option> is similar to
182 <option>simple</option>; however, it
183 is expected that the process has to
184 exit before systemd starts follow-up
185 units. <varname>RemainAfterExit=</varname>
186 is particularly useful for this type
187 of service. This is the implied
189 <varname>Type=</varname> or
190 <varname>ExecStart=</varname> are
194 <option>dbus</option> is similar to
195 <option>simple</option>; however, it is
196 expected that the daemon acquires a
197 name on the D-Bus bus, as configured
199 <varname>BusName=</varname>. systemd
200 will proceed with starting follow-up
201 units after the D-Bus bus name has been
202 acquired. Service units with this
203 option configured implicitly gain
205 <filename>dbus.socket</filename>
206 unit. This type is the default if
207 <varname>BusName=</varname> is
211 <option>notify</option> is similar to
212 <option>simple</option>; however, it is
213 expected that the daemon sends a
214 notification message via
215 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
216 or an equivalent call when it has finished
217 starting up. systemd will proceed with
218 starting follow-up units after this
219 notification message has been sent. If
221 <varname>NotifyAccess=</varname> (see
222 below) should be set to open access to
223 the notification socket provided by
225 <varname>NotifyAccess=</varname> is
226 not set, it will be implicitly set to
227 <option>main</option>. Note that
229 <varname>Type=</varname><option>notify</option>
230 will not work if used in combination with
231 <varname>PrivateNetwork=</varname><option>yes</option>.</para>
234 <option>idle</option> is very similar
235 to <option>simple</option>; however,
236 actual execution of the service
237 binary is delayed until all jobs are
238 dispatched. This may be used to avoid
239 interleaving of output of shell
240 services with the status output on the
246 <term><varname>RemainAfterExit=</varname></term>
248 <listitem><para>Takes a boolean value
249 that specifies whether the service
250 shall be considered active even when
251 all its processes exited. Defaults to
252 <option>no</option>.</para>
257 <term><varname>GuessMainPID=</varname></term>
259 <listitem><para>Takes a boolean value
260 that specifies whether systemd should
261 try to guess the main PID of a service
262 if it cannot be determined
263 reliably. This option is ignored
264 unless <option>Type=forking</option>
265 is set and <option>PIDFile=</option>
266 is unset because for the other types
267 or with an explicitly configured PID
268 file, the main PID is always known. The
269 guessing algorithm might come to
270 incorrect conclusions if a daemon
271 consists of more than one process. If
272 the main PID cannot be determined,
273 failure detection and automatic
274 restarting of a service will not work
275 reliably. Defaults to
276 <option>yes</option>.</para>
281 <term><varname>PIDFile=</varname></term>
283 <listitem><para>Takes an absolute file
284 name pointing to the PID file of this
285 daemon. Use of this option is
286 recommended for services where
287 <varname>Type=</varname> is set to
288 <option>forking</option>. systemd will
289 read the PID of the main process of
290 the daemon after start-up of the
291 service. systemd will not write to the
292 file configured here.</para>
297 <term><varname>BusName=</varname></term>
299 <listitem><para>Takes a D-Bus bus
300 name that this service is reachable
301 as. This option is mandatory for
303 <varname>Type=</varname> is set to
304 <option>dbus</option>, but its use
305 is otherwise recommended if the process
306 takes a name on the D-Bus bus.</para>
311 <term><varname>BusPolicy=</varname></term>
313 <listitem><para>If specified, a custom
314 <ulink url="https://code.google.com/p/d-bus/">kdbus</ulink>
315 endpoint will be created and installed as the
316 default bus node for the service. Such a custom
317 endpoint can hold an own set of policy rules
318 that are enforced on top of the bus-wide ones.
319 The custom endpoint is named after the service
320 it was created for, and its node will be
321 bind-mounted over the default bus node
322 location, so the service can only access the
323 bus through its own endpoint. Note that custom
324 bus endpoints default to a 'deny all' policy.
325 Hence, if at least one
326 <varname>BusPolicy=</varname> directive is
327 given, you have to make sure to add explicit
328 rules for everything the service should be able
330 <para>The value of this directive is comprised
331 of two parts; the bus name, and a verb to
332 specify to granted access, which is one of
333 <option>see</option>,
334 <option>talk</option>, or
335 <option>own</option>.
336 <option>talk</option> implies
337 <option>see</option>, and <option>own</option>
338 implies both <option>talk</option> and
339 <option>see</option>.
340 If multiple access levels are specified for the
341 same bus name, the most powerful one takes
344 <para>Examples:</para>
345 <programlisting>BusPolicy=org.freedesktop.systemd1 talk</programlisting>
346 <programlisting>BusPolicy=org.foo.bar see</programlisting>
347 <para>This option is only available on kdbus enabled systems.</para>
352 <term><varname>ExecStart=</varname></term>
353 <listitem><para>Commands with their
354 arguments that are executed when this
355 service is started. For each of the
356 specified commands, the first argument
357 must be an absolute and literal path
358 to an executable.</para>
360 <para>When <varname>Type</varname> is
361 not <option>oneshot</option>, only one
362 command may and must be given. When
363 <varname>Type=oneshot</varname> is
364 used, none or more than one command
365 may be specified. Multiple command
366 lines may be concatenated in a single
367 directive by separating them with
368 semicolons (these semicolons must be
370 words). Alternatively, this directive
371 may be specified more than once with
372 the same effect. Lone semicolons may
374 <literal>\;</literal>. If the empty
375 string is assigned to this option, the
376 list of commands to start is reset,
377 prior assignments of this option will
378 have no effect. If no
379 <varname>ExecStart=</varname> is
380 specified, then the service must have
381 <varname>RemainAfterExit=yes</varname>
384 <para>Each command line is split on
385 whitespace, with the first item being
386 the command to execute, and the
387 subsequent items being the arguments.
388 Double quotes ("...") and single
389 quotes ('...') may be used, in which
390 case everything until the next
391 matching quote becomes part of the
392 same argument. Quotes themselves are
393 removed after parsing. In addition, a
395 (<literal>\</literal>) may be used to
396 merge lines. This syntax is intended
397 to be very similar to shell syntax,
398 but only the meta-characters and
399 expansions described in the following
400 paragraphs are understood.
401 Specifically, redirection using
402 <literal><</literal>,
403 <literal><<</literal>,
404 <literal>></literal>, and
405 <literal>>></literal>, pipes
406 using <literal>|</literal>, and
407 running programs in the background
408 using <literal>&</literal>
409 and <emphasis>other elements of shell
410 syntax are not supported</emphasis>.
413 <para>If more than one command is
414 specified, the commands are invoked
415 sequentially in the order they appear
416 in the unit file. If one of the
417 commands fails (and is not prefixed
418 with <literal>-</literal>), other lines
419 are not executed, and the unit is
420 considered failed.</para>
423 <varname>Type=forking</varname> is
424 set, the process started via this
425 command line will be considered the
426 main process of the daemon.</para>
428 <para>The command line accepts
429 <literal>%</literal> specifiers as
431 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
432 Note that the first argument of the
433 command line (i.e. the program to
434 execute) may not include
437 <para>Basic environment variable
438 substitution is supported. Use
439 <literal>${FOO}</literal> as part of a
440 word, or as a word of its own, on the
441 command line, in which case it will be
442 replaced by the value of the
443 environment variable including all
444 whitespace it contains, resulting in a
446 <literal>$FOO</literal> as a separate
447 word on the command line, in which
448 case it will be replaced by the value
449 of the environment variable split at
450 whitespace, resulting in zero or more
451 arguments. To pass a literal dollar
452 sign, use <literal>$$</literal>.
453 Variables whose value is not known at
454 expansion time are treated as empty
455 strings. Note that the first argument
456 (i.e. the program to execute) may not
457 be a variable.</para>
459 <para>Variables to be used in this
460 fashion may be defined through
461 <varname>Environment=</varname> and
462 <varname>EnvironmentFile=</varname>.
463 In addition, variables listed in the
464 section "Environment variables in
465 spawned processes" in
466 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
467 which are considered "static
468 configuration", may be used (this includes
469 e.g. <varname>$USER</varname>, but not
470 <varname>$TERM</varname>).</para>
472 <para>Optionally, if the absolute file
473 name is prefixed with
474 <literal>@</literal>, the second token
476 <literal>argv[0]</literal> to the
477 executed process, followed by the
478 further arguments specified. If the
479 absolute filename is prefixed with
480 <literal>-</literal>, an exit code of
481 the command normally considered a
482 failure (i.e. non-zero exit status or
483 abnormal exit due to signal) is ignored
484 and considered success. If both
485 <literal>-</literal> and
486 <literal>@</literal> are used, they
487 can appear in either order.</para>
489 <para>Note that this setting does not
490 directly support shell command
491 lines. If shell command lines are to
492 be used, they need to be passed
493 explicitly to a shell implementation
494 of some kind. Example:</para>
495 <programlisting>ExecStart=/bin/sh -c 'dmesg | tac'</programlisting>
496 <para>Example:</para>
497 <programlisting>ExecStart=/bin/echo one ; /bin/echo "two two"</programlisting>
498 <para>This will execute
499 <command>/bin/echo</command> two
500 times, each time with one argument:
501 <literal>one</literal> and
502 <literal>two two</literal>,
503 respectively. Because two commands are
505 <varname>Type=oneshot</varname> must
508 <para>Example:</para>
509 <programlisting>ExecStart=/bin/echo / >/dev/null & \; \
510 /bin/ls</programlisting>
511 <para>This will execute
512 <command>/bin/echo</command> with five
513 arguments: <literal>/</literal>,
514 <literal>>/dev/null</literal>,
515 <literal>&</literal>,
516 <literal>;</literal>, and
517 <literal>/bin/ls</literal>.</para>
519 <para>Example:</para>
520 <programlisting>Environment="ONE=one" 'TWO=two two'
521 ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
522 <para>This will execute
523 <command>/bin/echo</command> with four
524 arguments: <literal>one</literal>,
525 <literal>two</literal>,
526 <literal>two</literal>, and
527 <literal>two two</literal>.</para>
532 <term><varname>ExecStartPre=</varname></term>
533 <term><varname>ExecStartPost=</varname></term>
534 <listitem><para>Additional commands
535 that are executed before or after
537 <varname>ExecStart=</varname>, respectively.
538 Syntax is the same as for
539 <varname>ExecStart=</varname>, except
540 that multiple command lines are allowed
541 and the commands are executed one
542 after the other, serially.</para>
544 <para>If any of those commands (not
545 prefixed with <literal>-</literal>)
546 fail, the rest are not executed and
547 the unit is considered failed.</para>
552 <term><varname>ExecReload=</varname></term>
553 <listitem><para>Commands to execute to
554 trigger a configuration reload in the
555 service. This argument takes multiple
556 command lines, following the same
557 scheme as described for
558 <varname>ExecStart=</varname>
559 above. Use of this setting is
560 optional. Specifier and environment
561 variable substitution is supported
562 here following the same scheme as for
563 <varname>ExecStart=</varname>.</para>
565 <para>One additional, special
566 environment variable is set: if known,
567 <varname>$MAINPID</varname> is set to
568 the main process of the daemon, and
569 may be used for command lines like the
572 <programlisting>/bin/kill -HUP $MAINPID</programlisting>
574 <para>Note however that reloading a
575 daemon by sending a signal (as with
576 the example line above) is usually not
577 a good choice, because this is an
578 asynchronous operation and hence not
579 suitable to order reloads of multiple
580 services against each other. It is
581 strongly recommended to set
582 <varname>ExecReload=</varname> to a
583 command that not only triggers a
584 configuration reload of the daemon,
585 but also synchronously waits for it to
591 <term><varname>ExecStop=</varname></term>
592 <listitem><para>Commands to execute to
593 stop the service started via
594 <varname>ExecStart=</varname>. This
595 argument takes multiple command lines,
596 following the same scheme as described
597 for <varname>ExecStart=</varname>
598 above. Use of this setting is
599 optional. After the commands configured
600 in this option are run, all processes
601 remaining for a service are
602 terminated according to the
603 <varname>KillMode=</varname> setting
605 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>). If
606 this option is not specified, the
607 process is terminated immediately when
608 service stop is requested. Specifier
609 and environment variable substitution
610 is supported (including
611 <varname>$MAINPID</varname>, see
612 above).</para></listitem>
616 <term><varname>ExecStopPost=</varname></term>
617 <listitem><para>Additional commands
618 that are executed after the service
619 was stopped. This includes cases where
620 the commands configured in
621 <varname>ExecStop=</varname> were used,
622 where the service does not have any
623 <varname>ExecStop=</varname> defined, or
624 where the service exited unexpectedly. This
625 argument takes multiple command lines,
626 following the same scheme as described
627 for <varname>ExecStart</varname>. Use
629 optional. Specifier and environment
630 variable substitution is
631 supported.</para></listitem>
635 <term><varname>RestartSec=</varname></term>
636 <listitem><para>Configures the time to
637 sleep before restarting a service (as
639 <varname>Restart=</varname>). Takes a
640 unit-less value in seconds, or a time
641 span value such as "5min
643 100ms.</para></listitem>
647 <term><varname>TimeoutStartSec=</varname></term>
648 <listitem><para>Configures the time to
649 wait for start-up. If a
650 daemon service does not signal
651 start-up completion within the
652 configured time, the service will be
653 considered failed and will be shut
655 Takes a unit-less value in seconds, or a
656 time span value such as "5min
657 20s". Pass <literal>0</literal> to
658 disable the timeout logic. Defaults to
659 <varname>DefaultTimeoutStartSec=</varname> from
660 the manager configuration file, except
661 when <varname>Type=oneshot</varname> is
662 used, in which case the timeout
663 is disabled by default
664 (see <citerefentry><refentrytitle>systemd-systemd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
669 <term><varname>TimeoutStopSec=</varname></term>
670 <listitem><para>Configures the time to
671 wait for stop. If a service is asked
672 to stop, but does not terminate in the
673 specified time, it will be terminated
674 forcibly via <constant>SIGTERM</constant>,
675 and after another timeout of equal duration
676 with <constant>SIGKILL</constant> (see
677 <varname>KillMode=</varname>
678 in <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
679 Takes a unit-less value in seconds, or a
680 time span value such as "5min
681 20s". Pass <literal>0</literal> to disable
682 the timeout logic. Defaults to
683 <varname>DefaultTimeoutStopSec=</varname> from the
684 manager configuration file
685 (see <citerefentry><refentrytitle>systemd-systemd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
690 <term><varname>TimeoutSec=</varname></term>
691 <listitem><para>A shorthand for configuring
692 both <varname>TimeoutStartSec=</varname>
693 and <varname>TimeoutStopSec=</varname>
694 to the specified value.
699 <term><varname>WatchdogSec=</varname></term>
700 <listitem><para>Configures the
701 watchdog timeout for a service. The
702 watchdog is activated when the start-up is
703 completed. The service must call
704 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
705 regularly with <literal>WATCHDOG=1</literal>
706 (i.e. the "keep-alive ping"). If the time
707 between two such calls is larger than
708 the configured time, then the service
709 is placed in a failed state. By
710 setting <varname>Restart=</varname> to
711 <option>on-failure</option> or
712 <option>always</option>, the service
713 will be automatically restarted. The
714 time configured here will be passed to
715 the executed service process in the
716 <varname>WATCHDOG_USEC=</varname>
717 environment variable. This allows
718 daemons to automatically enable the
719 keep-alive pinging logic if watchdog
720 support is enabled for the service. If
722 <varname>NotifyAccess=</varname> (see
723 below) should be set to open access to
724 the notification socket provided by
726 <varname>NotifyAccess=</varname> is
727 not set, it will be implicitly set to
728 <option>main</option>. Defaults to 0,
730 feature.</para></listitem>
734 <term><varname>Restart=</varname></term>
735 <listitem><para>Configures whether the
736 service shall be restarted when the
737 service process exits, is killed,
738 or a timeout is reached. The service
739 process may be the main service
740 process, but it may also be one of the
741 processes specified with
742 <varname>ExecStartPre=</varname>,
743 <varname>ExecStartPost=</varname>,
744 <varname>ExecStop=</varname>,
745 <varname>ExecStopPost=</varname>, or
746 <varname>ExecReload=</varname>.
747 When the death of the process is a
748 result of systemd operation (e.g. service
749 stop or restart), the service will not be
750 restarted. Timeouts include missing
751 the watchdog "keep-alive ping"
752 deadline and a service start, reload,
753 and stop operation timeouts.</para>
757 <option>on-success</option>,
758 <option>on-failure</option>,
759 <option>on-abnormal</option>,
760 <option>on-watchdog</option>,
761 <option>on-abort</option>, or
762 <option>always</option>. If set to
763 <option>no</option> (the default), the
764 service will not be restarted. If set
765 to <option>on-success</option>, it
766 will be restarted only when the
767 service process exits cleanly. In
768 this context, a clean exit means an
769 exit code of 0, or one of the signals
770 <constant>SIGHUP</constant>,
771 <constant>SIGINT</constant>,
772 <constant>SIGTERM</constant> or
773 <constant>SIGPIPE</constant>, and
774 additionally, exit statuses and
776 <varname>SuccessExitStatus=</varname>.
777 If set to <option>on-failure</option>,
778 the service will be restarted when the
779 process exits with a non-zero exit
780 code, is terminated by a signal
781 (including on core dump, but excluding
782 the aforementiond four signals), when
783 an operation (such as service reload)
784 times out, and when the configured
785 watchdog timeout is triggered. If set
786 to <option>on-abnormal</option>, the
787 service will be restarted when the
788 process is terminated by a signal
789 (including on core dump, excluding the
790 aforementioned four signals), when an
791 operation times out, or when the
792 watchdog timeout is triggered. If set
793 to <option>on-abort</option>, the
794 service will be restarted only if the
795 service process exits due to an
796 uncaught signal not specified as a
797 clean exit status. If set to
798 <option>on-watchdog</option>, the
799 service will be restarted only if the
800 watchdog timeout for the service
802 <option>always</option>, the service
803 will be restarted regardless of
804 whether it exited cleanly or not, got
805 terminated abnormally by a signal, or
806 hit a timeout.</para>
809 <title>Exit causes and the effect of the <varname>Restart=</varname> settings on them</title>
812 <colspec colname='path' />
813 <colspec colname='expl' />
816 <entry>Restart settings/Exit causes</entry>
817 <entry><option>no</option></entry>
818 <entry><option>always</option></entry>
819 <entry><option>on-success</option></entry>
820 <entry><option>on-failure</option></entry>
821 <entry><option>on-abnormal</option></entry>
822 <entry><option>on-abort</option></entry>
823 <entry><option>on-watchdog</option></entry>
828 <entry>Clean exit code or signal</entry>
838 <entry>Unclean exit code</entry>
848 <entry>Unclean signal</entry>
858 <entry>Timeout</entry>
868 <entry>Watchdog</entry>
881 <para>As exceptions to the setting
882 above the service will not be
883 restarted if the exit code or signal
885 <varname>RestartPreventExitStatus=</varname>
886 (see below). Also, the services will
887 always be restarted if the exit code
888 or signal is specified in
889 <varname>RestartForceExitStatus=</varname>
892 <para>Setting this to
893 <option>on-failure</option> is the
894 recommended choice for long-running
895 services, in order to increase
896 reliability by attempting automatic
897 recovery from errors. For services
898 that shall be able to terminate on
899 their own choice (and avoid
900 immediate restarting),
901 <option>on-abnormal</option> is an
902 alternative choice.</para>
907 <term><varname>SuccessExitStatus=</varname></term>
908 <listitem><para>Takes a list of exit
909 status definitions that when returned
910 by the main service process will be
911 considered successful termination, in
912 addition to the normal successful exit
913 code 0 and the signals <constant>SIGHUP</constant>, <constant>SIGINT</constant>,
914 <constant>SIGTERM</constant>, and <constant>SIGPIPE</constant>. Exit status
915 definitions can either be numeric exit
916 codes or termination signal names,
917 separated by spaces. For example:
918 <programlisting>SuccessExitStatus=1 2 8 SIGKILL</programlisting>
919 ensures that exit codes 1, 2, 8 and
920 the termination signal
921 <constant>SIGKILL</constant> are
922 considered clean service terminations.
925 <para>Note that if a process has a
926 signal handler installed and exits by
928 <citerefentry><refentrytitle>_exit</refentrytitle><manvolnum>2</manvolnum></citerefentry>
929 in response to a signal, the
930 information about the signal is lost.
931 Programs should instead perform cleanup and kill themselves with the same signal instead. See
932 <ulink url="http://www.cons.org/cracauer/sigint.html">Proper handling of SIGINT/SIGQUIT — How to be a proper program</ulink>.</para>
934 <para>This option may appear more than once,
935 in which case the list of successful
936 exit statuses is merged. If the empty
937 string is assigned to this option, the
938 list is reset, all prior assignments
939 of this option will have no
940 effect.</para></listitem>
944 <term><varname>RestartPreventExitStatus=</varname></term>
945 <listitem><para>Takes a list of exit
946 status definitions that when returned
947 by the main service process will
948 prevent automatic service restarts,
949 regardless of the restart setting
951 <varname>Restart=</varname>. Exit
952 status definitions can either be
953 numeric exit codes or termination
954 signal names, and are separated by
955 spaces. Defaults to the empty list, so
956 that, by default, no exit status is
957 excluded from the configured restart
959 <programlisting>RestartPreventExitStatus=1 6 SIGABRT</programlisting> ensures that exit
960 codes 1 and 6 and the termination
961 signal <constant>SIGABRT</constant> will
962 not result in automatic service
964 option may appear more than once, in
965 which case the list of restart-preventing
966 statuses is merged. If the empty
967 string is assigned to this option, the
968 list is reset and all prior assignments
969 of this option will have no
970 effect.</para></listitem>
974 <term><varname>RestartForceExitStatus=</varname></term>
975 <listitem><para>Takes a list of exit
976 status definitions that when returned
977 by the main service process will force
978 automatic service restarts, regardless
979 of the restart setting configured with
980 <varname>Restart=</varname>. The
981 argument format is similar to
982 <varname>RestartPreventExitStatus=</varname>.</para></listitem>
986 <term><varname>PermissionsStartOnly=</varname></term>
987 <listitem><para>Takes a boolean
988 argument. If true, the permission-related
989 execution options, as
991 <varname>User=</varname> and similar
993 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
994 for more information), are only applied
995 to the process started with
996 <varname>ExecStart=</varname>, and not
998 <varname>ExecStartPre=</varname>,
999 <varname>ExecStartPost=</varname>,
1000 <varname>ExecReload=</varname>,
1001 <varname>ExecStop=</varname>, and
1002 <varname>ExecStopPost=</varname>
1003 commands. If false, the setting is
1004 applied to all configured commands the
1005 same way. Defaults to
1006 false.</para></listitem>
1010 <term><varname>RootDirectoryStartOnly=</varname></term>
1011 <listitem><para>Takes a boolean
1012 argument. If true, the root directory,
1013 as configured with the
1014 <varname>RootDirectory=</varname>
1016 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
1017 for more information), is only applied
1018 to the process started with
1019 <varname>ExecStart=</varname>, and not
1020 to the various other
1021 <varname>ExecStartPre=</varname>,
1022 <varname>ExecStartPost=</varname>,
1023 <varname>ExecReload=</varname>,
1024 <varname>ExecStop=</varname>, and
1025 <varname>ExecStopPost=</varname>
1026 commands. If false, the setting is
1027 applied to all configured commands the
1028 same way. Defaults to
1029 false.</para></listitem>
1033 <term><varname>NonBlocking=</varname></term>
1034 <listitem><para>Set the
1035 <constant>O_NONBLOCK</constant> flag
1036 for all file descriptors passed via
1037 socket-based activation. If true, all
1038 file descriptors >= 3 (i.e. all except
1039 stdin, stdout, and stderr) will have
1040 the <constant>O_NONBLOCK</constant> flag
1041 set and hence are in
1042 non-blocking mode. This option is only
1043 useful in conjunction with a socket
1044 unit, as described in
1045 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Defaults
1046 to false.</para></listitem>
1050 <term><varname>NotifyAccess=</varname></term>
1051 <listitem><para>Controls access to the
1052 service status notification socket, as
1054 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
1056 <option>none</option> (the default),
1057 <option>main</option> or
1058 <option>all</option>. If
1059 <option>none</option>, no daemon status
1060 updates are accepted from the service
1061 processes, all status update messages
1062 are ignored. If <option>main</option>,
1063 only service updates sent from the
1064 main process of the service are
1065 accepted. If <option>all</option>, all
1066 services updates from all members of
1067 the service's control group are
1068 accepted. This option should be set to
1069 open access to the notification socket
1071 <varname>Type=notify</varname> or
1072 <varname>WatchdogSec=</varname> (see
1073 above). If those options are used but
1074 <varname>NotifyAccess=</varname> is not
1075 configured, it will be implicitly set
1077 <option>main</option>.</para></listitem>
1081 <term><varname>Sockets=</varname></term>
1082 <listitem><para>Specifies the name of
1083 the socket units this service shall
1084 inherit the sockets from when the
1085 service is started. Normally it
1086 should not be necessary to use this
1087 setting as all sockets whose unit
1088 shares the same name as the service
1089 (ignoring the different suffix of course)
1090 are passed to the spawned
1093 <para>Note that the same socket may be
1094 passed to multiple processes at the
1095 same time. Also note that a different
1096 service may be activated on incoming
1097 traffic than that which inherits the
1098 sockets. Or in other words: the
1099 <varname>Service=</varname> setting of
1100 <filename>.socket</filename> units
1101 does not have to match the inverse of
1102 the <varname>Sockets=</varname>
1104 <filename>.service</filename> it
1107 <para>This option may appear more than
1108 once, in which case the list of socket
1109 units is merged. If the empty string
1110 is assigned to this option, the list of
1111 sockets is reset, and all prior uses of
1112 this setting will have no
1113 effect.</para></listitem>
1117 <term><varname>StartLimitInterval=</varname></term>
1118 <term><varname>StartLimitBurst=</varname></term>
1120 <listitem><para>Configure service
1121 start rate limiting. By default,
1122 services which are started more
1123 than 5 times within 10 seconds are not
1124 permitted to start any more times
1125 until the 10 second interval ends. With
1126 these two options, this rate limiting
1127 may be modified. Use
1128 <varname>StartLimitInterval=</varname>
1129 to configure the checking interval (defaults to
1130 <varname>DefaultStartLimitInterval=</varname> in
1131 manager configuration file, set to 0 to disable
1132 any kind of rate limiting). Use
1133 <varname>StartLimitBurst=</varname> to
1134 configure how many starts per interval
1135 are allowed (defaults to
1136 <varname>DefaultStartLimitBurst=</varname> in
1137 manager configuration file). These
1138 configuration options are particularly
1139 useful in conjunction with
1140 <varname>Restart=</varname>; however,
1141 they apply to all kinds of starts
1142 (including manual), not just those
1144 <varname>Restart=</varname> logic.
1145 Note that units which are configured
1146 for <varname>Restart=</varname> and
1147 which reach the start limit are not
1148 attempted to be restarted anymore;
1149 however, they may still be restarted
1150 manually at a later point, from which
1151 point on, the restart logic is again
1152 activated. Note that
1154 reset-failed</command> will cause the
1155 restart rate counter for a service to
1156 be flushed, which is useful if the
1157 administrator wants to manually start
1158 a service and the start limit
1160 that.</para></listitem>
1164 <term><varname>StartLimitAction=</varname></term>
1166 <listitem><para>Configure the action
1167 to take if the rate limit configured
1169 <varname>StartLimitInterval=</varname>
1171 <varname>StartLimitBurst=</varname> is
1173 <option>none</option>,
1174 <option>reboot</option>,
1175 <option>reboot-force</option>,
1176 <option>reboot-immediate</option>,
1177 <option>poweroff</option>,
1178 <option>poweroff-force</option> or
1179 <option>poweroff-immediate</option>. If
1180 <option>none</option> is set, hitting
1181 the rate limit will trigger no action
1182 besides that the start will not be
1183 permitted. <option>reboot</option>
1184 causes a reboot following the normal
1185 shutdown procedure (i.e. equivalent to
1186 <command>systemctl reboot</command>).
1187 <option>reboot-force</option> causes a
1188 forced reboot which will terminate all
1189 processes forcibly but should cause no
1190 dirty file systems on reboot
1191 (i.e. equivalent to <command>systemctl
1192 reboot -f</command>) and
1193 <option>reboot-immediate</option>
1194 causes immediate execution of the
1195 <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
1196 system call, which might result in
1198 <option>poweroff</option>,
1199 <option>poweroff-force</option>,
1200 <option>poweroff-immediate</option>
1201 have the effect of powering down the
1203 semantics. Defaults to
1204 <option>none</option>.</para></listitem>
1208 <term><varname>FailureAction=</varname></term>
1209 <listitem><para>Configure the action
1210 to take when the service enters a failed
1211 state. Takes the same values as
1212 <varname>StartLimitAction=</varname>
1213 and executes the same actions.
1214 Defaults to <option>none</option>.
1219 <term><varname>RebootArgument=</varname></term>
1220 <listitem><para>Configure the optional
1222 <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
1224 <varname>StartLimitAction=</varname>
1225 or <varname>FailureAction=</varname>
1226 is a reboot action. This works just
1227 like the optional argument to
1228 <command>systemctl reboot</command>
1229 command.</para></listitem>
1235 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
1237 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
1238 for more settings.</para>
1243 <title>Compatibility Options</title>
1245 <para>The following options are also available in the
1246 <literal>[Service]</literal> section, but exist purely
1247 for compatibility reasons and should not be used in
1248 newly written service files.</para>
1250 <variablelist class='unit-directives'>
1252 <term><varname>SysVStartPriority=</varname></term>
1253 <listitem><para>Set the SysV start
1254 priority to use to order this service
1255 in relation to SysV services lacking
1256 LSB headers. This option is only
1257 necessary to fix ordering in relation
1258 to legacy SysV services that have no
1259 ordering information encoded in the
1260 script headers. As such, it should only
1261 be used as a temporary compatibility
1262 option and should not be used in new unit
1263 files. Almost always, it is a better
1264 choice to add explicit ordering
1266 <varname>After=</varname> or
1267 <varname>Before=</varname>,
1268 instead. For more details, see
1269 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
1270 If used, pass an integer value in the
1271 range 0-99.</para></listitem>
1277 <title>See Also</title>
1279 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1280 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1281 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1282 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1283 <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1284 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1285 <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>