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. The value is split
356 into zero or more command lines is
357 according to the rules described below
358 (see section "Command Lines" below).
361 <para>When <varname>Type</varname> is
362 not <option>oneshot</option>, only one
363 command may and must be given. When
364 <varname>Type=oneshot</varname> is
365 used, zero or more commands may be
366 specified. This can be specified by
367 providing multiple command lines in
368 the same directive, or alternatively,
369 this directive may be specified more
370 than once with the same effect. If the
371 empty string is assigned to this
372 option, the list of commands to start
373 is reset, prior assignments of this
374 option will have no effect. If no
375 <varname>ExecStart=</varname> is
376 specified, then the service must have
377 <varname>RemainAfterExit=yes</varname>
380 <para>For each of the specified
381 commands, the first argument must be
382 an absolute and literal path to an
383 executable. Optionally, if the
384 absolute file name is prefixed with
385 <literal>@</literal>, the second token
387 <literal>argv[0]</literal> to the
388 executed process, followed by the
389 further arguments specified. If the
390 absolute filename is prefixed with
391 <literal>-</literal>, an exit code of
392 the command normally considered a
393 failure (i.e. non-zero exit status or
394 abnormal exit due to signal) is
395 ignored and considered success. If
396 both <literal>-</literal> and
397 <literal>@</literal> are used, they
398 can appear in either order.</para>
400 <para>If more than one command is
401 specified, the commands are invoked
402 sequentially in the order they appear
403 in the unit file. If one of the
404 commands fails (and is not prefixed
405 with <literal>-</literal>), other
406 lines are not executed, and the unit
407 is considered failed.</para>
410 <varname>Type=forking</varname> is
411 set, the process started via this
412 command line will be considered the
413 main process of the daemon.</para>
419 <term><varname>ExecStartPre=</varname></term>
420 <term><varname>ExecStartPost=</varname></term>
421 <listitem><para>Additional commands
422 that are executed before or after
424 <varname>ExecStart=</varname>, respectively.
425 Syntax is the same as for
426 <varname>ExecStart=</varname>, except
427 that multiple command lines are allowed
428 and the commands are executed one
429 after the other, serially.</para>
431 <para>If any of those commands (not
432 prefixed with <literal>-</literal>)
433 fail, the rest are not executed and
434 the unit is considered failed.</para>
439 <term><varname>ExecReload=</varname></term>
440 <listitem><para>Commands to execute to
441 trigger a configuration reload in the
442 service. This argument takes multiple
443 command lines, following the same
444 scheme as described for
445 <varname>ExecStart=</varname>
446 above. Use of this setting is
447 optional. Specifier and environment
448 variable substitution is supported
449 here following the same scheme as for
450 <varname>ExecStart=</varname>.</para>
452 <para>One additional, special
453 environment variable is set: if known,
454 <varname>$MAINPID</varname> is set to
455 the main process of the daemon, and
456 may be used for command lines like the
459 <programlisting>/bin/kill -HUP $MAINPID</programlisting>
461 <para>Note however that reloading a
462 daemon by sending a signal (as with
463 the example line above) is usually not
464 a good choice, because this is an
465 asynchronous operation and hence not
466 suitable to order reloads of multiple
467 services against each other. It is
468 strongly recommended to set
469 <varname>ExecReload=</varname> to a
470 command that not only triggers a
471 configuration reload of the daemon,
472 but also synchronously waits for it to
478 <term><varname>ExecStop=</varname></term>
479 <listitem><para>Commands to execute to
480 stop the service started via
481 <varname>ExecStart=</varname>. This
482 argument takes multiple command lines,
483 following the same scheme as described
484 for <varname>ExecStart=</varname>
485 above. Use of this setting is
486 optional. After the commands configured
487 in this option are run, all processes
488 remaining for a service are
489 terminated according to the
490 <varname>KillMode=</varname> setting
492 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>). If
493 this option is not specified, the
494 process is terminated immediately when
495 service stop is requested. Specifier
496 and environment variable substitution
497 is supported (including
498 <varname>$MAINPID</varname>, see
499 above).</para></listitem>
503 <term><varname>ExecStopPost=</varname></term>
504 <listitem><para>Additional commands
505 that are executed after the service
506 was stopped. This includes cases where
507 the commands configured in
508 <varname>ExecStop=</varname> were used,
509 where the service does not have any
510 <varname>ExecStop=</varname> defined, or
511 where the service exited unexpectedly. This
512 argument takes multiple command lines,
513 following the same scheme as described
514 for <varname>ExecStart</varname>. Use
516 optional. Specifier and environment
517 variable substitution is
518 supported.</para></listitem>
522 <term><varname>RestartSec=</varname></term>
523 <listitem><para>Configures the time to
524 sleep before restarting a service (as
526 <varname>Restart=</varname>). Takes a
527 unit-less value in seconds, or a time
528 span value such as "5min
530 100ms.</para></listitem>
534 <term><varname>TimeoutStartSec=</varname></term>
535 <listitem><para>Configures the time to
536 wait for start-up. If a
537 daemon service does not signal
538 start-up completion within the
539 configured time, the service will be
540 considered failed and will be shut
542 Takes a unit-less value in seconds, or a
543 time span value such as "5min
544 20s". Pass <literal>0</literal> to
545 disable the timeout logic. Defaults to
546 <varname>DefaultTimeoutStartSec=</varname> from
547 the manager configuration file, except
548 when <varname>Type=oneshot</varname> is
549 used, in which case the timeout
550 is disabled by default
551 (see <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
556 <term><varname>TimeoutStopSec=</varname></term>
557 <listitem><para>Configures the time to
558 wait for stop. If a service is asked
559 to stop, but does not terminate in the
560 specified time, it will be terminated
561 forcibly via <constant>SIGTERM</constant>,
562 and after another timeout of equal duration
563 with <constant>SIGKILL</constant> (see
564 <varname>KillMode=</varname>
565 in <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
566 Takes a unit-less value in seconds, or a
567 time span value such as "5min
568 20s". Pass <literal>0</literal> to disable
569 the timeout logic. Defaults to
570 <varname>DefaultTimeoutStopSec=</varname> from the
571 manager configuration file
572 (see <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
577 <term><varname>TimeoutSec=</varname></term>
578 <listitem><para>A shorthand for configuring
579 both <varname>TimeoutStartSec=</varname>
580 and <varname>TimeoutStopSec=</varname>
581 to the specified value.
586 <term><varname>WatchdogSec=</varname></term>
587 <listitem><para>Configures the
588 watchdog timeout for a service. The
589 watchdog is activated when the start-up is
590 completed. The service must call
591 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
592 regularly with <literal>WATCHDOG=1</literal>
593 (i.e. the "keep-alive ping"). If the time
594 between two such calls is larger than
595 the configured time, then the service
596 is placed in a failed state and it will
597 be terminated with <varname>SIGABRT</varname>.
598 By setting <varname>Restart=</varname> to
599 <option>on-failure</option> or
600 <option>always</option>, the service
601 will be automatically restarted. The
602 time configured here will be passed to
603 the executed service process in the
604 <varname>WATCHDOG_USEC=</varname>
605 environment variable. This allows
606 daemons to automatically enable the
607 keep-alive pinging logic if watchdog
608 support is enabled for the service. If
610 <varname>NotifyAccess=</varname> (see
611 below) should be set to open access to
612 the notification socket provided by
614 <varname>NotifyAccess=</varname> is
615 not set, it will be implicitly set to
616 <option>main</option>. Defaults to 0,
618 feature.</para></listitem>
622 <term><varname>Restart=</varname></term>
623 <listitem><para>Configures whether the
624 service shall be restarted when the
625 service process exits, is killed,
626 or a timeout is reached. The service
627 process may be the main service
628 process, but it may also be one of the
629 processes specified with
630 <varname>ExecStartPre=</varname>,
631 <varname>ExecStartPost=</varname>,
632 <varname>ExecStop=</varname>,
633 <varname>ExecStopPost=</varname>, or
634 <varname>ExecReload=</varname>.
635 When the death of the process is a
636 result of systemd operation (e.g. service
637 stop or restart), the service will not be
638 restarted. Timeouts include missing
639 the watchdog "keep-alive ping"
640 deadline and a service start, reload,
641 and stop operation timeouts.</para>
645 <option>on-success</option>,
646 <option>on-failure</option>,
647 <option>on-abnormal</option>,
648 <option>on-watchdog</option>,
649 <option>on-abort</option>, or
650 <option>always</option>. If set to
651 <option>no</option> (the default), the
652 service will not be restarted. If set
653 to <option>on-success</option>, it
654 will be restarted only when the
655 service process exits cleanly. In
656 this context, a clean exit means an
657 exit code of 0, or one of the signals
658 <constant>SIGHUP</constant>,
659 <constant>SIGINT</constant>,
660 <constant>SIGTERM</constant> or
661 <constant>SIGPIPE</constant>, and
662 additionally, exit statuses and
664 <varname>SuccessExitStatus=</varname>.
665 If set to <option>on-failure</option>,
666 the service will be restarted when the
667 process exits with a non-zero exit
668 code, is terminated by a signal
669 (including on core dump, but excluding
670 the aforementiond four signals), when
671 an operation (such as service reload)
672 times out, and when the configured
673 watchdog timeout is triggered. If set
674 to <option>on-abnormal</option>, the
675 service will be restarted when the
676 process is terminated by a signal
677 (including on core dump, excluding the
678 aforementioned four signals), when an
679 operation times out, or when the
680 watchdog timeout is triggered. If set
681 to <option>on-abort</option>, the
682 service will be restarted only if the
683 service process exits due to an
684 uncaught signal not specified as a
685 clean exit status. If set to
686 <option>on-watchdog</option>, the
687 service will be restarted only if the
688 watchdog timeout for the service
690 <option>always</option>, the service
691 will be restarted regardless of
692 whether it exited cleanly or not, got
693 terminated abnormally by a signal, or
694 hit a timeout.</para>
697 <title>Exit causes and the effect of the <varname>Restart=</varname> settings on them</title>
700 <colspec colname='path' />
701 <colspec colname='expl' />
704 <entry>Restart settings/Exit causes</entry>
705 <entry><option>no</option></entry>
706 <entry><option>always</option></entry>
707 <entry><option>on-success</option></entry>
708 <entry><option>on-failure</option></entry>
709 <entry><option>on-abnormal</option></entry>
710 <entry><option>on-abort</option></entry>
711 <entry><option>on-watchdog</option></entry>
716 <entry>Clean exit code or signal</entry>
726 <entry>Unclean exit code</entry>
736 <entry>Unclean signal</entry>
746 <entry>Timeout</entry>
756 <entry>Watchdog</entry>
769 <para>As exceptions to the setting
770 above the service will not be
771 restarted if the exit code or signal
773 <varname>RestartPreventExitStatus=</varname>
774 (see below). Also, the services will
775 always be restarted if the exit code
776 or signal is specified in
777 <varname>RestartForceExitStatus=</varname>
780 <para>Setting this to
781 <option>on-failure</option> is the
782 recommended choice for long-running
783 services, in order to increase
784 reliability by attempting automatic
785 recovery from errors. For services
786 that shall be able to terminate on
787 their own choice (and avoid
788 immediate restarting),
789 <option>on-abnormal</option> is an
790 alternative choice.</para>
795 <term><varname>SuccessExitStatus=</varname></term>
796 <listitem><para>Takes a list of exit
797 status definitions that when returned
798 by the main service process will be
799 considered successful termination, in
800 addition to the normal successful exit
801 code 0 and the signals <constant>SIGHUP</constant>, <constant>SIGINT</constant>,
802 <constant>SIGTERM</constant>, and <constant>SIGPIPE</constant>. Exit status
803 definitions can either be numeric exit
804 codes or termination signal names,
805 separated by spaces. For example:
806 <programlisting>SuccessExitStatus=1 2 8 SIGKILL</programlisting>
807 ensures that exit codes 1, 2, 8 and
808 the termination signal
809 <constant>SIGKILL</constant> are
810 considered clean service terminations.
813 <para>Note that if a process has a
814 signal handler installed and exits by
816 <citerefentry><refentrytitle>_exit</refentrytitle><manvolnum>2</manvolnum></citerefentry>
817 in response to a signal, the
818 information about the signal is lost.
819 Programs should instead perform cleanup and kill themselves with the same signal instead. See
820 <ulink url="http://www.cons.org/cracauer/sigint.html">Proper handling of SIGINT/SIGQUIT — How to be a proper program</ulink>.</para>
822 <para>This option may appear more than once,
823 in which case the list of successful
824 exit statuses is merged. If the empty
825 string is assigned to this option, the
826 list is reset, all prior assignments
827 of this option will have no
828 effect.</para></listitem>
832 <term><varname>RestartPreventExitStatus=</varname></term>
833 <listitem><para>Takes a list of exit
834 status definitions that when returned
835 by the main service process will
836 prevent automatic service restarts,
837 regardless of the restart setting
839 <varname>Restart=</varname>. Exit
840 status definitions can either be
841 numeric exit codes or termination
842 signal names, and are separated by
843 spaces. Defaults to the empty list, so
844 that, by default, no exit status is
845 excluded from the configured restart
847 <programlisting>RestartPreventExitStatus=1 6 SIGABRT</programlisting> ensures that exit
848 codes 1 and 6 and the termination
849 signal <constant>SIGABRT</constant> will
850 not result in automatic service
852 option may appear more than once, in
853 which case the list of restart-preventing
854 statuses is merged. If the empty
855 string is assigned to this option, the
856 list is reset and all prior assignments
857 of this option will have no
858 effect.</para></listitem>
862 <term><varname>RestartForceExitStatus=</varname></term>
863 <listitem><para>Takes a list of exit
864 status definitions that when returned
865 by the main service process will force
866 automatic service restarts, regardless
867 of the restart setting configured with
868 <varname>Restart=</varname>. The
869 argument format is similar to
870 <varname>RestartPreventExitStatus=</varname>.</para></listitem>
874 <term><varname>PermissionsStartOnly=</varname></term>
875 <listitem><para>Takes a boolean
876 argument. If true, the permission-related
877 execution options, as
879 <varname>User=</varname> and similar
881 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
882 for more information), are only applied
883 to the process started with
884 <varname>ExecStart=</varname>, and not
886 <varname>ExecStartPre=</varname>,
887 <varname>ExecStartPost=</varname>,
888 <varname>ExecReload=</varname>,
889 <varname>ExecStop=</varname>, and
890 <varname>ExecStopPost=</varname>
891 commands. If false, the setting is
892 applied to all configured commands the
893 same way. Defaults to
894 false.</para></listitem>
898 <term><varname>RootDirectoryStartOnly=</varname></term>
899 <listitem><para>Takes a boolean
900 argument. If true, the root directory,
901 as configured with the
902 <varname>RootDirectory=</varname>
904 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
905 for more information), is only applied
906 to the process started with
907 <varname>ExecStart=</varname>, and not
909 <varname>ExecStartPre=</varname>,
910 <varname>ExecStartPost=</varname>,
911 <varname>ExecReload=</varname>,
912 <varname>ExecStop=</varname>, and
913 <varname>ExecStopPost=</varname>
914 commands. If false, the setting is
915 applied to all configured commands the
916 same way. Defaults to
917 false.</para></listitem>
921 <term><varname>NonBlocking=</varname></term>
922 <listitem><para>Set the
923 <constant>O_NONBLOCK</constant> flag
924 for all file descriptors passed via
925 socket-based activation. If true, all
926 file descriptors >= 3 (i.e. all except
927 stdin, stdout, and stderr) will have
928 the <constant>O_NONBLOCK</constant> flag
930 non-blocking mode. This option is only
931 useful in conjunction with a socket
932 unit, as described in
933 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Defaults
934 to false.</para></listitem>
938 <term><varname>NotifyAccess=</varname></term>
939 <listitem><para>Controls access to the
940 service status notification socket, as
942 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
944 <option>none</option> (the default),
945 <option>main</option> or
946 <option>all</option>. If
947 <option>none</option>, no daemon status
948 updates are accepted from the service
949 processes, all status update messages
950 are ignored. If <option>main</option>,
951 only service updates sent from the
952 main process of the service are
953 accepted. If <option>all</option>, all
954 services updates from all members of
955 the service's control group are
956 accepted. This option should be set to
957 open access to the notification socket
959 <varname>Type=notify</varname> or
960 <varname>WatchdogSec=</varname> (see
961 above). If those options are used but
962 <varname>NotifyAccess=</varname> is not
963 configured, it will be implicitly set
965 <option>main</option>.</para></listitem>
969 <term><varname>Sockets=</varname></term>
970 <listitem><para>Specifies the name of
971 the socket units this service shall
972 inherit socket file descriptors
973 from when the service is
974 started. Normally it should not be
975 necessary to use this setting as all
976 socket file descriptors whose unit
977 shares the same name as the service
978 (subject to the different unit name
979 suffix of course) are passed to the
980 spawned process.</para>
982 <para>Note that the same socket file
983 descriptors may be passed to multiple
984 processes simultaneously. Also note
985 that a different service may be
986 activated on incoming socket traffic
987 than the one which is ultimately
988 configured to inherit the socket file
989 descriptors. Or in other words: the
990 <varname>Service=</varname> setting of
991 <filename>.socket</filename> units
992 does not have to match the inverse of
993 the <varname>Sockets=</varname>
995 <filename>.service</filename> it
998 <para>This option may appear more than
999 once, in which case the list of socket
1000 units is merged. If the empty string
1001 is assigned to this option, the list of
1002 sockets is reset, and all prior uses of
1003 this setting will have no
1004 effect.</para></listitem>
1008 <term><varname>StartLimitInterval=</varname></term>
1009 <term><varname>StartLimitBurst=</varname></term>
1011 <listitem><para>Configure service
1012 start rate limiting. By default,
1013 services which are started more
1014 than 5 times within 10 seconds are not
1015 permitted to start any more times
1016 until the 10 second interval ends. With
1017 these two options, this rate limiting
1018 may be modified. Use
1019 <varname>StartLimitInterval=</varname>
1020 to configure the checking interval (defaults to
1021 <varname>DefaultStartLimitInterval=</varname> in
1022 manager configuration file, set to 0 to disable
1023 any kind of rate limiting). Use
1024 <varname>StartLimitBurst=</varname> to
1025 configure how many starts per interval
1026 are allowed (defaults to
1027 <varname>DefaultStartLimitBurst=</varname> in
1028 manager configuration file). These
1029 configuration options are particularly
1030 useful in conjunction with
1031 <varname>Restart=</varname>; however,
1032 they apply to all kinds of starts
1033 (including manual), not just those
1035 <varname>Restart=</varname> logic.
1036 Note that units which are configured
1037 for <varname>Restart=</varname> and
1038 which reach the start limit are not
1039 attempted to be restarted anymore;
1040 however, they may still be restarted
1041 manually at a later point, from which
1042 point on, the restart logic is again
1043 activated. Note that
1045 reset-failed</command> will cause the
1046 restart rate counter for a service to
1047 be flushed, which is useful if the
1048 administrator wants to manually start
1049 a service and the start limit
1051 that.</para></listitem>
1055 <term><varname>StartLimitAction=</varname></term>
1057 <listitem><para>Configure the action
1058 to take if the rate limit configured
1060 <varname>StartLimitInterval=</varname>
1062 <varname>StartLimitBurst=</varname> is
1064 <option>none</option>,
1065 <option>reboot</option>,
1066 <option>reboot-force</option>,
1067 <option>reboot-immediate</option>,
1068 <option>poweroff</option>,
1069 <option>poweroff-force</option> or
1070 <option>poweroff-immediate</option>. If
1071 <option>none</option> is set, hitting
1072 the rate limit will trigger no action
1073 besides that the start will not be
1074 permitted. <option>reboot</option>
1075 causes a reboot following the normal
1076 shutdown procedure (i.e. equivalent to
1077 <command>systemctl reboot</command>).
1078 <option>reboot-force</option> causes a
1079 forced reboot which will terminate all
1080 processes forcibly but should cause no
1081 dirty file systems on reboot
1082 (i.e. equivalent to <command>systemctl
1083 reboot -f</command>) and
1084 <option>reboot-immediate</option>
1085 causes immediate execution of the
1086 <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
1087 system call, which might result in
1089 <option>poweroff</option>,
1090 <option>poweroff-force</option>,
1091 <option>poweroff-immediate</option>
1092 have the effect of powering down the
1094 semantics. Defaults to
1095 <option>none</option>.</para></listitem>
1099 <term><varname>FailureAction=</varname></term>
1100 <listitem><para>Configure the action
1101 to take when the service enters a failed
1102 state. Takes the same values as
1103 <varname>StartLimitAction=</varname>
1104 and executes the same actions.
1105 Defaults to <option>none</option>.
1110 <term><varname>RebootArgument=</varname></term>
1111 <listitem><para>Configure the optional
1113 <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
1115 <varname>StartLimitAction=</varname>
1116 or <varname>FailureAction=</varname>
1117 is a reboot action. This works just
1118 like the optional argument to
1119 <command>systemctl reboot</command>
1120 command.</para></listitem>
1126 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
1128 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
1129 for more settings.</para>
1134 <title>Compatibility Options</title>
1136 <para>The following options are also available in the
1137 <literal>[Service]</literal> section, but exist purely
1138 for compatibility reasons and should not be used in
1139 newly written service files.</para>
1141 <variablelist class='unit-directives'>
1143 <term><varname>SysVStartPriority=</varname></term>
1144 <listitem><para>Set the SysV start
1145 priority to use to order this service
1146 in relation to SysV services lacking
1147 LSB headers. This option is only
1148 necessary to fix ordering in relation
1149 to legacy SysV services that have no
1150 ordering information encoded in the
1151 script headers. As such, it should only
1152 be used as a temporary compatibility
1153 option and should not be used in new unit
1154 files. Almost always, it is a better
1155 choice to add explicit ordering
1157 <varname>After=</varname> or
1158 <varname>Before=</varname>,
1159 instead. For more details, see
1160 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
1161 If used, pass an integer value in the
1162 range 0-99.</para></listitem>
1168 <title>Command lines</title>
1170 <para>This section describes command line parsing and
1171 variable and specifier substitions for
1172 <varname>ExecStart=</varname>,
1173 <varname>ExecStartPre=</varname>,
1174 <varname>ExecStartPost=</varname>,
1175 <varname>ExecReload=</varname>,
1176 <varname>ExecStop=</varname>, and
1177 <varname>ExecStopPost=</varname> options.</para>
1179 <para>Multiple command lines may be concatenated in a
1180 single directive by separating them with semicolons
1181 (these semicolons must be passed as separate words).
1182 Lone semicolons may be escaped as
1183 <literal>\;</literal>.</para>
1185 <para>Each command line is split on whitespace, with
1186 the first item being the command to execute, and the
1187 subsequent items being the arguments. Double quotes
1188 ("...") and single quotes ('...') may be used, in
1189 which case everything until the next matching quote
1190 becomes part of the same argument. Quotes themselves
1191 are removed after parsing. In addition, a trailing
1192 backslash (<literal>\</literal>) may be used to merge
1195 <para>This syntax is intended to be very similar to
1196 shell syntax, but only the meta-characters and
1197 expansions described in the following paragraphs are
1198 understood. Specifically, redirection using
1199 <literal><</literal>, <literal><<</literal>,
1200 <literal>></literal>, and
1201 <literal>>></literal>, pipes using
1202 <literal>|</literal>, running programs in the
1203 background using <literal>&</literal>, and
1204 <emphasis>other elements of shell syntax are not
1205 supported</emphasis>.</para>
1207 <para>The command line accepts <literal>%</literal>
1208 specifiers as described in
1209 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
1210 Note that the first argument of the command line
1211 (i.e. the program to execute) may not include
1214 <para>Basic environment variable substitution is
1215 supported. Use <literal>${FOO}</literal> as part of a
1216 word, or as a word of its own, on the command line, in
1217 which case it will be replaced by the value of the
1218 environment variable including all whitespace it
1219 contains, resulting in a single argument. Use
1220 <literal>$FOO</literal> as a separate word on the
1221 command line, in which case it will be replaced by the
1222 value of the environment variable split at whitespace
1223 resulting in zero or more arguments. For this type of
1224 expansion, quotes and respected when splitting into
1225 words, and afterwards removed.</para>
1227 <para>Example:</para>
1229 <programlisting>Environment="ONE=one" 'TWO=two two'
1230 ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
1232 <para>This will execute <command>/bin/echo</command>
1233 with four arguments: <literal>one</literal>,
1234 <literal>two</literal>, <literal>two</literal>, and
1235 <literal>two two</literal>.</para>
1237 <para>Example:</para>
1238 <programlisting>Environment=ONE='one' "TWO='two two' too" THREE=
1239 ExecStart=/bin/echo ${ONE} ${TWO} ${THREE}
1240 ExecStart=/bin/echo $ONE $TWO $THREE</programlisting>
1241 <para>This results in <filename>echo</filename> being
1242 called twice, the first time with arguments
1243 <literal>'one'</literal>,
1244 <literal>'two two' too</literal>, <literal></literal>,
1245 and the second time with arguments
1246 <literal>one</literal>, <literal>two two</literal>,
1247 <literal>too</literal>.
1250 <para>To pass a literal dollar sign, use
1251 <literal>$$</literal>. Variables whose value is not
1252 known at expansion time are treated as empty
1253 strings. Note that the first argument (i.e. the
1254 program to execute) may not be a variable.</para>
1256 <para>Variables to be used in this fashion may be
1257 defined through <varname>Environment=</varname> and
1258 <varname>EnvironmentFile=</varname>. In addition,
1259 variables listed in the section "Environment variables
1260 in spawned processes" in
1261 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1262 which are considered "static configuration", may be
1263 used (this includes e.g. <varname>$USER</varname>, but
1264 not <varname>$TERM</varname>).</para>
1266 <para>Note that shell command lines are not directly
1267 supported. If shell command lines are to be used, they
1268 need to be passed explicitly to a shell implementation
1269 of some kind. Example:</para>
1270 <programlisting>ExecStart=/bin/sh -c 'dmesg | tac'</programlisting>
1272 <para>Example:</para>
1274 <programlisting>ExecStart=/bin/echo one ; /bin/echo "two two"</programlisting>
1276 <para>This will execute <command>/bin/echo</command>
1277 two times, each time with one argument:
1278 <literal>one</literal> and <literal>two two</literal>,
1279 respectively. Because two commands are specified,
1280 <varname>Type=oneshot</varname> must be used.</para>
1282 <para>Example:</para>
1284 <programlisting>ExecStart=/bin/echo / >/dev/null & \; \
1285 /bin/ls</programlisting>
1287 <para>This will execute <command>/bin/echo</command>
1288 with five arguments: <literal>/</literal>,
1289 <literal>>/dev/null</literal>,
1290 <literal>&</literal>, <literal>;</literal>, and
1291 <literal>/bin/ls</literal>.</para>
1295 <title>See Also</title>
1297 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1298 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1299 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1300 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1301 <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1302 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1303 <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>