X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemd.socket.xml;h=0a2d86996be29c9001416b1e861dcee67f68a7a0;hp=f2d4dbe3b73c2c56b341648bf0eb558894dbe736;hb=05cc726731c5cec952722f1c14acb08e3d4d5e98;hpb=89ca69941d0422069903b95265cee02bc1f498f7

diff --git a/man/systemd.socket.xml b/man/systemd.socket.xml
index f2d4dbe3b..0a2d86996 100644
--- a/man/systemd.socket.xml
+++ b/man/systemd.socket.xml
@@ -48,7 +48,7 @@
         </refnamediv>
 
         <refsynopsisdiv>
-                <para><filename>systemd.socket</filename></para>
+                <para><filename><replaceable>socket</replaceable>.socket</filename></para>
         </refsynopsisdiv>
 
         <refsect1>
@@ -150,22 +150,24 @@
                                 <term><varname>ListenSequentialPacket=</varname></term>
                                 <listitem><para>Specifies an address
                                 to listen on for a stream
-                                (SOCK_STREAM), datagram (SOCK_DGRAM),
+                                (<constant>SOCK_STREAM</constant>), datagram (<constant>SOCK_DGRAM</constant>),
                                 or sequential packet
-                                (SOCK_SEQPACKET) socket, respectively. The address
+                                (<constant>SOCK_SEQPACKET</constant>) socket, respectively. The address
                                 can be written in various formats:</para>
 
                                 <para>If the address starts with a
-                                slash (/), it is read as file system
-                                socket in the AF_UNIX socket
+                                slash (<literal>/</literal>), it is read as file system
+                                socket in the <constant>AF_UNIX</constant> socket
                                 family.</para>
 
-                                <para>If the address starts with an
-                                at symbol (@) it is read as abstract
-                                namespace socket in the AF_UNIX
-                                family. The @ is replaced with a NUL
-                                character before binding. For details
-                                see
+                                <para>If the address starts with an at
+                                symbol (<literal>@</literal>) it is read as abstract
+                                namespace socket in the
+                                <constant>AF_UNIX</constant>
+                                family. The <literal>@</literal> is
+                                replaced with a
+                                <constant>NUL</constant> character
+                                before binding. For details see
                                 <citerefentry><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
 
                                 <para>If the address string is a
@@ -193,13 +195,13 @@
                                 setting (see below).
                                 </para>
 
-                                <para>Note that SOCK_SEQPACKET
+                                <para>Note that <constant>SOCK_SEQPACKET</constant>
                                 (i.e. <varname>ListenSequentialPacket=</varname>)
-                                is only available for AF_UNIX
-                                sockets. SOCK_STREAM
+                                is only available for <constant>AF_UNIX</constant>
+                                sockets. <constant>SOCK_STREAM</constant>
                                 (i.e. <varname>ListenStream=</varname>)
                                 when used for IP sockets refers to TCP
-                                sockets, SOCK_DGRAM
+                                sockets, <constant>SOCK_DGRAM</constant>
                                 (i.e. <varname>ListenDatagram=</varname>)
                                 to UDP.</para>
 
@@ -258,7 +260,7 @@
                                 <listitem><para>Specifies a Netlink
                                 family to create a socket for to
                                 listen on. This expects a short string
-                                referring to the AF_NETLINK family
+                                referring to the <constant>AF_NETLINK</constant> family
                                 name (such as <varname>audit</varname>
                                 or <varname>kobject-uevent</varname>)
                                 as argument, optionally suffixed by a
@@ -374,17 +376,30 @@
                                 and only one service unit is spawned
                                 for all connections (also see
                                 above). This value is ignored for
-                                datagram sockets and FIFOs where
-                                a single service unit unconditionally
+                                datagram sockets and FIFOs where a
+                                single service unit unconditionally
                                 handles all incoming traffic. Defaults
                                 to <option>false</option>. For
                                 performance reasons, it is recommended
                                 to write new daemons only in a way
                                 that is suitable for
