Copyright 2010 Lennart Poettering
systemd is free software; you can redistribute it and/or modify it
- under the terms of the GNU General Public License as published by
- the Free Software Foundation; either version 2 of the License, or
+ under the terms of the GNU Lesser General Public License as published by
+ the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.
systemd is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- General Public License for more details.
+ Lesser General Public License for more details.
- You should have received a copy of the GNU General Public License
+ You should have received a copy of the GNU Lesser General Public License
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
<refnamediv>
<refname>systemd.service</refname>
- <refpurpose>systemd service configuration files</refpurpose>
+ <refpurpose>Service unit configuration</refpurpose>
</refnamediv>
<refsynopsisdiv>
- <para><filename>systemd.service</filename></para>
+ <para><filename><replaceable>service</replaceable>.service</filename></para>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
- <para>A configuration file ending in .service encodes
- information about a process controlled and supervised
- by systemd.</para>
+ <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.</para>
+ 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>
- <variablelist>
+ <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>One of
- <literal>forking</literal>,
- <literal>simple</literal>,
- <literal>finish</literal>,
- <literal>dbus</literal>.</para>
-
- <para>If set to
- <literal>forking</literal>
- (the default) it is expected
- that the process configured
- with
- <varname>ExecStart=</varname>
- will start up and call
- <function>fork()</function>. The
- parent process is expected to
- finish when start-up is
- complete and all communication
- channels set up. The child
- continues to run as the main
- daemon process. This is the
- behaviour 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
- starting follow-up units as soon
- as the parent process exits.</para>
-
- <para>If set to
- <literal>simple</literal> (the
- recommended value) it is
- expected that the process
- configured with
- <varname>ExecStart=</varname>
- is the main process of the
- daemon. In this mode,
- communication channels must be
- available before the daemon is
- started up (sockets set up by systemd),
- as systemd will immediately proceed
- starting follow-up units.</para>
-
- <para>Behaviour of
- <literal>finish</literal> is
- similar to
- <literal>simple</literal>,
- however it is expected that
- the process has to exit before
- systemd starts follow-up
- units. <varname>ValidNoProcess=</varname>
- is particularly useful for
- this type of service.</para>
-
- <para>Behaviour of
- <literal>dbus</literal> is
- similar to
- <literal>simple</literal>,
- however it is expected that
- the daemon acquires a name on
- the D-Bus bus, as configured
- by
- <varname>BusName=</varname>. Systemd will
- proceed starting follow-up
- units after the D-Bus bus name has been
- acquired.</para>
+
+ <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>ValidNoProcess=</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 <literal>no</literal>.</para>
+ <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
- <literal>forking</literal>.</para>
+
+ <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,
- where this service is reachable
- as. This option is mandatory
- for services where
- <varname>Type=</varname> is
- set to
- <literal>dbus</literal>, but
- its use is otherwise
- recommended as well if the
- process takes a name on the
- D-Bus bus.</para>
+
+ <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>Takes a command line
- that is executed when this
- service shall be started
- up. The first word of the
- command line must be an
- absolute file name. It is
- mandatory to set this option
- for all services.</para>
+ <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>Example:</para>
+ <programlisting>Environment=ONE='one' "TWO='two two' too" THREE=
+ExecStart=/bin/echo ${ONE} ${TWO} ${THREE}
+ExecStart=/bin/echo $ONE $TWO $THREE</programlisting>
+ <para>This results in <filename>echo</filename> being
+ called twice, the first time with arguments
+ <literal>'one'</literal>,
+ <literal>'two two' too</literal>, <literal></literal>,
+ and the second time with arguments
+ <literal>one</literal>, <literal>two two</literal>,
+ <literal>too</literal>.
+ </para>
+
+ <para>To pass a literal dollar sign, use
+ <literal>$$</literal>. Variables whose value is not
+ known at expansion time are treated as empty
+ strings. Note that the first argument (i.e. the
+ program to execute) may not be a variable.</para>
+
+ <para>Variables to be used in this fashion may be
+ defined through <varname>Environment=</varname> and
+ <varname>EnvironmentFile=</varname>. In addition,
+ variables listed in the section "Environment variables
+ in spawned processes" in
+ <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ which are considered "static configuration", may be
+ used (this includes e.g. <varname>$USER</varname>, but
+ not <varname>$TERM</varname>).</para>
+
+ <para>Note that shell command lines are not directly
+ supported. If shell command lines are to be used, they
+ need to be passed explicitly to a shell implementation
+ of some kind. Example:</para>
+ <programlisting>ExecStart=/bin/sh -c 'dmesg | tac'</programlisting>
+
+ <para>Example:</para>
+
+ <programlisting>ExecStart=/bin/echo one ; /bin/echo "two two"</programlisting>
+
+ <para>This will execute <command>/bin/echo</command>
+ two times, each time with one argument:
+ <literal>one</literal> and <literal>two two</literal>,
+ respectively. Because two commands are specified,
+ <varname>Type=oneshot</varname> must be used.</para>
+
+ <para>Example:</para>
+
+ <programlisting>ExecStart=/bin/echo / >/dev/null & \; \
+/bin/ls</programlisting>
+
+ <para>This will execute <command>/bin/echo</command>
+ with five arguments: <literal>/</literal>,
+ <literal>>/dev/null</literal>,
+ <literal>&</literal>, <literal>;</literal>, and
+ <literal>/bin/ls</literal>.</para>
+
+ <table>
+ <title>C escapes supported in command lines and environment variables</title>
+ <tgroup cols='2'>
+ <colspec colname='escape' />
+ <colspec colname='meaning' />
+ <thead>
+ <row>
+ <entry>Literal</entry>
+ <entry>Actual value</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>\a</literal></entry>
+ <entry>bell</entry>
+ </row>
+ <row>
+ <entry><literal>\b</literal></entry>
+ <entry>backspace</entry>
+ </row>
+ <row>
+ <entry><literal>\f</literal></entry>
+ <entry>form feed</entry>
+ </row>
+ <row>
+ <entry><literal>\n</literal></entry>
+ <entry>newline</entry>
+ </row>
+ <row>
+ <entry><literal>\r</literal></entry>
+ <entry>carriage return</entry>
+ </row>
+ <row>
+ <entry><literal>\t</literal></entry>
+ <entry>tab</entry>
+ </row>
+ <row>
+ <entry><literal>\v</literal></entry>
+ <entry>vertical tab</entry>
+ </row>
+ <row>
+ <entry><literal>\\</literal></entry>
+ <entry>backslash</entry>
+ </row>
+ <row>
+ <entry><literal>\"</literal></entry>
+ <entry>double quotation mark</entry>
+ </row>
+ <row>
+ <entry><literal>\'</literal></entry>
+ <entry>single quotation mark</entry>
+ </row>
+ <row>
+ <entry><literal>\s</literal></entry>
+ <entry>space</entry>
+ </row>
+ <row>
+ <entry><literal>\x<replaceable>xx</replaceable></literal></entry>
+ <entry>character number <replaceable>xx</replaceable> in hexadecimal encoding</entry>
+ </row>
+ <row>
+ <entry><literal>\<replaceable>nnn</replaceable></literal></entry>
+ <entry>character number <replaceable>nnn</replaceable> in octal encoding</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </refsect1>
+
+ <refsect1>
+ <title>Examples</title>
+
+ <example>
+ <title>Simple service</title>
+
+ <para>The following unit file creates a service
+ that will execute
+ <filename>/usr/sbin/foo-daemon</filename>.
+ Since no <varname>Type=</varname> is specified,
+ the default
+ <varname>Type=</varname><option>simple</option>
+ will be assumed. systemd will assume the unit
+ to be started immediately after the program has
+ begun executing.</para>
+
+ <programlisting>[Unit]
+Description=Foo
+
+[Service]
+ExecStart=/usr/sbin/foo-daemon
+
+[Install]
+WantedBy=multi-user.target</programlisting>
+
+ <para>Note that systemd assumes here that the
+ process started by systemd will continue
+ running until the service terminates. If the
+ program daemonizes itself (i.e. forks), please
+ use
+ <varname>Type=</varname><option>forking</option>
+ instead.</para>
+
+ <para>Since no <varname>ExecStop=</varname> was
+ specified, systemd will send SIGTERM to all
+ processes started from this service, and after
+ a timeout also SIGKILL. This behavior can be
+ modified, see
+ <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for details.</para>
+
+ <para>Note that this unit type does not include
+ any type of notification when a service has
+ completed initialization. For this, you should
+ use other unit types, such as
+ <varname>Type=</varname><option>notify</option>
+ if the service understands systemd's
+ notification protocol,
+ <varname>Type=</varname><option>forking</option>
+ if the service can background itself or
+ <varname>Type=</varname><option>dbus</option>
+ if the unit acquires a DBus name once
+ initialization is complete. See below.</para>
+ </example>
+
+ <example>
+ <title>Oneshot service</title>
+
+ <para>Sometimes units should just execute an
+ action without keeping active processes, such
+ as a filesystem check or a cleanup action on
+ boot. For this,
+ <varname>Type=</varname><option>oneshot</option>
+ exists. Units of this type will wait until the
+ process specified terminates and then fall back
+ to being inactive. The following unit will
+ perform a clenaup action:</para>
+
+ <programlisting>[Unit]
+Description=Cleanup old Foo data
+
+[Service]
+Type=oneshot
+ExecStart=/usr/sbin/foo-cleanup
+
+[Install]
+WantedBy=multi-user.target</programlisting>
+
+ <para>Note that systemd will consider the unit
+ to be in the state 'starting' until the program
+ has terminated, so ordered dependencies will
+ wait for the program to finish before starting
+ themselves. The unit will revert to the
+ 'inactive' state after the execution is
+ done, never reaching the 'active' state. That
+ means another request to start the unit will
+ perform the action again.</para>
+
+ <para><varname>Type=</varname><option>oneshot</option>
+ are the only service units that may have more
+ than one <varname>ExecStart=</varname>
+ specified. They will be executed in order until
+ either they are all successful or one of them
+ fails.</para>
+ </example>
+
+ <example>
+ <title>Stoppable oneshot service</title>
+
+ <para>Similarly to the oneshot services, there
+ are sometimes units that need to execute a
+ program to set up something and then execute
+ another to shut it down, but no process remains
+ active while they are considered
+ 'started'. Network configuration can sometimes
+ fall into this category. Another use case is if
+ a oneshot service shall not be executed a
+ each time when they are pulled in as a
+ dependency, but only the first time.</para>
+
+ <para>For this, systemd knows the setting
+ <varname>RemainAfterExit=</varname><option>yes</option>,
+ which causes systemd to consider the unit to be
+ active if the start action exited successfully.
+ This directive can be used with all types, but
+ is most useful with
+ <varname>Type=</varname><option>oneshot</option>
+ and
+ <varname>Type=</varname><option>simple</option>.
+ With
+ <varname>Type=</varname><option>oneshot</option>
+ systemd waits until the start action has
+ completed before it considers the unit to be
+ active, so dependencies start only after the
+ start action has succeeded. With
+ <varname>Type=</varname><option>simple</option>
+ dependencies will start immediately after the
+ start action has been dispatched. The following
+ unit provides an example for a simple static
+ firewall.</para>
+
+ <programlisting>[Unit]
+Description=Simple firewall
+
+[Service]
+Type=oneshot
+RemainAfterExit=yes
+ExecStart=/usr/local/sbin/simple-firewall-start
+ExecStop=/usr/local/sbin/simple-firewall-stop
+
+[Install]
+WantedBy=multi-user.target</programlisting>
+
+ <para>Since the unit is considered to be
+ running after the start action has exited,
+ invoking <command>systemctl start</command> on
+ that unit again will cause no action to be
+ taken.</para>
+ </example>
+
+ <example>
+ <title>Traditional forking services</title>
+
+ <para>Many traditional daemons/services
+ background (i.e. fork, daemonize) themselves
+ when starting. Set
+ <varname>Type=</varname><option>forking</option>
+ in the service's unit file to support this mode
+ of operation. systemd will consider the service
+ to be in the process of initialization while
+ the original program is still running. Once
+ it exits successfully and at least a process
+ remains (and
+ <varname>RemainAfterExit=</varname><option>no</option>),
+ the service is considered started.</para>
+
+ <para>Often a traditional daemon only consists
+ of one process. Therefore, if only one process
+ is left after the original process terminates,
+ systemd will consider that process the main
+ process of the service. In that case, the
+ <varname>$MAINPID</varname> variable will be
+ available in <varname>ExecReload=</varname>,
+ <varname>ExecStop=</varname>, etc.</para>
+
+ <para>In case more than one process remains,
+ systemd will be unable to determine the main
+ process, so it will not assume there is one.
+ In that case, <varname>$MAINPID</varname> will
+ not expand to anything. However, if the process
+ decides to write a traditional PID file,
+ systemd will be able to read the main PID from
+ there. Please set <varname>PIDFile=</varname>
+ accordingly. Note that the daemon should write
+ that file before finishing with its
+ initialization, otherwise systemd might try to
+ read the file before it exists.</para>
+
+ <para>The following example shows a simple
+ daemon that forks and just starts one process
+ in the background:</para>
+
+ <programlisting>[Unit]
+Description=Some simple daemon
+
+[Service]
+Type=forking
+ExecStart=/usr/sbin/my-simple-daemon -d
+
+[Install]
+WantedBy=multi-user.target</programlisting>
+
+ <para>Please see
+ <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for details on how you can influence the way
+ systemd terminates the service.</para>
+ </example>
+
+ <example>
+ <title>DBus services</title>
+
+ <para>For services that acquire a name on the
+ DBus system bus, use
+ <varname>Type=</varname><option>dbus</option>
+ and set <varname>BusName=</varname>
+ accordingly. The service should not fork
+ (daemonize). systemd will consider the service
+ to be initialized once the name has been
+ acquired on the system bus. The following
+ example shows a typical DBus service:</para>
+
+ <programlisting>[Unit]
+Description=Simple DBus service
+
+[Service]
+Type=dbus
+BusName=org.example.simple-dbus-service
+ExecStart=/usr/sbin/simple-dbus-service
+
+[Install]
+WantedBy=multi-user.target</programlisting>
+
+ <para>For <emphasis>bus-activatable</emphasis>
+ services, don't include a
+ <literal>[Install]</literal> section in the
+ systemd service file, but use the
+ <varname>SystemdService=</varname> option in
+ the corresponding DBus service file, for
+ example
+ (<filename>/usr/share/dbus-1/system-services/org.example.simple-dbus-service.service</filename>):</para>
+
+ <programlisting>[D-BUS Service]
+Name=org.example.simple-dbus-service
+Exec=/usr/sbin/simple-dbus-service
+User=root
+SystemdService=simple-dbus-service.service</programlisting>
+
+ <para>Please see
+ <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for details on how you can influence the way
+ systemd terminates the service.</para>
+ </example>
+
+ <example>
+ <title>Services that notify systemd about their initialization</title>
+
+ <para><varname>Type=</varname><option>simple</option>
+ services are really easy to write, but have the
+ major disadvantage of systemd not being able to
+ tell when initialization of the given service
+ is complete. For this reason, systemd supports
+ a simple notification protocol that allows
+ daemons to make systemd aware that they are
+ done initializing. Use
+ <varname>Type=</varname><option>notify</option>
+ for this. A typical service file for such a
+ daemon would look like this:</para>
+
+ <programlisting>[Unit]
+Description=Simple notifying service
+
+[Service]
+Type=notify
+ExecStart=/usr/sbin/simple-notifying-service
+
+[Install]
+WantedBy=multi-user.target</programlisting>
+
+ <para>Note that the daemon has to support
+ systemd's notification protocol, else systemd
+ will think the service hasn't started yet and
+ kill it after a timeout. For an example of how
+ to update daemons to support this protocol
+ transparently, take a look at
+ <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
+ systemd will consider the unit to be in the
+ 'starting' state until a readiness notification
+ has arrived.</para>
+
+ <para>Please see
+ <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for details on how you can influence the way
+ systemd terminates the service.</para>
+ </example>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
- <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>
- <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ <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>
~ianmdlvl / elogind.git / blobdiff