<filename>systemd.swap</filename>,
<filename>systemd.target</filename>,
<filename>systemd.path</filename>,
- <filename>systemd.timer</filename></para>
+ <filename>systemd.timer</filename>,
+ <filename>systemd.snapshot</filename></para>
</refsynopsisdiv>
<refsect1>
<filename>.ini</filename> files.</para>
<para>This man pages lists the common configuration
- options of the all unit types. These options need to
+ options of all the unit types. These options need to
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
+ 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>
additional information in the unit files.</para>
<para>Boolean arguments used in unit files can be
- written in various forms. For positive settings the
+ written in various formats. 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>false</option> and <option>off</option> are
equivalent.</para>
+ <para>Time span values encoded in unit files can be
+ written in various formats. A stand-alone number
+ specifies a time in seconds. If suffixed with a time
+ unit, the unit is honored. A concatenation of
+ multiple values with units is supported, in which case
+ the values are added up. Example: "50" refers to 50
+ seconds; "2min 200ms" refers to 2 minutes plus 200
+ milliseconds, i.e. 120200ms. The following time units
+ are understood: s, min, h, d, w, ms, us.</para>
+
<para>Empty lines and lines starting with # or ; are
- ignored. This may be used for commenting.</para>
+ ignored. This may be used for commenting. Lines ending
+ in a backslash are concatenated with the following
+ line while reading and the backslash is replaced by a
+ space character. This may be used to wrap long lines.</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
+ 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>
<para>Along with a unit file
<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>
+ 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>
activation which makes dependencies implicit, which
both results in a simpler and more flexible
system.</para>
+
+ <para>Some unit names reflect paths existing in the
+ file system name space. Example: a device unit
+ <filename>dev-sda.device</filename> refers to a device
+ with the device node <filename>/dev/sda</filename> in
+ the file system namespace. If this applies a special
+ way to escape the path name is used, so that the
+ result is usable as part of a file name. Basically,
+ given a path, "/" is replaced by "-", and all
+ unprintable characters and the "-" are replaced by
+ C-style "\x20" escapes. The root directory "/" is
+ encoded as single dash, while otherwise the initial
+ and ending "/" is removed from all paths during
+ transformation. This escaping is reversible.</para>
+
+ <para>Optionally, units may be instantiated from a
+ template file at runtime. This allows creation of
+ multiple units from a single configuration file. If
+ systemd looks for a unit configuration file it will
+ first search for the literal unit name in the
+ filesystem. If that yields no success and the unit
+ name contains an @ character, systemd will look for a
+ unit template that shares the same name but with the
+ instance string (i.e. the part between the @ character
+ and the suffix) removed. Example: if a service
+ <filename>getty@tty3.service</filename> is requested
+ 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
+ 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>
+
+ <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>
<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>
+ describing the unit. This is intended
+ for use in UIs to show descriptive
+ information along with the unit
+ name.</para></listitem>
</varlistentry>
<varlistentry>
<listitem><para>Configures requirement
dependencies on other units. If this
- units get activated the units listed
+ unit gets activated, the units listed
here will be activated as well. If one
of the other units gets deactivated or
its activation fails, this unit will
Dependencies listed in
<varname>RequiresOverridable=</varname>
which cannot be fulfilled or fail to
- start are ignored iff the startup was
+ start are ignored if the startup was
explicitly requested by the user. If
the start-up was pulled in indirectly
by some dependency or automatic
<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
+ if 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
<listitem><para>Configures negative
requirement dependencies. If a unit
- that has a
+ has a
<varname>Conflicts=</varname> setting
- on another unit starting the former
+ 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>
+ dependencies.</para>
+
+ <para>If a unit A that conflicts with
+ a unit B is scheduled to be started at
+ the same time as B, the transaction
+ will either fail (in case both are
+ required part of the transaction) or
+ be modified to be fixed (in case one
+ or both jobs are not a required part
+ of the transaction). In the latter
+ case the job that is not the required
+ will be removed, or in case both are
+ not required the unit that conflicts
+ will be started and the unit that is
+ conflicted is
+ stopped.</para></listitem>
</varlistentry>
<varlistentry>
<filename>foo.service</filename>
contains a setting
<option>Before=bar.service</option>
- and both units are being started
+ and both units are being started,
<filename>bar.service</filename>'s
start-up is delayed until
<filename>foo.service</filename> is
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
+ inverse 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
place. </para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>OnFailure=</varname></term>
+
+ <listitem><para>Lists one or more
+ units that are activated when this
+ unit enters the
+ '<literal>failed</literal>'
+ state.</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
+ 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 user request
+ 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 the unit will be shut down as well
+ shutdown of a unit, all units depending
+ on that unit will be shut down as well
and at the same time. Defaults to
<option>false</option>.</para></listitem>
</varlistentry>
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
+ minimize the work to be executed,
+ systemd will not stop units by default
unless they are conflicting with other
units, or the user explicitly
requested their shut down. If this
- option is set a unit will be
+ 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>
+ <term><varname>RefuseManualStart=</varname></term>
+ <term><varname>RefuseManualStop=</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 accidentally activate units that are
- not intended to be activated
- explicitly. This option defaults to
+ this unit can only be activated
+ (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
+ (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>
+
+ <varlistentry>
+ <term><varname>DefaultDependencies=</varname></term>
+
+ <listitem><para>Takes a boolean
+ argument. If <option>true</option>
+ (the default), a few default
+ dependencies will implicitly be
+ created for the unit. The actual
+ dependencies created depend on the
+ unit type. For example, for service
+ units, these dependencies ensure that
+ the service is started only after
+ basic system initialization is
+ completed and is properly terminated on
+ system shutdown. See the respective
+ man pages for details. Generally, only
+ services involved with early boot or
+ late shutdown should set this option
+ to <option>false</option>. It is
+ highly recommended to leave this
+ option enabled for the majority of
+ common units. If set to
+ <option>false</option> this option
+ does not disable all implicit
+ dependencies, just non-essential
+ 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>
+
+ <listitem><para>When clients are
+ waiting for a job of this unit to
+ complete, time out after the specified
+ time. If this time limit is reached
+ the job will be cancelled, the unit
+ however will not change state or even
+ 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
+ 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>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>ConditionPathExists=</varname></term>
+ <term><varname>ConditionKernelCommandLine=</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
+ 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. 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, seperated
+ by the equality sign). In the former
+ case the kernel command line is search
+ 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. If multiple conditions
+ are specified the unit will be
+ executed iff at least one of them
+ apply (i.e. a logical OR is
+ applied).</para></listitem>
+ </varlistentry>
</variablelist>
<para>Unit file may include a [Install] section, which
section is not interpreted by
<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>
+ <command>enable</command> and
+ <command>disable</command> commands of the
+ <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
tool during installation of a unit:</para>
<variablelist>
<varlistentry>
<term><varname>Alias=</varname></term>
- <listitem><para>Additional names, this
+ <listitem><para>Additional names this
unit shall be installed under. The
names listed here must have the same
suffix (i.e. type) as the unit file
more than once, in which case all
listed names are used. At installation
time,
- <command>systemd-install</command>
+ <command>systemctl enable</command>
will create symlinks from these names
to the unit file name. Note that this
is different from the
<varname>Alias=</varname> apply only
if the unit has actually been
installed with the
- <command>systemd-install</command>
- tool. Also, if systemd searches for a
+ <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
effect that when the listed unit name
is activated the unit listing it is
activated
- to. <command>WantedBy=foo.service</command>
+ too. <command>WantedBy=foo.service</command>
in a service
<filename>bar.service</filename> is
mostly equivalent to
install when this unit is
installed. If the user requests
installation of a unit with this
- option configured
- <command>systemd-install</command>
+ option configured,
+ <command>systemctl enable</command>
will automatically install units
listed in this option as
well.</para></listitem>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>systemd-install</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<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.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>
</para>
</refsect1>
~ianmdlvl / elogind.git / blobdiff