diff options
Diffstat (limited to 'man/systemd.service.xml')
| -rw-r--r-- | man/systemd.service.xml | 1346 |
1 files changed, 0 insertions, 1346 deletions
diff --git a/man/systemd.service.xml b/man/systemd.service.xml deleted file mode 100644 index f59870563..000000000 --- a/man/systemd.service.xml +++ /dev/null @@ -1,1346 +0,0 @@ -<?xml version='1.0'?> <!--*-nxml-*--> -<!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>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>BusPolicy=</varname></term> - - <listitem><para>If specified, a custom - <ulink url="https://code.google.com/p/d-bus/">kdbus</ulink> - endpoint will be created and installed as the default bus node - for the service. Such a custom endpoint can hold an own set of - policy rules that are enforced on top of the bus-wide ones. - The custom endpoint is named after the service it was created - for, and its node will be bind-mounted over the default bus - node location, so the service can only access the bus through - its own endpoint. Note that custom bus endpoints default to a - 'deny all' policy. Hence, if at least one - <varname>BusPolicy=</varname> directive is given, you have to - make sure to add explicit rules for everything the service - should be able to do.</para> - <para>The value of this directive is comprised - of two parts; the bus name, and a verb to - specify to granted access, which is one of - <option>see</option>, - <option>talk</option>, or - <option>own</option>. - <option>talk</option> implies - <option>see</option>, and <option>own</option> - implies both <option>talk</option> and - <option>see</option>. - If multiple access levels are specified for the - same bus name, the most powerful one takes - effect. - </para> - <para>Examples:</para> - <programlisting>BusPolicy=org.freedesktop.systemd1 talk</programlisting> - <programlisting>BusPolicy=org.foo.bar see</programlisting> - <para>This option is only available on kdbus enabled systems.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>ExecStart=</varname></term> - <listitem><para>Commands with their arguments that are - executed when this service is started. The value is split into - zero or more command lines is according to the rules described - below (see section "Command Lines" below). - </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, zero or - more commands may be specified. This can be specified by - providing multiple command lines in the same directive, or - alternatively, this directive may be specified more than once - with the same effect. 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>For each of the specified commands, the first argument - must be an absolute path to an executable. Optionally, if this - 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>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> - </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> - - <para>Note that <varname>ExecStartPre=</varname> may not be - used to start long-running processes. All processes forked - off by processes invoked via <varname>ExecStartPre=</varname> will - be killed before the next service process is run.</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-system.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-system.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 and it will be terminated with - <varname>SIGABRT</varname>. 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 socket file descriptors from when the - service is started. Normally it should not be necessary to use - this setting as all socket file descriptors whose unit shares - the same name as the service (subject to the different unit - name suffix of course) are passed to the spawned - process.</para> - - <para>Note that the same socket file descriptors may be passed - to multiple processes simultaneously. Also note that a - different service may be activated on incoming socket traffic - than the one which is ultimately configured to inherit the - socket file descriptors. 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>, - <option>reboot-immediate</option>, - <option>poweroff</option>, - <option>poweroff-force</option> or - <option>poweroff-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. Similar, - <option>poweroff</option>, <option>poweroff-force</option>, - <option>poweroff-immediate</option> have the effect of - powering down the system with similar semantics. 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> - - <varlistentry> - <term><varname>FileDescriptorStoreMax=</varname></term> - <listitem><para>Configure how many file descriptors may be - stored in the service manager for the service using - <citerefentry><refentrytitle>sd_pid_notify_with_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>'s - <literal>FDSTORE=1</literal> messages. This is useful for - implementing service restart schemes where the state is - serialized to <filename>/run</filename> and the file - descriptors passed to the service manager, to allow restarts - without losing state. Defaults to 0, i.e. no file descriptors - may be stored in the service manager by default. All file - descriptors passed to the service manager from a specific - service are passed back to the service's main process on the - next service restart. Any file descriptors passed to the - service manager are automatically closed when POLLHUP or - POLLERR is seen on them, or when the service is fully stopped - and no job queued or being executed for it.</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>Command lines</title> - - <para>This section describes command line parsing and - variable and specifier substitions for - <varname>ExecStart=</varname>, - <varname>ExecStartPre=</varname>, - <varname>ExecStartPost=</varname>, - <varname>ExecReload=</varname>, - <varname>ExecStop=</varname>, and - <varname>ExecStopPost=</varname> options.</para> - - <para>Multiple command lines may be concatenated in a single - directive by separating them with semicolons (these semicolons - must be passed as separate words). Lone semicolons may be escaped - as <literal>\;</literal>.</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. C-style escapes are also - supported, see table below. Quotes themselves are removed after - parsing and escape sequences substituted. In addition, a trailing - backslash (<literal>\</literal>) may be used to merge lines. - </para> - - <para>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>, running programs in the background using - <literal>&</literal>, and <emphasis>other elements of shell - syntax are not supported</emphasis>.</para> - - <para>The command to execute must an absolute path name. It may - contain spaces, but control characters are not allowed.</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. - For this type of expansion, quotes and respected when splitting - into words, and afterwards removed.</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> - - <para>Example:</para> - <programlisting>Environment=ONE='one' "TWO='two two' too" THREE= -ExecStart=/bin/echo ${ONE} ${TWO} ${THREE} -ExecStart=/bin/echo $ONE $TWO $THREE</programlisting> - <para>This results in <filename>echo</filename> being - called twice, the first time with arguments - <literal>'one'</literal>, - <literal>'two two' too</literal>, <literal></literal>, - and the second time with arguments - <literal>one</literal>, <literal>two two</literal>, - <literal>too</literal>. - </para> - - <para>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>Note that shell command lines are not directly supported. 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> - - <table> - <title>C escapes supported in command lines and environment variables</title> - <tgroup cols='2'> - <colspec colname='escape' /> - <colspec colname='meaning' /> - <thead> - <row> - <entry>Literal</entry> - <entry>Actual value</entry> - </row> - </thead> - <tbody> - <row> - <entry><literal>\a</literal></entry> - <entry>bell</entry> - </row> - <row> - <entry><literal>\b</literal></entry> - <entry>backspace</entry> - </row> - <row> - <entry><literal>\f</literal></entry> - <entry>form feed</entry> - </row> - <row> - <entry><literal>\n</literal></entry> - <entry>newline</entry> - </row> - <row> - <entry><literal>\r</literal></entry> - <entry>carriage return</entry> - </row> - <row> - <entry><literal>\t</literal></entry> - <entry>tab</entry> - </row> - <row> - <entry><literal>\v</literal></entry> - <entry>vertical tab</entry> - </row> - <row> - <entry><literal>\\</literal></entry> - <entry>backslash</entry> - </row> - <row> - <entry><literal>\"</literal></entry> - <entry>double quotation mark</entry> - </row> - <row> - <entry><literal>\'</literal></entry> - <entry>single quotation mark</entry> - </row> - <row> - <entry><literal>\s</literal></entry> - <entry>space</entry> - </row> - <row> - <entry><literal>\x<replaceable>xx</replaceable></literal></entry> - <entry>character number <replaceable>xx</replaceable> in hexadecimal encoding</entry> - </row> - <row> - <entry><literal>\<replaceable>nnn</replaceable></literal></entry> - <entry>character number <replaceable>nnn</replaceable> in octal encoding</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - <title>Examples</title> - - <example> - <title>Simple service</title> - - <para>The following unit file creates a service that will - execute <filename>/usr/sbin/foo-daemon</filename>. Since no - <varname>Type=</varname> is specified, the default - <varname>Type=</varname><option>simple</option> will be assumed. - systemd will assume the unit to be started immediately after the - program has begun executing.</para> - - <programlisting>[Unit] -Description=Foo - -[Service] -ExecStart=/usr/sbin/foo-daemon - -[Install] -WantedBy=multi-user.target</programlisting> - - <para>Note that systemd assumes here that the process started by - systemd will continue running until the service terminates. If - the program daemonizes itself (i.e. forks), please use - <varname>Type=</varname><option>forking</option> instead.</para> - - <para>Since no <varname>ExecStop=</varname> was specified, - systemd will send SIGTERM to all processes started from this - service, and after a timeout also SIGKILL. This behavior can be - modified, see - <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details.</para> - - <para>Note that this unit type does not include any type of - notification when a service has completed initialization. For - this, you should use other unit types, such as - <varname>Type=</varname><option>notify</option> if the service - understands systemd's notification protocol, - <varname>Type=</varname><option>forking</option> if the service - can background itself or - <varname>Type=</varname><option>dbus</option> if the unit - acquires a DBus name once initialization is complete. See - below.</para> - </example> - - <example> - <title>Oneshot service</title> - - <para>Sometimes units should just execute an action without - keeping active processes, such as a filesystem check or a - cleanup action on boot. For this, - <varname>Type=</varname><option>oneshot</option> exists. Units - of this type will wait until the process specified terminates - and then fall back to being inactive. The following unit will - perform a clenaup action:</para> - - <programlisting>[Unit] -Description=Cleanup old Foo data - -[Service] -Type=oneshot -ExecStart=/usr/sbin/foo-cleanup - -[Install] -WantedBy=multi-user.target</programlisting> - - <para>Note that systemd will consider the unit to be in the - state 'starting' until the program has terminated, so ordered - dependencies will wait for the program to finish before starting - themselves. The unit will revert to the 'inactive' state after - the execution is done, never reaching the 'active' state. That - means another request to start the unit will perform the action - again.</para> - - <para><varname>Type=</varname><option>oneshot</option> are the - only service units that may have more than one - <varname>ExecStart=</varname> specified. They will be executed - in order until either they are all successful or one of them - fails.</para> - </example> - - <example> - <title>Stoppable oneshot service</title> - - <para>Similarly to the oneshot services, there are sometimes - units that need to execute a program to set up something and - then execute another to shut it down, but no process remains - active while they are considered 'started'. Network - configuration can sometimes fall into this category. Another use - case is if a oneshot service shall not be executed a each time - when they are pulled in as a dependency, but only the first - time.</para> - - <para>For this, systemd knows the setting - <varname>RemainAfterExit=</varname><option>yes</option>, which - causes systemd to consider the unit to be active if the start - action exited successfully. This directive can be used with all - types, but is most useful with - <varname>Type=</varname><option>oneshot</option> and - <varname>Type=</varname><option>simple</option>. With - <varname>Type=</varname><option>oneshot</option> systemd waits - until the start action has completed before it considers the - unit to be active, so dependencies start only after the start - action has succeeded. With - <varname>Type=</varname><option>simple</option> dependencies - will start immediately after the start action has been - dispatched. The following unit provides an example for a simple - static firewall.</para> - - <programlisting>[Unit] -Description=Simple firewall - -[Service] -Type=oneshot -RemainAfterExit=yes -ExecStart=/usr/local/sbin/simple-firewall-start -ExecStop=/usr/local/sbin/simple-firewall-stop - -[Install] -WantedBy=multi-user.target</programlisting> - - <para>Since the unit is considered to be running after the start - action has exited, invoking <command>systemctl start</command> - on that unit again will cause no action to be taken.</para> - </example> - - <example> - <title>Traditional forking services</title> - - <para>Many traditional daemons/services background (i.e. fork, - daemonize) themselves when starting. Set - <varname>Type=</varname><option>forking</option> in the - service's unit file to support this mode of operation. systemd - will consider the service to be in the process of initialization - while the original program is still running. Once it exits - successfully and at least a process remains (and - <varname>RemainAfterExit=</varname><option>no</option>), the - service is considered started.</para> - - <para>Often a traditional daemon only consists of one process. - Therefore, if only one process is left after the original - process terminates, systemd will consider that process the main - process of the service. In that case, the - <varname>$MAINPID</varname> variable will be available in - <varname>ExecReload=</varname>, <varname>ExecStop=</varname>, - etc.</para> - - <para>In case more than one process remains, systemd will be - unable to determine the main process, so it will not assume - there is one. In that case, <varname>$MAINPID</varname> will not - expand to anything. However, if the process decides to write a - traditional PID file, systemd will be able to read the main PID - from there. Please set <varname>PIDFile=</varname> accordingly. - Note that the daemon should write that file before finishing - with its initialization, otherwise systemd might try to read the - file before it exists.</para> - - <para>The following example shows a simple daemon that forks and - just starts one process in the background:</para> - - <programlisting>[Unit] -Description=Some simple daemon - -[Service] -Type=forking -ExecStart=/usr/sbin/my-simple-daemon -d - -[Install] -WantedBy=multi-user.target</programlisting> - - <para>Please see - <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details on how you can influence the way systemd terminates - the service.</para> - </example> - - <example> - <title>DBus services</title> - - <para>For services that acquire a name on the DBus system bus, - use <varname>Type=</varname><option>dbus</option> and set - <varname>BusName=</varname> accordingly. The service should not - fork (daemonize). systemd will consider the service to be - initialized once the name has been acquired on the system bus. - The following example shows a typical DBus service:</para> - - <programlisting>[Unit] -Description=Simple DBus service - -[Service] -Type=dbus -BusName=org.example.simple-dbus-service -ExecStart=/usr/sbin/simple-dbus-service - -[Install] -WantedBy=multi-user.target</programlisting> - - <para>For <emphasis>bus-activatable</emphasis> services, don't - include a <literal>[Install]</literal> section in the systemd - service file, but use the <varname>SystemdService=</varname> - option in the corresponding DBus service file, for example - (<filename>/usr/share/dbus-1/system-services/org.example.simple-dbus-service.service</filename>):</para> - - <programlisting>[D-BUS Service] -Name=org.example.simple-dbus-service -Exec=/usr/sbin/simple-dbus-service -User=root -SystemdService=simple-dbus-service.service</programlisting> - - <para>Please see - <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details on how you can influence the way systemd terminates - the service.</para> - </example> - - <example> - <title>Services that notify systemd about their initialization</title> - - <para><varname>Type=</varname><option>simple</option> services - are really easy to write, but have the major disadvantage of - systemd not being able to tell when initialization of the given - service is complete. For this reason, systemd supports a simple - notification protocol that allows daemons to make systemd aware - that they are done initializing. Use - <varname>Type=</varname><option>notify</option> for this. A - typical service file for such a daemon would look like - this:</para> - - <programlisting>[Unit] -Description=Simple notifying service - -[Service] -Type=notify -ExecStart=/usr/sbin/simple-notifying-service - -[Install] -WantedBy=multi-user.target</programlisting> - - <para>Note that the daemon has to support systemd's notification - protocol, else systemd will think the service hasn't started yet - and kill it after a timeout. For an example of how to update - daemons to support this protocol transparently, take a look at - <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - systemd will consider the unit to be in the 'starting' state - until a readiness notification has arrived.</para> - - <para>Please see - <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details on how you can influence the way systemd terminates - the service.</para> - </example> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</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> |