<?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>systemd service configuration files</refpurpose>

</refnamediv>

<refsynopsisdiv>

<para><filename>systemd.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.</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.</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>. The

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

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

<variablelist>

<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

value if <varname>BusName=</varname>

is not 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 set up. The child continues

to run as the main daemon

process. This is the behaviour 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 starting follow-up units as

soon as the parent process

exits.</para>

<para>Behaviour 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.</para>

<para>Behaviour 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 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>Behaviour 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 finished

starting up. systemd will proceed

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

<para>Behaviour of

<option>idle</option> is very similar

to <option>simple</option>, however

actual execution of a 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

should 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, where this service is reachable

as. This option is mandatory for

services where

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

<option>dbus</option>, but its use

is otherwise recommended as well if

the process takes a name on the D-Bus

bus.</para>

</listitem>

</varlistentry>

<varlistentry>

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

<listitem><para>Takes a command line

that is executed when this service

shall be started up. The first token

of the command line must be an

absolute file name, then followed by

arguments for the process. It is

mandatory to set this option for all

services. This option may not be

specified more than once, except when

<varname>Type=oneshot</varname> is

used in which case more than one

<varname>ExecStart=</varname> line is

accepted which are then invoked one by

one, sequentially in the order they

appear in the unit file.</para>

<para>Optionally, if the absolute 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

first token 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 for the

same command the former must precede

the latter. Unless

<varname>Type=forking</varname> is

set, the process started via this

command line will be considered the

main process of the daemon. The

command line accepts % specifiers as

described in

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

<para>On top of that basic environment

variable substitution is

supported. Use

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

word, or as 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 up

at whitespace, resulting in no or more

arguments. Note that the first

argument (i.e. the program to execute)

may not be a variable, and must be a

literal and absolute path

name.</para></listitem>

</varlistentry>

<varlistentry>

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

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

<listitem><para>Additional commands

that are executed before (resp. after)

the command in

<varname>ExecStart=</varname>. Multiple

command lines may be concatenated in a

single directive, by separating them

by semicolons (these semicolons must

be passed as separate words). In that

case, the commands are executed one

after the other,

serially. Alternatively, these

directives may be specified more than

once with the same effect. However,

the latter syntax is not recommended

for compatibility with parsers

suitable for XDG

<filename>.desktop</filename> files.

Use of these settings is

optional. Specifier and environment

variable substitution is

supported.</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 pointed out for

<varname>ExecStartPre=</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>. One

special environment variable is set:

if known <literal>$MAINPID</literal> is

set to the main process of the

daemon, and may be used for command

lines like the following:

<command>/bin/kill -HUP

$MAINPID</command>.</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 pointed

out for

<varname>ExecStartPre=</varname>

above. Use of this setting is

optional. All processes remaining for

a service after the commands

configured in this option are run are

terminated according to the

<varname>KillMode=</varname> setting

(see below). If this option is not

specified the process is terminated

right-away when service stop is

requested. Specifier and environment

variable substitution is supported

(including

<literal>$MAINPID</literal>, see

above).</para></listitem>

</varlistentry>

<varlistentry>

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

<listitem><para>Additional commands

that are executed after the service

was stopped using the commands

configured in

<varname>ExecStop=</varname>. This

argument takes multiple command lines,

following the same scheme as pointed

out for

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

<listitem><para>Configures the time to

wait for start-up and stop. If a

daemon service does not signal

start-up completion within the

configured time the service will be

considered failed and be shut down

again. If a service is asked to stop

but does not terminate in the

specified time it will be terminated

forcibly via SIGTERM, and after

another delay of this time with

SIGKILL. (See

<varname>KillMode=</varname>

below.) Takes a unit-less value in seconds, or a

time span value such as "5min

20s". Pass 0 to disable the timeout

logic. Defaults to

90s.</para></listitem>

</varlistentry>

<varlistentry>

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

<listitem><para>Configures the

watchdog timeout for a service. This

is activated when the start-up is

completed. The service must call

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

regularly with "WATCHDOG=1". If the

time between two such calls is larger

than the configured time then the

service is placed in a failure

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

main service process shall be

restarted when it exits. Takes one of

<option>no</option>,

<option>on-success</option>,

<option>on-failure</option>,

<option>on-abort</option> or

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

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

service will not be restarted when it

exits. If set to

<option>on-success</option> it will be

restarted only when it exited cleanly,

i.e. terminated with an exit code of

0. If set to

<option>on-failure</option> it will be

restarted only when it exited with an

exit code not equalling 0, when

terminated by a signal, when an

operation times out or when the

