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

<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?>

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

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

<refentry id="systemd.service">

<refentryinfo>

<title>systemd.service</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.service</refentrytitle>

<manvolnum>5</manvolnum>

</refmeta>

<refnamediv>

<refname>systemd.service</refname>

<refpurpose>Service unit configuration</refpurpose>

</refnamediv>

<refsynopsisdiv>

<para><filename><replaceable>service</replaceable>.service</filename></para>

</refsynopsisdiv>

<refsect1>

<title>Description</title>

<para>A unit configuration file whose name ends in

<filename>.service</filename> encodes information

about a process controlled and supervised by

systemd.</para>

<para>This man page lists the configuration options

specific to this unit type. See

<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>

for the common options of all unit configuration

files. The common configuration items are configured

in the generic <literal>[Unit]</literal> and

<literal>[Install]</literal> sections. The service

specific configuration options are configured in the

<literal>[Service]</literal> section.</para>

<para>Additional options are listed in

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

which define the execution environment the commands

are executed in, and in

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

which define the way the processes of the service are

terminated, and in

<citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,

which configure resource control settings for the

processes of the service.</para>

<para>Unless <varname>DefaultDependencies=</varname>

is set to <option>false</option>, service units will

implicitly have dependencies of type

<varname>Requires=</varname> and

<varname>After=</varname> on

<filename>basic.target</filename> as well as

dependencies of type <varname>Conflicts=</varname> and

<varname>Before=</varname> on

<filename>shutdown.target</filename>. These ensure

that normal service units pull in basic system

initialization, and are terminated cleanly prior to

system shutdown. Only services involved with early

boot or late system shutdown should disable this

option.</para>

<para>If a service is requested under a certain name

but no unit configuration file is found, systemd looks

for a SysV init script by the same name (with the

<filename>.service</filename> suffix removed) and

dynamically creates a service unit from that

script. This is useful for compatibility with

SysV. Note that this compatibility is quite

comprehensive but not 100%. For details about the

incompatibilities, see the <ulink

url="http://www.freedesktop.org/wiki/Software/systemd/Incompatibilities">Incompatibilities

with SysV</ulink> document.

</para>

</refsect1>

<refsect1>

<title>Options</title>

<para>Service files must include a

<literal>[Service]</literal> section, which carries

information about the service and the process it

supervises. A number of options that may be used in

this section are shared with other unit types. These

options are documented in

<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>

and

<citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The

options specific to the <literal>[Service]</literal>

section of service units are the following:</para>

<variablelist class='unit-directives'>

<varlistentry>

<term><varname>Type=</varname></term>

<listitem><para>Configures the process

start-up type for this service

unit. One of <option>simple</option>,

<option>forking</option>,

<option>oneshot</option>,

<option>dbus</option>,

<option>notify</option> or

<option>idle</option>.</para>

<para>If set to

<option>simple</option> (the default

if neither

<varname>Type=</varname> nor

<varname>BusName=</varname>, but

<varname>ExecStart=</varname> are

specified), it is expected that the

process configured with

<varname>ExecStart=</varname> is the

main process of the service. In this

mode, if the process offers

functionality to other processes on

the system, its communication channels

should be installed before the daemon

is started up (e.g. sockets set up by

systemd, via socket activation), as

systemd will immediately proceed

starting follow-up units.</para>

<para>If set to

<option>forking</option>, it is

expected that the process configured

with <varname>ExecStart=</varname>

will call <function>fork()</function>

as part of its start-up. The parent process is

expected to exit when start-up is

complete and all communication

channels are set up. The child continues

to run as the main daemon

process. This is the behavior of

traditional UNIX daemons. If this

setting is used, it is recommended to

also use the

<varname>PIDFile=</varname> option, so

that systemd can identify the main

process of the daemon. systemd will

proceed with starting follow-up units

as soon as the parent process

exits.</para>

<para>Behavior of

<option>oneshot</option> is similar to

<option>simple</option>; however, it

is expected that the process has to

exit before systemd starts follow-up

units. <varname>RemainAfterExit=</varname>

is particularly useful for this type

of service. This is the implied

default if neither

<varname>Type=</varname> or

<varname>ExecStart=</varname> are

specified.</para>

<para>Behavior of

<option>dbus</option> is similar to

<option>simple</option>; however, it is

expected that the daemon acquires a

name on the D-Bus bus, as configured

by

<varname>BusName=</varname>. systemd

will proceed with starting follow-up

units after the D-Bus bus name has been

