diff options
Diffstat (limited to 'man/systemd.service.xml')
| -rw-r--r-- | man/systemd.service.xml | 201 |
1 files changed, 103 insertions, 98 deletions
diff --git a/man/systemd.service.xml b/man/systemd.service.xml index 6e9b6696fc..be9bdcaf99 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -103,7 +103,7 @@ script. This is useful for compatibility with SysV. Note that this compatibility is quite comprehensive but not 100%. For details about the - incompatibilities see the <ulink + incompatibilities, see the <ulink url="http://www.freedesktop.org/wiki/Software/systemd/Incompatibilities">Incompatibilities with SysV</ulink> document. </para> @@ -172,13 +172,13 @@ <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 + proceed with starting follow-up units + as soon as the parent process exits.</para> <para>Behavior of <option>oneshot</option> is similar - to <option>simple</option>, however + to <option>simple</option>; however, it is expected that the process has to exit before systemd starts follow-up units. <varname>RemainAfterExit=</varname> @@ -187,13 +187,13 @@ <para>Behavior of <option>dbus</option> is similar to - <option>simple</option>, however it is + <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 + will proceed with starting follow-up + units after the D-Bus bus name has been acquired. Service units with this option configured implicitly gain dependencies on the @@ -204,12 +204,12 @@ <para>Behavior of <option>notify</option> is similar to - <option>simple</option>, however it is + <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 + or an equivalent call when it has finished + starting up. systemd will proceed with starting follow-up units after this notification message has been sent. If this option is used, @@ -227,7 +227,7 @@ <para>Behavior of <option>idle</option> is very similar - to <option>simple</option>, however + to <option>simple</option>; however, actual execution of the service binary is delayed until all jobs are dispatched. This may be used to avoid @@ -260,7 +260,7 @@ 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 + 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 @@ -292,14 +292,13 @@ <term><varname>BusName=</varname></term> <listitem><para>Takes a D-Bus bus - name, that this service is reachable + name that 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> + is otherwise recommended if the process + takes a name on the D-Bus bus.</para> </listitem> </varlistentry> @@ -318,7 +317,7 @@ <varname>Type=oneshot</varname> is used, more than one command may be specified. Multiple command lines may - be concatenated in a single directive, + be concatenated in a single directive by separating them with semicolons (these semicolons must be passed as separate words). Alternatively, this @@ -362,12 +361,12 @@ <para>If more than one command is specified, the commands are invoked - one by one sequentially in the order - they appear in the unit file. If one - of the commands fails (and is not - prefixed with <literal>-</literal>), - other lines are not executed and the - unit is considered failed.</para> + sequentially in the order they appear + in the unit file. If one of the + commands fails (and is not prefixed + with <literal>-</literal>), other lines + are not executed, and the unit is + considered failed.</para> <para>Unless <varname>Type=forking</varname> is @@ -387,7 +386,7 @@ <para>Basic environment variable substitution is supported. Use <literal>${FOO}</literal> as part of a - word, or as a word of its own on the + word, or as a word of its own, on the command line, in which case it will be replaced by the value of the environment variable including all @@ -410,12 +409,12 @@ fashion may be defined through <varname>Environment=</varname> and <varname>EnvironmentFile=</varname>. - In addition, variables listed in + In addition, variables listed in the section "Environment variables in spawned processes" in - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, which are considered "static - configuration" may used (this includes + configuration", may be used (this includes e.g. <varname>$USER</varname>, but not <varname>$TERM</varname>).</para> @@ -447,10 +446,10 @@ <programlisting>ExecStart=/bin/echo one ; /bin/echo "two two"</programlisting> <para>This will execute <command>/bin/echo</command> two - times, each time with one argument, + times, each time with one argument: <literal>one</literal> and <literal>two two</literal>, - respectively. Since two commands are + respectively. Because two commands are specified, <varname>Type=oneshot</varname> must be used.</para> @@ -512,8 +511,8 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting> here following the same scheme as for <varname>ExecStart=</varname>.</para> - <para>One additional special - environment variables is set: if known + <para>One additional, special + environment variable is set: if known, <varname>$MAINPID</varname> is set to the main process of the daemon, and may be used for command lines like the @@ -532,15 +531,15 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting> following the same scheme as described for <varname>ExecStart=</varname> above. Use of this setting is - optional. All processes remaining for - a service after the commands - configured in this option are run are + optional. After the commands configured + in this option are run, all processes + remaining for a service are terminated according to the <varname>KillMode=</varname> setting (see <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>). If this option is not specified, the - process is terminated right-away when + process is terminated immediately when service stop is requested. Specifier and environment variable substitution is supported (including @@ -586,14 +585,15 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting> daemon service does not signal start-up completion within the configured time, the service will be - considered failed and be shut down - again. + considered failed and will be shut + down again. 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 <varname>TimeoutStartSec=</varname> from the - manager configuration file, except when - <varname>Type=oneshot</varname> is + 20s". Pass <literal>0</literal> to + disable the timeout logic. Defaults to + <varname>TimeoutStartSec=</varname> from + the manager configuration file, except + when <varname>Type=oneshot</varname> is used, in which case the timeout is disabled by default. </para></listitem> @@ -603,17 +603,18 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting> <term><varname>TimeoutStopSec=</varname></term> <listitem><para>Configures the time to wait for stop. If a service is asked - to stop but does not terminate in the + to stop, but does not terminate in the specified time, it will be terminated - forcibly via <constant>SIGTERM</constant>, and after - another delay of this time with - <constant>SIGKILL</constant> (See + forcibly via <constant>SIGTERM</constant>, + and after another timeout of equal duration + with <constant>SIGKILL</constant> (see <varname>KillMode=</varname> in <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>). 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 <varname>TimeoutStartSec=</varname> from the + 20s". Pass <literal>0</literal> to disable + the timeout logic. Defaults to + <varname>TimeoutStartSec=</varname> from the manager configuration file. </para></listitem> </varlistentry> @@ -634,11 +635,11 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting> watchdog 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" (i.e. the - "keep-alive ping"). If the time + regularly with <literal>WATCHDOG=1</literal> + (i.e. the "keep-alive ping"). If the time between two such calls is larger than the configured time, then the service - is placed in a failure state. By + is placed in a failed state. By setting <varname>Restart=</varname> to <option>on-failure</option> or <option>always</option>, the service @@ -669,8 +670,8 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting> service process exits, is killed, or a timeout is reached. The service process may be the main service - process, but also one of the processes - specified with + process, but it may also be one of the + processes specified with <varname>ExecStartPre=</varname>, <varname>ExecStartPost=</varname>, <varname>ExecStopPre=</varname>, @@ -698,12 +699,15 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting> exits cleanly. In this context, a clean exit means an exit code of 0, or one of the signals - <constant>SIGHUP</constant>, <constant>SIGINT</constant>, <constant>SIGTERM</constant>, or <constant>SIGPIPE</constant>, and + <constant>SIGHUP</constant>, + <constant>SIGINT</constant>, + <constant>SIGTERM</constant>, + or <constant>SIGPIPE</constant>, and additionally, exit statuses and signals specified in <varname>SuccessExitStatus=</varname>. If set to <option>on-failure</option>, the service will be restarted when the - process exits with an nonzero exit code, + process exits with a non-zero exit code, is terminated by a signal (including on core dump), when an operation (such as service reload) times out, and when the @@ -722,7 +726,7 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting> <option>always</option>, the service will be restarted regardless of whether it exited cleanly or not, got - terminated abnormally by a signal or + terminated abnormally by a signal, or hit a timeout.</para> <para>In addition to the above settings, @@ -777,7 +781,7 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting> <listitem><para>Takes a list of exit status definitions that when returned by the main service process will - prevent automatic service restarts + prevent automatic service restarts, regardless of the restart setting configured with <varname>Restart=</varname>. Exit @@ -785,19 +789,20 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting> numeric exit codes or termination signal names, and are separated by spaces. Defaults to the empty list, so - that by default no exit status is + that, by default, no exit status is excluded from the configured restart logic. Example: <literal>RestartPreventExitStatus=1 6 SIGABRT</literal>, ensures that exit codes 1 and 6 and the termination - signal SIGABRT will not result in - automatic service restarting. This - option may appear more than once in - which case the list of restart preventing + signal <constant>SIGABRT</constant> will + not result in automatic service + restarting. This + option may appear more than once, in + which case the list of restart-preventing statuses is merged. If the empty string is assigned to this option, the - list is reset, all prior assignments + list is reset and all prior assignments of this option will have no effect.</para></listitem> </varlistentry> @@ -805,20 +810,20 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting> <varlistentry> <term><varname>PermissionsStartOnly=</varname></term> <listitem><para>Takes a boolean - argument. If true, the permission - related execution options as + 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 + 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>ExecStop=</varname>, and <varname>ExecStopPost=</varname> commands. If false, the setting is applied to all configured commands the @@ -829,19 +834,19 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting> <varlistentry> <term><varname>RootDirectoryStartOnly=</varname></term> <listitem><para>Takes a boolean - argument. If true, the root directory + 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 + 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>ExecStop=</varname>, and <varname>ExecStopPost=</varname> commands. If false, the setting is applied to all configured commands the @@ -851,12 +856,14 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting> <varlistentry> <term><varname>NonBlocking=</varname></term> - <listitem><para>Set O_NONBLOCK flag + <listitem><para>Set the + <constant>O_NONBLOCK</constant> 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 + the <constant>O_NONBLOCK</constant> flag + set and hence are in non-blocking mode. This option is only useful in conjunction with a socket unit, as described in @@ -912,8 +919,8 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting> 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 + traffic than that which inherits the + sockets. Or in other words: the <varname>Service=</varname> setting of <filename>.socket</filename> units does not have to match the inverse of @@ -926,7 +933,7 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting> once, in which case the list of socket units is merged. If the empty string is assigned to this option, the list of - sockets is reset, all prior uses of + sockets is reset, and all prior uses of this setting will have no effect.</para></listitem> </varlistentry> @@ -937,10 +944,10 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting> <listitem><para>Configure service start rate limiting. By default, - services which are started more often - than 5 times within 10s are not + services which are started more + than 5 times within 10 seconds are not permitted to start any more times - until the 10s interval ends. With + until the 10 second interval ends. With these two options, this rate limiting may be modified. Use <varname>StartLimitInterval=</varname> @@ -955,18 +962,18 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting> manager configuration file). These configuration options are particularly useful in conjunction with - <varname>Restart=</varname>, however - apply to all kinds of starts + <varname>Restart=</varname>; however, + they apply to all kinds of starts (including manual), not just those triggered by the <varname>Restart=</varname> logic. Note that units which are configured for <varname>Restart=</varname> and which reach the start limit are not - attempted to be restarted anymore, - however they may still be restarted - manually at a later point from which - point on the restart logic is again + attempted to be restarted anymore; + however, they may still be restarted + manually at a later point, from which + point on, the restart logic is again activated. Note that <command>systemctl reset-failed</command> will cause the @@ -990,18 +997,17 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting> hit. Takes one of <option>none</option>, <option>reboot</option>, - <option>reboot-force</option> or + <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> + be permitted. <option>reboot</option> causes a reboot following the normal shutdown procedure (i.e. equivalent to - <command>systemctl reboot</command>), + <command>systemctl reboot</command>). <option>reboot-force</option> causes - an forced reboot which will terminate + a forced reboot which will terminate all processes forcibly but should cause no dirty file systems on reboot (i.e. equivalent to <command>systemctl @@ -1010,7 +1016,7 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting> causes immediate execution of the <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> system call, which might result in - data loss. Defaults to + data loss. Defaults to <option>none</option>.</para></listitem> </varlistentry> @@ -1040,22 +1046,21 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting> 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 + 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 + script headers. As such, it should only + be used as a temporary compatibility + option and should 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 + 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> - </variablelist> </refsect1> |