man: document Sockets= switch

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

diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index 962388342c56e33413a5d641d1083cc1b0b2322a..8f455ea4c721fd74874fba38c35cd12568baa43c 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,11 +160,11 @@
                                 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

-                                units. <varname>ValidNoProcess=</varname>
+                                units. <varname>RemainAfterExit=</varname>

                                 is particularly useful for this type
                                 of service.</para>
 
                                 is particularly useful for this type
                                 of service.</para>
 


@@ -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,17 +195,17 @@
                                 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>
 
                         <varlistentry>
                                 <option>main</option>.</para>
                                 </listitem>
                         </varlistentry>
 
                         <varlistentry>

-                                <term><varname>ValidNoProcess=</varname></term>
+                                <term><varname>RemainAfterExit=</varname></term>

 
                                 <listitem><para>Takes a boolean value
                                 that specifies whether the service
 
                                 <listitem><para>Takes a boolean value
                                 that specifies whether the service


@@ -250,21 +252,31 @@
                                 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
                                 further arguments specified. If the
                                 first token is prefixed with
                                 <literal>argv[0]</literal> to the
                                 executed process, followed by the
                                 further arguments specified. If the
                                 first token is prefixed with

-                                <literal>-</literal> an error code of
+                                <literal>-</literal> an exit code of

                                 the command normally considered a
                                 the command normally considered a

-                                failure is ignored and considered
-                                success. If both <literal>-</literal>
-                                and <literal>@</literal> are used for
-                                the same command the latter must
-                                preceed the latter. Unless
+                                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
                                 <varname>Type=forking</varname> is
                                 set, the process started via this
                                 command line will be considered the


@@ -274,10 +286,17 @@
                                 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. On
                                 top of that basic environment variable
                                 substitution is supported, where
                                 <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 value of the environment
-                                variable of the same
-                                name.</para></listitem>
+                                <literal>${FOO}</literal> is replaced
+                                by the string value of the environment
+                                variable of the same name. Also
+                                <literal>$FOO</literal> may appear as
+                                separate word on the command line in
+                                which case the variable is replaced by
+                                its value split at whitespaces. Note
+                                that the first argument (i.e. the
+                                binary to execute) may not be a
+                                variable, and must be a literal and
+                                absolute path name.</para></listitem>

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


@@ -290,7 +309,7 @@
                                 command lines may be concatenated in a
                                 single directive, by seperating them
                                 by semicolons (these semicolons must
                                 command lines may be concatenated in a
                                 single directive, by seperating them
                                 by semicolons (these semicolons must

-                                be passed as seperate words). In that
+                                be passed as separate words). In that

                                 case, the commands are executed one
                                 after the other,
                                 serially. Alternatively, these
                                 case, the commands are executed one
                                 after the other,
                                 serially. Alternatively, these


@@ -409,17 +428,17 @@
                                 <listitem><para>Configures whether the
                                 main service process shall be restarted when
                                 it exists. Takes one of
                                 <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
+                                <option>no</option>,
+                                <option>on-success</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
                                 default) the service will not be
                                 restarted when it exits. If set to

-                                <option>restart-on-success</option> it
+                                <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
                                 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
+                                <option>always</option> the

                                 service will be restarted regardless
                                 whether it exited cleanly or not, or
                                 got terminated abnormally by a
                                 service will be restarted regardless
                                 whether it exited cleanly or not, or
                                 got terminated abnormally by a


@@ -583,6 +602,33 @@
                                 <varname>Type=notify</varname> (see above).</para></listitem>
                         </varlistentry>
 
                                 <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 (ignoring the different suffix
+                                of course) is started. Normally it
+                                should not be necessary to use this
+                                setting as all sockets whose unit
+                                shares the same name as the service
+                                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> setiing of
+                                the <filename>.service</filename> it
+                                refers to.</para></listitem>
+                        </varlistentry>
+

                 </variablelist>
         </refsect1>
 
                 </variablelist>
         </refsect1>