| <?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 |
| value if neither |
| <varname>Type=</varname> nor |
| <varname>BusName=</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.</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 be given. When |
| <varname>Type=oneshot</varname> is |
| used, 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.</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><</literal>, |
| <literal><<</literal>, |
| <literal>></literal>, and |
| <literal>>></literal>, pipes |
| using <literal>|</literal>, and |
| running programs in the background |
| using <literal>&</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 / >/dev/null & \; \ |
| /bin/ls</programlisting> |
| <para>This will execute |
| <command>/bin/echo</command> with five |
| arguments: <literal>/</literal>, |
| <literal>>/dev/null</literal>, |
| <literal>&</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 no only triggers a |
| configuration reload of the daemon, |
| but also synchronously waits for it |
| 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>TimeoutStartSec=</varname> from |
| the manager configuration file, except |
| when <varname>Type=oneshot</varname> is |
| used, in which case the timeout |
| is disabled by default. |
| </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>TimeoutStartSec=</varname> from the |
| manager configuration file. |
| </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-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), when an operation (such as |
| service reload) times out, and when the |
| configured 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> |
| |
| <para>In addition to the above settings, |
| the service will not be restarted if the |
| exit code or signal is specified in |
| <varname>RestartPreventExitStatus=</varname> |
| (see below).</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 <constant>SIGKILL</constant></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. Example: |
| <literal>RestartPreventExitStatus=1 6 |
| SIGABRT</literal>, 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>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> |
| |
| </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> |