acquired. Service units with this

option configured implicitly gain

dependencies on the

<filename>dbus.socket</filename>

unit. This type is the default if

<varname>BusName=</varname> is

specified.</para>

<para>Behavior of

<option>notify</option> is similar to

<option>simple</option>; however, it is

expected that the daemon sends a

notification message via

<citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>

or an equivalent call when it has finished

starting up. systemd will proceed with

starting follow-up units after this

notification message has been sent. If

this option is used,

<varname>NotifyAccess=</varname> (see

below) should be set to open access to

the notification socket provided by

systemd. If

<varname>NotifyAccess=</varname> is

not set, it will be implicitly set to

<option>main</option>. Note that

currently

<varname>Type=</varname><option>notify</option>

will not work if used in combination with

<varname>PrivateNetwork=</varname><option>yes</option>.</para>

<para>Behavior of

<option>idle</option> is very similar

to <option>simple</option>; however,

actual execution of the service

binary is delayed until all jobs are

dispatched. This may be used to avoid

interleaving of output of shell

services with the status output on the

console.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>RemainAfterExit=</varname></term>

<listitem><para>Takes a boolean value

that specifies whether the service

shall be considered active even when

all its processes exited. Defaults to

<option>no</option>.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>GuessMainPID=</varname></term>

<listitem><para>Takes a boolean value

that specifies whether systemd should

try to guess the main PID of a service

if it cannot be determined

reliably. This option is ignored

unless <option>Type=forking</option>

is set and <option>PIDFile=</option>

is unset because for the other types

or with an explicitly configured PID

file, the main PID is always known. The

guessing algorithm might come to

incorrect conclusions if a daemon

consists of more than one process. If

the main PID cannot be determined,

failure detection and automatic

restarting of a service will not work

reliably. Defaults to

<option>yes</option>.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>PIDFile=</varname></term>

<listitem><para>Takes an absolute file

name pointing to the PID file of this

daemon. Use of this option is

recommended for services where

<varname>Type=</varname> is set to

<option>forking</option>. systemd will

read the PID of the main process of

the daemon after start-up of the

service. systemd will not write to the

file configured here.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>BusName=</varname></term>

<listitem><para>Takes a D-Bus bus

name that this service is reachable

as. This option is mandatory for

services where

<varname>Type=</varname> is set to

<option>dbus</option>.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>BusPolicy=</varname></term>

<listitem><para>If specified, a custom

<ulink url="https://code.google.com/p/d-bus/">kdbus</ulink>

endpoint will be created and installed as the

default bus node for the service. Such a custom

endpoint can hold an own set of policy rules

that are enforced on top of the bus-wide ones.

The custom endpoint is named after the service

it was created for, and its node will be

bind-mounted over the default bus node

location, so the service can only access the

bus through its own endpoint. Note that custom

bus endpoints default to a 'deny all' policy.

Hence, if at least one

<varname>BusPolicy=</varname> directive is

given, you have to make sure to add explicit

rules for everything the service should be able

to do.</para>

<para>The value of this directive is comprised

of two parts; the bus name, and a verb to

specify to granted access, which is one of

<option>see</option>,

<option>talk</option>, or

<option>own</option>.

<option>talk</option> implies

<option>see</option>, and <option>own</option>

implies both <option>talk</option> and

<option>see</option>.

If multiple access levels are specified for the

same bus name, the most powerful one takes

effect.

</para>

<para>Examples:</para>

<programlisting>BusPolicy=org.freedesktop.systemd1 talk</programlisting>

<programlisting>BusPolicy=org.foo.bar see</programlisting>

<para>This option is only available on kdbus enabled systems.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>ExecStart=</varname></term>

<listitem><para>Commands with their

arguments that are executed when this

service is started. The value is split

into zero or more command lines is

according to the rules described below

(see section "Command Lines" below).

</para>

<para>When <varname>Type</varname> is

not <option>oneshot</option>, only one

command may and must be given. When

<varname>Type=oneshot</varname> is

used, zero or more commands may be

specified. This can be specified by

providing multiple command lines in

the same directive, or alternatively,

this directive may be specified more

than once with the same effect. If the

empty string is assigned to this

option, the list of commands to start

is reset, prior assignments of this

option will have no effect. If no

<varname>ExecStart=</varname> is

specified, then the service must have

<varname>RemainAfterExit=yes</varname>

set.</para>

<para>For each of the specified

commands, the first argument must be

an absolute path to an executable.

Optionally, if this file name is

