chiark / gitweb /
man: wording and grammar updates
[elogind.git] / man / systemd.socket.xml
index 7885b07..419a38c 100644 (file)
         </refnamediv>
 
         <refsynopsisdiv>
-                <para><filename>systemd.socket</filename></para>
+                <para><filename><replaceable>socket</replaceable>.socket</filename></para>
         </refsynopsisdiv>
 
         <refsect1>
                 <title>Description</title>
 
                 <para>A unit configuration file whose name ends in
-                <filename>.socket</filename> encodes information about
+                <literal>.socket</literal> encodes information about
                 an IPC or network socket or a file system FIFO
                 controlled and supervised by systemd, for socket-based
                 activation.</para>
                 <option>ExecStartPre=</option>,
                 <option>ExecStartPost=</option>,
                 <option>ExecStopPre=</option> and
-                <option>ExecStoptPost=</option> commands are executed
+                <option>ExecStopPost=</option> commands are executed
                 in, and in
-                <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                 which define the way the processes are
-                terminated.</para>
+                terminated, and in
+                <citerefentry><refentrytitle>systemd.cgroup</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+                which configure control group settings for the
+                processes of the service.</para>
 
                 <para>For each socket file a matching service file
                 (see
@@ -93,7 +96,7 @@
                 <filename>foo.socket</filename> needs a matching
                 service <filename>foo.service</filename> if
                 <option>Accept=false</option> is set. If
-                <option>Accept=true</option> is set a service template
+                <option>Accept=true</option> is set, a service template
                 file <filename>foo@.service</filename> must exist from
                 which services are instantiated for each incoming
                 connection.</para>
                 options specific to the [Socket] section of socket
                 units are the following:</para>
 
-                <variablelist>
+                <variablelist class='unit-directives'>
                         <varlistentry>
                                 <term><varname>ListenStream=</varname></term>
                                 <term><varname>ListenDatagram=</varname></term>
                                 <term><varname>ListenSequentialPacket=</varname></term>
                                 <listitem><para>Specifies an address
                                 to listen on for a stream
-                                (SOCK_STREAM), datagram (SOCK_DGRAM)
-                                resp. sequential packet
-                                (SOCK_SEQPACKET) socket. The address
+                                (<constant>SOCK_STREAM</constant>), datagram (<constant>SOCK_DGRAM</constant>),
+                                or sequential packet
+                                (<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
-                                single number it is read as port
+                                single number, it is read as port
                                 number to listen on via
                                 IPv6. Depending on the value of
                                 <varname>BindIPv6Only=</varname> (see below) this
                                 </para>
 
                                 <para>If the address string is a
-                                string in the format v.w.x.y:z it is
+                                string in the format v.w.x.y:z, it is
                                 read as IPv4 specifier for listening
                                 on an address v.w.x.y on a port
                                 z.</para>
 
                                 <para>If the address string is a
-                                string in the format [x]:y it is read
+                                string in the format [x]:y, it is read
                                 as IPv6 address x on a port y. Note
                                 that this might make the service
                                 available via IPv4, too, depending on
                                 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>
 
                                 <para>These options may be specified
                                 more than once in which case incoming
-                                traffic on any of the sockets will trigger
-                                service activation, and all listed
-                                sockets will be passed to the service,
-                                regardless whether there is incoming
-                                traffic on them or not.</para>
-
-                                <para>If an IP address is used here, it
-                                is often desirable to listen on it
+                                traffic on any of the sockets will
+                                trigger service activation, and all
+                                listed sockets will be passed to the
+                                service, regardless whether there is
+                                incoming traffic on them or not. If
+                                the empty string is assigned to any of
+                                these options, the list of addresses
+                                to listen on is reset, all prior uses
+                                of any of these options will have no
+                                effect.</para>
+
+                                <para>If an IP address is used here,
+                                it is often desirable to listen on it
                                 before the interface it is configured
                                 on is up and running, and even
                                 regardless whether it will be up and
-                                running ever at all. To deal with this it is
-                                recommended to set the
+                                running ever at all. To deal with this
+                                it is recommended to set the
                                 <varname>FreeBind=</varname> option
                                 described below.</para></listitem>
                         </varlistentry>
                                 <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
                                 <option>ipv6-only</option>, they will
                                 be accessible via IPv6 only. If
                                 <option>default</option> (which is the
-                                default, surprise!) the system wide
+                                default, surprise!), the system wide
                                 default setting is used, as controlled
                                 by
                                 <filename>/proc/sys/net/ipv6/bindv6only</filename>,
                                 <term><varname>BindToDevice=</varname></term>
                                 <listitem><para>Specifies a network
                                 interface name to bind this socket
-                                to. If set traffic will only be
+                                to. If set, traffic will only be
                                 accepted from the specified network
                                 interfaces. This controls the
                                 SO_BINDTODEVICE socket option (see
                         <varlistentry>
                                 <term><varname>DirectoryMode=</varname></term>
                                 <listitem><para>If listening on a file
-                                system socket of FIFO, the parent
+                                system socket or FIFO, the parent
                                 directories are automatically created
                                 if needed. This option specifies the
                                 file system access mode used when
                         <varlistentry>
                                 <term><varname>SocketMode=</varname></term>
                                 <listitem><para>If listening on a file
-                                system socket of FIFO, this option
+                                system socket or FIFO, this option
                                 specifies the file system access mode
                                 used when creating the file
                                 node. Takes an access mode in octal
                                 and only one service unit is spawned
                                 for all connections (also see
                                 above). This value is ignored for
-                                datagram sockets and FIFOs where
-                                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>
                                 are coming in, they will be refused
                                 until at least one existing connection
                                 is terminated. This setting has no
-                                effect for sockets configured with
-                                <option>Accept=no</option> or datagram
+                                effect on sockets configured with
+                                <option>Accept=false</option> or datagram
                                 sockets. Defaults to
                                 64.</para></listitem>
                         </varlistentry>
                                 <term><varname>SendBuffer=</varname></term>
                                 <listitem><para>Takes an integer
                                 argument controlling the receive
-                                resp. send buffer sizes of this
-                                socket. This controls the SO_RCVBUF
-                                resp. SO_SNDBUF socket options (see
+                                or send buffer sizes of this
+                                socket, respectively. This controls the SO_RCVBUF
+                                and SO_SNDBUF socket options (see
                                 <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
                                 for details.).</para></listitem>
                         </varlistentry>
                         </varlistentry>
 
                         <varlistentry>
+                                <term><varname>ReusePort=</varname></term>
+                                <listitem><para>Takes a boolean
+                                value. If true, allows multiple <citerefentry><refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum></citerefentry>s
+                                to this TCP or UDP port.  This
+                                controls the SO_REUSEPORT socket
+                                option.  See
+                                <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+                                for details.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>SmackLabel=</varname></term>
+                                <term><varname>SmackLabelIPIn=</varname></term>
+                                <term><varname>SmackLabelIPOut=</varname></term>
+                                <listitem><para>Takes a string
+                                value. Controls the extended
+                                attributes
+                                <literal>security.SMACK64</literal>,
+                                <literal>security.SMACK64IPIN</literal>
+                                and
+                                <literal>security.SMACK64IPOUT</literal>,
+                                respectively, i.e. the security label
+                                of the FIFO, or the security label for
+                                the incoming or outgoing connections
+                                of the socket, respectively. See
+                                <ulink
+                                url="https://www.kernel.org/doc/Documentation/security/Smack.txt">Smack.txt</ulink>
+                                for details.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
                                 <term><varname>PipeSize=</varname></term>
                                 <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>
                                 <varname>MessageQueueMessageSize=</varname></term>
                                 <listitem><para>These two settings
                                 take integer values and control the
-                                mq_maxmsg resp. mq_msgsize field when
+                                mq_maxmsg field or the mq_msgsize field, respectively, when
                                 creating the message queue. Note that
                                 either none or both of these variables
                                 need to be set. See
                                 <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
                                 <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>
 
                                 <term><varname>ExecStartPost=</varname></term>
                                 <listitem><para>Takes one or more
                                 command lines, which are executed
-                                before (resp. after) the listening
+                                before or after the listening
                                 sockets/FIFOs are created and
-                                bound. The first token of the command
-                                line must be an absolute file name,
+                                bound, respectively. The first token of the command
+                                line must be an absolute filename,
                                 then followed by arguments for the
                                 process. Multiple command lines may be
                                 specified following the same scheme as
                                 <term><varname>ExecStopPre=</varname></term>
                                 <term><varname>ExecStopPost=</varname></term>
                                 <listitem><para>Additional commands
-                                that are executed before (resp. after)
+                                that are executed before or after
                                 the listening sockets/FIFOs are closed
-                                and removed. Multiple command lines
+                                and removed, respectively. Multiple command lines
                                 may be specified following the same
                                 scheme as used for
                                 <varname>ExecStartPre=</varname> of
                                 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
                           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
-                          <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                          <citerefentry><refentrytitle>systemd.cgroup</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+                          <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>