-                                <option>Accept=false</option>. This
-                                option is mostly useful to allow
-                                daemons designed for usage with
-                                <citerefentry><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+                                <option>Accept=false</option>. A
+                                daemon listening on an <constant>AF_UNIX</constant> socket
+                                may, but does not need to, call
+                                <citerefentry><refentrytitle>close</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+                                on the received socket before
+                                exiting. However, it must not unlink
+                                the socket from a file system. It
+                                should not invoke
+                                <citerefentry><refentrytitle>shutdown</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+                                on sockets it got with
+                                <varname>Accept=false</varname>, but
+                                it may do so for sockets it got with
+                                <varname>Accept=true</varname> set.
+                                Setting <varname>Accept=true</varname>
+                                is mostly useful to allow daemons
+                                designed for usage with
+                                <citerefentry><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
                                 to work unmodified with systemd socket
                                 activation.</para></listitem>
                         </varlistentry>
@@ -399,7 +414,7 @@
                                 are coming in, they will be refused
                                 until at least one existing connection
                                 is terminated. This setting has no
-                                effect for sockets configured with
+                                effect on sockets configured with
                                 <option>Accept=false</option> or datagram
                                 sockets. Defaults to
                                 64.</para></listitem>
@@ -503,7 +518,7 @@
                                 respectively, i.e. the security label
                                 of the FIFO, or the security label for
                                 the incoming or outgoing connections
-                                of the socket, respectively.  See
+                                of the socket, respectively. See
                                 <ulink
                                 url="https://www.kernel.org/doc/Documentation/security/Smack.txt">Smack.txt</ulink>
                                 for details.</para></listitem>
@@ -514,7 +529,7 @@
                                 <listitem><para>Takes an integer
                                 value. Controls the pipe buffer size
                                 of FIFOs configured in this socket
-                                unit.  See
+                                unit. See
                                 <citerefentry><refentrytitle>fcntl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
                                 for details.</para></listitem>
                         </varlistentry>
@@ -571,7 +586,7 @@
                                 <term><varname>PassCredentials=</varname></term>
                                 <listitem><para>Takes a boolean
                                 value. This controls the SO_PASSCRED
-                                socket option, which allows AF_UNIX sockets to
+                                socket option, which allows <constant>AF_UNIX</constant> sockets to
                                 receive the credentials of the sending
                                 process in an ancillary message.
                                 Defaults to
@@ -582,10 +597,10 @@
                                 <term><varname>PassSecurity=</varname></term>
                                 <listitem><para>Takes a boolean
                                 value. This controls the SO_PASSSEC
-                                socket option, which allows AF_UNIX
+                                socket option, which allows <constant>AF_UNIX</constant>
                                 sockets to receive the security
                                 context of the sending process in an
-                                ancillary message.  Defaults to
+                                ancillary message. Defaults to
                                 <option>false</option>.</para></listitem>
                         </varlistentry>
 
@@ -609,7 +624,7 @@
                                 before or after the listening
                                 sockets/FIFOs are created and
                                 bound, respectively. The first token of the command
-                                line must be an absolute file name,
+                                line must be an absolute filename,
                                 then followed by arguments for the
                                 process. Multiple command lines may be
                                 specified following the same scheme as
@@ -644,8 +659,8 @@
                                 will be considered failed and be shut
                                 down again. All commands still running,
                                 will be terminated forcibly via
-                                SIGTERM, and after another delay of
-                                this time with SIGKILL. (See
+                                <constant>SIGTERM</constant>, and after another delay of
+                                this time with <constant>SIGKILL</constant>. (See
                                 <option>KillMode=</option> 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
@@ -686,6 +701,14 @@
                           <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
                   </para>
+
+                  <para>
+                          For more extensive descriptions see the "systemd for Developers" series:
+                          <ulink url="http://0pointer.de/blog/projects/socket-activation.html">Socket Activation</ulink>,
+                          <ulink url="http://0pointer.de/blog/projects/socket-activation2.html">Socket Activation, part II</ulink>,
+                          <ulink url="http://0pointer.de/blog/projects/inetd.html">Converting inetd Services</ulink>,
+                          <ulink url="http://0pointer.de/blog/projects/socket-activated-containers.html">Socket Activated Internet Services and OS Containers</ulink>.
+                  </para>
         </refsect1>
 
 </refentry>