prefixed with <literal>@</literal>,

the second token will be passed as

<literal>argv[0]</literal> to the

executed process, followed by the

further arguments specified. If the

absolute filename is prefixed with

<literal>-</literal>, an exit code of

the command normally considered a

failure (i.e. non-zero exit status or

abnormal exit due to signal) is

ignored and considered success. If

both <literal>-</literal> and

<literal>@</literal> are used, they

can appear in either order.</para>

<para>If more than one command is

specified, the commands are invoked

sequentially in the order they appear

in the unit file. If one of the

commands fails (and is not prefixed

with <literal>-</literal>), other

lines are not executed, and the unit

is considered failed.</para>

<para>Unless

<varname>Type=forking</varname> is

set, the process started via this

command line will be considered the

main process of the daemon.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>ExecStartPre=</varname></term>

<term><varname>ExecStartPost=</varname></term>

<listitem><para>Additional commands

that are executed before or after

the command in

<varname>ExecStart=</varname>, respectively.

Syntax is the same as for

<varname>ExecStart=</varname>, except

that multiple command lines are allowed

and the commands are executed one

after the other, serially.</para>

<para>If any of those commands (not

prefixed with <literal>-</literal>)

fail, the rest are not executed and

the unit is considered failed.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>ExecReload=</varname></term>

<listitem><para>Commands to execute to

trigger a configuration reload in the

service. This argument takes multiple

command lines, following the same

scheme as described for

<varname>ExecStart=</varname>

above. Use of this setting is

optional. Specifier and environment

variable substitution is supported

here following the same scheme as for

<varname>ExecStart=</varname>.</para>

<para>One additional, special

environment variable is set: if known,

<varname>$MAINPID</varname> is set to

the main process of the daemon, and

may be used for command lines like the

following:</para>

<programlisting>/bin/kill -HUP $MAINPID</programlisting>

<para>Note however that reloading a

daemon by sending a signal (as with

the example line above) is usually not

a good choice, because this is an

asynchronous operation and hence not

suitable to order reloads of multiple

services against each other. It is

strongly recommended to set

<varname>ExecReload=</varname> to a

command that not only triggers a

configuration reload of the daemon,

but also synchronously waits for it to

complete.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>ExecStop=</varname></term>

<listitem><para>Commands to execute to

stop the service started via

<varname>ExecStart=</varname>. This

argument takes multiple command lines,

following the same scheme as described

for <varname>ExecStart=</varname>

above. Use of this setting is

optional. After the commands configured

in this option are run, all processes

remaining for a service are

terminated according to the

<varname>KillMode=</varname> setting

(see

<citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>). If

this option is not specified, the

process is terminated immediately when

service stop is requested. Specifier

and environment variable substitution

is supported (including

<varname>$MAINPID</varname>, see

above).</para></listitem>

</varlistentry>

<varlistentry>

<term><varname>ExecStopPost=</varname></term>

<listitem><para>Additional commands

that are executed after the service

was stopped. This includes cases where

the commands configured in

<varname>ExecStop=</varname> were used,

where the service does not have any

<varname>ExecStop=</varname> defined, or

where the service exited unexpectedly. This

argument takes multiple command lines,

following the same scheme as described

for <varname>ExecStart</varname>. Use

of these settings is

optional. Specifier and environment

variable substitution is

supported.</para></listitem>

</varlistentry>

<varlistentry>

<term><varname>RestartSec=</varname></term>

<listitem><para>Configures the time to

sleep before restarting a service (as

configured with

<varname>Restart=</varname>). Takes a

unit-less value in seconds, or a time

span value such as "5min

20s". Defaults to

100ms.</para></listitem>

</varlistentry>

<varlistentry>

<term><varname>TimeoutStartSec=</varname></term>

<listitem><para>Configures the time to

wait for start-up. If a

daemon service does not signal

start-up completion within the

configured time, the service will be

considered failed and will be shut

down again.

Takes a unit-less value in seconds, or a

time span value such as "5min

20s". Pass <literal>0</literal> to

disable the timeout logic. Defaults to

<varname>DefaultTimeoutStartSec=</varname> from

the manager configuration file, except

when <varname>Type=oneshot</varname> is

used, in which case the timeout

is disabled by default

(see <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).

</para></listitem>

</varlistentry>

<varlistentry>

<term><varname>TimeoutStopSec=</varname></term>

<listitem><para>Configures the time to

wait for stop. If a service is asked

to stop, but does not terminate in the

specified time, it will be terminated

