<?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></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 the all 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 forms. 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 concatentation of

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

<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

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

units get 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 iff 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,

it 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

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

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

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

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 by default not stop units

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

<option>false</option>.</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

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

</para>

</refsect1>

</refentry>