man: document socket units

3 files changed, 540 insertions, 4 deletions

diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index 449fe6561d..c6fdc0d504 100644
--- a/man/systemd.service.xml
+++ b/man/systemd.service.xml
@@ -54,9 +54,9 @@
         <refsect1>
                 <title>Description</title>
 
-                <para>A configuration file ending in .service encodes
-                information about a process controlled and supervised
-                by systemd.</para>
+                <para>A unit configuration file whose name ends in
+                .service encodes information about a process
+                controlled and supervised by systemd.</para>
 
                 <para>This man page lists the configuration options
                 specific to this unit type. See
@@ -308,7 +308,7 @@
                                 forcibly via SIGTERM, and after
                                 another delay of this time with
                                 SIGKILL. (See
-                                <option>KilleMode=</option>
+                                <option>KillMode=</option>
                                 below.) Takes a unit-less value in seconds, or a
                                 time span value such as "5min
                                 20s". Pass 0 to disable the timeout
diff --git a/man/systemd.socket.xml b/man/systemd.socket.xml
new file mode 100644
index 0000000000..f187fe3bdf
--- /dev/null
+++ b/man/systemd.socket.xml
@@ -0,0 +1,498 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!--
+  This file is part of systemd.
+
+  Copyright 2010 Lennart Poettering
+
+  systemd is free software; you can redistribute it and/or modify it
+  under the terms of the GNU General Public License as published by
+  the Free Software Foundation; either version 2 of the License, or
+  (at your option) any later version.
+
+  systemd is distributed in the hope that it will be useful, but
+  WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+  General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with systemd; If not, see <http://www.gnu.org/licenses/>.
+-->
+
+<refentry id="systemd.socket">
+        <refentryinfo>
+                <title>systemd.socket</title>
+                <productname>systemd</productname>
+
+                <authorgroup>
+                        <author>
+                                <contrib>Developer</contrib>
+                                <firstname>Lennart</firstname>
+                                <surname>Poettering</surname>
+                                <email>lennart@poettering.net</email>
+                        </author>
+                </authorgroup>
+        </refentryinfo>
+
+        <refmeta>
+                <refentrytitle>systemd.socket</refentrytitle>
+                <manvolnum>5</manvolnum>
+        </refmeta>
+
+        <refnamediv>
+                <refname>systemd.socket</refname>
+                <refpurpose>systemd socket configuration files</refpurpose>
+        </refnamediv>
+
+        <refsynopsisdiv>
+                <para><filename>systemd.socket</filename></para>
+        </refsynopsisdiv>
+
+        <refsect1>
+                <title>Description</title>
+
+                <para>A unit configuration file whose name ends in .socket
+                encodes information about an IPC or network socket or
+                a file system FIFO controlled and supervised by systemd,
+                for socket-based activation.</para>
+
+                <para>This man page lists the configuration options
+                specific to this unit type. See
+                <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                for the common options of all unit configuration
+                files. The common configuration items are configured
+                in the generic [Unit] and [Install] sections. The
+                service specific configuration options are configured
+                in the [Socket] section.</para>
+
+                <para>Additional options are listed in
+                <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
+
+                <para>For each socket file a matching service file (see <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details)
+                must exist, describing the service to start on
+                incoming traffic on the socket. Depending on the
+                setting of <option>Accept=</option> (see below) this
+                must either be named like the socket unit, but with
+                the suffix replaced; or it must be a template file
+                named the same way. Example: a socket file
+                <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
+                file <filename>foo@.service</filename> must exist from
+                which services are instantiated for each incoming
+                connection.</para>
+        </refsect1>
+
+        <refsect1>
+                <title>Options</title>
+
+                <para>Socket files must include a [Socket] section,
+                which carries information about the socket or FIFO it
+                supervises. A number of options that may be used in
+                this section are shared with other unit types. These
+                options are documented in
+                <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
+                options specific to the [Socket] section of service
+                units are the following:</para>
+
+                <variablelist>
+                        <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
+                                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
+                                family.</para>
+
+                                <para>If the address starts with an
+                                ampersand (@) it is read as abstract
+                                namespace socket in the AF_UNIX
+                                family. The @ is replaced with a NUL
+                                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
+                                number to listen on for both IPv4 and
+                                IPv6.</para>
+
+                                <para>If the address string is a
+                                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
+                                as IPv6 address x on a port y.</para>
+
+                                <para>Note that SOCK_SEQPACKET
+                                (i.e. <varname>ListenSequentialPacket=</varname>)
+                                is only available for AF_UNIX
+                                sockets. SOCK_STREAM
+                                (i.e. <varname>ListenStream=</varname>)
+                                when used for IP sockets refers to TCP
+                                sockets, SOCK_DGRAM
+                                (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
+                                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
+                                <varname>FreeBind=</varname> option
+                                described below.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>ListenFIFO=</varname></term>
+                                <listitem><para>Specifies a file
+                                system FIFO to listen on. This expects
+                                an absolute file system path as
+                                argument. Behaviour otherwise is very
+                                similar to the
+                                <varname>ListenDatagram=</varname>
+                                directive above.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>BindIPv6Only=</varname></term>
+                                <listitem><para>Takes a one of
+                                <option>default</option>,
+                                <option>both</option> or
+                                <option>ipv6-only</option>. Controls
+                                the IPV6_V6ONLY socket option (see
+                                <citerefentry><refentrytitle>ipv6</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+                                for details). If
+                                <option>both</option>, IPv6 sockets
+                                bound will be accessible via both IPv4
+                                and IPv6. If
+                                <option>ipv6-only</option>, they will
+                                be accessible via IPv6 only. If
+                                <option>default</option> (which is the
+                                default, surprise!) the system wide
+                                default setting is used, as controlled
+                                by
+                                <filename>/proc/sys/net/ipv6/bindv6only</filename>.</para>
+                                </listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>Backlog=</varname></term>
+                                <listitem><para>Takes an unsigned
+                                integer argument. Specifies the number
+                                of connections to queue that have not
+                                been accepted yet. This setting
+                                matters only for stream and sequential
+                                packet sockets. See
+                                <citerefentry><refentrytitle>listen</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+                                for details. Defaults to SOMAXCONN
+                                (128).</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>BindToDevice=</varname></term>
+                                <listitem><para>Specifies a network
+                                interface name to bind this socket
+                                to. If set traffic will only be
+                                accepted from the specified network
+                                interfaces. This controls the
+                                SO_BINDTODEVICE socket option (see
+                                <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+                                for details). If this option is used
+                                an automatic dependency from this
+                                socket unit on the network interface
+                                device unit
+                                (<citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                                is created.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>DirectoryMode=</varname></term>
+                                <listitem><para>If listening on a file
+                                system socket of FIFO the parent
+                                directories are automatically created
+                                if needed. This option specifies the
+                                file system access mode used when
+                                creating these directories. Defaults
+                                to 0755.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>SocketMode=</varname></term>
+                                <listitem><para>If listening on a file
+                                system socket of FIFO this option
+                                specifies the file system access mode
+                                used when creating the file
+                                node. Defaults to
+                                0666.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>Accept=</varname></term>
+                                <listitem><para>Takes a boolean
+                                argument. If true a service instance
+                                is spawned for each incoming
+                                connection and only the connection
+                                socket is passed to it. If false all
+                                listening sockets themselves are
+                                passed to the started service unit,
+                                and only one service unit is spawned
+                                for all connections (also see
+                                above). This value is ignored for
+                                datagram sockets and FIFOs where
+                                unconditionally a single service unit
+                                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>
+                                to work unmodified with system socket
+                                activation.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>MaxConnections=</varname></term>
+                                <listitem><para>The maximum number of
+                                connections to simultaneously run
+                                services instances for, when
+                                <option>Accept=true</option> is
+                                set. If more concurrent connections
+                                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
+                                sockets. Defaults to
+                                64.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>KeepAlive=</varname></term>
+                                <listitem><para>Takes a boolean
+                                argument. If true, the TCP/IP stack
+                                will send a keep alive message after
+                                2h (depending on the configuration of
+                                <filename>/proc/sys/net/ipv4/tcp_keepalive_time</filename>)
+                                for all TCP streams accepted on this
+                                socket. This controls the SO_KEEPALIVE
+                                socket option (see
+                                <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+                                and the <ulink
+                                url="http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP
+                                Keepalive HOWTO</ulink> for details.)
+                                Defaults to
+                                <option>false</option>.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>Priority=</varname></term>
+                                <listitem><para>Takes an integer
+                                argument controlling the priority for
+                                all traffic sent from this
+                                socket. This controls the SO_PRIORITY
+                                socket option (see
+                                <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+                                for details.).</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>ReceiveBuffer=</varname></term>
+                                <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
+                                <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+                                for details.).</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>IPTOS=</varname></term>
+                                <listitem><para>Takes an integer
+                                argument controlling the IP
+                                Type-Of-Service field for packets
+                                generated from this socket. This
+                                controls the IP_TOS socket option (see
+                                <citerefentry><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+                                for details.). Either a numeric string
+                                or one of <option>low-delay</option>,
+                                <option>throughput</option>,
+                                <option>reliability</option> or
+                                <option>low-cost</option> may be
+                                specified.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>IPTTL=</varname></term>
+                                <listitem><para>Takes an integer
+                                argument controlling the IPv4
+                                Time-To-Live/IPv6 Hop-Count field for
+                                packets generated from this
+                                socket. This sets the
+                                IP_TTL/IPV6_UNICAST_HOPS socket
+                                options (see
+                                <citerefentry><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+                                and
+                                <citerefentry><refentrytitle>ipv6</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+                                for details.)</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>Mark=</varname></term>
+                                <listitem><para>Takes an integer
+                                value. Controls the firewall mark of
+                                packets generated by this socket. This
+                                can be used in the firewall logic to
+                                filter packets from this socket. This
+                                sets the SO_MARK socket option. See
+                                <citerefentry><refentrytitle>iptables</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+                                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
+                                <citerefentry><refentrytitle>fcntl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+                                for details.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>FreeBind=</varname></term>
+                                <listitem><para>Takes a boolean
+                                value. Controls whether the socket can
+                                be bound to non-local IP
+                                addresses. This is useful to configure
+                                sockets listening on specific IP
+                                addresses before those IP addresses
+                                are successfully configured on a
+                                network interface. This sets the
+                                IP_FREEBIND socket option. For
+                                robustness reasons it is recommended
+                                to use this option whenever you bind a
+                                socket to a specific IP
+                                address. Defaults to <option>false</option>.</para></listitem>
+                        </varlistentry>
+
+    <!--
+                { "TimeoutSec",             config_parse_usec,            &u->socket.timeout_usec,                         "Socket"  },
+                { "KillMode",               config_parse_kill_mode,       &u->socket.kill_mode,                            "Socket"  },
+-->
+                        <varlistentry>
+                                <term><varname>ExecStartPre=</varname></term>
+                                <term><varname>ExecStartPost=</varname></term>
+                                <listitem><para>Takes a command line
+                                that is executed before (resp. after)
+                                the listening sockets/FIFOs are created and
+                                bound. The first token of the command
+                                line must be an absolute file name,
+                                then followed by arguments for the
+                                process. If specified more than once,
+                                all commands are executed one after
+                                the other, serially. Use of these
+                                settings is optional.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>ExecStopPre=</varname></term>
+                                <term><varname>ExecStopPost=</varname></term>
+                                <listitem><para>Additional commands
+                                that are executed before (resp. after)
+                                the listening sockets/FIFOs are closed
+                                and removed. If specified more than
+                                once, all commands are executed one
+                                after the other, serially. Use of
+                                these settings is
+                                optional.</para></listitem>
+                        </varlistentry>
+
+
+                        <varlistentry>
+                                <term><varname>TimeoutSec=</varname></term>
+                                <listitem><para>Configures the time to
+                                wait for the commands specified in
+                                <varname>ExecStartPre=</varname>,
+                                <varname>ExecStartPost=</varname>,
+                                <varname>ExecStopPre=</varname> and
+                                <varname>ExecStopPost=</varname> to
+                                finish. If a comand does not exit
+                                within the configured time the socket
+                                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
+                                <option>KilleMode=</option> below.)
+                                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
+                                60s.</para></listitem>
+                        </varlistentry>
+
+
+                        <varlistentry>
+                                <term><varname>KillMode=</varname></term>
+                                <listitem><para>Specifies how
+                                processes of this service shall be
+                                killed. One of
+                                <option>control-group</option>,
+                                <option>process-group</option>,
+                                <option>process</option>,
+                                <option>none</option>.</para>
+
+                                <para>This option is mostly equivalent
+                                to the <option>KillMode=</option>
+                                option of service files. See
+                                <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                                for details.</para></listitem>
+                        </varlistentry>
+
+
+                </variablelist>
+        </refsect1>
+
+        <refsect1>
+                  <title>See Also</title>
+                  <para>
+                          <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>8</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>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                  </para>
+        </refsect1>
+
+</refentry>
diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index 81634410c1..da077e2097 100644
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -144,6 +144,44 @@
                 activation which makes dependencies implicit, which
                 both results in a simpler and more flexible
                 system.</para>
