<?xml version='1.0'?> <!--*-nxml-*-->

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<refentry id="systemd.unit">

<refentryinfo>

<title>systemd.unit</title>

<productname>systemd</productname>

<authorgroup>

<author>

<contrib>Developer</contrib>

<firstname>Lennart</firstname>

<surname>Poettering</surname>

<email>lennart@poettering.net</email>

</author>

</authorgroup>

</refentryinfo>

<refmeta>

<refentrytitle>systemd.unit</refentrytitle>

<manvolnum>5</manvolnum>

</refmeta>

<refnamediv>

<refname>systemd.unit</refname>

<refpurpose>systemd unit configuration files</refpurpose>

</refnamediv>

<refsynopsisdiv>

<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>,

<filename>systemd.snapshot</filename></para>

</refsynopsisdiv>

<refsect1>

<title>Description</title>

<para>A unit configuration file encodes information

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 <ulink

url="http://standards.freedesktop.org/desktop-entry-spec/latest/">XDG

Desktop Entry Specification</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 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

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 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>0</option>, <option>no</option>,

<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. 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 were 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>

<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>

</refsect1>

<refsect1>

<title>Options</title>

<para>Unit file may include a [Unit] section, which

carries generic information about the unit that is not

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>

<listitem><para>A free-form string

describing the unit. This is intended

for use in UIs to show descriptive

information along with the unit

name.</para></listitem>

</varlistentry>

<varlistentry>

<term><varname>Requires=</varname></term>

<listitem><para>Configures requirement

dependencies on other units. If this

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

be deactivated. This option may be

specified more than once, in which

case requirement dependencies for all

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 if 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 honored 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,

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

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

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 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>OnFailure=</varname></term>

<listitem><para>Lists one or more

units that are activated when this

unit fails (i.e. enters maintenance

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 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

<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 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

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 can only be activated

indirectly. In this case explicit

start-up requested by the user is

denied, however if it is started 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

<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 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

<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>

</variablelist>

<para>Unit file may include a [Install] section, which

carries installation information for the unit. This

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>

tool during installation of a unit:</para>

<variablelist>

<varlistentry>

<term><varname>Alias=</varname></term>

<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

name. This option may be specified

more than once, in which case all

listed names are used. At installation

time,

<command>systemd-install</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>systemd-install</command>

tool. 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>

</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

too. <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>

</refsect1>

<refsect1>

<title>See Also</title>

<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.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>,

<citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,

<citerefentry><refentrytitle>systemd.automount</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.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>

</para>

</refsect1>

</refentry>