diff options
Diffstat (limited to 'man/systemd.socket.xml')
| -rw-r--r-- | man/systemd.socket.xml | 674 |
1 files changed, 674 insertions, 0 deletions
diff --git a/man/systemd.socket.xml b/man/systemd.socket.xml new file mode 100644 index 000000000..d9921e496 --- /dev/null +++ b/man/systemd.socket.xml @@ -0,0 +1,674 @@ +<?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 + 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 + <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>ListenMessageQueue=</varname></term> + <listitem><para>Specifies a POSIX + message queue name to listen on. This + expects a valid message queue name + (i.e. beginning with /). Behaviour + otherwise is very similar to the + <varname>ListenFIFO=</varname> + directive above. On Linux message + queue descriptors are actually file + descriptors and can be inherited + between processes.</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>MessageQueueMaxMessages=</varname>, + <varname>MessageQueueMessageSize=</varname></term> + <listitem><para>These two settings + take integer values and control the + mq_maxmsg resp. mq_msgsize field when + creating the message queue. Note that + either none or both of these variables + need to be set. See + <citerefentry><refentrytitle>mq_setattr</refentrytitle><manvolnum>3</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>Transparent=</varname></term> + <listitem><para>Takes a boolean + value. Controls the IP_TRANSPARENT + socket option. Defaults to + <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Broadcast=</varname></term> + <listitem><para>Takes a boolean + value. This controls the SO_BROADCAST + socket option, which allows broadcast + datagrams to be sent from this + socket. Defaults to + <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PassCredentials=</varname></term> + <listitem><para>Takes a boolean + value. This controls the SO_PASSCRED + socket option, which allows AF_UNIX sockets to + receive the credentials of the sending + process in an ancillary message. + Defaults to + <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PassSecurity=</varname></term> + <listitem><para>Takes a boolean + value. This controls the SO_PASSSEC + socket option, which allows AF_UNIX + sockets to receive the security + context of the sending process in an + ancillary message. 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 + 90s.</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> |