core: add support for a configurable system-wide start-up timeout

[thirdparty/systemd.git] / man / systemd.service.xml

<?xml version='1.0'?> <!--*-nxml-*-->
<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<!--
  This file is part of systemd.

  Copyright 2010 Lennart Poettering

  systemd is free software; you can redistribute it and/or modify it
  under the terms of the GNU Lesser General Public License as published by
  the Free Software Foundation; either version 2.1 of the License, or
  (at your option) any later version.

  systemd is distributed in the hope that it will be useful, but
  WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  Lesser General Public License for more details.

  You should have received a copy of the GNU Lesser General Public License
  along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->

<refentry id="systemd.service">
        <refentryinfo>
                <title>systemd.service</title>
                <productname>systemd</productname>

                <authorgroup>
                        <author>
                                <contrib>Developer</contrib>
                                <firstname>Lennart</firstname>
                                <surname>Poettering</surname>
                                <email>lennart@poettering.net</email>
                        </author>
                </authorgroup>
        </refentryinfo>

        <refmeta>
                <refentrytitle>systemd.service</refentrytitle>
                <manvolnum>5</manvolnum>
        </refmeta>

        <refnamediv>
                <refname>systemd.service</refname>
                <refpurpose>Service unit configuration</refpurpose>
        </refnamediv>

        <refsynopsisdiv>
                <para><filename><replaceable>service</replaceable>.service</filename></para>
        </refsynopsisdiv>

        <refsect1>
                <title>Description</title>

                <para>A unit configuration file whose name ends in
                <filename>.service</filename> encodes information
                about a process controlled and supervised by
                systemd.</para>

                <para>This man page lists the configuration options
                specific to this unit type. See
                <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                for the common options of all unit configuration
                files. The common configuration items are configured
                in the generic <literal>[Unit]</literal> and
                <literal>[Install]</literal> sections. The service
                specific configuration options are configured in the
                <literal>[Service]</literal> section.</para>

                <para>Additional options are listed in
                <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                which define the execution environment the commands
                are executed in, and in
                <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                which define the way the processes of the service are
                terminated, and in
                <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                which configure resource control settings for the
                processes of the service.</para>

                <para>Unless <varname>DefaultDependencies=</varname>
                is set to <option>false</option>, service units will
                implicitly have dependencies of type
                <varname>Requires=</varname> and
                <varname>After=</varname> on
                <filename>basic.target</filename> as well as
                dependencies of type <varname>Conflicts=</varname> and
                <varname>Before=</varname> on
                <filename>shutdown.target</filename>. These ensure
                that normal service units pull in basic system
                initialization, and are terminated cleanly prior to
                system shutdown. Only services involved with early
                boot or late system shutdown should disable this
                option.</para>

                <para>If a service is requested under a certain name
                but no unit configuration file is found, systemd looks
                for a SysV init script by the same name (with the
                <filename>.service</filename> suffix removed) and
                dynamically creates a service unit from that
                script. This is useful for compatibility with
                SysV. Note that this compatibility is quite
                comprehensive but not 100%. For details about the
                incompatibilities, see the <ulink
                url="http://www.freedesktop.org/wiki/Software/systemd/Incompatibilities">Incompatibilities
                with SysV</ulink> document.
                </para>
        </refsect1>

        <refsect1>
                <title>Options</title>

                <para>Service files must include a
                <literal>[Service]</literal> section, which carries
                information about the service and the process it
                supervises. A number of options that may be used in
                this section are shared with other unit types. These
                options are documented in
                <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                and
                <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
                options specific to the <literal>[Service]</literal>
                section of service units are the following:</para>

                <variablelist class='unit-directives'>
                        <varlistentry>
                                <term><varname>Type=</varname></term>

                                <listitem><para>Configures the process
                                start-up type for this service
                                unit. One of <option>simple</option>,
                                <option>forking</option>,
                                <option>oneshot</option>,
                                <option>dbus</option>,
                                <option>notify</option> or
                                <option>idle</option>.</para>

                                <para>If set to
                                <option>simple</option> (the default
                                if neither
                                <varname>Type=</varname> nor
                                <varname>BusName=</varname>, but
                                <varname>ExecStart=</varname> are
                                specified), it is expected that the
                                process configured with
                                <varname>ExecStart=</varname> is the
                                main process of the service. In this
                                mode, if the process offers
                                functionality to other processes on
                                the system, its communication channels
                                should be installed before the daemon
                                is started up (e.g. sockets set up by
                                systemd, via socket activation), as
                                systemd will immediately proceed
                                starting follow-up units.</para>

                                <para>If set to
                                <option>forking</option>, it is
                                expected that the process configured
                                with <varname>ExecStart=</varname>
                                will call <function>fork()</function>
                                as part of its start-up. The parent process is
                                expected to exit when start-up is
                                complete and all communication
                                channels are set up. The child continues
                                to run as the main daemon
                                process. This is the behavior of
                                traditional UNIX daemons. If this
                                setting is used, it is recommended to
                                also use the
                                <varname>PIDFile=</varname> option, so
                                that systemd can identify the main
                                process of the daemon. systemd will
                                proceed with starting follow-up units
                                as soon as the parent process
                                exits.</para>

                                <para>Behavior of
                                <option>oneshot</option> is similar to
                                <option>simple</option>; however, it
                                is expected that the process has to
                                exit before systemd starts follow-up
                                units. <varname>RemainAfterExit=</varname>
                                is particularly useful for this type
                                of service. This is the implied
                                default if neither
                                <varname>Type=</varname> or
                                <varname>ExecStart=</varname> are
                                specified.</para>

                                <para>Behavior of
                                <option>dbus</option> is similar to
                                <option>simple</option>; however, it is
                                expected that the daemon acquires a
                                name on the D-Bus bus, as configured
                                by
                                <varname>BusName=</varname>. systemd
                                will proceed with starting follow-up
                                units after the D-Bus bus name has been
                                acquired. Service units with this
                                option configured implicitly gain
                                dependencies on the
                                <filename>dbus.socket</filename>
                                unit. This type is the default if
                                <varname>BusName=</varname> is
                                specified.</para>

                                <para>Behavior of
                                <option>notify</option> is similar to
                                <option>simple</option>; however, it is
                                expected that the daemon sends a
                                notification message via
                                <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                                or an equivalent call when it has finished
                                starting up. systemd will proceed with
                                starting follow-up units after this
                                notification message has been sent. If
                                this option is used,
                                <varname>NotifyAccess=</varname> (see
                                below) should be set to open access to
                                the notification socket provided by
                                systemd. If
                                <varname>NotifyAccess=</varname> is
                                not set, it will be implicitly set to
                                <option>main</option>. Note that
                                currently
                                <varname>Type=</varname><option>notify</option>
                                will not work if used in combination with
                                <varname>PrivateNetwork=</varname><option>yes</option>.</para>

                                <para>Behavior of
                                <option>idle</option> is very similar
                                to <option>simple</option>; however,
                                actual execution of the service
                                binary is delayed until all jobs are
                                dispatched. This may be used to avoid
                                interleaving of output of shell
                                services with the status output on the
                                console.</para>
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>RemainAfterExit=</varname></term>

                                <listitem><para>Takes a boolean value
                                that specifies whether the service
                                shall be considered active even when
                                all its processes exited. Defaults to
                                <option>no</option>.</para>
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>GuessMainPID=</varname></term>

                                <listitem><para>Takes a boolean value
                                that specifies whether systemd should
                                try to guess the main PID of a service
                                if it cannot be determined
                                reliably. This option is ignored
                                unless <option>Type=forking</option>
                                is set and <option>PIDFile=</option>
                                is unset because for the other types
                                or with an explicitly configured PID
                                file, the main PID is always known. The
                                guessing algorithm might come to
                                incorrect conclusions if a daemon
                                consists of more than one process. If
                                the main PID cannot be determined,
                                failure detection and automatic
                                restarting of a service will not work
                                reliably. Defaults to
                                <option>yes</option>.</para>
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>PIDFile=</varname></term>

                                <listitem><para>Takes an absolute file
                                name pointing to the PID file of this
                                daemon. Use of this option is
                                recommended for services where
                                <varname>Type=</varname> is set to
                                <option>forking</option>. systemd will
                                read the PID of the main process of
                                the daemon after start-up of the
                                service. systemd will not write to the
                                file configured here.</para>
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>BusName=</varname></term>

                                <listitem><para>Takes a D-Bus bus
                                name that this service is reachable
                                as. This option is mandatory for
                                services where
                                <varname>Type=</varname> is set to
                                <option>dbus</option>, but its use
                                is otherwise recommended if the process
                                takes a name on the D-Bus bus.</para>
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>ExecStart=</varname></term>
                                <listitem><para>Commands with their
                                arguments that are executed when this
                                service is started. For each of the
                                specified commands, the first argument
                                must be an absolute and literal path
                                to an executable.</para>

                                <para>When <varname>Type</varname> is
                                not <option>oneshot</option>, only one
                                command may and must be given. When
                                <varname>Type=oneshot</varname> is
                                used, none or more than one command
                                may be specified. Multiple command
                                lines may be concatenated in a single
                                directive by separating them with
                                semicolons (these semicolons must be
                                passed as separate
                                words). Alternatively, this directive
                                may be specified more than once with
                                the same effect.  Lone semicolons may
                                be escaped as
                                <literal>\;</literal>. If the empty
                                string is assigned to this option, the
                                list of commands to start is reset,
                                prior assignments of this option will
                                have no effect. If no
                                <varname>ExecStart=</varname> is
                                specified, then the service must have
                                <varname>RemainAfterExit=yes</varname>
                                set.</para>

                                <para>Each command line is split on
                                whitespace, with the first item being
                                the command to execute, and the
                                subsequent items being the arguments.
                                Double quotes ("...") and single
                                quotes ('...') may be used, in which
                                case everything until the next
                                matching quote becomes part of the
                                same argument. Quotes themselves are
                                removed after parsing. In addition, a
                                trailing backslash
                                (<literal>\</literal>) may be used to
                                merge lines. This syntax is intended
                                to be very similar to shell syntax,
                                but only the meta-characters and
                                expansions described in the following
                                paragraphs are understood.
                                Specifically, redirection using
                                <literal>&lt;</literal>,
                                <literal>&lt;&lt;</literal>,
                                <literal>&gt;</literal>, and
                                <literal>&gt;&gt;</literal>, pipes
                                using <literal>|</literal>, and
                                running programs in the background
                                using <literal>&amp;</literal>
                                and <emphasis>other elements of shell
                                syntax are not supported</emphasis>.
                                </para>

                                <para>If more than one command is
                                specified, the commands are invoked
                                sequentially in the order they appear
                                in the unit file. If one of the
                                commands fails (and is not prefixed
                                with <literal>-</literal>), other lines
                                are not executed, and the unit is
                                considered failed.</para>

                                <para>Unless
                                <varname>Type=forking</varname> is
                                set, the process started via this
                                command line will be considered the
                                main process of the daemon.</para>

                                <para>The command line accepts
                                <literal>%</literal> specifiers as
                                described in
                                <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
                                Note that the first argument of the
                                command line (i.e. the program to
                                execute) may not include
                                specifiers.</para>

                                <para>Basic environment variable
                                substitution is supported. Use
                                <literal>${FOO}</literal> as part of a
                                word, or as a word of its own, on the
                                command line, in which case it will be
                                replaced by the value of the
                                environment variable including all
                                whitespace it contains, resulting in a
                                single argument. Use
                                <literal>$FOO</literal> as a separate
                                word on the command line, in which
                                case it will be replaced by the value
                                of the environment variable split at
                                whitespace, resulting in zero or more
                                arguments. To pass a literal dollar
                                sign, use <literal>$$</literal>.
                                Variables whose value is not known at
                                expansion time are treated as empty
                                strings. Note that the first argument
                                (i.e. the program to execute) may not
                                be a variable.</para>

                                <para>Variables to be used in this
                                fashion may be defined through
                                <varname>Environment=</varname> and
                                <varname>EnvironmentFile=</varname>.
                                In addition, variables listed in the
                                section "Environment variables in
                                spawned processes" in
                                <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                                which are considered "static
                                configuration", may be used (this includes
                                e.g. <varname>$USER</varname>, but not
                                <varname>$TERM</varname>).</para>

                                <para>Optionally, if the absolute file
                                name is prefixed with
                                <literal>@</literal>, the second token
                                will be passed as
                                <literal>argv[0]</literal> to the
                                executed process, followed by the
                                further arguments specified. If the
                                absolute filename is prefixed with
                                <literal>-</literal>, an exit code of
                                the command normally considered a
                                failure (i.e. non-zero exit status or
                                abnormal exit due to signal) is ignored
                                and considered success. If both
                                <literal>-</literal> and
                                <literal>@</literal> are used, they
                                can appear in either order.</para>

                                <para>Note that this setting does not
                                directly support shell command
                                lines. If shell command lines are to
                                be used, they need to be passed
                                explicitly to a shell implementation
                                of some kind. Example:</para>
                                <programlisting>ExecStart=/bin/sh -c 'dmesg | tac'</programlisting>
                                <para>Example:</para>
                                <programlisting>ExecStart=/bin/echo one ; /bin/echo "two two"</programlisting>
                                <para>This will execute
                                <command>/bin/echo</command> two
                                times, each time with one argument:
                                <literal>one</literal> and
                                <literal>two two</literal>,
                                respectively. Because two commands are
                                specified,
                                <varname>Type=oneshot</varname> must
                                be used.</para>

                                <para>Example:</para>
                                <programlisting>ExecStart=/bin/echo / &gt;/dev/null &amp; \; \
