diff options
Diffstat (limited to 'man/systemd.service.xml')
| -rw-r--r-- | man/systemd.service.xml | 516 |
1 files changed, 407 insertions, 109 deletions
diff --git a/man/systemd.service.xml b/man/systemd.service.xml index 5230a78337..449fe6561d 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -62,140 +62,437 @@ specific to this unit type. See <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for the common options of all unit configuration - files.</para> + files. The common configuration items are configured + in the generic [Unit] and [Install] sections. The + service specific configuration options are configured + in the [Service] section.</para> + + <para>Additional options are listed in <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> </refsect1> <refsect1> <title>Options</title> + <para>Service files must include a [Service] 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 [Service] section of service + units are the following:</para> + <variablelist> <varlistentry> <term><varname>Type=</varname></term> - <listitem> - <para>One of - <literal>forking</literal>, - <literal>simple</literal>, - <literal>finish</literal>, - <literal>dbus</literal>.</para> - - <para>If set to - <literal>forking</literal> - (the default) it is expected - that the process configured - with - <varname>ExecStart=</varname> - will start up and call - <function>fork()</function>. The - parent process is expected to - finish 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>If set to - <literal>simple</literal> (the - recommended value) it is - expected that the process - configured with - <varname>ExecStart=</varname> - is the main process of the - daemon. In this mode, - communication channels must be - available before the daemon is - started up (sockets set up by systemd), - as systemd will immediately proceed - starting follow-up units.</para> - - <para>Behaviour of - <literal>finish</literal> is - similar to - <literal>simple</literal>, - however it is expected that - the process has to exit before - systemd starts follow-up - units. <varname>ValidNoProcess=</varname> - is particularly useful for - this type of service.</para> - - <para>Behaviour of - <literal>dbus</literal> is - similar to - <literal>simple</literal>, - 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.</para> + + <listitem><para>Configures the process + start-up type for this service + unit. One of <option>simple</option>, + <option>forking</option>, + <option>finish</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, communication channels must 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 start up and call + <function>fork()</function>. The + parent process is expected to finish + 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>finish</option> is similar + to <option>simple</option>, however + it is expected that the process has to + exit before systemd starts follow-up + units. <varname>ValidNoProcess=</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.</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 + <option>NotifyAccess=</option> (see + below) must be set to open access to + the notification socket provided by + systemd.</para> </listitem> </varlistentry> + <varlistentry> <term><varname>ValidNoProcess=</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 <literal>no</literal>.</para> + + <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>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 - <literal>forking</literal>.</para> + + <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>.</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 - <literal>dbus</literal>, but - its use is otherwise - recommended as well if the - process takes a name on the - D-Bus bus.</para> + + <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 word of the - command line must be an - absolute file name. It is - mandatory to set this option - for all services.</para> - </listitem> + <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. Optionally, + if the absolute file name is prefixed + with @, the second token will be + passed as argv[0] to the executed + process, followed by the further + arguments specified. Unless + <option>Type=forking</option> is set, + the process started via this command + line will be considered the main + process of the + daemon.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ExecStartPre=</varname></term> + <term><varname>ExecStartPost=</varname></term> + <listitem><para>Additional commands + that are executed before (resp. after) + the command in + <varname>ExecStart=</varname>. If + specified more than once, all commands + are executed one after the other, + serially. Use of these settings is + optional.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ExecReload=</varname></term> + <listitem><para>Commands to execute to + trigger a configuration reload in the + service. If used more than once, all + commands are executed one after the + other, serially. Use of this setting is optional. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ExecStop=</varname></term> + <listitem><para>Commands to execute to + stop the service started via + <varname>ExecStart=</varname>. If used + more than once, all commands are + executed one after the other, + serially. 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.</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>. If + specified more than once, all commands + are executed one after the other, + serially. Use of these settings is + optional.</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 + <option>KilleMode=</option> + 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 restarted when + it exists. Takes one of + <option>once</option>, + <option>restart-on-success</option> or + <option>restart-always</option>. If + set to <option>once</option> (the + default) the service will not be + restarted when it exits. If set to + <option>restart-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>restart-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-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 + <option>control-croup</option>.</para> + + <para>Processes will first be + terminated via SIGTERM. If then after + a delay (configured via the + <option>TimeoutSec=</option> option) + processes still remain, the + termination request is repeated with + the SIGKILL signal. See + <citerefentry><refentrytitle>kill</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for more + information.</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 by 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> </variablelist> @@ -205,8 +502,9 @@ <title>See Also</title> <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry> - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</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> |