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> are
145 specified), it is expected that the
146 process configured with
147 <varname>ExecStart=</varname> is the
148 main process of the service. In this
149 mode, if the process offers
150 functionality to other processes on
151 the system, its communication channels
152 should be installed before the daemon
153 is started up (e.g. sockets set up by
154 systemd, via socket activation), as
155 systemd will immediately proceed
156 starting follow-up units.</para>
159 <option>forking</option>, it is
160 expected that the process configured
161 with <varname>ExecStart=</varname>
162 will call <function>fork()</function>
163 as part of its start-up. The parent process is
164 expected to exit when start-up is
165 complete and all communication
166 channels are set up. The child continues
167 to run as the main daemon
168 process. This is the behavior of
169 traditional UNIX daemons. If this
170 setting is used, it is recommended to
172 <varname>PIDFile=</varname> option, so
173 that systemd can identify the main
174 process of the daemon. systemd will
175 proceed with starting follow-up units
176 as soon as the parent process
180 <option>oneshot</option> is similar
181 to <option>simple</option>; however,
182 it is expected that the process has to
183 exit before systemd starts follow-up
184 units. <varname>RemainAfterExit=</varname>
185 is particularly useful for this type
189 <option>dbus</option> is similar to
190 <option>simple</option>; however, it is
191 expected that the daemon acquires a
192 name on the D-Bus bus, as configured
194 <varname>BusName=</varname>. systemd
195 will proceed with starting follow-up
196 units after the D-Bus bus name has been
197 acquired. Service units with this
198 option configured implicitly gain
200 <filename>dbus.socket</filename>
201 unit. This type is the default if
202 <varname>BusName=</varname> is
206 <option>notify</option> is similar to
207 <option>simple</option>; however, it is
208 expected that the daemon sends a
209 notification message via
210 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
211 or an equivalent call when it has finished
212 starting up. systemd will proceed with
213 starting follow-up units after this
214 notification message has been sent. If
216 <varname>NotifyAccess=</varname> (see
217 below) should be set to open access to
218 the notification socket provided by
220 <varname>NotifyAccess=</varname> is
221 not set, it will be implicitly set to
222 <option>main</option>. Note that
224 <varname>Type=</varname><option>notify</option>
225 will not work if used in combination with
226 <varname>PrivateNetwork=</varname><option>yes</option>.</para>
229 <option>idle</option> is very similar
230 to <option>simple</option>; however,
231 actual execution of the service
232 binary is delayed until all jobs are
233 dispatched. This may be used to avoid
234 interleaving of output of shell
235 services with the status output on the
241 <term><varname>RemainAfterExit=</varname></term>
243 <listitem><para>Takes a boolean value
244 that specifies whether the service
245 shall be considered active even when
246 all its processes exited. Defaults to
247 <option>no</option>.</para>
252 <term><varname>GuessMainPID=</varname></term>
254 <listitem><para>Takes a boolean value
255 that specifies whether systemd should
256 try to guess the main PID of a service
257 if it cannot be determined
258 reliably. This option is ignored
259 unless <option>Type=forking</option>
260 is set and <option>PIDFile=</option>
261 is unset because for the other types
262 or with an explicitly configured PID
263 file, the main PID is always known. The
264 guessing algorithm might come to
265 incorrect conclusions if a daemon
266 consists of more than one process. If
267 the main PID cannot be determined,
268 failure detection and automatic
269 restarting of a service will not work
270 reliably. Defaults to
271 <option>yes</option>.</para>
276 <term><varname>PIDFile=</varname></term>
278 <listitem><para>Takes an absolute file
279 name pointing to the PID file of this
280 daemon. Use of this option is
281 recommended for services where
282 <varname>Type=</varname> is set to
283 <option>forking</option>. systemd will
284 read the PID of the main process of
285 the daemon after start-up of the
286 service. systemd will not write to the
287 file configured here.</para>
292 <term><varname>BusName=</varname></term>
294 <listitem><para>Takes a D-Bus bus
295 name that this service is reachable
296 as. This option is mandatory for
298 <varname>Type=</varname> is set to
299 <option>dbus</option>, but its use
300 is otherwise recommended if the process
301 takes a name on the D-Bus bus.</para>
306 <term><varname>ExecStart=</varname></term>
307 <listitem><para>Commands with their
308 arguments that are executed when this
309 service is started. For each of the
310 specified commands, the first argument
311 must be an absolute and literal path
312 to an executable.</para>
314 <para>When <varname>Type</varname> is
315 not <option>oneshot</option>, only one
316 command may be given. When
317 <varname>Type=oneshot</varname> is
318 used, more than one command may be
319 specified. Multiple command lines may
320 be concatenated in a single directive
321 by separating them with semicolons
322 (these semicolons must be passed as
323 separate words). Alternatively, this
324 directive may be specified more than
325 once with the same effect.
326 Lone semicolons may be escaped as
327 <literal>\;</literal>. If the empty
328 string is assigned to this option, the
329 list of commands to start is reset,
330 prior assignments of this option will
331 have no effect.</para>
333 <para>Each command line is split on
334 whitespace, with the first item being
335 the command to execute, and the
336 subsequent items being the arguments.
337 Double quotes ("...") and single
338 quotes ('...') may be used, in which
339 case everything until the next
340 matching quote becomes part of the
341 same argument. Quotes themselves are
342 removed after parsing. In addition, a
344 (<literal>\</literal>) may be used to
345 merge lines. This syntax is intended
346 to be very similar to shell syntax,
347 but only the meta-characters and
348 expansions described in the following
349 paragraphs are understood.
350 Specifically, redirection using
351 <literal><</literal>,
352 <literal><<</literal>,
353 <literal>></literal>, and
354 <literal>>></literal>, pipes
355 using <literal>|</literal>, and
356 running programs in the background
357 using <literal>&</literal>
358 and <emphasis>other elements of shell
359 syntax are not supported</emphasis>.
362 <para>If more than one command is
363 specified, the commands are invoked
364 sequentially in the order they appear
365 in the unit file. If one of the
366 commands fails (and is not prefixed
367 with <literal>-</literal>), other lines
368 are not executed, and the unit is
369 considered failed.</para>
372 <varname>Type=forking</varname> is
373 set, the process started via this
374 command line will be considered the
375 main process of the daemon.</para>
377 <para>The command line accepts
378 <literal>%</literal> specifiers as
380 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
381 Note that the first argument of the
382 command line (i.e. the program to
383 execute) may not include
386 <para>Basic environment variable
387 substitution is supported. Use
388 <literal>${FOO}</literal> as part of a
389 word, or as a word of its own, on the
390 command line, in which case it will be
391 replaced by the value of the
392 environment variable including all
393 whitespace it contains, resulting in a
395 <literal>$FOO</literal> as a separate
396 word on the command line, in which
397 case it will be replaced by the value
398 of the environment variable split at
399 whitespace, resulting in zero or more
400 arguments. To pass a literal dollar
401 sign, use <literal>$$</literal>.
402 Variables whose value is not known at
403 expansion time are treated as empty
404 strings. Note that the first argument
405 (i.e. the program to execute) may not
406 be a variable.</para>
408 <para>Variables to be used in this
409 fashion may be defined through
410 <varname>Environment=</varname> and
411 <varname>EnvironmentFile=</varname>.
412 In addition, variables listed in the
413 section "Environment variables in
414 spawned processes" in
415 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
416 which are considered "static
417 configuration", may be used (this includes
418 e.g. <varname>$USER</varname>, but not
419 <varname>$TERM</varname>).</para>
421 <para>Optionally, if the absolute file
422 name is prefixed with
423 <literal>@</literal>, the second token
425 <literal>argv[0]</literal> to the
426 executed process, followed by the
427 further arguments specified. If the
428 absolute filename is prefixed with
429 <literal>-</literal>, an exit code of
430 the command normally considered a
431 failure (i.e. non-zero exit status or
432 abnormal exit due to signal) is ignored
433 and considered success. If both
434 <literal>-</literal> and
435 <literal>@</literal> are used, they
436 can appear in either order.</para>
438 <para>Note that this setting does not
439 directly support shell command
440 lines. If shell command lines are to
441 be used, they need to be passed
442 explicitly to a shell implementation
443 of some kind. Example:</para>
444 <programlisting>ExecStart=/bin/sh -c 'dmesg | tac'</programlisting>
445 <para>Example:</para>
446 <programlisting>ExecStart=/bin/echo one ; /bin/echo "two two"</programlisting>
447 <para>This will execute
448 <command>/bin/echo</command> two
449 times, each time with one argument:
450 <literal>one</literal> and
451 <literal>two two</literal>,
452 respectively. Because two commands are
454 <varname>Type=oneshot</varname> must
457 <para>Example:</para>
458 <programlisting>ExecStart=/bin/echo / >/dev/null & \; \
459 /bin/ls</programlisting>
460 <para>This will execute
461 <command>/bin/echo</command> with five
462 arguments: <literal>/</literal>,
463 <literal>>/dev/null</literal>,
464 <literal>&</literal>,
465 <literal>;</literal>, and
466 <literal>/bin/ls</literal>.</para>
468 <para>Example:</para>
469 <programlisting>Environment="ONE=one" 'TWO=two two'
470 ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
471 <para>This will execute
472 <command>/bin/echo</command> with four
473 arguments: <literal>one</literal>,
474 <literal>two</literal>,
475 <literal>two</literal>, and
476 <literal>two two</literal>.</para>
481 <term><varname>ExecStartPre=</varname></term>
482 <term><varname>ExecStartPost=</varname></term>
483 <listitem><para>Additional commands
484 that are executed before or after
486 <varname>ExecStart=</varname>, respectively.
487 Syntax is the same as for
488 <varname>ExecStart=</varname>, except
489 that multiple command lines are allowed
490 and the commands are executed one
491 after the other, serially.</para>
493 <para>If any of those commands (not
494 prefixed with <literal>-</literal>)
495 fail, the rest are not executed and
496 the unit is considered failed.</para>
501 <term><varname>ExecReload=</varname></term>
502 <listitem><para>Commands to execute to
503 trigger a configuration reload in the
504 service. This argument takes multiple
505 command lines, following the same
506 scheme as described for
507 <varname>ExecStart=</varname>
508 above. Use of this setting is
509 optional. Specifier and environment
510 variable substitution is supported
511 here following the same scheme as for
512 <varname>ExecStart=</varname>.</para>
514 <para>One additional, special
515 environment variable is set: if known,
516 <varname>$MAINPID</varname> is set to
517 the main process of the daemon, and
518 may be used for command lines like the
521 <programlisting>/bin/kill -HUP $MAINPID</programlisting>
523 <para>Note however that reloading a
524 daemon by sending a signal (as with
525 the example line above) is usually not
526 a good choice, because this is an
527 asynchronous operation and hence not
528 suitable to order reloads of multiple
529 services against each other. It is
530 strongly recommended to set
531 <varname>ExecReload=</varname> to a
532 command that not only triggers a
533 configuration reload of the daemon,
534 but also synchronously waits for it to
540 <term><varname>ExecStop=</varname></term>
541 <listitem><para>Commands to execute to
542 stop the service started via
543 <varname>ExecStart=</varname>. This
544 argument takes multiple command lines,
545 following the same scheme as described
546 for <varname>ExecStart=</varname>
547 above. Use of this setting is
548 optional. After the commands configured
549 in this option are run, all processes
550 remaining for a service are
551 terminated according to the
552 <varname>KillMode=</varname> setting
554 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>). If
555 this option is not specified, the
556 process is terminated immediately when
557 service stop is requested. Specifier
558 and environment variable substitution
559 is supported (including
560 <varname>$MAINPID</varname>, see
561 above).</para></listitem>
565 <term><varname>ExecStopPost=</varname></term>
566 <listitem><para>Additional commands
567 that are executed after the service
568 was stopped. This includes cases where
569 the commands configured in
570 <varname>ExecStop=</varname> were used,
571 where the service does not have any
572 <varname>ExecStop=</varname> defined, or
573 where the service exited unexpectedly. This
574 argument takes multiple command lines,
575 following the same scheme as described
576 for <varname>ExecStart</varname>. Use
578 optional. Specifier and environment
579 variable substitution is
580 supported.</para></listitem>
584 <term><varname>RestartSec=</varname></term>
585 <listitem><para>Configures the time to
586 sleep before restarting a service (as
588 <varname>Restart=</varname>). Takes a
589 unit-less value in seconds, or a time
590 span value such as "5min
592 100ms.</para></listitem>
596 <term><varname>TimeoutStartSec=</varname></term>
597 <listitem><para>Configures the time to
598 wait for start-up. If a
599 daemon service does not signal
600 start-up completion within the
601 configured time, the service will be
602 considered failed and will be shut
604 Takes a unit-less value in seconds, or a
605 time span value such as "5min
606 20s". Pass <literal>0</literal> to
607 disable the timeout logic. Defaults to
608 <varname>DefaultTimeoutStartSec=</varname> from
609 the manager configuration file, except
610 when <varname>Type=oneshot</varname> is
611 used, in which case the timeout
612 is disabled by default
613 (see <citerefentry><refentrytitle>systemd-systemd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
618 <term><varname>TimeoutStopSec=</varname></term>
619 <listitem><para>Configures the time to
620 wait for stop. If a service is asked
621 to stop, but does not terminate in the
622 specified time, it will be terminated
623 forcibly via <constant>SIGTERM</constant>,
624 and after another timeout of equal duration
625 with <constant>SIGKILL</constant> (see
626 <varname>KillMode=</varname>
627 in <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
628 Takes a unit-less value in seconds, or a
629 time span value such as "5min
630 20s". Pass <literal>0</literal> to disable
631 the timeout logic. Defaults to
632 <varname>DefaultTimeoutStopSec=</varname> from the
633 manager configuration file
634 (see <citerefentry><refentrytitle>systemd-systemd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
639 <term><varname>TimeoutSec=</varname></term>
640 <listitem><para>A shorthand for configuring
641 both <varname>TimeoutStartSec=</varname>
642 and <varname>TimeoutStopSec=</varname>
643 to the specified value.
648 <term><varname>WatchdogSec=</varname></term>
649 <listitem><para>Configures the
650 watchdog timeout for a service. The
651 watchdog is activated when the start-up is
652 completed. The service must call
653 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
654 regularly with <literal>WATCHDOG=1</literal>
655 (i.e. the "keep-alive ping"). If the time
656 between two such calls is larger than
657 the configured time, then the service
658 is placed in a failed state. By
659 setting <varname>Restart=</varname> to
660 <option>on-failure</option> or
661 <option>always</option>, the service
662 will be automatically restarted. The
663 time configured here will be passed to
664 the executed service process in the
665 <varname>WATCHDOG_USEC=</varname>
666 environment variable. This allows
667 daemons to automatically enable the
668 keep-alive pinging logic if watchdog
669 support is enabled for the service. If
671 <varname>NotifyAccess=</varname> (see
672 below) should be set to open access to
673 the notification socket provided by
675 <varname>NotifyAccess=</varname> is
676 not set, it will be implicitly set to
677 <option>main</option>. Defaults to 0,
679 feature.</para></listitem>
683 <term><varname>Restart=</varname></term>
684 <listitem><para>Configures whether the
685 service shall be restarted when the
686 service process exits, is killed,
687 or a timeout is reached. The service
688 process may be the main service
689 process, but it may also be one of the
690 processes specified with
691 <varname>ExecStartPre=</varname>,
692 <varname>ExecStartPost=</varname>,
693 <varname>ExecStop=</varname>,
694 <varname>ExecStopPost=</varname>, or
695 <varname>ExecReload=</varname>.
696 When the death of the process is a
697 result of systemd operation (e.g. service
698 stop or restart), the service will not be
699 restarted. Timeouts include missing
700 the watchdog "keep-alive ping"
701 deadline and a service start, reload,
702 and stop operation timeouts.</para>
706 <option>on-success</option>,
707 <option>on-failure</option>,
708 <option>on-abnormal</option>,
709 <option>on-watchdog</option>,
710 <option>on-abort</option>, or
711 <option>always</option>. If set to
712 <option>no</option> (the default), the
713 service will not be restarted. If set
714 to <option>on-success</option>, it
715 will be restarted only when the
716 service process exits cleanly. In
717 this context, a clean exit means an
718 exit code of 0, or one of the signals
719 <constant>SIGHUP</constant>,
720 <constant>SIGINT</constant>,
721 <constant>SIGTERM</constant> or
722 <constant>SIGPIPE</constant>, and
723 additionally, exit statuses and
725 <varname>SuccessExitStatus=</varname>.
726 If set to <option>on-failure</option>,
727 the service will be restarted when the
728 process exits with a non-zero exit
729 code, is terminated by a signal
730 (including on core dump, but excluding
731 the aforementiond four signals), when
732 an operation (such as service reload)
733 times out, and when the configured
734 watchdog timeout is triggered. If set
735 to <option>on-abnormal</option>, the
736 service will be restarted when the
737 process is terminated by a signal
738 (including on core dump, excluding the
739 aforementioned four signals), when an
740 operation times out, or when the
741 watchdog timeout is triggered. If set
742 to <option>on-abort</option>, the
743 service will be restarted only if the
744 service process exits due to an
745 uncaught signal not specified as a
746 clean exit status. If set to
747 <option>on-watchdog</option>, the
748 service will be restarted only if the
749 watchdog timeout for the service
751 <option>always</option>, the service
752 will be restarted regardless of
753 whether it exited cleanly or not, got
754 terminated abnormally by a signal, or
755 hit a timeout.</para>
758 <title>Exit causes and the effect of the <varname>Restart=</varname> settings on them</title>
761 <colspec colname='path' />
762 <colspec colname='expl' />
765 <entry>Restart settings/Exit causes</entry>
766 <entry><option>no</option></entry>
767 <entry><option>always</option></entry>
768 <entry><option>on-success</option></entry>
769 <entry><option>on-failure</option></entry>
770 <entry><option>on-abnormal</option></entry>
771 <entry><option>on-abort</option></entry>
772 <entry><option>on-watchdog</option></entry>
777 <entry>Clean exit code or signal</entry>
787 <entry>Unclean exit code</entry>
797 <entry>Unclean signal</entry>
807 <entry>Timeout</entry>
817 <entry>Watchdog</entry>
830 <para>As exceptions to the setting
831 above the service will not be
832 restarted if the exit code or signal
834 <varname>RestartPreventExitStatus=</varname>
835 (see below). Also, the services will
836 always be restarted if the exit code
837 or signal is specified in
838 <varname>RestartForceExitStatus=</varname>
841 <para>Setting this to
842 <option>on-failure</option> is the
843 recommended choice for long-running
844 services, in order to increase
845 reliability by attempting automatic
846 recovery from errors. For services
847 that shall be able to terminate on
848 their own choice (and avoid
849 immediate restarting),
850 <option>on-abnormal</option> is an
851 alternative choice.</para>
856 <term><varname>SuccessExitStatus=</varname></term>
857 <listitem><para>Takes a list of exit
858 status definitions that when returned
859 by the main service process will be
860 considered successful termination, in
861 addition to the normal successful exit
862 code 0 and the signals <constant>SIGHUP</constant>, <constant>SIGINT</constant>,
863 <constant>SIGTERM</constant>, and <constant>SIGPIPE</constant>. Exit status
864 definitions can either be numeric exit
865 codes or termination signal names,
866 separated by spaces. For example:
867 <programlisting>SuccessExitStatus=1 2 8 SIGKILL</programlisting>
868 ensures that exit codes 1, 2, 8 and
869 the termination signal
870 <constant>SIGKILL</constant> are
871 considered clean service terminations.
874 <para>Note that if a process has a
875 signal handler installed and exits by
877 <citerefentry><refentrytitle>_exit</refentrytitle><manvolnum>2</manvolnum></citerefentry>
878 in response to a signal, the
879 information about the signal is lost.
880 Programs should instead perform cleanup and kill themselves with the same signal instead. See
881 <ulink url="http://www.cons.org/cracauer/sigint.html">Proper handling of SIGINT/SIGQUIT — How to be a proper program</ulink>.</para>
883 <para>This option may appear more than once,
884 in which case the list of successful
885 exit statuses is merged. If the empty
886 string is assigned to this option, the
887 list is reset, all prior assignments
888 of this option will have no
889 effect.</para></listitem>
893 <term><varname>RestartPreventExitStatus=</varname></term>
894 <listitem><para>Takes a list of exit
895 status definitions that when returned
896 by the main service process will
897 prevent automatic service restarts,
898 regardless of the restart setting
900 <varname>Restart=</varname>. Exit
901 status definitions can either be
902 numeric exit codes or termination
903 signal names, and are separated by
904 spaces. Defaults to the empty list, so
905 that, by default, no exit status is
906 excluded from the configured restart
908 <programlisting>RestartPreventExitStatus=1 6 SIGABRT</programlisting> ensures that exit
909 codes 1 and 6 and the termination
910 signal <constant>SIGABRT</constant> will
911 not result in automatic service
913 option may appear more than once, in
914 which case the list of restart-preventing
915 statuses is merged. If the empty
916 string is assigned to this option, the
917 list is reset and all prior assignments
918 of this option will have no
919 effect.</para></listitem>
923 <term><varname>RestartForceExitStatus=</varname></term>
924 <listitem><para>Takes a list of exit
925 status definitions that when returned
926 by the main service process will force
927 automatic service restarts, regardless
928 of the restart setting configured with
929 <varname>Restart=</varname>. The
930 argument format is similar to
931 <varname>RestartPreventExitStatus=</varname>.</para></listitem>
935 <term><varname>PermissionsStartOnly=</varname></term>
936 <listitem><para>Takes a boolean
937 argument. If true, the permission-related
938 execution options, as
940 <varname>User=</varname> and similar
942 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
943 for more information), are only applied
944 to the process started with
945 <varname>ExecStart=</varname>, and not
947 <varname>ExecStartPre=</varname>,
948 <varname>ExecStartPost=</varname>,
949 <varname>ExecReload=</varname>,
950 <varname>ExecStop=</varname>, and
951 <varname>ExecStopPost=</varname>
952 commands. If false, the setting is
953 applied to all configured commands the
954 same way. Defaults to
955 false.</para></listitem>
959 <term><varname>RootDirectoryStartOnly=</varname></term>
960 <listitem><para>Takes a boolean
961 argument. If true, the root directory,
962 as configured with the
963 <varname>RootDirectory=</varname>
965 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
966 for more information), is only applied
967 to the process started with
968 <varname>ExecStart=</varname>, and not
970 <varname>ExecStartPre=</varname>,
971 <varname>ExecStartPost=</varname>,
972 <varname>ExecReload=</varname>,
973 <varname>ExecStop=</varname>, and
974 <varname>ExecStopPost=</varname>
975 commands. If false, the setting is
976 applied to all configured commands the
977 same way. Defaults to
978 false.</para></listitem>
982 <term><varname>NonBlocking=</varname></term>
983 <listitem><para>Set the
984 <constant>O_NONBLOCK</constant> flag
985 for all file descriptors passed via
986 socket-based activation. If true, all
987 file descriptors >= 3 (i.e. all except
988 stdin, stdout, and stderr) will have
989 the <constant>O_NONBLOCK</constant> flag
991 non-blocking mode. This option is only
992 useful in conjunction with a socket
993 unit, as described in
994 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Defaults
995 to false.</para></listitem>
999 <term><varname>NotifyAccess=</varname></term>
1000 <listitem><para>Controls access to the
1001 service status notification socket, as
1003 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
1005 <option>none</option> (the default),
1006 <option>main</option> or
1007 <option>all</option>. If
1008 <option>none</option>, no daemon status
1009 updates are accepted from the service
1010 processes, all status update messages
1011 are ignored. If <option>main</option>,
1012 only service updates sent from the
1013 main process of the service are
1014 accepted. If <option>all</option>, all
1015 services updates from all members of
1016 the service's control group are
1017 accepted. This option should be set to
1018 open access to the notification socket
1020 <varname>Type=notify</varname> or
1021 <varname>WatchdogSec=</varname> (see
1022 above). If those options are used but
1023 <varname>NotifyAccess=</varname> is not
1024 configured, it will be implicitly set
1026 <option>main</option>.</para></listitem>
1030 <term><varname>Sockets=</varname></term>
1031 <listitem><para>Specifies the name of
1032 the socket units this service shall
1033 inherit the sockets from when the
1034 service is started. Normally it
1035 should not be necessary to use this
1036 setting as all sockets whose unit
1037 shares the same name as the service
1038 (ignoring the different suffix of course)
1039 are passed to the spawned
1042 <para>Note that the same socket may be
1043 passed to multiple processes at the
1044 same time. Also note that a different
1045 service may be activated on incoming
1046 traffic than that which inherits the
1047 sockets. Or in other words: the
1048 <varname>Service=</varname> setting of
1049 <filename>.socket</filename> units
1050 does not have to match the inverse of
1051 the <varname>Sockets=</varname>
1053 <filename>.service</filename> it
1056 <para>This option may appear more than
1057 once, in which case the list of socket
1058 units is merged. If the empty string
1059 is assigned to this option, the list of
1060 sockets is reset, and all prior uses of
1061 this setting will have no
1062 effect.</para></listitem>
1066 <term><varname>StartLimitInterval=</varname></term>
1067 <term><varname>StartLimitBurst=</varname></term>
1069 <listitem><para>Configure service
1070 start rate limiting. By default,
1071 services which are started more
1072 than 5 times within 10 seconds are not
1073 permitted to start any more times
1074 until the 10 second interval ends. With
1075 these two options, this rate limiting
1076 may be modified. Use
1077 <varname>StartLimitInterval=</varname>
1078 to configure the checking interval (defaults to
1079 <varname>DefaultStartLimitInterval=</varname> in
1080 manager configuration file, set to 0 to disable
1081 any kind of rate limiting). Use
1082 <varname>StartLimitBurst=</varname> to
1083 configure how many starts per interval
1084 are allowed (defaults to
1085 <varname>DefaultStartLimitBurst=</varname> in
1086 manager configuration file). These
1087 configuration options are particularly
1088 useful in conjunction with
1089 <varname>Restart=</varname>; however,
1090 they apply to all kinds of starts
1091 (including manual), not just those
1093 <varname>Restart=</varname> logic.
1094 Note that units which are configured
1095 for <varname>Restart=</varname> and
1096 which reach the start limit are not
1097 attempted to be restarted anymore;
1098 however, they may still be restarted
1099 manually at a later point, from which
1100 point on, the restart logic is again
1101 activated. Note that
1103 reset-failed</command> will cause the
1104 restart rate counter for a service to
1105 be flushed, which is useful if the
1106 administrator wants to manually start
1107 a service and the start limit
1109 that.</para></listitem>
1113 <term><varname>StartLimitAction=</varname></term>
1115 <listitem><para>Configure the action
1116 to take if the rate limit configured
1118 <varname>StartLimitInterval=</varname>
1120 <varname>StartLimitBurst=</varname> is
1122 <option>none</option>,
1123 <option>reboot</option>,
1124 <option>reboot-force</option>, or
1125 <option>reboot-immediate</option>. If
1126 <option>none</option> is set,
1127 hitting the rate limit will trigger no
1128 action besides that the start will not
1129 be permitted. <option>reboot</option>
1130 causes a reboot following the normal
1131 shutdown procedure (i.e. equivalent to
1132 <command>systemctl reboot</command>).
1133 <option>reboot-force</option> causes
1134 a forced reboot which will terminate
1135 all processes forcibly but should
1136 cause no dirty file systems on reboot
1137 (i.e. equivalent to <command>systemctl
1138 reboot -f</command>) and
1139 <option>reboot-immediate</option>
1140 causes immediate execution of the
1141 <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
1142 system call, which might result in
1143 data loss. Defaults to
1144 <option>none</option>.</para></listitem>
1148 <term><varname>RebootArgument=</varname></term>
1149 <listitem><para>Configure the optional
1151 <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
1153 <varname>StartLimitAction=</varname>
1154 is a reboot action. This works just
1155 like the optional argument to
1156 <command>systemctl reboot</command>
1157 command.</para></listitem>
1161 <term><varname>FailureAction=</varname></term>
1162 <listitem><para>Configure the action
1163 to take when the service enters a failed
1164 state. Takes the same values as
1165 <varname>StartLimitAction=</varname>
1166 and executes the same actions.
1167 Defaults to <option>none</option>.
1174 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
1176 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
1177 for more settings.</para>
1182 <title>Compatibility Options</title>
1184 <para>The following options are also available in the
1185 <literal>[Service]</literal> section, but exist purely
1186 for compatibility reasons and should not be used in
1187 newly written service files.</para>
1189 <variablelist class='unit-directives'>
1191 <term><varname>SysVStartPriority=</varname></term>
1192 <listitem><para>Set the SysV start
1193 priority to use to order this service
1194 in relation to SysV services lacking
1195 LSB headers. This option is only
1196 necessary to fix ordering in relation
1197 to legacy SysV services that have no
1198 ordering information encoded in the
1199 script headers. As such, it should only
1200 be used as a temporary compatibility
1201 option and should not be used in new unit
1202 files. Almost always, it is a better
1203 choice to add explicit ordering
1205 <varname>After=</varname> or
1206 <varname>Before=</varname>,
1207 instead. For more details, see
1208 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
1209 If used, pass an integer value in the
1210 range 0-99.</para></listitem>
1216 <title>See Also</title>
1218 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1219 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
1220 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1221 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1222 <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1223 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1224 <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>