update fixme

[elogind.git] / man / systemd.service.xml

diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index 008ebd752e9532564944b1f74fcfb5b693b7c873..c3eebeabc1950395f31b1f03340dbe846c25fe9c 100644 (file)
--- a/man/systemd.service.xml
+++ b/man/systemd.service.xml
@@ -119,7 +119,7 @@
                                 start-up type for this service
                                 unit. One of <option>simple</option>,
                                 <option>forking</option>,
                                 start-up type for this service
                                 unit. One of <option>simple</option>,
                                 <option>forking</option>,

-                                <option>finish</option>,
+                                <option>oneshot</option>,

                                 <option>dbus</option>,
                                 <option>notify</option>.</para>
 
                                 <option>dbus</option>,
                                 <option>notify</option>.</para>
 


@@ -129,25 +129,27 @@
                                 configured with
                                 <varname>ExecStart=</varname> is the
                                 main process of the service. In this
                                 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>
+                                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>
 
                                 <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
+                                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
                                 setting is used, it is recommended to
                                 also use the
                                 <varname>PIDFile=</varname> option, so


@@ -158,7 +160,7 @@
                                 exits.</para>
 
                                 <para>Behaviour of
                                 exits.</para>
 
                                 <para>Behaviour of

-                                <option>finish</option> is similar
+                                <option>oneshot</option> is similar

                                 to <option>simple</option>, however
                                 it is expected that the process has to
                                 exit before systemd starts follow-up
                                 to <option>simple</option>, however
                                 it is expected that the process has to
                                 exit before systemd starts follow-up


@@ -176,7 +178,7 @@
                                 will proceed starting follow-up units
                                 after the D-Bus bus name has been
                                 acquired. Service units with this
                                 will proceed starting follow-up units
                                 after the D-Bus bus name has been
                                 acquired. Service units with this

-                                option configured implicitly have
+                                option configured implicitly gain

                                 dependencies on the
                                 <filename>dbus.target</filename>
                                 unit.</para>
                                 dependencies on the
                                 <filename>dbus.target</filename>
                                 unit.</para>


@@ -193,11 +195,11 @@
                                 notification message has been sent. If
                                 this option is used
                                 <varname>NotifyAccess=</varname> (see
                                 notification message has been sent. If
                                 this option is used
                                 <varname>NotifyAccess=</varname> (see

-                                below) must be set to open access to
+                                below) should be set to open access to

                                 the notification socket provided by
                                 systemd. If
                                 <varname>NotifyAccess=</varname> is not
                                 the notification socket provided by
                                 systemd. If
                                 <varname>NotifyAccess=</varname> is not

-                                set, it will be implicitly set to
+                                set, it will implicitly be set to

                                 <option>main</option>.</para>
                                 </listitem>
                         </varlistentry>
                                 <option>main</option>.</para>
                                 </listitem>
                         </varlistentry>


@@ -250,18 +252,48 @@
                                 arguments for the process. It is
                                 mandatory to set this option for all
                                 services. This option may not be
                                 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 <literal>@</literal>, the second
-                                token will be passed as
+                                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
                                 <literal>argv[0]</literal> to the
                                 executed process, followed by the

-                                further arguments specified. Unless
-                                <varname>Type=forking</varname> is set,
-                                the process started via this command
-                                line will be considered the main
-                                process of the
-                                daemon.</para></listitem>
+                                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
+                                abormal 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 preceed
+                                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>. 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
+                                seperate word on the command line in
+                                which case the variable is replaced by
+                                its value split at
+                                whitespaces.</para></listitem>

                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>


@@ -270,31 +302,58 @@
                                 <listitem><para>Additional commands
                                 that are executed before (resp. after)
                                 the command in
                                 <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>
+                                <varname>ExecStart=</varname>. Multiple
+                                command lines may be concatenated in a
+                                single directive, by seperating them
+                                by semicolons (these semicolons must
+                                be passed as seperate words). In that
+                                case, the commands are executed one
+                                after the other,
+                                serially. Alternatively, these
+                                directives may be specified more than
+                                once whith 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
                         </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>
+                                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
                         </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
+                                <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
                                 optional. All processes remaining for
                                 a service after the commands
                                 configured in this option are run are


@@ -303,7 +362,11 @@
                                 (see below). If this option is not
                                 specified the process is terminated
                                 right-away when service stop is
                                 (see below). If this option is not
                                 specified the process is terminated
                                 right-away when service stop is

-                                requested.</para></listitem>
+                                requested. Specifier and environment
+                                variable substitution is supported
+                                (including
+                                <literal>$(MAINPID)</literal>, see
+                                above).</para></listitem>

                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>


@@ -312,11 +375,15 @@
                                 that are executed after the service
                                 was stopped using the commands
                                 configured in
                                 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>
+                                <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>
                         </varlistentry>
 
                         <varlistentry>


@@ -538,7 +605,7 @@
         <refsect1>
                   <title>See Also</title>
                   <para>
         <refsect1>
                   <title>See Also</title>
                   <para>

-                          <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+                          <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>
                           <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>