+
+                <para>Some unit names reflect paths existing in the
+                file system name space. Example: a device unit
+                <filename>dev-sda.device</filename> refers to a device
+                with the device node <filename>/dev/sda</filename> in
+                the file system namespace. If this applies a special
+                way to escape the path name is used, so that it is
+                usable as part of a file name. Basically, given a path,
+                "/" is replaced by "-", and all unprintable characters
+                and the "-" are replaced by C-style "\x20"
+                escapes. This escaping is reversible.</para>
+
+                <para>Optionally, units may be instantiated from a
+                template file at runtime. This allows creation of
+                multiple units from a single configuration file. If
+                systemd looks for a unit configuration file it will
+                first search for the literal unit name in the
+                filesystem. If that yields no success and the unit
+                name contains an @ character, systemd will look for a
+                unit template that shares the same name but with the
+                instance string (i.e. the part between the @ character
+                and the suffix) removed. Example: if a service
+                <filename>getty@tty3.service</filename> is requested
+                and no file by that name is found, systemd will look
+                for <filename>getty@.service</filename> and
+                instantiate a service from that configuration file if
+                it is found. To refer to the instance string from
+                within the configuration file you may use the special
+                <literal>%i</literal> specifier in many of the
+                configuration options. Other specifiers that may be
+                used are <literal>%n</literal>, <literal>%N</literal>,
+                <literal>%p</literal>, <literal>%P</literal> and
+                <literal>%I</literal>, for the full unit name, the
+                unescaped unit name, the prefix name, the unescaped
+                prefix name and the unescaped instance name,
+                respectively. The prefix name here refers to the
+                string before the @, i.e. "getty" in the example
+                above, where "tty3" is the instance name.</para>
         </refsect1>
 
         <refsect1>