forcibly via <constant>SIGTERM</constant>,

and after another timeout of equal duration

with <constant>SIGKILL</constant> (see

<varname>KillMode=</varname>

in <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>).

Takes a unit-less value in seconds, or a

time span value such as "5min

20s". Pass <literal>0</literal> to disable

the timeout logic. Defaults to

<varname>DefaultTimeoutStopSec=</varname> from the

manager configuration file

(see <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).

</para></listitem>

</varlistentry>

<varlistentry>

<term><varname>TimeoutSec=</varname></term>

<listitem><para>A shorthand for configuring

both <varname>TimeoutStartSec=</varname>

and <varname>TimeoutStopSec=</varname>

to the specified value.

</para></listitem>

</varlistentry>

<varlistentry>

<term><varname>WatchdogSec=</varname></term>

<listitem><para>Configures the

watchdog timeout for a service. The

watchdog is activated when the start-up is

completed. The service must call

<citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>

regularly with <literal>WATCHDOG=1</literal>

(i.e. the "keep-alive ping"). If the time

between two such calls is larger than

the configured time, then the service

is placed in a failed state and it will

be terminated with <varname>SIGABRT</varname>.

By setting <varname>Restart=</varname> to

<option>on-failure</option> or

<option>always</option>, the service

will be automatically restarted. The

time configured here will be passed to

the executed service process in the

<varname>WATCHDOG_USEC=</varname>

environment variable. This allows

daemons to automatically enable the

keep-alive pinging logic if watchdog

support is enabled for the service. If

this option is used,

<varname>NotifyAccess=</varname> (see

below) should be set to open access to

the notification socket provided by

systemd. If

<varname>NotifyAccess=</varname> is

not set, it will be implicitly set to

<option>main</option>. Defaults to 0,

which disables this

feature.</para></listitem>

</varlistentry>

<varlistentry>

<term><varname>Restart=</varname></term>

<listitem><para>Configures whether the

service shall be restarted when the

service process exits, is killed,

or a timeout is reached. The service

process may be the main service

process, but it may also be one of the

processes specified with

<varname>ExecStartPre=</varname>,

<varname>ExecStartPost=</varname>,

<varname>ExecStop=</varname>,

<varname>ExecStopPost=</varname>, or

<varname>ExecReload=</varname>.

When the death of the process is a

result of systemd operation (e.g. service

stop or restart), the service will not be

restarted. Timeouts include missing

the watchdog "keep-alive ping"

deadline and a service start, reload,

and stop operation timeouts.</para>

<para>Takes one of

<option>no</option>,

<option>on-success</option>,

<option>on-failure</option>,

<option>on-abnormal</option>,

<option>on-watchdog</option>,

<option>on-abort</option>, or

<option>always</option>. If set to

<option>no</option> (the default), the

service will not be restarted. If set

to <option>on-success</option>, it

will be restarted only when the

service process exits cleanly. In

this context, a clean exit means an

exit code of 0, or one of the signals

<constant>SIGHUP</constant>,

<constant>SIGINT</constant>,

<constant>SIGTERM</constant> or

<constant>SIGPIPE</constant>, and

additionally, exit statuses and

signals specified in

<varname>SuccessExitStatus=</varname>.

If set to <option>on-failure</option>,

the service will be restarted when the

process exits with a non-zero exit

code, is terminated by a signal

(including on core dump, but excluding

the aforementiond four signals), when

an operation (such as service reload)

times out, and when the configured

watchdog timeout is triggered. If set

to <option>on-abnormal</option>, the

service will be restarted when the

process is terminated by a signal

(including on core dump, excluding the

aforementioned four signals), when an

operation times out, or when the

watchdog timeout is triggered. If set

to <option>on-abort</option>, the

service will be restarted only if the

service process exits due to an

uncaught signal not specified as a

clean exit status. If set to

<option>on-watchdog</option>, the

service will be restarted only if the

watchdog timeout for the service

expires. If set to

<option>always</option>, the service

will be restarted regardless of

whether it exited cleanly or not, got

terminated abnormally by a signal, or

hit a timeout.</para>

<table>

<title>Exit causes and the effect of the <varname>Restart=</varname> settings on them</title>

<tgroup cols='2'>

<colspec colname='path' />

<colspec colname='expl' />

<thead>

<row>

<entry>Restart settings/Exit causes</entry>

<entry><option>no</option></entry>

<entry><option>always</option></entry>

<entry><option>on-success</option></entry>