configured watchdog timeout is

triggered. If set to

<option>on-abort</option> it will be

restarted only if it exits due to

reception of an uncaught signal. If

set to <option>always</option> the

service will be restarted regardless

whether it exited cleanly or not,

got terminated abnormally by a

signal or hit a timeout.</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>,

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

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

<listitem><para>Set the SysV start

priority to use to order this service

in relation to SysV services lacking

LSB headers. This option is only

necessary to fix ordering in relation

to legacy SysV services, that have no

ordering information encoded in the

script headers. As such it should only

be used as temporary compatibility

option, and not be used in new unit

files. Almost always it is a better

choice to add explicit ordering

directives via

<varname>After=</varname> or

<varname>Before=</varname>,

instead. For more details see

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

used, pass an integer value in the

range 0-99.</para></listitem>

</varlistentry>

<varlistentry>

<term><varname>KillMode=</varname></term>

<listitem><para>Specifies how

processes of this service shall be

killed. One of

<option>control-group</option>,

<option>process</option>,

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

<para>If set to

<option>control-group</option> all

remaining processes in the control

group of this service will be

terminated on service stop, after the

stop command (as configured with

<varname>ExecStop=</varname>) is

executed. If set to

<option>process</option> only the main

process itself is killed. If set to

<option>none</option> no process is

killed. In this case only the stop

command will be executed on service

stop, but no process be killed

otherwise. Processes remaining alive

after stop are left in their control

group and the control group continues

to exist after stop unless it is

empty. Defaults to

<option>control-group</option>.</para>

<para>Processes will first be

terminated via SIGTERM (unless the

signal to send is changed via

<varname>KillSignal=</varname>). If

then after a delay (configured via the

<varname>TimeoutSec=</varname> option)

processes still remain, the

termination request is repeated with

the SIGKILL signal (unless this is

disabled via the

<varname>SendSIGKILL=</varname>

option). See

<citerefentry><refentrytitle>kill</refentrytitle><manvolnum>2</manvolnum></citerefentry>

for more

information.</para></listitem>

</varlistentry>

<varlistentry>

<term><varname>KillSignal=</varname></term>

<listitem><para>Specifies which signal

to use when killing a

service. Defaults to SIGTERM.

</para></listitem>

</varlistentry>

<varlistentry>

<term><varname>SendSIGKILL=</varname></term>

<listitem><para>Specifies whether to

send SIGKILL to remaining processes

after a timeout, if the normal

shutdown procedure left processes of

the service around. Takes a boolean

value. Defaults to "yes".

</para></listitem>

</varlistentry>

<varlistentry>

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

<listitem><para>Set O_NONBLOCK flag

for all file descriptors passed via

socket-based activation. If true, all

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

STDIN/STDOUT/STDERR) will have

the O_NONBLOCK 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>WatchdogUsec=</varname> (see

above). If those options are used but

<varname>NotifyAccess=</varname> 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 the sockets from when the

service is started. Normally it

should not be necessary to use this

setting as all sockets whose unit

shares the same name as the service

(ignoring the different suffix of course)

are passed to the spawned

process.</para>

<para>Note that the same socket may be

passed to multiple processes at the

same time. Also note that a different

service may be activated on incoming

traffic than inherits the sockets. Or

in other words: The

<varname>Service=</varname> setting of

<filename>.socket</filename> units

doesn't have to match the inverse of the

<varname>Sockets=</varname> setting of

the <filename>.service</filename> it

refers to.</para></listitem>

</varlistentry>

<varlistentry>

<term><varname>FsckPassNo=</varname></term>

<listitem><para>Set the fsck passno

priority to use to order this service

in relation to other file system

checking services. This option is only

necessary to fix ordering in relation

to fsck jobs automatically created for

all <filename>/etc/fstab</filename>

entries with a value in the fs_passno

column > 0. As such it should only be

used as option for fsck

services. Almost always it is a better

choice to add explicit ordering

directives via

<varname>After=</varname> or

<varname>Before=</varname>,

instead. For more details see

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

used, pass an integer value in the

same range as

<filename>/etc/fstab</filename>'s

fs_passno column. See

<citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>

for details.</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 often

than 5 times within 10s are not

permitted to start any more times

until the 10s interval ends. With

these two options this rate limiting

may be modified. Use

<varname>StartLimitInterval=</varname>

to configure the checking interval

(defaults to 10s, 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 5). These

configuration options are particularly

useful in conjunction with

<varname>Restart=</varname>.</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> or

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

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

<option>none</option>.</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.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,

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

</para>

</refsect1>

</refentry>