diff options
Diffstat (limited to 'man/systemd.service.xml')
| -rw-r--r-- | man/systemd.service.xml | 837 |
1 files changed, 837 insertions, 0 deletions
diff --git a/man/systemd.service.xml b/man/systemd.service.xml new file mode 100644 index 0000000000..837a992ba4 --- /dev/null +++ b/man/systemd.service.xml @@ -0,0 +1,837 @@ +<?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> + + <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>.</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> + + <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.</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> + </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> |