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
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>, <literal>%f</literal>,
- <literal>%c</literal>, <literal>%r</literal>,
- <literal>%R</literal> and <literal>%t</literal> for
- the full unit name, the unescaped unit name, the
- prefix name, the unescaped prefix name, the unescaped
- instance name, the unescaped filename, the control
- group path of the unit, the root control group path of
- systemd, and the parent directory of the root control
- cgroup path of systemd and the runtime socket dir,
- 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. The runtime socket
- directory is either <filename>/run</filename> (for the
- system manager) or <literal>$XDG_RUNTIME_DIR</literal>
- (for user managers).</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>
+ </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>
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>
state.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>PropagateReloadTo=</varname></term>
+ <term><varname>PropagateReloadFrom=</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>
argument. If <option>true</option>
this unit will not be included in
snapshots. Defaults to
- <option>false</option> for device and
- snapshot units, <option>true</option>
+ <option>true</option> for device and
+ snapshot units, <option>false</option>
for the others.</para></listitem>
</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
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>ConditionPathExistsGlob=</varname>
- work in a similar way, but checks for
- the existance of at least one file or
+ 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.
+ exists and is a
+ directory. <varname>ConditionPathIsSymbolicLink=</varname>
+ is similar to
+ <varname>ConditionPathExists=</varname>
+ 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>
whether it is a specific
implementation. Takes either boolean
value to check if being executed in
- any virtual environment or one of the
+ 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>pidns</varname>,
- <varname>openvz</varname> to test
- against a specific implementation. The
+ <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>
system. Currently the only recognized
value is <varname>selinux</varname>.
The test may be negated by prepending
- an exclamation mark. Finally,
+ 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
prefix an argument with the pipe
symbol and an exclamation mark the
pipe symbol must be passed first, the
- exclamation second.</para></listitem>
+ exclamation second. Except for
+ <varname>ConditionPathIsSymbolicLink=</varname>,
+ all path checks follow
+ symlinks.</para></listitem>
</varlistentry>
<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. Note
- that in almost all cases this option
- is not what you want. A symlink alias
- in the file system is generally
- preferable since it can be used as
- lookup key. If a unit with a symlinked
- alias name is not loaded and needs to
- be it is easily found via the
- symlink. However, if a unit with an
- alias name configured with this
- setting is not loaded it will not be
- discovered. This settings' only use is
- in conjunction with service
- instances.</para>
- </listitem>
+ <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>