| <?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 implicitly be 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>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, 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 |
| 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</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 must be set to |
| open access to the notification socket |
| when using |
| <varname>Type=notify</varname> (see above).</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> |
| |
| </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> |