<entry><option>on-failure</option></entry>

<entry><option>on-abnormal</option></entry>

<entry><option>on-abort</option></entry>

<entry><option>on-watchdog</option></entry>

</row>

</thead>

<tbody>

<row>

<entry>Clean exit code or signal</entry>

<entry/>

<entry>X</entry>

<entry>X</entry>

<entry/>

<entry/>

<entry/>

<entry/>

</row>

<row>

<entry>Unclean exit code</entry>

<entry/>

<entry>X</entry>

<entry/>

<entry>X</entry>

<entry/>

<entry/>

<entry/>

</row>

<row>

<entry>Unclean signal</entry>

<entry/>

<entry>X</entry>

<entry/>

<entry>X</entry>

<entry>X</entry>

<entry>X</entry>

<entry/>

</row>

<row>

<entry>Timeout</entry>

<entry/>

<entry>X</entry>

<entry/>

<entry>X</entry>

<entry>X</entry>

<entry/>

<entry/>

</row>

<row>

<entry>Watchdog</entry>

<entry/>

<entry>X</entry>

<entry/>

<entry>X</entry>

<entry>X</entry>

<entry/>

<entry>X</entry>

</row>

</tbody>

</tgroup>

</table>

<para>As exceptions to the setting

above the service will not be

restarted if the exit code or signal

is specified in

<varname>RestartPreventExitStatus=</varname>

(see below). Also, the services will

always be restarted if the exit code

or signal is specified in

<varname>RestartForceExitStatus=</varname>

(see below).</para>

<para>Setting this to

<option>on-failure</option> is the

recommended choice for long-running

services, in order to increase

reliability by attempting automatic

recovery from errors. For services

that shall be able to terminate on

their own choice (and avoid

immediate restarting),

<option>on-abnormal</option> is an

alternative choice.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>SuccessExitStatus=</varname></term>

<listitem><para>Takes a list of exit

status definitions that when returned

by the main service process will be

considered successful termination, in

addition to the normal successful exit

code 0 and the signals <constant>SIGHUP</constant>, <constant>SIGINT</constant>,

<constant>SIGTERM</constant>, and <constant>SIGPIPE</constant>. Exit status

definitions can either be numeric exit

codes or termination signal names,

separated by spaces. For example:

<programlisting>SuccessExitStatus=1 2 8 SIGKILL</programlisting>

ensures that exit codes 1, 2, 8 and

the termination signal

<constant>SIGKILL</constant> are

considered clean service terminations.

</para>

<para>Note that if a process has a

signal handler installed and exits by

calling

<citerefentry><refentrytitle>_exit</refentrytitle><manvolnum>2</manvolnum></citerefentry>

in response to a signal, the

information about the signal is lost.

Programs should instead perform cleanup and kill themselves with the same signal instead. See

<ulink url="http://www.cons.org/cracauer/sigint.html">Proper handling of SIGINT/SIGQUIT — How to be a proper program</ulink>.</para>

<para>This option may appear more than once,

in which case the list of successful

exit statuses is merged. If the empty

string is assigned to this option, the

list is reset, all prior assignments

of this option will have no

effect.</para></listitem>

</varlistentry>

<varlistentry>

<term><varname>RestartPreventExitStatus=</varname></term>

<listitem><para>Takes a list of exit

status definitions that when returned

by the main service process will

prevent automatic service restarts,

regardless of the restart setting

configured with

<varname>Restart=</varname>. Exit

status definitions can either be

numeric exit codes or termination

signal names, and are separated by

spaces. Defaults to the empty list, so

that, by default, no exit status is

excluded from the configured restart

logic. For example:

<programlisting>RestartPreventExitStatus=1 6 SIGABRT</programlisting> ensures that exit

codes 1 and 6 and the termination

signal <constant>SIGABRT</constant> will

not result in automatic service

restarting. This

option may appear more than once, in

which case the list of restart-preventing

statuses is merged. If the empty

string is assigned to this option, the

list is reset and all prior assignments

of this option will have no

effect.</para></listitem>

</varlistentry>

<varlistentry>

<term><varname>RestartForceExitStatus=</varname></term>

<listitem><para>Takes a list of exit

status definitions that when returned

by the main service process will force

automatic service restarts, regardless

of the restart setting configured with

<varname>Restart=</varname>. The

argument format is similar to

<varname>RestartPreventExitStatus=</varname>.</para></listitem>

</varlistentry>

<varlistentry>

<term><varname>PermissionsStartOnly=</varname></term>

