tmpfiles.d: switch to stacked config dirs in /lib, /etc, /run

[thirdparty/systemd.git] / man / systemd.socket.xml

<?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
                <filename>.socket</filename> 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
                socket 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>,
                which define the execution environment the
                <option>ExecStartPre=</option>,
                <option>ExecStartPost=</option>,
                <option>ExecStopPre=</option> and
                <option>ExecStoptPost=</option> commands are executed
                in.</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>

                <para>Unless <varname>DefaultDependencies=</varname>
                is set to <option>false</option>, socket units will
                implicitly have dependencies of type
                <varname>Requires=</varname> and
                <varname>After=</varname> on
                <filename>sysinit.target</filename> as well as
                dependencies of type <varname>Conflicts=</varname> and
                <varname>Before=</varname> on
                <filename>shutdown.target</filename>. These ensure
                that socket units pull in basic system
                initialization, and are terminated cleanly prior to
                system shutdown. Only sockets involved with early
                boot or late system shutdown should disable this
                option.</para>

                <para>Socket units may be used to implement on-demand
                starting of services, as well as parallelized starting
                of services.</para>

                <para>Note that the daemon software configured for
                socket activation with socket units needs to be able
                to accept sockets from systemd, either via systemd's
                native socket passing interface (see
                <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                for details) or via the traditional
                <citerefentry><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry>-style
                socket passing (i.e. sockets passed in via STDIN and
                STDOUT, using <varname>StandardInput=socket</varname>
                in the service file).</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 socket
                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>ListenSpecial=</varname></term>
                                <listitem><para>Specifies a special
                                file in the file system to listen
                                on. This expects an absolute file
                                system path as argument. Behaviour
                                otherwise is very similar to the
                                <varname>ListenFIFO=</varname>
                                directive above. Use this to open
                                character device nodes as well as
                                special files in
                                <filename>/proc</filename> and
                                <filename>/sys</filename>.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>ListenNetlink=</varname></term>
                                <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
                                name (such as <varname>audit</varname>
                                or <varname>kobject-uevent</varname>)
                                as argument, optionally suffixed by a
                                whitespace followed by a multicast
                                group integer. 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. Takes an
                                access mode in octal
                                notation. 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. Takes an access mode in octal
                                notation. 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
                                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>,
                                to work unmodified with systemd 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>

                        <varlistentry>
                                <term><varname>TCPCongestion=</varname></term>
                                <listitem><para>Takes a string
                                value. Controls the TCP congestion
                                algorithm used by this socket. Should
                                be one of "westwood", "veno", "cubic",
                                "lp" or any other available algorithm
                                supported by the IP stack. This
                                setting applies only to stream
                                sockets.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>ExecStartPre=</varname></term>
                                <term><varname>ExecStartPost=</varname></term>
                                <listitem><para>Takes one or more
                                command lines, which are 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. Multiple command lines may be
                                specified following the same scheme as
                                used for
                                <varname>ExecStartPre=</varname> of
                                service unit files.</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. Multiple command lines
                                may be specified following the same
                                scheme as used for
                                <varname>ExecStartPre=</varname> of
                                service unit files.</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 command 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>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
                                logic. Defaults to
                                3min.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>KillMode=</varname></term>
                                <listitem><para>Specifies how
                                processes of this socket unit shall be
                                killed. One of
                                <option>control-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>

                        <varlistentry>
                                <term><varname>KillSignal=</varname></term>
                                <listitem><para>Specifies which signal
                                to use when killing a process of this
                                socket. Defaults to SIGTERM.
                                </para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>SendSIGKILL=</varname></term>
                                <listitem><para>Specifies whether to
                                send SIGKILL to remaining processes
                                after a timeout, if the normal
                                shutdown procedure left processes of
                                the socket around. Takes a boolean
                                value. Defaults to "yes".
                                </para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>Service=</varname></term>
                                <listitem><para>Specifies the service
                                unit name to activate on incoming
                                traffic. This defaults to the service
                                that bears the same name as the socket
                                (ignoring the different suffixes). In
                                most cases it should not be necessary
                                to use this option.</para></listitem>
                        </varlistentry>

                </variablelist>
        </refsect1>

        <refsect1>
                  <title>See Also</title>
                  <para>
                          <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>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                  </para>
        </refsect1>

</refentry>