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> and
- <literal>%I</literal>, for the full unit name, the
- unescaped unit name, the prefix name, the unescaped
- prefix name and the unescaped instance name,
- respectively. 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>
+ </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>
+ its configuration will not be loaded and it appears
+ with a load state of <literal>masked</literal>, and
+ cannot be activated. Use this as an effective way to
+ fully disable a unit, making it impossible to start it
+ even manually.</para>
+
+ <para>The unit file format is covered by the
+ <ulink
+ url="http://www.freedesktop.org/wiki/Software/systemd/InterfaceStabilityPromise">Interface
+ Stability Promise</ulink>.</para>
</refsect1>
<refsect1>
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>
services.</para></listitem>
</varlistentry>
-
<varlistentry>
<term><varname>RequiresOverridable=</varname></term>
details see above.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>BindTo=</varname></term>
+
+ <listitem><para>Configures requirement
+ dependencies, very similar in style to
+ <varname>Requires=</varname>, however
+ in addition to this behaviour it also
+ declares that this unit is stopped
+ when any of the units listed suddenly
+ disappears. Units can suddenly,
+ unexpectedly disappear if a service
+ terminates on its own choice, a device
+ is unplugged or a mount point
+ unmounted without involvement of
+ systemd.</para></listitem>
+ </varlistentry>
+
<varlistentry>
<term><varname>Conflicts=</varname></term>
<listitem><para>Lists one or more
units that are activated when this
- unit fails (i.e. enters maintenance
- state).</para></listitem>
+ unit enters the
+ '<literal>failed</literal>'
+ state.</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>RecursiveStop=</varname></term>
+ <term><varname>IgnoreOnIsolate=</varname></term>
<listitem><para>Takes a boolean
- argument. If <option>true</option> and
- the unit stops without 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 a user request,
- units depending on it will not be
- terminated. Only if the user requested
- shutdown of a unit, all units depending
- on that unit will be shut down as well
- and at the same time. Defaults to
+ 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>
<varlistentry>
- <term><varname>OnlyByDependency=</varname></term>
+ <term><varname>RefuseManualStart=</varname></term>
+ <term><varname>RefuseManualStop=</varname></term>
<listitem><para>Takes a boolean
argument. If <option>true</option>
this unit can only be activated
- indirectly. In this case explicit
- start-up requested by the user is
- denied, however if it is started as a
+ (resp. deactivated) indirectly. In
+ this case explicit start-up
+ (resp. termination) requested by the
+ user is denied, however if it is
+ started (resp. stopped) as a
dependency of another unit, start-up
- will succeed. This is mostly a safety
- feature to ensure that the user does
- not accidentally activate units that are
- not intended to be activated
- explicitly. This option defaults to
+ (resp. termination) will succeed. This
+ is mostly a safety feature to ensure
+ that the user does not accidentally
+ activate units that are not intended
+ to be activated explicitly, and not
+ accidentally deactivate units that are
+ not intended to be deactivated.
+ These options default to
+ <option>false</option>.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>AllowIsolate=</varname></term>
+
+ <listitem><para>Takes a boolean
+ argument. If <option>true</option>
+ this unit may be used with the
+ <command>systemctl isolate</command>
+ command. Otherwise this will be
+ refused. It probably is a good idea to
+ leave this disabled except for target
+ units that shall be used similar to
+ runlevels in SysV init systems, just
+ as a precaution to avoid unusable
+ system states. This option defaults to
<option>false</option>.</para></listitem>
</varlistentry>
ones.</para></listitem>
</varlistentry>
- <varlistentry>
- <term><varname>IgnoreDependencyFailure=</varname></term>
-
- <listitem><para>Takes a boolean
- argument. If <option>true</option> and
- a requirement dependency of this unit
- fails to start up this unit will be
- started nonetheless, ignoring that
- failure. If <option>false</option>
- (the default) and a dependency unit
- fails the unit will immediately fail
- too and the job is removed.</para></listitem>
- </varlistentry>
-
<varlistentry>
<term><varname>JobTimeoutSec=</varname></term>
time. If this time limit is reached
the job will be cancelled, the unit
however will not change state or even
- enter maintenance mode. This value
- defaults to 0 (job timeouts disabled),
- except for device units. NB: this
- timeout is independent from any
- unit-specific timeout (for example,
- the timeout set with
+ enter the '<literal>failed</literal>'
+ mode. This value defaults to 0 (job
+ timeouts disabled), except for device
+ units. NB: this timeout is independent
+ from any unit-specific timeout (for
+ example, the timeout set with
<varname>Timeout=</varname> in service
- units) as the job timeout has no effect
- on the unit itself, only on the job
- that might be pending for it. Or in
- other words: unit-specific timeouts
+ units) as the job timeout has no
+ effect on the unit itself, only on the
+ job that might be pending for it. Or
+ in other words: unit-specific timeouts
are useful to abort unit state
changes, and revert them. The job
timeout set with this option however
- is useful to abort only the job waiting
- for the unit state to change.</para></listitem>
+ is useful to abort only the job
+ waiting for the unit state to
+ change.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>ConditionPathExists=</varname></term>
+ <term><varname>ConditionPathExistsGlob=</varname></term>
+ <term><varname>ConditionPathIsDirectory=</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>ConditionNull=</varname></term>
+
+ <listitem><para>Before starting a unit
+ verify that the specified condition is
+ true. With
+ <varname>ConditionPathExists=</varname>
+ 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
+ actually happen, however the unit is
+ still useful for ordering purposes in
+ this case. The condition is checked at
+ the time the queued start job is to be
+ executed. If the absolute path name
+ passed to
+ <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
+ 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>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>
+ may be used to check whether a
+ specific kernel command line option is
+ set (or if prefixed with the
+ exclamation mark unset). The argument
+ must either be a single word, or an
+ 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,
+ or as left hand side of an
+ assignment. In the latter case the
+ exact assignment is looked for with
+ right and left hand side
+ 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 virtual environment or one of the
+ <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
+ 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. Finally,
+ <varname>ConditionNull=</varname> may
+ be used to add a constant condition
+ check value to the unit. It takes a
+ boolean argument. If set to
+ <varname>false</varname> the condition
+ will always fail, otherwise
+ succeed. If multiple conditions are
+ 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.</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>
+ </varlistentry>
</variablelist>
<para>Unit file may include a [Install] section, which
~ianmdlvl / elogind.git / blobdiff