<listitem><para>Takes a boolean

argument. If true, the permission-related

execution options, as

configured with

<varname>User=</varname> and similar

options (see

<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>

for more information), are only applied

to the process started with

<varname>ExecStart=</varname>, and not

to the various other

<varname>ExecStartPre=</varname>,

<varname>ExecStartPost=</varname>,

<varname>ExecReload=</varname>,

<varname>ExecStop=</varname>, and

<varname>ExecStopPost=</varname>

commands. If false, the setting is

applied to all configured commands the

same way. Defaults to

false.</para></listitem>

</varlistentry>

<varlistentry>

<term><varname>RootDirectoryStartOnly=</varname></term>

<listitem><para>Takes a boolean

argument. If true, the root directory,

as configured with the

<varname>RootDirectory=</varname>

option (see

<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>

for more information), is only applied

to the process started with

<varname>ExecStart=</varname>, and not

to the various other

<varname>ExecStartPre=</varname>,

<varname>ExecStartPost=</varname>,

<varname>ExecReload=</varname>,

<varname>ExecStop=</varname>, and

<varname>ExecStopPost=</varname>

commands. If false, the setting is

applied to all configured commands the

same way. Defaults to

false.</para></listitem>

</varlistentry>

<varlistentry>

<term><varname>NonBlocking=</varname></term>

<listitem><para>Set the

<constant>O_NONBLOCK</constant> flag

for all file descriptors passed via

socket-based activation. If true, all

file descriptors >= 3 (i.e. all except

stdin, stdout, and stderr) will have

the <constant>O_NONBLOCK</constant> flag

set and hence are in

non-blocking mode. This option is only

useful in conjunction with a socket

unit, as described in

<citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Defaults

to false.</para></listitem>

</varlistentry>

<varlistentry>

<term><varname>NotifyAccess=</varname></term>

<listitem><para>Controls access to the

service status notification socket, as

accessible via the

<citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>

call. Takes one of

<option>none</option> (the default),

<option>main</option> or

<option>all</option>. If

<option>none</option>, no daemon status

updates are accepted from the service

processes, all status update messages

are ignored. If <option>main</option>,

only service updates sent from the

main process of the service are

accepted. If <option>all</option>, all

services updates from all members of

the service's control group are

accepted. This option should be set to

open access to the notification socket

when using

<varname>Type=notify</varname> or

<varname>WatchdogSec=</varname> (see

above). If those options are used but

<varname>NotifyAccess=</varname> is not

configured, it will be implicitly set

to

<option>main</option>.</para></listitem>

</varlistentry>

<varlistentry>

<term><varname>Sockets=</varname></term>

<listitem><para>Specifies the name of

the socket units this service shall

inherit socket file descriptors

from when the service is

started. Normally it should not be

necessary to use this setting as all

socket file descriptors whose unit

shares the same name as the service

(subject to the different unit name

suffix of course) are passed to the

spawned process.</para>

<para>Note that the same socket file

descriptors may be passed to multiple

processes simultaneously. Also note

that a different service may be

activated on incoming socket traffic

than the one which is ultimately

configured to inherit the socket file

descriptors. Or in other words: the

<varname>Service=</varname> setting of

<filename>.socket</filename> units

does not have to match the inverse of

the <varname>Sockets=</varname>

setting of the

<filename>.service</filename> it

refers to.</para>

<para>This option may appear more than

once, in which case the list of socket

units is merged. If the empty string

is assigned to this option, the list of

sockets is reset, and all prior uses of

this setting will have no

effect.</para></listitem>

</varlistentry>

<varlistentry>

<term><varname>StartLimitInterval=</varname></term>

<term><varname>StartLimitBurst=</varname></term>

<listitem><para>Configure service

start rate limiting. By default,

services which are started more

than 5 times within 10 seconds are not

permitted to start any more times

until the 10 second interval ends. With

these two options, this rate limiting

may be modified. Use

<varname>StartLimitInterval=</varname>

to configure the checking interval (defaults to

<varname>DefaultStartLimitInterval=</varname> in

manager configuration file, set to 0 to disable

any kind of rate limiting). Use

<varname>StartLimitBurst=</varname> to

configure how many starts per interval

are allowed (defaults to

<varname>DefaultStartLimitBurst=</varname> in

manager configuration file). These

configuration options are particularly

useful in conjunction with

<varname>Restart=</varname>; however,

they apply to all kinds of starts

(including manual), not just those

triggered by the

