"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
-<refentry id="systemd.socket">
+<refentry id="systemd.socket" xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>systemd.socket</title>
<productname>systemd</productname>
<refsect1>
<title>Options</title>
- <para>Socket files must include a [Socket] section, which carries
+ <para>Socket unit files may include [Unit] and [Install] sections, which are described in
+ <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+ </para>
+
+ <para>Socket unit 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
<varlistentry>
<term><varname>ListenUSBFunction=</varname></term>
<listitem><para>Specifies a <ulink
- url="https://www.kernel.org/doc/Documentation/usb/functionfs.txt">USB
+ url="https://docs.kernel.org/usb/functionfs.html">USB
FunctionFS</ulink> endpoints location to listen on, for
implementation of USB gadget functions. This expects an
absolute file system path of a FunctionFS mount point as the argument.
activated service has to have the
<varname>USBFunctionDescriptors=</varname> and
<varname>USBFunctionStrings=</varname> options set.
- </para></listitem>
+ </para>
+
+ <xi:include href="version-info.xml" xpointer="v227"/></listitem>
</varlistentry>
<varlistentry>
or <option>sctp</option>. The socket will use the UDP-Lite
(<constant>IPPROTO_UDPLITE</constant>) or SCTP
(<constant>IPPROTO_SCTP</constant>) protocol, respectively.</para>
+
+ <xi:include href="version-info.xml" xpointer="v229"/>
</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>
+ <listitem><para>Takes an unsigned 32-bit 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 4294967295. Note that this value is silently capped by the
+ <literal>net.core.somaxconn</literal> sysctl, which typically defaults to 4096, so typically
+ the sysctl is the setting that actually matters.</para></listitem>
</varlistentry>
<varlistentry>
sockets and FIFO nodes in the file system are owned by the specified user and group. If unset (the
default), the nodes are owned by the root user/group (if run in system context) or the invoking
user/group (if run in user context). If only a user is specified but no group, then the group is
- derived from the user's default group.</para></listitem>
+ derived from the user's default group.</para>
+
+ <xi:include href="version-info.xml" xpointer="v214"/></listitem>
</varlistentry>
<varlistentry>
<varlistentry>
<term><varname>Accept=</varname></term>
- <listitem><para>Takes a boolean argument. If yes, a service
- instance is spawned for each incoming connection and only the
- connection socket is passed to it. If no, 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>no</option>. For
- performance reasons, it is recommended to write new daemons
- only in a way that is suitable for
- <option>Accept=no</option>. A daemon listening on an
- <constant>AF_UNIX</constant> socket may, but does not need to,
- call
- <citerefentry><refentrytitle>close</refentrytitle><manvolnum>2</manvolnum></citerefentry>
- on the received socket before exiting. However, it must not
- unlink the socket from a file system. It should not invoke
- <citerefentry><refentrytitle>shutdown</refentrytitle><manvolnum>2</manvolnum></citerefentry>
- on sockets it got with <varname>Accept=no</varname>, but it
- may do so for sockets it got with
- <varname>Accept=yes</varname> set. Setting
- <varname>Accept=yes</varname> is mostly useful to allow
- daemons designed for usage with
- <citerefentry project='freebsd'><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
- to work unmodified with systemd socket
- activation.</para>
+ <listitem><para>Takes a boolean argument. If yes, a service instance is spawned for each incoming
+ connection and only the connection socket is passed to it. If no, 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>no</option>. For performance
+ reasons, it is recommended to write new daemons only in a way that is suitable for
+ <option>Accept=no</option>. A daemon listening on an <constant>AF_UNIX</constant> socket may, but
+ does not need to, call
+ <citerefentry><refentrytitle>close</refentrytitle><manvolnum>2</manvolnum></citerefentry> on the
+ received socket before exiting. However, it must not unlink the socket from a file system. It should
+ not invoke
+ <citerefentry><refentrytitle>shutdown</refentrytitle><manvolnum>2</manvolnum></citerefentry> on
+ sockets it got with <varname>Accept=no</varname>, but it may do so for sockets it got with
+ <varname>Accept=yes</varname> set. Setting <varname>Accept=yes</varname> is mostly useful to allow
+ daemons designed for usage with <citerefentry
+ project='freebsd'><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry> to work
+ unmodified with systemd socket activation.</para>
+
+ <para>Note that depending on this setting the services activated by units of this type are either
+ regular services (in case of <varname>Accept=</varname><option>no</option>) or instances of templated
+ services (in case of <varname>Accept=</varname><option>yes</option>). See the Description section
+ above for a more detailed discussion of the naming rules of triggered services.</para>
<para>For IPv4 and IPv6 connections, the <varname>REMOTE_ADDR</varname> environment variable will
contain the remote IP address, and <varname>REMOTE_PORT</varname> will contain the remote port. This
is the same as the format used by CGI. For <constant>SOCK_RAW</constant>, the port is the IP
- protocol.</para></listitem>
+ protocol.</para>
+
+ <para>It is recommended to set <varname>CollectMode=inactive-or-failed</varname> for service
+ instances activated via <varname>Accept=yes</varname>, to ensure that failed connection services are
+ cleaned up and released from memory, and do not accumulate.</para></listitem>
</varlistentry>
<varlistentry>
<listitem><para>Takes a boolean argument. May only be used in
conjunction with <varname>ListenSpecial=</varname>. If true,
the specified special file is opened in read-write mode, if
- false, in read-only mode. Defaults to false.</para></listitem>
+ false, in read-only mode. Defaults to false.</para>
+
+ <xi:include href="version-info.xml" xpointer="v227"/></listitem>
</varlistentry>
<varlistentry>
socket's buffers won't be cleared, permitting the service to handle any
pending connections after restart, which is the usually expected behaviour.
Defaults to <option>no</option>.
- </para></listitem>
+ </para>
+
+ <xi:include href="version-info.xml" xpointer="v247"/></listitem>
</varlistentry>
<varlistentry>
<listitem><para>The maximum number of connections for a service per source IP address.
This is very similar to the <varname>MaxConnections=</varname> directive
above. Disabled by default.</para>
+
+ <xi:include href="version-info.xml" xpointer="v232"/>
</listitem>
</varlistentry>
and the <ulink
url="http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP
Keepalive HOWTO</ulink> for details.)
- Defaults value is 7200 seconds (2 hours).</para></listitem>
+ Default value is 7200 seconds (2 hours).</para>
+
+ <xi:include href="version-info.xml" xpointer="v216"/></listitem>
</varlistentry>
<varlistentry>
<constant>TCP_KEEPINTVL</constant> socket option (see <citerefentry
project='man-pages'><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 value is 75 seconds.</para></listitem>
+ HOWTO</ulink> for details.) Default value is 75 seconds.</para>
+
+ <xi:include href="version-info.xml" xpointer="v216"/></listitem>
</varlistentry>
<varlistentry>
<citerefentry project='man-pages'><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 value is
- 9.</para></listitem>
+ Keepalive HOWTO</ulink> for details.) Default value is
+ 9.</para>
+
+ <xi:include href="version-info.xml" xpointer="v216"/></listitem>
</varlistentry>
<varlistentry>
messages, and sending them all at once. This controls the
TCP_NODELAY socket option (see
<citerefentry project='die-net'><refentrytitle>tcp</refentrytitle><manvolnum>7</manvolnum></citerefentry>).
- Defaults to <option>false</option>.</para></listitem>
+ Defaults to <option>false</option>.</para>
+
+ <xi:include href="version-info.xml" xpointer="v216"/></listitem>
</varlistentry>
<varlistentry>
third packet in the "three-way handshake").</para>
<para>Disabled by default.</para>
+
+ <xi:include href="version-info.xml" xpointer="v216"/>
</listitem>
</varlistentry>
<citerefentry><refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum></citerefentry>s to this TCP
or UDP port. This controls the <constant>SO_REUSEPORT</constant> socket option. See <citerefentry
project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
- details.</para></listitem>
+ details.</para>
+
+ <xi:include href="version-info.xml" xpointer="v206"/></listitem>
</varlistentry>
<varlistentry>
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>
+ url="https://docs.kernel.org/admin-guide/LSM/Smack.html">Smack</ulink>
+ for details.</para>
+
+ <xi:include href="version-info.xml" xpointer="v196"/></listitem>
</varlistentry>
<varlistentry>
resulting SELinux context originate from either the target
binary that is effectively triggered by socket unit or from
the value of the <varname>SELinuxContext=</varname> option.
- This configuration option only affects sockets with
- <varname>Accept=</varname> mode set to
- <literal>yes</literal>. Also note that this option is useful
- only when MLS/MCS SELinux policy is deployed. Defaults to
- <literal>false</literal>. </para></listitem>
+ This configuration option applies only when activated service
+ is passed in single socket file descriptor, i.e. service
+ instances that have standard input connected to a socket or
+ services triggered by exactly one socket unit. Also note
+ that this option is useful only when MLS/MCS SELinux policy
+ is deployed. Defaults to
+ <literal>false</literal>. </para>
+
+ <xi:include href="version-info.xml" xpointer="v217"/></listitem>
</varlistentry>
<varlistentry>
<constant>PACKET_AUXDATA</constant> socket options, which enable reception of additional per-packet
metadata as ancillary message, on <constant>AF_INET</constant>, <constant>AF_INET6</constant>,
<constant>AF_UNIX</constant> and <constant>AF_PACKET</constant> sockets. Defaults to
- <option>false</option>.</para></listitem>
+ <option>false</option>.</para>
+
+ <xi:include href="version-info.xml" xpointer="v246"/></listitem>
</varlistentry>
<varlistentry>
<term><varname>Timestamping=</varname></term>
<listitem><para>Takes one of <literal>off</literal>, <literal>us</literal> (alias:
- <literal>usec</literal>, <literal>µs</literal>) or <literal>ns</literal> (alias:
+ <literal>usec</literal>, <literal>μs</literal>) or <literal>ns</literal> (alias:
<literal>nsec</literal>). This controls the <constant>SO_TIMESTAMP</constant> or
<constant>SO_TIMESTAMPNS</constant> socket options, and enables whether ingress network traffic shall
- carry timestamping metadata. Defaults to <option>off</option>.</para></listitem>
+ carry timestamping metadata. Defaults to <option>off</option>.</para>
+
+ <xi:include href="version-info.xml" xpointer="v247"/></listitem>
</varlistentry>
<varlistentry>
<varname>Symlinks=</varname>. Normally, it should not be necessary to use this option, and is not
recommended as services might continue to run after the socket unit has been terminated and it should
still be possible to communicate with them via their file system node. Defaults to
- off.</para></listitem>
+ off.</para>
+
+ <xi:include href="version-info.xml" xpointer="v214"/></listitem>
</varlistentry>
<varlistentry>
this option to manage one or more symlinked alias names for a socket, binding their lifecycle together. Note
that if creation of a symlink fails this is not considered fatal for the socket unit, and the socket unit may
still start. If an empty string is assigned, the list of paths is reset. Defaults to an empty
- list.</para></listitem>
+ list.</para>
+
+ <xi:include href="version-info.xml" xpointer="v214"/></listitem>
</varlistentry>
<varlistentry>
be at most 255 characters in length. If this setting is not
used, the file descriptor name defaults to the name of the
socket unit, including its <filename>.socket</filename>
- suffix.</para></listitem>
+ suffix.</para>
+
+ <xi:include href="version-info.xml" xpointer="v227"/></listitem>
</varlistentry>
<varlistentry>
<term><varname>TriggerLimitIntervalSec=</varname></term>
<term><varname>TriggerLimitBurst=</varname></term>
- <listitem><para>Configures a limit on how often this socket unit my be activated within a specific time
- interval. The <varname>TriggerLimitIntervalSec=</varname> may be used to configure the length of the time
- interval in the usual time units <literal>us</literal>, <literal>ms</literal>, <literal>s</literal>,
- <literal>min</literal>, <literal>h</literal>, … and defaults to 2s (See
- <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details on
- the various time units understood). The <varname>TriggerLimitBurst=</varname> setting takes a positive integer
- value and specifies the number of permitted activations per time interval, and defaults to 200 for
- <varname>Accept=yes</varname> sockets (thus by default permitting 200 activations per 2s), and 20 otherwise (20
- activations per 2s). Set either to 0 to disable any form of trigger rate limiting. If the limit is hit, the
- socket unit is placed into a failure mode, and will not be connectible anymore until restarted. Note that this
- limit is enforced before the service activation is enqueued.</para></listitem>
+ <listitem><para>Configures a limit on how often this socket unit may be activated within a specific
+ time interval. The <varname>TriggerLimitIntervalSec=</varname> setting may be used to configure the
+ length of the time interval in the usual time units <literal>us</literal>, <literal>ms</literal>,
+ <literal>s</literal>, <literal>min</literal>, <literal>h</literal>, … and defaults to 2s (See
+ <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
+ details on the various time units understood). The <varname>TriggerLimitBurst=</varname> setting
+ takes a positive integer value and specifies the number of permitted activations per time interval,
+ and defaults to 200 for <varname>Accept=yes</varname> sockets (thus by default permitting 200
+ activations per 2s), and 20 otherwise (20 activations per 2s). Set either to 0 to disable any form of
+ trigger rate limiting.</para>
+
+ <para>If the limit is hit, the socket unit is placed into a failure mode, and will not be connectible
+ anymore until restarted. Note that this limit is enforced before the service activation is
+ enqueued.</para>
+
+ <para>Compare with <varname>PollLimitIntervalSec=</varname>/<varname>PollLimitBurst=</varname>
+ described below, which implements a temporary slowdown if a socket unit is flooded with incoming
+ traffic, as opposed to the permanent failure state
+ <varname>TriggerLimitIntervalSec=</varname>/<varname>TriggerLimitBurst=</varname> results in.</para>
+
+ <xi:include href="version-info.xml" xpointer="v230"/></listitem>
</varlistentry>
- </variablelist>
+ <varlistentry>
+ <term><varname>PollLimitIntervalSec=</varname></term>
+ <term><varname>PollLimitBurst=</varname></term>
- <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>
+ <listitem><para>Configures a limit on how often polling events on the file descriptors backing this
+ socket unit will be considered. This pair of settings is similar to
+ <varname>TriggerLimitIntervalSec=</varname>/<varname>TriggerLimitBurst=</varname> but instead of
+ putting a (fatal) limit on the activation frequency puts a (transient) limit on the polling
+ frequency. The expected parameter syntax and range are identical to that of the aforementioned
+ options, and can be disabled the same way.</para>
+
+ <para>If the polling limit is hit polling is temporarily disabled on it until the specified time
+ window passes. The polling limit hence slows down connection attempts if hit, but unlike the trigger
+ limit won't cause permanent failures. It's the recommended mechanism to deal with DoS attempts
+ through packet flooding.</para>
+
+ <para>The polling limit is enforced per file descriptor to listen on, as opposed to the trigger limit
+ which is enforced for the entire socket unit. This distinction matters for socket units that listen
+ on multiple file descriptors (i.e. have multiple <varname>ListenXYZ=</varname> stanzas).</para>
+
+ <para>These setting defaults to 150 (in case of <varname>Accept=yes</varname>) and 15 (otherwise)
+ polling events per 2s. This is considerably lower than the default values for the trigger limit (see
+ above) and means that the polling limit should typically ensure the trigger limit is never hit,
+ unless one of them is reconfigured or disabled.</para>
+
+ <xi:include href="version-info.xml" xpointer="v255"/></listitem>
+ </varlistentry>
+
+ </variablelist>
+ <xi:include href="systemd.service.xml" xpointer="shared-unit-options" />
</refsect1>
<refsect1>
</para>
<para>
For more extensive descriptions see the "systemd for Developers" series:
- <ulink url="http://0pointer.de/blog/projects/socket-activation.html">Socket Activation</ulink>,
- <ulink url="http://0pointer.de/blog/projects/socket-activation2.html">Socket Activation, part II</ulink>,
- <ulink url="http://0pointer.de/blog/projects/inetd.html">Converting inetd Services</ulink>,
- <ulink url="http://0pointer.de/blog/projects/socket-activated-containers.html">Socket Activated Internet Services and OS Containers</ulink>.
+ <ulink url="https://0pointer.de/blog/projects/socket-activation.html">Socket Activation</ulink>,
+ <ulink url="https://0pointer.de/blog/projects/socket-activation2.html">Socket Activation, part II</ulink>,
+ <ulink url="https://0pointer.de/blog/projects/inetd.html">Converting inetd Services</ulink>,
+ <ulink url="https://0pointer.de/blog/projects/socket-activated-containers.html">Socket Activated Internet Services and OS Containers</ulink>.
</para>
</refsect1>
projects / thirdparty / systemd.git / blobdiff