eudev/man/systemd.service.xml

710 lines
40 KiB
XML
Raw Normal View History

2010-05-16 04:06:41 +07:00
<?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">
<!--
This file is part of systemd.
Copyright 2010 Lennart Poettering
systemd is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
systemd is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
<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>
2010-07-02 04:49:50 +07:00
<para>A unit configuration file whose name ends in
2010-07-02 06:17:55 +07:00
<filename>.service</filename> encodes information
about a process controlled and supervised by
systemd.</para>
2010-05-16 04:06:41 +07:00
<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
2010-07-02 00:39:35 +07:00
files. The common configuration items are configured
2010-07-04 00:54:00 +07:00
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>
2010-07-02 00:39:35 +07:00
<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>
2010-07-04 00:54:00 +07:00
<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>
2010-07-06 08:46:31 +07:00
<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>
2010-05-16 04:06:41 +07:00
</refsect1>
<refsect1>
<title>Options</title>
2010-07-04 00:54:00 +07:00
<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
2010-07-02 00:39:35 +07:00
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
2010-07-04 00:54:00 +07:00
options specific to the <literal>[Service]</literal>
section of service units are the following:</para>
2010-07-02 00:39:35 +07:00
2010-05-16 04:06:41 +07:00
<variablelist>
<varlistentry>
<term><varname>Type=</varname></term>
2010-07-02 00:39:35 +07:00
<listitem><para>Configures the process
start-up type for this service
unit. One of <option>simple</option>,
<option>forking</option>,
<option>oneshot</option>,
2010-07-02 00:39:35 +07:00
<option>dbus</option>,
<option>notify</option>.</para>
<para>If set to
<option>simple</option> (the default
value) 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>
2010-07-02 00:39:35 +07:00
<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
2010-07-02 00:39:35 +07:00
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
2010-07-02 00:39:35 +07:00
to <option>simple</option>, however
it is expected that the process has to
exit before systemd starts follow-up
units. <varname>RemainAfterExit=</varname>
2010-07-02 00:39:35 +07:00
is particularly useful for this type
of service.</para>
<para>Behaviour of
<option>dbus</option> is similar to
2010-07-04 00:54:00 +07:00
<option>simple</option>, however it is
expected that the daemon acquires a
2010-07-02 00:39:35 +07:00
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
2010-07-04 00:54:00 +07:00
acquired. Service units with this
option configured implicitly gain
2010-07-04 00:54:00 +07:00
dependencies on the
<filename>dbus.target</filename>
unit.</para>
2010-07-02 00:39:35 +07:00
<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
2010-07-04 00:54:00 +07:00
<varname>NotifyAccess=</varname> (see
below) should be set to open access to
2010-07-02 00:39:35 +07:00
the notification socket provided by
2010-07-04 00:54:00 +07:00
systemd. If
<varname>NotifyAccess=</varname> is not
set, it will implicitly be set to
2010-07-04 00:54:00 +07:00
<option>main</option>.</para>
2010-05-16 04:06:41 +07:00
</listitem>
</varlistentry>
2010-07-02 00:39:35 +07:00
2010-05-16 04:06:41 +07:00
<varlistentry>
<term><varname>RemainAfterExit=</varname></term>
2010-07-02 00:39:35 +07:00
<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>
2010-05-16 04:06:41 +07:00
</listitem>
</varlistentry>
<varlistentry>
<term><varname>PIDFile=</varname></term>
2010-07-02 00:39:35 +07:00
<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
2011-02-09 17:00:17 +07:00
<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>
2010-05-16 04:06:41 +07:00
</listitem>
</varlistentry>
<varlistentry>
<term><varname>BusName=</varname></term>
2010-07-02 00:39:35 +07:00
<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>
2010-05-16 04:06:41 +07:00
</listitem>
</varlistentry>
<varlistentry>
<term><varname>ExecStart=</varname></term>
2010-07-02 00:39:35 +07:00
<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
2010-07-04 00:54:00 +07:00
<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
2010-12-31 07:50:51 +07:00
abnormal exit due to signal) is ignored
and considered success. If both
<literal>-</literal> and
<literal>@</literal> are used for the
2010-12-31 07:50:51 +07:00
same command the former must precede
the latter. Unless
2010-07-08 09:19:54 +07:00
<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>. On
top of that basic environment variable
substitution is supported, where
<literal>${FOO}</literal> is replaced
by the string value of the environment
variable of the same name. Also
<literal>$FOO</literal> may appear as
separate word on the command line in
which case the variable is replaced by
its value split at whitespaces. Note
that the first argument (i.e. the
binary to execute) may not be a
variable, and must be a literal and
absolute path name.</para></listitem>
2010-07-02 00:39:35 +07:00
</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
2010-09-29 20:13:04 +07:00
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
2010-12-31 07:50:51 +07:00
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
2010-07-08 09:19:54 +07:00
optional. Specifier and environment
variable substitution is
supported.</para></listitem>
2010-07-02 00:39:35 +07:00
</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
2010-07-08 09:19:54 +07:00
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>
2010-07-02 00:39:35 +07:00
</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
2010-07-02 00:39:35 +07:00
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
2010-07-08 09:19:54 +07:00
requested. Specifier and environment
variable substitution is supported
(including
<literal>$MAINPID</literal>, see
2010-07-08 09:19:54 +07:00
above).</para></listitem>
2010-07-02 00:39:35 +07:00
</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
2010-07-08 09:19:54 +07:00
optional. Specifier and environment
variable substitution is
supported.</para></listitem>
2010-07-02 00:39:35 +07:00
</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
2010-07-04 00:54:00 +07:00
<varname>KillMode=</varname>
2010-07-02 00:39:35 +07:00
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
60s.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>Restart=</varname></term>
<listitem><para>Configures whether the
main service process shall be
2010-11-11 20:24:47 +07:00
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
2010-12-31 07:50:51 +07:00
restarted only when it exited with an
exit code not equalling 0, or when
terminated by a signal. 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
2010-07-02 00:39:35 +07:00
service will be restarted regardless
whether it exited cleanly or not, or
got terminated abnormally by a
signal.</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-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-group</option> only
the members of the process group of
the main service process are
killed. 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
2010-11-11 20:24:47 +07:00
<option>control-group</option>.</para>
2010-07-02 00:39:35 +07:00
<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
2010-07-04 00:54:00 +07:00
<varname>TimeoutSec=</varname> option)
2010-07-02 00:39:35 +07:00
processes still remain, the
termination request is repeated with
the SIGKILL signal (unless this is
disabled via the
<varname>SendSIGKILL=</varname>
option). See
2010-07-02 00:39:35 +07:00
<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>
2010-07-02 00:39:35 +07:00
<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
2010-11-11 20:24:47 +07:00
updates are accepted from the service
2010-07-02 00:39:35 +07:00
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 must be set to
open access to the notification socket
when using
<varname>Type=notify</varname> (see above).</para></listitem>
2010-05-16 04:06:41 +07:00
</varlistentry>
2010-10-06 01:51:00 +07:00
<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 (ignoring the different suffix
of course) is started. Normally it
should not be necessary to use this
setting as all sockets whose unit
shares the same name as the service
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
2010-10-06 02:22:41 +07:00
<varname>Sockets=</varname> setting of
2010-10-06 01:51:00 +07:00
the <filename>.service</filename> it
refers to.</para></listitem>
</varlistentry>
2010-10-20 19:22:23 +07:00
<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>
2010-05-16 04:06:41 +07:00
</variablelist>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
2010-07-07 06:38:56 +07:00
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
2010-07-02 00:39:35 +07:00
<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>
2010-05-16 04:06:41 +07:00
</para>
</refsect1>
</refentry>