<varname>Restart=</varname> logic.

Note that units which are configured

for <varname>Restart=</varname> and

which reach the start limit are not

attempted to be restarted anymore;

however, they may still be restarted

manually at a later point, from which

point on, the restart logic is again

activated. Note that

<command>systemctl

reset-failed</command> will cause the

restart rate counter for a service to

be flushed, which is useful if the

administrator wants to manually start

a service and the start limit

interferes with

that.</para></listitem>

</varlistentry>

<varlistentry>

<term><varname>StartLimitAction=</varname></term>

<listitem><para>Configure the action

to take if the rate limit configured

with

<varname>StartLimitInterval=</varname>

and

<varname>StartLimitBurst=</varname> is

hit. Takes one of

<option>none</option>,

<option>reboot</option>,

<option>reboot-force</option>,

<option>reboot-immediate</option>,

<option>poweroff</option>,

<option>poweroff-force</option> or

<option>poweroff-immediate</option>. If

<option>none</option> is set, hitting

the rate limit will trigger no action

besides that the start will not be

permitted. <option>reboot</option>

causes a reboot following the normal

shutdown procedure (i.e. equivalent to

<command>systemctl reboot</command>).

<option>reboot-force</option> causes a

forced reboot which will terminate all

processes forcibly but should cause no

dirty file systems on reboot

(i.e. equivalent to <command>systemctl

reboot -f</command>) and

<option>reboot-immediate</option>

causes immediate execution of the

<citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>

system call, which might result in

data loss. Similar,

<option>poweroff</option>,

<option>poweroff-force</option>,

<option>poweroff-immediate</option>

have the effect of powering down the

system with similar

semantics. Defaults to

<option>none</option>.</para></listitem>

</varlistentry>

<varlistentry>

<term><varname>FailureAction=</varname></term>

<listitem><para>Configure the action

to take when the service enters a failed

state. Takes the same values as

<varname>StartLimitAction=</varname>

and executes the same actions.

Defaults to <option>none</option>.

</para></listitem>

</varlistentry>

<varlistentry>

<term><varname>RebootArgument=</varname></term>

<listitem><para>Configure the optional

argument for the

<citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>

system call if

<varname>StartLimitAction=</varname>

or <varname>FailureAction=</varname>

is a reboot action. This works just

like the optional argument to

<command>systemctl reboot</command>

command.</para></listitem>

</varlistentry>

</variablelist>

<para>Check

<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>

and

<citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>

for more settings.</para>

</refsect1>

<refsect1>

<title>Command lines</title>

<para>This section describes command line parsing and

variable and specifier substitions for

<varname>ExecStart=</varname>,

<varname>ExecStartPre=</varname>,

<varname>ExecStartPost=</varname>,

<varname>ExecReload=</varname>,

<varname>ExecStop=</varname>, and

<varname>ExecStopPost=</varname> options.</para>

<para>Multiple command lines may be concatenated in a

single directive by separating them with semicolons

(these semicolons must be passed as separate words).

Lone semicolons may be escaped as

<literal>\;</literal>.</para>

<para>Each command line is split on whitespace, with

the first item being the command to execute, and the

subsequent items being the arguments. Double quotes

("...") and single quotes ('...') may be used, in

which case everything until the next matching quote

becomes part of the same argument. C-style escapes are

also supported, see table below. Quotes themselves are

removed after parsing and escape sequences

substituted. In addition, a trailing backslash

(<literal>\</literal>) may be used to merge lines.

</para>

<para>This syntax is intended to be very similar to

shell syntax, but only the meta-characters and

expansions described in the following paragraphs are

understood. Specifically, redirection using

<literal>&lt;</literal>, <literal>&lt;&lt;</literal>,

<literal>&gt;</literal>, and

<literal>&gt;&gt;</literal>, pipes using

<literal>|</literal>, running programs in the

background using <literal>&amp;</literal>, and

<emphasis>other elements of shell syntax are not

supported</emphasis>.</para>

<para>The command to execute must an absolute path

name. It may contain spaces, but control characters

are not allowed.</para>

<para>The command line accepts <literal>%</literal>

specifiers as described in

<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.

Note that the first argument of the command line

(i.e. the program to execute) may not include

specifiers.</para>

<para>Basic environment variable substitution is

supported. Use <literal>${FOO}</literal> as part of a

word, or as a word of its own, on the command line, in

which case it will be replaced by the value of the

environment variable including all whitespace it

contains, resulting in a single argument. Use

