-<?xml version='1.0'?> <!--*-nxml-*-->
+<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-<!ENTITY % entities SYSTEM "custom-entities.ent" >
-%entities;
-]>
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
This file is part of systemd.
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
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>
+ with SysV</ulink> document.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Automatic Dependencies</title>
+
+ <para>Services with <varname>Type=dbus</varname> set automatically
+ acquire dependencies of type <varname>Requires=</varname> and
+ <varname>After=</varname> on
+ <filename>dbus.socket</filename>.</para>
+
+ <para>Socket activated service are automatically ordered after
+ their activated <filename>.socket</filename> units via an
+ automatic <varname>After=</varname> dependency.</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>sysinit.target</filename>,
+ a dependency of type <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>Additional implicit dependencies may be added as result of
+ execution and resource control parameters as documented in
+ <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ and
+ <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
</refsect1>
<refsect1>
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>
+ systemd will not write to the file configured here, although
+ it will remove the file after the service has shut down if it
+ still exists.
+ </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>
+ <listitem><para>If specified, a custom kdbus
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.
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
+ "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>
<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
+ zero or more command lines according to the rules described
below (see section "Command Lines" below).
</para>
- <para>When <varname>Type</varname> is not
+ <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
<literal>-</literal>) fail, the rest are not executed and the
unit is considered failed.</para>
+ <para><varname>ExecStart=</varname> commands are only run after
+ all <varname>ExecStartPre=</varname> commands that were not prefixed
+ with a <literal>-</literal> exit successfully.</para>
+
+ <para><varname>ExecStartPost=</varname> commands are only run after
+ the service has started, as determined by <varname>Type=</varname>
+ (i.e. the process has been started for <varname>Type=simple</varname>
+ or <varname>Type=idle</varname>, the process exits successfully for
+ <varname>Type=oneshot</varname>, the initial process exits successfully
+ for <varname>Type=forking</varname>, <literal>READY=1</literal> is sent
+ for <varname>Type=notify</varname>, or the <varname>BusName=</varname>
+ has been taken for <varname>Type=dbus</varname>).</para>
+
<para>Note that <varname>ExecStartPre=</varname> may not be
used to start long-running processes. All processes forked
off by processes invoked via <varname>ExecStartPre=</varname> will
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>
+ If this option is not specified, the process is terminated by
+ sending the signal specified in <varname>KillSignal=</varname>
+ when service stop is requested. Specifier and environment
+ variable substitution is supported (including
+ <varname>$MAINPID</varname>, see above).</para>
+
+ <para>Note that it is usually not sufficient to specify a
+ command for this setting that only asks the service to
+ terminate (for example, by queuing some form of termination
+ signal for it), but does not wait for it to do so. Since the
+ remaining processes of the services are killed using
+ <constant>SIGKILL</constant> immediately after the command
+ exited, this would not result in a clean stop. The specified
+ command should hence be a synchronous operation, not an
+ asynchronous one.</para></listitem>
</varlistentry>
<varlistentry>
<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
+ <varname>ExecStart=</varname>. Use of these settings is
optional. Specifier and environment variable substitution is
supported.</para></listitem>
</varlistentry>
"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
+ <constant>SIGABRT</constant>. 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
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>
+ Defaults to 0, which disables this feature. The service can
+ check whether the service manager expects watchdog keep-alive
+ notifications. See
+ <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ for details.
+ </para></listitem>
</varlistentry>
<varlistentry>
</tgroup>
</table>
- <para>As exceptions to the setting above the service will not
+ <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
<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
+ <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
<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
+ <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
<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
+ <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
<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
+ 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>
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
+ 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
<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,
+ system call, which might result in data loss. Similarly,
<option>poweroff</option>, <option>poweroff-force</option>,
<option>poweroff-immediate</option> have the effect of
powering down the system with similar semantics. Defaults to
and no job queued or being executed for it.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>USBFunctionDescriptors=</varname></term>
+ <listitem><para>Configure the location of a file containing
+ <ulink
+ url="https://www.kernel.org/doc/Documentation/usb/functionfs.txt">USB
+ FunctionFS</ulink> descriptors, for implementation of USB
+ gadget functions. This is used only in conjunction with a
+ socket unit with <varname>ListenUSBFunction=</varname>
+ configured. The contents of this file are written to the
+ <filename>ep0</filename> file after it is
+ opened.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>USBFunctionStrings=</varname></term>
+ <listitem><para>Configure the location of a file containing
+ USB FunctionFS strings. Behavior is similar to
+ <varname>USBFunctionDescriptors=</varname>
+ above.</para></listitem>
+ </varlistentry>
+
</variablelist>
<para>Check
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
+ supported. The table below contains the list of allowed escape
+ patterns. Only patterns which match the syntax in the table are
+ allowed; others will result in an error, and must be escaped by
+ doubling the backslash. Quotes themselves are removed after
parsing and escape sequences substituted. In addition, a trailing
backslash (<literal>\</literal>) may be used to merge lines.
</para>
<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
+ <para>The command to execute must be an absolute path name. It may
contain spaces, but control characters are not allowed.</para>
<para>The command line accepts <literal>%</literal> specifiers as
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
+ variable split at whitespace, resulting in zero or more arguments.
+ For this type of expansion, quotes are respected when splitting
into words, and afterwards removed.</para>
<para>Example:</para>
<example>
<title>Oneshot service</title>
- <para>Sometimes units should just execute an action without
+ <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
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
+ 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
+ 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>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
+ 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
+ case is if a oneshot service shall not be executed each time
when they are pulled in as a dependency, but only the first
time.</para>
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
+ <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
+ <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>
<varname>RemainAfterExit=</varname><option>no</option>), the
service is considered started.</para>
- <para>Often a traditional daemon only consists of one process.
+ <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
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
+ 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
[Install]
WantedBy=multi-user.target</programlisting>
- <para>For <emphasis>bus-activatable</emphasis> services, don't
+ <para>For <emphasis>bus-activatable</emphasis> services, do not
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
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
+ protocol, else systemd will think the service has not 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>.
projects / thirdparty / systemd.git / blobdiff