/bin/ls</programlisting>
                                <para>This will execute
                                <command>/bin/echo</command> with five
                                arguments: <literal>/</literal>,
                                <literal>&gt;/dev/null</literal>,
                                <literal>&amp;</literal>,
                                <literal>;</literal>, and
                                <literal>/bin/ls</literal>.</para>

                                <para>Example:</para>
                                <programlisting>Environment="ONE=one" 'TWO=two two'
ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                <para>This will execute
                                <command>/bin/echo</command> with four
                                arguments: <literal>one</literal>,
                                <literal>two</literal>,
                                <literal>two</literal>, and
                                <literal>two two</literal>.</para>
                              </listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>ExecStartPre=</varname></term>
                                <term><varname>ExecStartPost=</varname></term>
                                <listitem><para>Additional commands
                                that are executed before or after
                                the command in
                                <varname>ExecStart=</varname>, respectively.
                                Syntax is the same as for
                                <varname>ExecStart=</varname>, except
                                that multiple command lines are allowed
                                and the commands are executed one
                                after the other, serially.</para>

                                <para>If any of those commands (not
                                prefixed with <literal>-</literal>)
                                fail, the rest are not executed and
                                the unit is considered failed.</para>
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>ExecReload=</varname></term>
                                <listitem><para>Commands to execute to
                                trigger a configuration reload in the
                                service. This argument takes multiple
                                command lines, following the same
                                scheme as described for
                                <varname>ExecStart=</varname>
                                above. Use of this setting is
                                optional. Specifier and environment
                                variable substitution is supported
                                here following the same scheme as for
                                <varname>ExecStart=</varname>.</para>

                                <para>One additional, special
                                environment variable is set: if known,
                                <varname>$MAINPID</varname> is set to
                                the main process of the daemon, and
                                may be used for command lines like the
                                following:</para>

                                <programlisting>/bin/kill -HUP $MAINPID</programlisting>

                                <para>Note however that reloading a
                                daemon by sending a signal (as with
                                the example line above) is usually not
                                a good choice, because this is an
                                asynchronous operation and hence not
                                suitable to order reloads of multiple
                                services against each other. It is
                                strongly recommended to set
                                <varname>ExecReload=</varname> to a
                                command that not only triggers a
                                configuration reload of the daemon,
                                but also synchronously waits for it to
                                complete.</para>
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>ExecStop=</varname></term>
                                <listitem><para>Commands to execute to
                                stop the service started via
                                <varname>ExecStart=</varname>. This
                                argument takes multiple command lines,
                                following the same scheme as described
                                for <varname>ExecStart=</varname>
                                above. Use of this setting is
                                optional. After the commands configured
                                in this option are run, all processes
                                remaining for a service are
                                terminated according to the
                                <varname>KillMode=</varname> setting
                                (see
                                <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>). If
                                this option is not specified, the
                                process is terminated immediately when
                                service stop is requested. Specifier
                                and environment variable substitution
                                is supported (including
                                <varname>$MAINPID</varname>, see
                                above).</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>ExecStopPost=</varname></term>
                                <listitem><para>Additional commands
                                that are executed after the service
                                was stopped. This includes cases where
                                the commands configured in
                                <varname>ExecStop=</varname> were used,
                                where the service does not have any
                                <varname>ExecStop=</varname> defined, or
                                where the service exited unexpectedly. This
                                argument takes multiple command lines,
                                following the same scheme as described
                                for <varname>ExecStart</varname>. Use
                                of these settings is
                                optional. Specifier and environment
                                variable substitution is
                                supported.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>RestartSec=</varname></term>
                                <listitem><para>Configures the time to
                                sleep before restarting a service (as
                                configured with
                                <varname>Restart=</varname>). Takes a
                                unit-less value in seconds, or a time
                                span value such as "5min
                                20s". Defaults to
                                100ms.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>TimeoutStartSec=</varname></term>
                                <listitem><para>Configures the time to
                                wait for start-up. If a
                                daemon service does not signal
                                start-up completion within the
                                configured time, the service will be
                                considered failed and will be shut
                                down again.
                                Takes a unit-less value in seconds, or a
                                time span value such as "5min
                                20s". Pass <literal>0</literal> to
                                disable the timeout logic. Defaults to
                                <varname>DefaultTimeoutStartSec=</varname> from
                                the manager configuration file, except
                                when <varname>Type=oneshot</varname> is
                                used, in which case the timeout
                                is disabled by default
                                (see <citerefentry><refentrytitle>systemd-systemd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
                                </para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>TimeoutStopSec=</varname></term>
                                <listitem><para>Configures the time to
                                wait for stop. If a service is asked
                                to stop, but does not terminate in the
                                specified time, it will be terminated
                                forcibly via <constant>SIGTERM</constant>,
                                and after another timeout of equal duration
                                with <constant>SIGKILL</constant> (see
                                <varname>KillMode=</varname>
                                in <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
                                Takes a unit-less value in seconds, or a
                                time span value such as "5min
                                20s". Pass <literal>0</literal> to disable
                                the timeout logic. Defaults to
                                <varname>DefaultTimeoutStopSec=</varname> from the
                                manager configuration file
                                (see <citerefentry><refentrytitle>systemd-systemd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
                                </para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>TimeoutSec=</varname></term>
                                <listitem><para>A shorthand for configuring
                                both <varname>TimeoutStartSec=</varname>
                                and <varname>TimeoutStopSec=</varname>
                                to the specified value.
                                </para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>WatchdogSec=</varname></term>
                                <listitem><para>Configures the
                                watchdog timeout for a service. The
                                watchdog is activated when the start-up is
                                completed. The service must call
                                <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                                regularly with <literal>WATCHDOG=1</literal>
                                (i.e. the "keep-alive ping"). If the time
                                between two such calls is larger than
                                the configured time, then the service
                                is placed in a failed state. By
                                setting <varname>Restart=</varname> to
                                <option>on-failure</option> or
                                <option>always</option>, the service
                                will be automatically restarted. The
                                time configured here will be passed to
                                the executed service process in the
                                <varname>WATCHDOG_USEC=</varname>
                                environment variable. This allows
                                daemons to automatically enable the
                                keep-alive pinging logic if watchdog
                                support is enabled for the service. If
                                this option is used,
                                <varname>NotifyAccess=</varname> (see
                                below) should be set to open access to
                                the notification socket provided by
                                systemd. If
                                <varname>NotifyAccess=</varname> is
                                not set, it will be implicitly set to
                                <option>main</option>. Defaults to 0,
                                which disables this
                                feature.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>Restart=</varname></term>
                                <listitem><para>Configures whether the
                                service shall be restarted when the
                                service process exits, is killed,
                                or a timeout is reached. The service
                                process may be the main service
                                process, but it may also be one of the
                                processes specified with
                                <varname>ExecStartPre=</varname>,
                                <varname>ExecStartPost=</varname>,
                                <varname>ExecStop=</varname>,
                                <varname>ExecStopPost=</varname>, or
                                <varname>ExecReload=</varname>.
                                When the death of the process is a
                                result of systemd operation (e.g. service
                                stop or restart), the service will not be
                                restarted. Timeouts include missing
                                the watchdog "keep-alive ping"
                                deadline and a service start, reload,
                                and stop operation timeouts.</para>

                                <para>Takes one of
                                <option>no</option>,
                                <option>on-success</option>,
                                <option>on-failure</option>,
                                <option>on-abnormal</option>,
                                <option>on-watchdog</option>,
                                <option>on-abort</option>, or
                                <option>always</option>. If set to
                                <option>no</option> (the default), the
                                service will not be restarted. If set
                                to <option>on-success</option>, it
                                will be restarted only when the
                                service process exits cleanly.  In
                                this context, a clean exit means an
                                exit code of 0, or one of the signals
                                <constant>SIGHUP</constant>,
                                <constant>SIGINT</constant>,
                                <constant>SIGTERM</constant> or
                                <constant>SIGPIPE</constant>, and
                                additionally, exit statuses and
                                signals specified in
                                <varname>SuccessExitStatus=</varname>.
                                If set to <option>on-failure</option>,
                                the service will be restarted when the
                                process exits with a non-zero exit
                                code, is terminated by a signal
                                (including on core dump, but excluding
                                the aforementiond four signals), when
                                an operation (such as service reload)
                                times out, and when the configured
                                watchdog timeout is triggered.  If set
                                to <option>on-abnormal</option>, the
                                service will be restarted when the
                                process is terminated by a signal
                                (including on core dump, excluding the
                                aforementioned four signals), when an
                                operation times out, or when the
                                watchdog timeout is triggered. If set
                                to <option>on-abort</option>, the
                                service will be restarted only if the
                                service process exits due to an
                                uncaught signal not specified as a
                                clean exit status.  If set to
                                <option>on-watchdog</option>, the
                                service will be restarted only if the
                                watchdog timeout for the service
                                expires.  If set to
                                <option>always</option>, the service
                                will be restarted regardless of
                                whether it exited cleanly or not, got
                                terminated abnormally by a signal, or
                                hit a timeout.</para>

                                <table>
                                        <title>Exit causes and the effect of the <varname>Restart=</varname> settings on them</title>

                                        <tgroup cols='2'>
                                                <colspec colname='path' />
                                                <colspec colname='expl' />
                                                <thead>
                                                        <row>
                                                                <entry>Restart settings/Exit causes</entry>
                                                                <entry><option>no</option></entry>
                                                                <entry><option>always</option></entry>
                                                                <entry><option>on-success</option></entry>
                                                                <entry><option>on-failure</option></entry>
                                                                <entry><option>on-abnormal</option></entry>
                                                                <entry><option>on-abort</option></entry>
                                                                <entry><option>on-watchdog</option></entry>
                                                        </row>
                                                </thead>
                                                <tbody>
                                                        <row>
                                                                <entry>Clean exit code or signal</entry>
                                                                <entry/>
                                                                <entry>X</entry>
                                                                <entry>X</entry>
                                                                <entry/>
                                                                <entry/>
                                                                <entry/>
                                                                <entry/>
                                                        </row>
                                                        <row>
                                                                <entry>Unclean exit code</entry>
                                                                <entry/>
                                                                <entry>X</entry>
                                                                <entry/>
                                                                <entry>X</entry>
                                                                <entry/>
                                                                <entry/>
                                                                <entry/>
                                                        </row>
                                                        <row>
                                                                <entry>Unclean signal</entry>
                                                                <entry/>
                                                                <entry>X</entry>
                                                                <entry/>
                                                                <entry>X</entry>
                                                                <entry>X</entry>
                                                                <entry>X</entry>
                                                                <entry/>
                                                        </row>
                                                        <row>
                                                                <entry>Timeout</entry>
                                                                <entry/>
                                                                <entry>X</entry>
                                                                <entry/>
                                                                <entry>X</entry>
                                                                <entry>X</entry>
                                                                <entry/>
                                                                <entry/>
                                                        </row>
                                                        <row>
                                                                <entry>Watchdog</entry>
                                                                <entry/>
                                                                <entry>X</entry>
                                                                <entry/>
                                                                <entry>X</entry>
                                                                <entry>X</entry>
                                                                <entry/>
                                                                <entry>X</entry>
                                                        </row>
                                                </tbody>
                                        </tgroup>
                                </table>

                                <para>As exceptions to the setting
                                above the service will not be
                                restarted if the exit code or signal
                                is specified in
                                <varname>RestartPreventExitStatus=</varname>
                                (see below). Also, the services will
                                always be restarted if the exit code
                                or signal is specified in
                                <varname>RestartForceExitStatus=</varname>
                                (see below).</para>

                                <para>Setting this to
                                <option>on-failure</option> is the
                                recommended choice for long-running
                                services, in order to increase
                                reliability by attempting automatic
                                recovery from errors. For services
                                that shall be able to terminate on
                                their own choice (and avoid
                                immediate restarting),
                                <option>on-abnormal</option> is an
                                alternative choice.</para>
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>SuccessExitStatus=</varname></term>
                                <listitem><para>Takes a list of exit
                                status definitions that when returned
                                by the main service process will be
                                considered successful termination, in
                                addition to the normal successful exit
                                code 0 and the signals <constant>SIGHUP</constant>, <constant>SIGINT</constant>,
                                <constant>SIGTERM</constant>, and <constant>SIGPIPE</constant>. Exit status
                                definitions can either be numeric exit
                                codes or termination signal names,
                                separated by spaces. For example:
                                <programlisting>SuccessExitStatus=1 2 8 SIGKILL</programlisting>
                                ensures that exit codes 1, 2, 8 and
                                the termination signal
                                <constant>SIGKILL</constant> are
                                considered clean service terminations.
                                </para>

                                <para>Note that if a process has a
                                signal handler installed and exits by
                                calling
                                <citerefentry><refentrytitle>_exit</refentrytitle><manvolnum>2</manvolnum></citerefentry>
                                in response to a signal, the
                                information about the signal is lost.
                                Programs should instead perform cleanup and kill themselves with the same signal instead. See
                                <ulink url="http://www.cons.org/cracauer/sigint.html">Proper handling of SIGINT/SIGQUIT — How to be a proper program</ulink>.</para>

                                <para>This option may appear more than once,
                                in which case the list of successful
                                exit statuses is merged. If the empty
                                string is assigned to this option, the
                                list is reset, all prior assignments
                                of this option will have no
                                effect.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>RestartPreventExitStatus=</varname></term>
                                <listitem><para>Takes a list of exit
                                status definitions that when returned
                                by the main service process will
                                prevent automatic service restarts,
                                regardless of the restart setting
                                configured with
                                <varname>Restart=</varname>. Exit
                                status definitions can either be
                                numeric exit codes or termination
                                signal names, and are separated by
                                spaces. Defaults to the empty list, so
                                that, by default, no exit status is
                                excluded from the configured restart
                                logic. For example:
                                <programlisting>RestartPreventExitStatus=1 6 SIGABRT</programlisting> ensures that exit
                                codes 1 and 6 and the termination
                                signal <constant>SIGABRT</constant> will
                                not result in automatic service
                                restarting. This
                                option may appear more than once, in
                                which case the list of restart-preventing
                                statuses is merged. If the empty
                                string is assigned to this option, the
                                list is reset and all prior assignments
                                of this option will have no
                                effect.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>RestartForceExitStatus=</varname></term>
                                <listitem><para>Takes a list of exit
                                status definitions that when returned
                                by the main service process will force
                                automatic service restarts, regardless
                                of the restart setting configured with
                                <varname>Restart=</varname>. The
                                argument format is similar to
                                <varname>RestartPreventExitStatus=</varname>.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>PermissionsStartOnly=</varname></term>
                                <listitem><para>Takes a boolean
                                argument. If true, the permission-related
                                execution options, as
                                configured with
                                <varname>User=</varname> and similar
                                options (see
                                <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                                for more information), are only applied
                                to the process started with
                                <varname>ExecStart=</varname>, and not
                                to the various other
                                <varname>ExecStartPre=</varname>,
                                <varname>ExecStartPost=</varname>,
                                <varname>ExecReload=</varname>,
                                <varname>ExecStop=</varname>, and
                                <varname>ExecStopPost=</varname>
                                commands. If false, the setting is
                                applied to all configured commands the
                                same way. Defaults to
                                false.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>RootDirectoryStartOnly=</varname></term>
                                <listitem><para>Takes a boolean
                                argument. If true, the root directory,
                                as configured with the
                                <varname>RootDirectory=</varname>
                                option (see
                                <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                                for more information), is only applied
                                to the process started with
                                <varname>ExecStart=</varname>, and not
                                to the various other
                                <varname>ExecStartPre=</varname>,
                                <varname>ExecStartPost=</varname>,
                                <varname>ExecReload=</varname>,
                                <varname>ExecStop=</varname>, and
                                <varname>ExecStopPost=</varname>
                                commands. If false, the setting is
                                applied to all configured commands the
                                same way. Defaults to
                                false.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>NonBlocking=</varname></term>
                                <listitem><para>Set the
                                <constant>O_NONBLOCK</constant> flag
                                for all file descriptors passed via
                                socket-based activation. If true, all
                                file descriptors >= 3 (i.e. all except
                                stdin, stdout, and stderr) will have
                                the <constant>O_NONBLOCK</constant> flag
                                set and hence are in
                                non-blocking mode. This option is only
                                useful in conjunction with a socket
                                unit, as described in
                                <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Defaults
                                to false.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>NotifyAccess=</varname></term>
                                <listitem><para>Controls access to the
                                service status notification socket, as
                                accessible via the
                                <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                                call. Takes one of
                                <option>none</option> (the default),
                                <option>main</option> or
                                <option>all</option>. If
                                <option>none</option>, no daemon status
                                updates are accepted from the service
                                processes, all status update messages
                                are ignored. If <option>main</option>,
                                only service updates sent from the
                                main process of the service are
                                accepted. If <option>all</option>, all
                                services updates from all members of
                                the service's control group are
                                accepted. This option should be set to
                                open access to the notification socket
                                when using
                                <varname>Type=notify</varname> or
                                <varname>WatchdogSec=</varname> (see
                                above). If those options are used but
                                <varname>NotifyAccess=</varname> is not
                                configured, it will be implicitly set
                                to
                                <option>main</option>.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>Sockets=</varname></term>
                                <listitem><para>Specifies the name of
                                the socket units this service shall
                                inherit the sockets from when the
                                service is started. Normally it
                                should not be necessary to use this
                                setting as all sockets whose unit
                                shares the same name as the service
                                (ignoring the different suffix of course)
                                are passed to the spawned
                                process.</para>

                                <para>Note that the same socket may be
                                passed to multiple processes at the
                                same time. Also note that a different
                                service may be activated on incoming
                                traffic than that which inherits the
                                sockets. Or in other words: the
                                <varname>Service=</varname> setting of
                                <filename>.socket</filename> units
                                does not have to match the inverse of
                                the <varname>Sockets=</varname>
                                setting of the
                                <filename>.service</filename> it
                                refers to.</para>

                                <para>This option may appear more than
                                once, in which case the list of socket
                                units is merged. If the empty string
                                is assigned to this option, the list of
                                sockets is reset, and all prior uses of
                                this setting will have no
                                effect.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>StartLimitInterval=</varname></term>
                                <term><varname>StartLimitBurst=</varname></term>

                                <listitem><para>Configure service
                                start rate limiting. By default,
                                services which are started more
                                than 5 times within 10 seconds are not
                                permitted to start any more times
                                until the 10 second interval ends. With
                                these two options, this rate limiting
                                may be modified. Use
                                <varname>StartLimitInterval=</varname>
                                to configure the checking interval (defaults to
                                <varname>DefaultStartLimitInterval=</varname> in
                                manager configuration file, set to 0 to disable
                                any kind of rate limiting). Use
                                <varname>StartLimitBurst=</varname> to
                                configure how many starts per interval
                                are allowed (defaults to
                                <varname>DefaultStartLimitBurst=</varname> in
                                manager configuration file). These
                                configuration options are particularly
                                useful in conjunction with
                                <varname>Restart=</varname>; however,
                                they apply to all kinds of starts
                                (including manual), not just those
                                triggered by the
                                <varname>Restart=</varname> logic.
                                Note that units which are configured
                                for <varname>Restart=</varname> and
                                which reach the start limit are not
                                attempted to be restarted anymore;
                                however, they may still be restarted
                                manually at a later point, from which
                                point on, the restart logic is again
                                activated. Note that
                                <command>systemctl
                                reset-failed</command> will cause the
                                restart rate counter for a service to
                                be flushed, which is useful if the
                                administrator wants to manually start
                                a service and the start limit
                                interferes with
                                that.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>StartLimitAction=</varname></term>

                                <listitem><para>Configure the action
                                to take if the rate limit configured
                                with
                                <varname>StartLimitInterval=</varname>
                                and
                                <varname>StartLimitBurst=</varname> is
                                hit. Takes one of
                                <option>none</option>,
                                <option>reboot</option>,
                                <option>reboot-force</option>, or
                                <option>reboot-immediate</option>. If
                                <option>none</option> is set,
                                hitting the rate limit will trigger no
                                action besides that the start will not
                                be permitted. <option>reboot</option>
                                causes a reboot following the normal
                                shutdown procedure (i.e. equivalent to
                                <command>systemctl reboot</command>).
                                <option>reboot-force</option> causes
                                a forced reboot which will terminate
                                all processes forcibly but should
                                cause no dirty file systems on reboot
                                (i.e. equivalent to <command>systemctl
                                reboot -f</command>) and
                                <option>reboot-immediate</option>
                                causes immediate execution of the
                                <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
                                system call, which might result in
                                data loss. Defaults to
                                <option>none</option>.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>FailureAction=</varname></term>
                                <listitem><para>Configure the action
                                to take when the service enters a failed
                                state. Takes the same values as
                                <varname>StartLimitAction=</varname>
                                and executes the same actions.
                                Defaults to <option>none</option>.
                                </para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>RebootArgument=</varname></term>
                                <listitem><para>Configure the optional
                                argument for the
                                <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
                                system call if
                                <varname>StartLimitAction=</varname>
                                or <varname>FailureAction=</varname>
                                is a reboot action. This works just
                                like the optional argument to
                                <command>systemctl reboot</command>
                                command.</para></listitem>
                        </varlistentry>

                </variablelist>

                <para>Check
                <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                and
                <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                for more settings.</para>

        </refsect1>

        <refsect1>
                <title>Compatibility Options</title>

                <para>The following options are also available in the
                <literal>[Service]</literal> section, but exist purely
                for compatibility reasons and should not be used in
                newly written service files.</para>

                <variablelist class='unit-directives'>
                        <varlistentry>
                                <term><varname>SysVStartPriority=</varname></term>
                                <listitem><para>Set the SysV start
                                priority to use to order this service
                                in relation to SysV services lacking
                                LSB headers. This option is only
                                necessary to fix ordering in relation
                                to legacy SysV services that have no
                                ordering information encoded in the
                                script headers. As such, it should only
                                be used as a temporary compatibility
                                option and should not be used in new unit
                                files. Almost always, it is a better
                                choice to add explicit ordering
                                directives via
                                <varname>After=</varname> or
                                <varname>Before=</varname>,
                                instead. For more details, see
                                <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
                                If used, pass an integer value in the
                                range 0-99.</para></listitem>
                        </varlistentry>
                </variablelist>
        </refsect1>

        <refsect1>
                  <title>See Also</title>
                  <para>
                          <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                          <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
                          <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                          <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                          <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                          <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                          <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
                  </para>
        </refsect1>

</refentry>