<literal>$FOO</literal> as a separate word on the

command line, in which case it will be replaced by the

value of the environment variable split at whitespace

resulting in zero or more arguments. For this type of

expansion, quotes and respected when splitting into

words, and afterwards removed.</para>

<para>Example:</para>

<programlisting>Environment="ONE=one" 'TWO=two two'

ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>

<para>This will execute <command>/bin/echo</command>

with four arguments: <literal>one</literal>,

<literal>two</literal>, <literal>two</literal>, and

<literal>two two</literal>.</para>

<para>Example:</para>

<programlisting>Environment=ONE='one' "TWO='two two' too" THREE=

ExecStart=/bin/echo ${ONE} ${TWO} ${THREE}

ExecStart=/bin/echo $ONE $TWO $THREE</programlisting>

<para>This results in <filename>echo</filename> being

called twice, the first time with arguments

<literal>'one'</literal>,

<literal>'two two' too</literal>, <literal></literal>,

and the second time with arguments

<literal>one</literal>, <literal>two two</literal>,

<literal>too</literal>.

</para>

<para>To pass a literal dollar sign, use

<literal>$$</literal>. Variables whose value is not

known at expansion time are treated as empty

strings. Note that the first argument (i.e. the

program to execute) may not be a variable.</para>

<para>Variables to be used in this fashion may be

defined through <varname>Environment=</varname> and

<varname>EnvironmentFile=</varname>. In addition,

variables listed in the section "Environment variables

in spawned processes" in

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

which are considered "static configuration", may be

used (this includes e.g. <varname>$USER</varname>, but

not <varname>$TERM</varname>).</para>

<para>Note that shell command lines are not directly

supported. If shell command lines are to be used, they

need to be passed explicitly to a shell implementation

of some kind. Example:</para>

<programlisting>ExecStart=/bin/sh -c 'dmesg | tac'</programlisting>

<para>Example:</para>

<programlisting>ExecStart=/bin/echo one ; /bin/echo "two two"</programlisting>

<para>This will execute <command>/bin/echo</command>

two times, each time with one argument:

<literal>one</literal> and <literal>two two</literal>,

respectively. Because two commands are specified,

<varname>Type=oneshot</varname> must be used.</para>

<para>Example:</para>

<programlisting>ExecStart=/bin/echo / &gt;/dev/null &amp; \; \

/bin/ls</programlisting>

<para>This will execute <command>/bin/echo</command>

with five arguments: <literal>/</literal>,

<literal>&gt;/dev/null</literal>,

<literal>&amp;</literal>, <literal>;</literal>, and

<literal>/bin/ls</literal>.</para>

<table>

<title>C escapes supported in command lines and environment variables</title>

<tgroup cols='2'>

<colspec colname='escape' />

<colspec colname='meaning' />

<thead>

<row>

<entry>Literal</entry>

<entry>Actual value</entry>

</row>

</thead>

<tbody>

<row>

<entry><literal>\a</literal></entry>

<entry>bell</entry>

</row>

<row>

<entry><literal>\b</literal></entry>

<entry>backspace</entry>

</row>

<row>

<entry><literal>\f</literal></entry>

<entry>form feed</entry>

</row>

<row>

<entry><literal>\n</literal></entry>

<entry>newline</entry>

</row>

<row>

<entry><literal>\r</literal></entry>

<entry>carriage return</entry>

</row>

<row>

<entry><literal>\t</literal></entry>

<entry>tab</entry>

</row>

<row>

<entry><literal>\v</literal></entry>

<entry>vertical tab</entry>

</row>

<row>

<entry><literal>\\</literal></entry>

<entry>backslash</entry>

</row>

<row>

<entry><literal>\"</literal></entry>

<entry>double quotation mark</entry>

</row>

<row>

<entry><literal>\'</literal></entry>

<entry>single quotation mark</entry>

</row>

<row>

<entry><literal>\s</literal></entry>

<entry>space</entry>

</row>

<row>

<entry><literal>\x<replaceable>xx</replaceable></literal></entry>

<entry>character number <replaceable>xx</replaceable> in hexadecimal encoding</entry>

</row>

<row>

<entry><literal>\<replaceable>nnn</replaceable></literal></entry>

<entry>character number <replaceable>nnn</replaceable> in octal encoding</entry>

</row>

</tbody>

</tgroup>

</table>

</refsect1>

<refsect1>

<title>See Also</title>

<para>

<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

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

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

<citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,

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

<citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>

</para>

</refsect1>

</refentry>