diff options
Diffstat (limited to 'man/systemd.service.xml')
| -rw-r--r-- | man/systemd.service.xml | 2821 |
1 files changed, 1247 insertions, 1574 deletions
diff --git a/man/systemd.service.xml b/man/systemd.service.xml index f33e8df056..37d9e98219 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -1,7 +1,7 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,1357 +23,1069 @@ --> <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> - </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' + <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> + </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>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= + <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 & \; \ + <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] + <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] @@ -1382,50 +1094,42 @@ 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] + <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] @@ -1435,60 +1139,50 @@ 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] + <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] @@ -1500,56 +1194,46 @@ 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] + <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] @@ -1559,26 +1243,23 @@ 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] + <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] @@ -1589,43 +1270,38 @@ 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> + <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] + <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] + <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] @@ -1635,35 +1311,32 @@ 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> + <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> |