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/>.
-->
<para>If a line starts with <option>.include</option>
followed by a file name, the specified file will be
- read as if its contents were listed in place of the
- <option>.include</option> directive.</para>
+ parsed at this point. Make sure that the file that is
+ included has the appropriate section headers before
+ any directives.</para>
<para>Along with a unit file
<filename>foo.service</filename> a directory
with the <command>enable</command> command of the
<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
tool which reads information from the [Install]
- section of unit files. (See below.)</para>
+ section of unit files. (See below.) A similar
+ functionality exists for <varname>Requires=</varname>
+ type dependencies as well, the directory suffix is
+ <filename>.requires/</filename> in this case.</para>
<para>Note that while systemd offers a flexible
dependency system between units it is recommended to
and no file by that name is found, systemd will look
for <filename>getty@.service</filename> and
instantiate a service from that configuration file if
- it is found. To refer to the instance string from
+ it is found.</para>
+
+ <para>To refer to the instance string from
within the configuration file you may use the special
<literal>%i</literal> specifier in many of the
- configuration options. Other specifiers that may be
- used are <literal>%n</literal>, <literal>%N</literal>,
- <literal>%p</literal>, <literal>%P</literal>,
- <literal>%I</literal> and <literal>%f</literal>, for
- the full unit name, the unescaped unit name, the
- prefix name, the unescaped prefix name, the unescaped
- instance name and the unescaped filename,
- respectively. The unescaped filename is either the
- unescaped instance name (if set) with / prepended (if
- necessary), or the prefix name similarly prepended
- with /. The prefix name here refers to the string
- before the @, i.e. "getty" in the example above, where
- "tty3" is the instance name.</para>
+ configuration options. Other specifiers exist, the
+ full list is:</para>
+
+ <table>
+ <title>Specifiers available in unit files</title>
+ <tgroup cols='3' align='left' colsep='1' rowsep='1'>
+ <colspec colname="spec" />
+ <colspec colname="mean" />
+ <colspec colname="detail" />
+ <thead>
+ <row>
+ <entry>Specifier</entry>
+ <entry>Meaning</entry>
+ <entry>Details</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>%n</literal></entry>
+ <entry>Full unit name</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry><literal>%N</literal></entry>
+ <entry>Unescaped full unit name</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry><literal>%p</literal></entry>
+ <entry>Prefix name</entry>
+ <entry>This refers to the string before the @, i.e. "getty" in the example above, where "tty3" is the instance name.</entry>
+ </row>
+ <row>
+ <entry><literal>%P</literal></entry>
+ <entry>Unescaped prefix name</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry><literal>%i</literal></entry>
+ <entry>Instance name</entry>
+ <entry>This is the string between the @ character and the suffix.</entry>
+ </row>
+ <row>
+ <entry><literal>%I</literal></entry>
+ <entry>Unescaped instance name</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry><literal>%f</literal></entry>
+ <entry>Unescaped file name</entry>
+ <entry>This is either the unescaped instance name (if set) with / prepended (if necessary), or the prefix name similarly prepended with /.</entry>
+ </row>
+ <row>
+ <entry><literal>%c</literal></entry>
+ <entry>Control group path of the unit</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry><literal>%r</literal></entry>
+ <entry>Root control group path of systemd</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry><literal>%R</literal></entry>
+ <entry>Parent directory of the root control group path of systemd</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry><literal>%t</literal></entry>
+ <entry>Runtime socket dir</entry>
+ <entry>This is either /run (for the system manager) or $XDG_RUNTIME_DIR (for user managers).</entry>
+ </row>
+ <row>
+ <entry><literal>%u</literal></entry>
+ <entry>User name</entry>
+ <entry>This is the name of the configured user of the unit, or (if none is set) the user running the systemd instance.</entry>
+ </row>
+ <row>
+ <entry><literal>%h</literal></entry>
+ <entry>User home directory</entry>
+ <entry>This is the home directory of the configured user of the unit, or (if none is set) the user running the systemd instance.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
<para>If a unit file is empty (i.e. has the file size
0) or is symlinked to <filename>/dev/null</filename>
dependent on the type of unit:</para>
<variablelist>
- <varlistentry>
- <term><varname>Names=</varname></term>
-
- <listitem><para>Additional names for
- this unit. The names listed here must
- have the same suffix (i.e. type) as
- the unit file name. This option may be
- specified more than once, in which
- case all listed names are used. Note
- that this option is different from the
- <varname>Alias=</varname> option from
- the [Install] section mentioned
- below. See below for details.</para>
- </listitem>
- </varlistentry>
<varlistentry>
<term><varname>Description=</varname></term>
name.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>Documentation=</varname></term>
+ <listitem><para>A space separated list
+ of URIs referencing documentation for
+ this unit or its
+ configuration. Accepted are only URIs
+ of the types
+ <literal>http://</literal>,
+ <literal>https://</literal>,
+ <literal>file:</literal>,
+ <literal>info:</literal>,
+ <literal>man:</literal>. For more
+ information about the syntax of these
+ URIs see
+ <citerefentry><refentrytitle>uri</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para></listitem>
+ </varlistentry>
+
<varlistentry>
<term><varname>Requires=</varname></term>
</varlistentry>
<varlistentry>
- <term><varname>BindTo=</varname></term>
+ <term><varname>BindsTo=</varname></term>
<listitem><para>Configures requirement
dependencies, very similar in style to
unexpectedly disappear if a service
terminates on its own choice, a device
is unplugged or a mount point
- unmounted with involvement of
+ unmounted without involvement of
systemd.</para></listitem>
</varlistentry>
state.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>PropagatesReloadTo=</varname></term>
+ <term><varname>ReloadPropagatedFrom=</varname></term>
+
+ <listitem><para>Lists one or more
+ units where reload requests on the
+ unit will be propagated to/on the
+ other unit will be propagated
+ from. Issuing a reload request on a
+ unit will automatically also enqueue a
+ reload request on all units that the
+ reload request shall be propagated to
+ via these two
+ settings.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>RequiresMountsFor=</varname></term>
+
+ <listitem><para>Takes a space
+ separated list of paths. Automatically
+ adds dependencies of type
+ <varname>Requires=</varname> and
+ <varname>After=</varname> for all
+ mount units required to access the
+ specified path.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>OnFailureIsolate=</varname></term>
+
+ <listitem><para>Takes a boolean
+ argument. If <option>true</option> the
+ unit listed in
+ <varname>OnFailure=</varname> will be
+ enqueued in isolation mode, i.e. all
+ units that are not its dependency will
+ be stopped. If this is set only a
+ single unit may be listed in
+ <varname>OnFailure=</varname>. Defaults
+ to
+ <option>false</option>.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>IgnoreOnIsolate=</varname></term>
+
+ <listitem><para>Takes a boolean
+ argument. If <option>true</option>
+ this unit will not be stopped when
+ isolating another unit. Defaults to
+ <option>false</option>.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>IgnoreOnSnapshot=</varname></term>
+
+ <listitem><para>Takes a boolean
+ argument. If <option>true</option>
+ this unit will not be included in
+ snapshots. Defaults to
+ <option>true</option> for device and
+ snapshot units, <option>false</option>
+ for the others.</para></listitem>
+ </varlistentry>
+
<varlistentry>
<term><varname>StopWhenUnneeded=</varname></term>
<varlistentry>
<term><varname>ConditionPathExists=</varname></term>
+ <term><varname>ConditionPathExistsGlob=</varname></term>
+ <term><varname>ConditionPathIsDirectory=</varname></term>
+ <term><varname>ConditionPathIsSymbolicLink=</varname></term>
+ <term><varname>ConditionPathIsMountPoint=</varname></term>
+ <term><varname>ConditionPathIsReadWrite=</varname></term>
<term><varname>ConditionDirectoryNotEmpty=</varname></term>
+ <term><varname>ConditionFileIsExecutable=</varname></term>
<term><varname>ConditionKernelCommandLine=</varname></term>
+ <term><varname>ConditionVirtualization=</varname></term>
+ <term><varname>ConditionSecurity=</varname></term>
+ <term><varname>ConditionCapability=</varname></term>
<term><varname>ConditionNull=</varname></term>
<listitem><para>Before starting a unit
verify that the specified condition is
true. With
<varname>ConditionPathExists=</varname>
- a file existance condition can be
+ a file existence condition can be
checked before a unit is started. If
the specified absolute path name does
- not exist startup of a unit will not
+ not exist, startup of a unit will not
actually happen, however the unit is
still useful for ordering purposes in
this case. The condition is checked at
<varname>ConditionPathExists=</varname>
is prefixed with an exclamation mark
(!), the test is negated, and the unit
- only started if the path does not
- exist. <varname>ConditionDirectoryNotEmpty=</varname>
+ is only started if the path does not
+ exist.
+ <varname>ConditionPathExistsGlob=</varname>
+ works in a similar way, but checks for
+ the existence of at least one file or
+ directory matching the specified
+ globbing
+ pattern. <varname>ConditionPathIsDirectory=</varname>
+ is similar to
+ <varname>ConditionPathExists=</varname>
+ but verifies whether a certain path
+ exists and is a
+ directory. <varname>ConditionPathIsSymbolicLink=</varname>
is similar to
<varname>ConditionPathExists=</varname>
- but verifies whether a cetrain path is
+ but verifies whether a certain path
+ exists and is a symbolic
+ link. <varname>ConditionPathIsMountPoint=</varname>
+ is similar to
+ <varname>ConditionPathExists=</varname>
+ but verifies whether a certain path
+ exists and is a mount
+ point. <varname>ConditionPathIsReadWrite=</varname>
+ is similar to
+ <varname>ConditionPathExists=</varname>
+ but verifies whether the underlying
+ file system is read and writable
+ (i.e. not mounted
+ read-only). <varname>ConditionFileIsExecutable=</varname>
+ is similar to
+ <varname>ConditionPathExists=</varname>
+ but verifies whether a certain path
+ exists, is a regular file and marked
+ executable.
+ <varname>ConditionDirectoryNotEmpty=</varname>
+ is similar to
+ <varname>ConditionPathExists=</varname>
+ but verifies whether a certain path
exists and is a non-empty
directory. Similarly
<varname>ConditionKernelCommandLine=</varname>
set (or if prefixed with the
exclamation mark unset). The argument
must either be a single word, or an
- assignment (i.e. two words, seperated
+ assignment (i.e. two words, separated
by the equality sign). In the former
case the kernel command line is
searched for the word appearing as is,
assignment. In the latter case the
exact assignment is looked for with
right and left hand side
- matching. Finally,
+ matching. <varname>ConditionVirtualization=</varname>
+ may be used to check whether the
+ system is executed in a virtualized
+ environment and optionally test
+ whether it is a specific
+ implementation. Takes either boolean
+ value to check if being executed in
+ any virtualized environment, or one of
+ <varname>vm</varname> and
+ <varname>container</varname> to test
+ against a specific type of
+ virtualization solution, or one of
+ <varname>qemu</varname>,
+ <varname>kvm</varname>,
+ <varname>vmware</varname>,
+ <varname>microsoft</varname>,
+ <varname>oracle</varname>,
+ <varname>xen</varname>,
+ <varname>bochs</varname>,
+ <varname>chroot</varname>,
+ <varname>openvz</varname>,
+ <varname>lxc</varname>,
+ <varname>lxc-libvirt</varname>,
+ <varname>systemd-nspawn</varname> to
+ test against a specific
+ implementation. If multiple
+ virtualization technologies are nested
+ only the innermost is considered. The
+ test may be negated by prepending an
+ exclamation mark.
+ <varname>ConditionSecurity=</varname>
+ may be used to check whether the given
+ security module is enabled on the
+ system. Currently the only recognized
+ value is <varname>selinux</varname>.
+ The test may be negated by prepending
+ an exclamation
+ mark. <varname>ConditionCapability=</varname>
+ may be used to check whether the given
+ capability exists in the capability
+ bounding set of the service manager
+ (i.e. this does not check whether
+ capability is actually available in
+ the permitted or effective sets, see
+ <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ for details). Pass a capability name
+ such as <literal>CAP_MKNOD</literal>,
+ possibly prefixed with an exclamation
+ mark to negate the check. Finally,
<varname>ConditionNull=</varname> may
be used to add a constant condition
check value to the unit. It takes a
<varname>false</varname> the condition
will always fail, otherwise
succeed. If multiple conditions are
- specified the unit will be executed
- iff at least one of them applies
- (i.e. a logical OR is
- applied).</para></listitem>
+ specified the unit will be executed if
+ all of them apply (i.e. a logical AND
+ is applied). Condition checks can be
+ prefixed with a pipe symbol (|) in
+ which case a condition becomes a
+ triggering condition. If at least one
+ triggering condition is defined for a
+ unit then the unit will be executed if
+ at least one of the triggering
+ conditions apply and all of the
+ non-triggering conditions. If you
+ prefix an argument with the pipe
+ symbol and an exclamation mark the
+ pipe symbol must be passed first, the
+ exclamation second. Except for
+ <varname>ConditionPathIsSymbolicLink=</varname>,
+ all path checks follow
+ symlinks.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>SourcePath=</varname></term>
+ <listitem><para>A path to a
+ configuration file this unit has been
+ generated from. This is primarily
+ useful for implementation of generator
+ tools that convert configuration from
+ an external configuration file format
+ into native unit files. Thus
+ functionality should not be used in
+ normal units.</para></listitem>
</varlistentry>
</variablelist>
time,
<command>systemctl enable</command>
will create symlinks from these names
- to the unit file name. Note that this
- is different from the
- <varname>Names=</varname> option from
- the [Unit] section mentioned above:
- The names from
- <varname>Names=</varname> apply
- unconditionally if the unit is
- loaded. The names from
- <varname>Alias=</varname> apply only
- if the unit has actually been
- installed with the
- <command>systemctl enable</command>
- command. Also, if systemd searches for a
- unit, it will discover symlinked alias
- 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>
+ to the unit file name.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>WantedBy=</varname></term>
+ <term><varname>RequiredBy=</varname></term>
<listitem><para>Installs a symlink in
the <filename>.wants/</filename>
+ resp. <filename>.requires/</filename>
subdirectory for a unit. This has the
effect that when the listed unit name
is activated the unit listing it is
<citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
</para>
</refsect1>
~ianmdlvl / elogind.git / blobdiff