diff options
Diffstat (limited to 'man/systemd.socket.xml')
| -rw-r--r-- | man/systemd.socket.xml | 685 |
1 files changed, 0 insertions, 685 deletions
diff --git a/man/systemd.socket.xml b/man/systemd.socket.xml deleted file mode 100644 index 4b1fcc8b0c..0000000000 --- a/man/systemd.socket.xml +++ /dev/null @@ -1,685 +0,0 @@ -<?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 Lesser General Public License as published by - the Free Software Foundation; either version 2.1 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 - Lesser General Public License for more details. - - You should have received a copy of the GNU Lesser 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>Socket unit configuration</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, and in - <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> - which define the way the processes are - terminated.</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> - and - <citerefentry><refentrytitle>systemd.kill</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), - or sequential packet - (SOCK_SEQPACKET) 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 - 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 via - IPv6. Depending on the value of - <varname>BindIPv6Only=</varname> (see below) this - might result in the service being - available via both IPv6 and IPv4 (default) or - just via 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. Note - that this might make the service - available via IPv4, too, depending on - the <varname>BindIPv6Only=</varname> - setting (see below). - </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. Behavior 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. Behavior - 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. Behavior 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 /). Behavior - 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>, - which in turn defaults to the - equivalent of - <option>both</option>.</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 or 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 or 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=false</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 - 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> - <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>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 - <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 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 - <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 or after the listening - sockets/FIFOs are created and - bound, respectively. 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 or after - the listening sockets/FIFOs are closed - and removed, respectively. 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> 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 - 20s". Pass 0 to disable the timeout - logic. Defaults to - 90s.</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> - - <para>Check - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> - and - <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for more settings.</para> - - </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.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> |