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>TimeoutStartSec=</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.
617 <term><varname>TimeoutStopSec=</varname></term>
618 <listitem><para>Configures the time to
619 wait for stop. If a service is asked
620 to stop, but does not terminate in the
621 specified time, it will be terminated
622 forcibly via <constant>SIGTERM</constant>,
623 and after another timeout of equal duration
624 with <constant>SIGKILL</constant> (see
625 <varname>KillMode=</varname>
626 in <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
627 Takes a unit-less value in seconds, or a
628 time span value such as "5min
629 20s". Pass <literal>0</literal> to disable
630 the timeout logic. Defaults to
631 <varname>TimeoutStartSec=</varname> from the
632 manager configuration file.
637 <term><varname>TimeoutSec=</varname></term>
638 <listitem><para>A shorthand for configuring
639 both <varname>TimeoutStartSec=</varname>
640 and <varname>TimeoutStopSec=</varname>
641 to the specified value.
646 <term><varname>WatchdogSec=</varname></term>
647 <listitem><para>Configures the
648 watchdog timeout for a service. The
649 watchdog is activated when the start-up is
650 completed. The service must call
651 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
652 regularly with <literal>WATCHDOG=1</literal>
653 (i.e. the "keep-alive ping"). If the time
654 between two such calls is larger than
655 the configured time, then the service
656 is placed in a failed state. By
657 setting <varname>Restart=</varname> to
658 <option>on-failure</option> or
659 <option>always</option>, the service
660 will be automatically restarted. The
661 time configured here will be passed to
662 the executed service process in the
663 <varname>WATCHDOG_USEC=</varname>
664 environment variable. This allows
665 daemons to automatically enable the
666 keep-alive pinging logic if watchdog
667 support is enabled for the service. If
669 <varname>NotifyAccess=</varname> (see
670 below) should be set to open access to
671 the notification socket provided by
673 <varname>NotifyAccess=</varname> is
674 not set, it will be implicitly set to
675 <option>main</option>. Defaults to 0,
677 feature.</para></listitem>
681 <term><varname>Restart=</varname></term>
682 <listitem><para>Configures whether the
683 service shall be restarted when the
684 service process exits, is killed,
685 or a timeout is reached. The service
686 process may be the main service
687 process, but it may also be one of the
688 processes specified with
689 <varname>ExecStartPre=</varname>,
690 <varname>ExecStartPost=</varname>,
691 <varname>ExecStop=</varname>,
692 <varname>ExecStopPost=</varname>, or
693 <varname>ExecReload=</varname>.
694 When the death of the process is a
695 result of systemd operation (e.g. service
696 stop or restart), the service will not be
697 restarted. Timeouts include missing
698 the watchdog "keep-alive ping"
699 deadline and a service start, reload,
700 and stop operation timeouts.</para>
704 <option>on-success</option>,
705 <option>on-failure</option>,
706 <option>on-watchdog</option>,
707 <option>on-abort</option>, or
708 <option>always</option>. If set to
709 <option>no</option> (the default), the
710 service will not be restarted. If set to
711 <option>on-success</option>, it will be
712 restarted only when the service process
714 In this context, a clean exit means
715 an exit code of 0, or one of the signals
716 <constant>SIGHUP</constant>,
717 <constant>SIGINT</constant>,
718 <constant>SIGTERM</constant>,
719 or <constant>SIGPIPE</constant>, and
720 additionally, exit statuses and signals
721 specified in <varname>SuccessExitStatus=</varname>.
722 If set to <option>on-failure</option>,
723 the service will be restarted when the
724 process exits with a non-zero exit code,
725 is terminated by a signal (including on
726 core dump), when an operation (such as
727 service reload) times out, and when the
728 configured watchdog timeout is triggered.
730 <option>on-abort</option>, the service
731 will be restarted only if the service
732 process exits due to an uncaught
733 signal not specified as a clean exit
736 <option>on-watchdog</option>, the service
737 will be restarted only if the watchdog
738 timeout for the service expires.
740 <option>always</option>, the service
741 will be restarted regardless of whether
742 it exited cleanly or not, got
743 terminated abnormally by a signal, or
744 hit a timeout.</para>
746 <para>In addition to the above settings,
747 the service will not be restarted if the
748 exit code or signal is specified in
749 <varname>RestartPreventExitStatus=</varname>
750 (see below).</para></listitem>
754 <term><varname>SuccessExitStatus=</varname></term>
755 <listitem><para>Takes a list of exit
756 status definitions that when returned
757 by the main service process will be
758 considered successful termination, in
759 addition to the normal successful exit
760 code 0 and the signals <constant>SIGHUP</constant>, <constant>SIGINT</constant>,
761 <constant>SIGTERM</constant>, and <constant>SIGPIPE</constant>. Exit status
762 definitions can either be numeric exit
763 codes or termination signal names,
764 separated by spaces. For example:
765 <programlisting>SuccessExitStatus=1 2 8 <constant>SIGKILL</constant></programlisting>
766 ensures that exit codes 1, 2, 8 and
767 the termination signal
768 <constant>SIGKILL</constant> are
769 considered clean service terminations.
772 <para>Note that if a process has a
773 signal handler installed and exits by
775 <citerefentry><refentrytitle>_exit</refentrytitle><manvolnum>2</manvolnum></citerefentry>
776 in response to a signal, the
777 information about the signal is lost.
778 Programs should instead perform cleanup and kill themselves with the same signal instead. See
779 <ulink url="http://www.cons.org/cracauer/sigint.html">Proper handling of SIGINT/SIGQUIT — How to be a proper program</ulink>.</para>
781 <para>This option may appear more than once,
782 in which case the list of successful
783 exit statuses is merged. If the empty
784 string is assigned to this option, the
785 list is reset, all prior assignments
786 of this option will have no
787 effect.</para></listitem>
791 <term><varname>RestartPreventExitStatus=</varname></term>
792 <listitem><para>Takes a list of exit
793 status definitions that when returned
794 by the main service process will
795 prevent automatic service restarts,
796 regardless of the restart setting
798 <varname>Restart=</varname>. Exit
799 status definitions can either be
800 numeric exit codes or termination
801 signal names, and are separated by
802 spaces. Defaults to the empty list, so
803 that, by default, no exit status is
804 excluded from the configured restart
806 <literal>RestartPreventExitStatus=1 6
807 SIGABRT</literal>, ensures that exit
808 codes 1 and 6 and the termination
809 signal <constant>SIGABRT</constant> will
810 not result in automatic service
812 option may appear more than once, in
813 which case the list of restart-preventing
814 statuses is merged. If the empty
815 string is assigned to this option, the
816 list is reset and all prior assignments
817 of this option will have no
818 effect.</para></listitem>
822 <term><varname>PermissionsStartOnly=</varname></term>
823 <listitem><para>Takes a boolean
824 argument. If true, the permission-related
825 execution options, as
827 <varname>User=</varname> and similar
829 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
830 for more information), are only applied
831 to the process started with
832 <varname>ExecStart=</varname>, and not
834 <varname>ExecStartPre=</varname>,
835 <varname>ExecStartPost=</varname>,
836 <varname>ExecReload=</varname>,
837 <varname>ExecStop=</varname>, and
838 <varname>ExecStopPost=</varname>
839 commands. If false, the setting is
840 applied to all configured commands the
841 same way. Defaults to
842 false.</para></listitem>
846 <term><varname>RootDirectoryStartOnly=</varname></term>
847 <listitem><para>Takes a boolean
848 argument. If true, the root directory,
849 as configured with the
850 <varname>RootDirectory=</varname>
852 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
853 for more information), is only applied
854 to the process started with
855 <varname>ExecStart=</varname>, and not
857 <varname>ExecStartPre=</varname>,
858 <varname>ExecStartPost=</varname>,
859 <varname>ExecReload=</varname>,
860 <varname>ExecStop=</varname>, and
861 <varname>ExecStopPost=</varname>
862 commands. If false, the setting is
863 applied to all configured commands the
864 same way. Defaults to
865 false.</para></listitem>
869 <term><varname>NonBlocking=</varname></term>
870 <listitem><para>Set the
871 <constant>O_NONBLOCK</constant> flag
872 for all file descriptors passed via
873 socket-based activation. If true, all
874 file descriptors >= 3 (i.e. all except
875 stdin, stdout, and stderr) will have
876 the <constant>O_NONBLOCK</constant> flag
878 non-blocking mode. This option is only
879 useful in conjunction with a socket
880 unit, as described in
881 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Defaults
882 to false.</para></listitem>
886 <term><varname>NotifyAccess=</varname></term>
887 <listitem><para>Controls access to the
888 service status notification socket, as
890 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
892 <option>none</option> (the default),
893 <option>main</option> or
894 <option>all</option>. If
895 <option>none</option>, no daemon status
896 updates are accepted from the service
897 processes, all status update messages
898 are ignored. If <option>main</option>,
899 only service updates sent from the
900 main process of the service are
901 accepted. If <option>all</option>, all
902 services updates from all members of
903 the service's control group are
904 accepted. This option should be set to
905 open access to the notification socket
907 <varname>Type=notify</varname> or
908 <varname>WatchdogSec=</varname> (see
909 above). If those options are used but
910 <varname>NotifyAccess=</varname> is not
911 configured, it will be implicitly set
913 <option>main</option>.</para></listitem>
917 <term><varname>Sockets=</varname></term>
918 <listitem><para>Specifies the name of
919 the socket units this service shall
920 inherit the sockets from when the
921 service is started. Normally it
922 should not be necessary to use this
923 setting as all sockets whose unit
924 shares the same name as the service
925 (ignoring the different suffix of course)
926 are passed to the spawned
929 <para>Note that the same socket may be
930 passed to multiple processes at the
931 same time. Also note that a different
932 service may be activated on incoming
933 traffic than that which inherits the
934 sockets. Or in other words: the
935 <varname>Service=</varname> setting of
936 <filename>.socket</filename> units
937 does not have to match the inverse of
938 the <varname>Sockets=</varname>
940 <filename>.service</filename> it
943 <para>This option may appear more than
944 once, in which case the list of socket
945 units is merged. If the empty string
946 is assigned to this option, the list of
947 sockets is reset, and all prior uses of
948 this setting will have no
949 effect.</para></listitem>
953 <term><varname>StartLimitInterval=</varname></term>
954 <term><varname>StartLimitBurst=</varname></term>
956 <listitem><para>Configure service
957 start rate limiting. By default,
958 services which are started more
959 than 5 times within 10 seconds are not
960 permitted to start any more times
961 until the 10 second interval ends. With
962 these two options, this rate limiting
964 <varname>StartLimitInterval=</varname>
965 to configure the checking interval (defaults to
966 <varname>DefaultStartLimitInterval=</varname> in
967 manager configuration file, set to 0 to disable
968 any kind of rate limiting). Use
969 <varname>StartLimitBurst=</varname> to
970 configure how many starts per interval
971 are allowed (defaults to
972 <varname>DefaultStartLimitBurst=</varname> in
973 manager configuration file). These
974 configuration options are particularly
975 useful in conjunction with
976 <varname>Restart=</varname>; however,
977 they apply to all kinds of starts
978 (including manual), not just those
980 <varname>Restart=</varname> logic.
981 Note that units which are configured
982 for <varname>Restart=</varname> and
983 which reach the start limit are not
984 attempted to be restarted anymore;
985 however, they may still be restarted
986 manually at a later point, from which
987 point on, the restart logic is again
990 reset-failed</command> will cause the
991 restart rate counter for a service to
992 be flushed, which is useful if the
993 administrator wants to manually start
994 a service and the start limit
996 that.</para></listitem>
1000 <term><varname>StartLimitAction=</varname></term>
1002 <listitem><para>Configure the action
1003 to take if the rate limit configured
1005 <varname>StartLimitInterval=</varname>
1007 <varname>StartLimitBurst=</varname> is
1009 <option>none</option>,
1010 <option>reboot</option>,
1011 <option>reboot-force</option>, or
1012 <option>reboot-immediate</option>. If
1013 <option>none</option> is set,
1014 hitting the rate limit will trigger no
1015 action besides that the start will not
1016 be permitted. <option>reboot</option>
1017 causes a reboot following the normal
1018 shutdown procedure (i.e. equivalent to
1019 <command>systemctl reboot</command>).
1020 <option>reboot-force</option> causes
1021 a forced reboot which will terminate
1022 all processes forcibly but should
1023 cause no dirty file systems on reboot
1024 (i.e. equivalent to <command>systemctl
1025 reboot -f</command>) and
1026 <option>reboot-immediate</option>
1027 causes immediate execution of the
1028 <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
1029 system call, which might result in
1030 data loss. Defaults to
1031 <option>none</option>.</para></listitem>
1035 <term><varname>RebootArgument=</varname></term>
1036 <listitem><para>Configure the optional
1038 <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
1040 <varname>StartLimitAction=</varname>
1041 is a reboot action. This works just
1042 like the optional argument to
1043 <command>systemctl reboot</command>
1044 command.</para></listitem>
1048 <term><varname>FailureAction=</varname></term>
1049 <listitem><para>Configure the action
1050 to take when the service enters a failed
1051 state. Takes the same values as
1052 <varname>StartLimitAction=</varname>
1053 and executes the same actions.
1054 Defaults to <option>none</option>.
1061 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
1063 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
1064 for more settings.</para>
1069 <title>Compatibility Options</title>
1071 <para>The following options are also available in the
1072 <literal>[Service]</literal> section, but exist purely
1073 for compatibility reasons and should not be used in
1074 newly written service files.</para>
1076 <variablelist class='unit-directives'>
1078 <term><varname>SysVStartPriority=</varname></term>
1079 <listitem><para>Set the SysV start
1080 priority to use to order this service
1081 in relation to SysV services lacking
1082 LSB headers. This option is only
1083 necessary to fix ordering in relation
1084 to legacy SysV services that have no
1085 ordering information encoded in the
1086 script headers. As such, it should only
1087 be used as a temporary compatibility
1088 option and should not be used in new unit
1089 files. Almost always, it is a better
1090 choice to add explicit ordering
1092 <varname>After=</varname> or
1093 <varname>Before=</varname>,
1094 instead. For more details, see
1095 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
1096 If used, pass an integer value in the
1097 range 0-99.</para></listitem>
1103 <title>See Also</title>
1105 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1106 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
1107 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1108 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1109 <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1110 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1111 <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>