summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLennart Poettering <lennart@poettering.net>2010-06-24 19:08:38 +0200
committerLennart Poettering <lennart@poettering.net>2010-06-24 19:08:38 +0200
commit11e299550e832659095d7bf833e4e8fc1971ef1e (patch)
tree01085fcc4a2419f01c0f9adc8273a23dd1bcaad4
parent436c44a5d64ef136ead64e9b03c8c05cc573a61b (diff)
man: finish systemd.unit.5
-rw-r--r--man/systemd.unit.xml376
1 files changed, 347 insertions, 29 deletions
diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index 7e657c64f7..99bd8b3906 100644
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -48,15 +48,15 @@
</refnamediv>
<refsynopsisdiv>
- <para><filename>systemd.service</filename></para>
- <para><filename>systemd.socket</filename></para>
- <para><filename>systemd.device</filename></para>
- <para><filename>systemd.mount</filename></para>
- <para><filename>systemd.automount</filename></para>
- <para><filename>systemd.swap</filename></para>
- <para><filename>systemd.target</filename></para>
- <para><filename>systemd.path</filename></para>
- <para><filename>systemd.timer</filename></para>
+ <para><filename>systemd.service</filename>,
+ <filename>systemd.socket</filename>,
+ <filename>systemd.device</filename>,
+ <filename>systemd.mount</filename>,
+ <filename>systemd.automount</filename>,
+ <filename>systemd.swap</filename>,
+ <filename>systemd.target</filename>,
+ <filename>systemd.path</filename>,
+ <filename>systemd.timer</filename></para>
</refsynopsisdiv>
<refsect1>
@@ -66,15 +66,74 @@
about a service, a socket, a device, a mount point, an
automount point, a swap file or partition, a start-up
target, a file system path or a timer controlled and
- supervised by <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>. The syntax is inspired by XDG
- <filename>.desktop</filename> files, which are in turn
- inspired by Microsoft Windows <filename>.ini</filename>
- files.</para>
+ supervised by
+ <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>. The
+ syntax is inspired by <ulink
+ url="http://standards.freedesktop.org/desktop-entry-spec/latest/">XDG
+ Desktop Entry Specificiation</ulink> <filename>.desktop</filename> files, which are in turn
+ inspired by Microsoft Windows
+ <filename>.ini</filename> files.</para>
<para>This man pages lists the common configuration
options of the all unit types. These options need to
- be configured either in the [Unit] resp. [Install]
+ be configured in the [Unit] resp. [Install]
section of the unit files.</para>
+
+ <para>In addition to the generic [Unit] and [Install]
+ sections described here each unit should have a
+ type-specific section, e.g. [Service] for a service
+ unit. See the respective man pages for more
+ information.</para>
+
+ <para>Unit files may contain additional options on top
+ of those listed here. If systemd encounters an unknown
+ option it will write a warning log message but
+ continue loading the unit. If an option is prefixed
+ with <option>X-</option> it is ignored completely by
+ systemd. Applications may use this to include
+ additional information in the unit files.</para>
+
+ <para>Boolean arguments used in unit files can be
+ written in various forms. For positive settings the
+ strings <option>1</option>, <option>yes</option>,
+ <option>true</option> and <option>on</option> are
+ equivalent. For negative settings the strings
+ <option>0</option>, <option>no</option>,
+ <option>false</option> and <option>off</option> are
+ equivalent.</para>
+
+ <para>Empty lines and lines starting with # or ; are
+ ignored. This may be used for commenting.</para>
+
+ <para>If a line starts with <option>.include</option>
+ followed by a file name the specified file will be
+ read as if its contents where listed in place of the
+ <option>.include</option> directive.</para>
+
+ <para>Along with a unit file
+ <filename>foo.service</filename> a directory
+ <filename>foo.service.wants/</filename> may exist. All
+ units symlinked from such a directory are implicitly
+ added as dependencies of type
+ <varname>Wanted=</varname> to the unit. This is useful
+ to hook units into the start-up of other units,
+ without having to modify their unit configuration
+ files. For details about the semantics of
+ <varname>Wanted=</varname> see below. The preferred
+ way to create symlinks in the
+ <filename>.wants/</filename> directory of a service is
+ with the
+ <citerefentry><refentrytitle>systemd-install</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ tool which reads information from the [Install]
+ section of unit files. (See below.)</para>
+
+ <para>Note that while systemd offers a flexible
+ dependency system between units it is recommended to
+ use this functionality only sparsely and instead rely
+ on techniques such as bus-based or socket-based
+ activation which makes dependencies implicit, which
+ both results in a simpler and more flexible
+ system.</para>
</refsect1>
<refsect1>
@@ -97,13 +156,23 @@
that this option is different from the
<varname>Alias=</varname> option from
the [Install] section mentioned
- below. See below for details</para>
+ below. See below for details.</para>
</listitem>
</varlistentry>
+
+ <varlistentry>
+ <term><varname>Description=</varname></term>
+ <listitem><para>A free-form string
+ describing the unit. This is intended for use
+ in UIs wanting to show
+ descriptive information along with the
+ unit name.</para></listitem>
+ </varlistentry>
+
<varlistentry>
<term><varname>Requires=</varname></term>
- <listitem><para>Requirement
+ <listitem><para>Configures requirement
dependencies on other units. If this
units get activated the units listed
here will be activated as well. If one
@@ -112,9 +181,224 @@
be deactivated. This option may be
specified more than once, in which
case requirement dependencies for all
- listed names are created.</para>
- </listitem>
+ listed names are created. Note that
+ requirement dependencies do not
+ influence the order in which services
+ are started or stopped. This has to be
+ configured independently with the
+ <varname>After=</varname> or
+ <varname>Before=</varname> options. If
+ a unit
+ <filename>foo.service</filename>
+ requires a unit
+ <filename>bar.service</filename> as
+ configured with
+ <varname>Requires=</varname> and no
+ ordering is configured with
+ <varname>After=</varname> or
+ <varname>Before=</varname>, then both
+ units will be started simultaneously
+ and without any delay between them if
+ <filename>foo.service</filename> is
+ activated. Often it is a better choice
+ to use <varname>Wants=</varname>
+ instead of
+ <varname>Requires=</varname> in order
+ to achieve a system that is more
+ robust when dealing with failing
+ services.</para></listitem>
</varlistentry>
+
+
+ <varlistentry>
+ <term><varname>RequiresOverridable=</varname></term>
+
+ <listitem><para>Similar to
+ <varname>Requires=</varname>.
+ Dependencies listed in
+ <varname>RequiresOverridable=</varname>
+ which cannot be fulfilled or fail to
+ start are ignored iff the startup was
+ explicitly requested by the user. If
+ the start-up was pulled in indirectly
+ by some dependency or automatic
+ start-up of units that is not
+ requested by the user this dependency
+ must be fulfilled and otherwise the
+ transaction fails. Hence, this option
+ may be used to configure dependencies
+ that are normally honoured unless the
+ user explicitly starts up the unit, in
+ which case whether they failed or not
+ is irrelevant.</para></listitem>
+
+ </varlistentry>
+ <varlistentry>
+ <term><varname>Requisite=</varname></term>
+ <term><varname>RequisiteOverridable=</varname></term>
+
+ <listitem><para>Similar to
+ <varname>Requires=</varname>
+ resp. <varname>RequiresOverridable=</varname>. However,
+ if a unit listed here is not started
+ already it will not be started and the
+ transaction fails
+ immediately.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>Wants=</varname></term>
+
+ <listitem><para>A weaker version of
+ <varname>Requires=</varname>. A unit
+ listed in this option will be started
+ if the configuring unit is. However,
+ it the listed unit fails to start up
+ or cannot be added to the transaction
+ this has no impact on the validity of
+ the transaction as a whole. This is
+ the recommended way to hook start-up
+ of one unit to the start-up of another
+ unit. Note that dependencies of this
+ type may also be configured outside of
+ the unit configuration file by
+ adding a symlink to a
+ <filename>.wants/</filename> directory
+ accompanying the unit file. For
+ details see above.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>Conflicts=</varname></term>
+
+ <listitem><para>Configures negative
+ requirement dependencies. If a unit
+ that has a
+ <varname>Conflicts=</varname> setting
+ on another unit starting the former
+ will stop the latter and vice
+ versa. Note that this setting is
+ independent of and orthogonal to the
+ <varname>After=</varname> and
+ <varname>Before=</varname> ordering
+ dependencies.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>Before=</varname></term>
+ <term><varname>After=</varname></term>
+
+ <listitem><para>Configures ordering
+ dependencies between units. If a unit
+ <filename>foo.service</filename>
+ contains a setting
+ <option>Before=bar.service</option>
+ and both units are being started
+ <filename>bar.service</filename>'s
+ start-up is delayed until
+ <filename>foo.service</filename> is
+ started up. Note that this setting is
+ independent of and orthogonal to the
+ requirement dependencies as configured
+ by <varname>Requires=</varname>. It is
+ a common pattern to include a unit
+ name in both the
+ <varname>After=</varname> and
+ <varname>Requires=</varname> option in
+ which case the unit listed will be
+ started before the unit that is
+ configured with these options. This
+ option may be specified more than
+ once, in which case ordering
+ dependencies for all listed names are
+ created. <varname>After=</varname> is
+ the inverse of
+ <varname>Before=</varname>, i.e. while
+ <varname>After=</varname> ensures that
+ the configured unit is started after
+ the listed unit finished starting up,
+ <varname>Before=</varname> ensures the
+ opposite, i.e. that the configured
+ unit is fully started up before the
+ listed unit is started. Note that when
+ two units with an ordering dependency
+ between them are shut down, the
+ inverse of of the start-up order is
+ applied. i.e. if a unit is configured
+ with <varname>After=</varname> on
+ another unit, the former is stopped
+ before the latter if both are shut
+ down. If one unit with an ordering
+ dependency on another unit is shut
+ down while the latter is started up,
+ the shut down is ordered before the
+ start-up regardless whether the
+ ordering dependency is actually of
+ type <varname>After=</varname> or
+ <varname>Before=</varname>. If two
+ units have no ordering dependencies
+ between them they are shut down
+ resp. started up simultaneously, and
+ no ordering takes
+ place. </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>RecursiveStop=</varname></term>
+
+ <listitem><para>Takes a boolean
+ argument. If <option>true</option> and
+ the unit stops without this being
+ requested by the user all units
+ depending on it will be stopped as
+ well. (e.g. if a service exits or
+ crashes on its own behalf, units using
+ it will be stopped) Note that normally
+ if a unit stops without user request
+ units depending on it will not be
+ terminated. Only if the user requested
+ shutdown of a unit all units depending
+ on the unit will be shut down as well
+ and at the same time. Defaults to
+ <option>false</option>.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>StopWhenUnneeded=</varname></term>
+
+ <listitem><para>Takes a boolean
+ argument. If <option>true</option>
+ this unit will be stopped when it is
+ no longer used. Note that in order to
+ minimize the work to be executed
+ systemd will by default not stop units
+ unless they are conflicting with other
+ units, or the user explicitly
+ requested their shut down. If this
+ option is set a unit will be
+ automatically cleaned up if no other
+ active unit requires it. Defaults to
+ <option>false</option>.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>OnlyByDependency=</varname></term>
+
+ <listitem><para>Takes a boolean
+ argument. If <option>true</option>
+ this unit may only be activated
+ indirectly. In this case explicit
+ start-up requested by the user is
+ denied, however if it is started as
+ dependency of another unit start-up
+ will succeed. This is mostly a safety
+ feature to ensure that the user does
+ not accidently activate units that are
+ not intended to be activated
+ explicitly. This option defaults to
+ <option>false</option>.</para></listitem>
+ </varlistentry>
+
</variablelist>
<para>Unit file may include a [Install] section, which
@@ -123,7 +407,7 @@
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
during runtime. It is used exclusively by the
<citerefentry><refentrytitle>systemd-install</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- during installation of a unit:</para>
+ tool during installation of a unit:</para>
<variablelist>
<varlistentry>
@@ -148,18 +432,52 @@
unconditionally if the unit is
loaded. The names from
<varname>Alias=</varname> apply only
- if the unit is actually installed with
- the <command>systemd-install</command>
+ if the unit has actually been
+ installed with the
+ <command>systemd-install</command>
tool. Also, if systemd searches for a
unit, it will discover symlinked alias
- names, but not names configured only
- with <varname>Names=</varname>. It is
- a common pattern to list a name in both
- options. In this case, a unit will be
- active under all names if installed,
- but also if not installed but
- requested
- explicitly.</para></listitem>
+ names as configured with
+ <varname>Alias=</varname>, but not
+ names configured with
+ <varname>Names=</varname> only. It is
+ a common pattern to list a name in
+ both options. In this case, a unit
+ will be active under all names if
+ installed, but also if not installed
+ but requested explicitly under its
+ main name.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>WantedBy=</varname></term>
+
+ <listitem><para>Installs a symlink in
+ the <filename>.wants/</filename>
+ subdirectory for a unit. This has the
+ effect that when the listed unit name
+ is activated the unit listing it is
+ activated
+ to. <command>WantedBy=foo.service</command>
+ in a service
+ <filename>bar.service</filename> is
+ mostly equivalent to
+ <command>Alias=foo.service.wants/bar.service</command>
+ in the same file.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>Also=</varname></term>
+
+ <listitem><para>Additional units to
+ install when this unit is
+ installed. If the user requests
+ installation of a unit with this
+ option configured
+ <command>systemd-install</command>
+ will automatically install units
+ listed in this option as
+ well.</para></listitem>
</varlistentry>
</variablelist>