"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
+ SPDX-License-Identifier: LGPL-2.1+
+
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">
<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 will have a <varname>Before=</varname>
- dependency on the service which they trigger added implicitly. No
- implicit <varname>WantedBy=</varname> or
+ <para>No implicit <varname>WantedBy=</varname> or
<varname>RequiredBy=</varname> dependency from the socket to the
service is added. This means that the service may be started
without the socket, in which case it must be able to open sockets
<refsect1>
<title>Automatic Dependencies</title>
- <para>Socket units automatically gain a <varname>Before=</varname>
- dependency on the service units they activate.</para>
-
- <para>Socket units referring to file system paths (such as AF_UNIX
- sockets or FIFOs) implicitly gain <varname>Requires=</varname> and
- <varname>After=</varname> dependencies on all mount units
- necessary to access those paths.</para>
-
- <para>Socket units using the <varname>BindToDevice=</varname>
- setting automatically gain a <varname>BindsTo=</varname> and
- <varname>After=</varname> dependency on the device unit
- encapsulating the specified network interface.</para>
-
- <para>If <varname>DefaultDependencies=yes</varname> is set (the
- default), socket units automatically gain a
- <varname>Before=</varname> dependency on
- <filename>sockets.target</filename>. They also gain a pair of
- <varname>After=</varname> and <varname>Requires=</varname>
- dependency on <filename>sysinit.target</filename>, and a pair of
- <varname>Before=</varname> and <varname>Conflicts=</varname>
- dependencies on <filename>shutdown.target</filename>. These
- dependencies ensure that the socket unit is started before normal
- services at boot, and is stopped on shutdown.</para>
-
- <para>Additional implicit dependencies may be added as result of
- execution and resource control parameters as documented in
- <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
- and
- <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
+ <refsect2>
+ <title>Implicit Dependencies</title>
+
+ <para>The following dependencies are implicitly added:</para>
+
+ <itemizedlist>
+ <listitem><para>Socket units automatically gain a <varname>Before=</varname>
+ dependency on the service units they activate.</para></listitem>
+
+ <listitem><para>Socket units referring to file system paths (such as AF_UNIX
+ sockets or FIFOs) implicitly gain <varname>Requires=</varname> and
+ <varname>After=</varname> dependencies on all mount units
+ necessary to access those paths.</para></listitem>
+
+ <listitem><para>Socket units using the <varname>BindToDevice=</varname>
+ setting automatically gain a <varname>BindsTo=</varname> and
+ <varname>After=</varname> dependency on the device unit
+ encapsulating the specified network interface.</para></listitem>
+ </itemizedlist>
+
+ <para>Additional implicit dependencies may be added as result of
+ execution and resource control parameters as documented in
+ <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ and
+ <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
+ </refsect2>
+
+ <refsect2>
+ <title>Default Dependencies</title>
+
+ <para>The following dependencies are added unless
+ <varname>DefaultDependencies=no</varname> is set:</para>
+
+ <itemizedlist>
+ <listitem><para>Socket units automatically gain a
+ <varname>Before=</varname> dependency on
+ <filename>sockets.target</filename>.</para></listitem>
+
+ <listitem><para>Socket units automatically gain a pair of
+ <varname>After=</varname> and <varname>Requires=</varname>
+ dependency on <filename>sysinit.target</filename>, and a pair of
+ <varname>Before=</varname> and <varname>Conflicts=</varname>
+ dependencies on <filename>shutdown.target</filename>. These
+ dependencies ensure that the socket unit is started before normal
+ services at boot, and is stopped on shutdown. Only sockets
+ involved with early boot or late system shutdown should disable
+ <varname>DefaultDependencies=</varname> option.</para></listitem>
+ </itemizedlist>
+ </refsect2>
</refsect1>
<refsect1>
<varname>BindIPv6Only=</varname> setting (see below).
</para>
+ <para>If the address string is a string in the format
+ <literal>vsock:x:y</literal>, it is read as CID <literal>x</literal> on
+ a port <literal>y</literal> address in the
+ <constant>AF_VSOCK</constant> family. The CID is a unique 32-bit
+ integer identifier in <constant>AF_VSOCK</constant> analogous to an IP
+ address. Specifying the CID is optional, and may be set to the empty
+ string.</para>
+
<para>Note that <constant>SOCK_SEQPACKET</constant> (i.e.
<varname>ListenSequentialPacket=</varname>) is only available
for <constant>AF_UNIX</constant> sockets.
<term><varname>ListenUSBFunction=</varname></term>
<listitem><para>Specifies a <ulink
url="https://www.kernel.org/doc/Documentation/usb/functionfs.txt">USB
- FunctionFS</ulink> endpoint location to listen on, for
+ FunctionFS</ulink> endpoints location to listen on, for
implementation of USB gadget functions. This expects an
- absolute file system path as the argument. Behavior otherwise
- is very similar to the <varname>ListenFIFO=</varname>
+ absolute file system path of functionfs mount point as the argument.
+ Behavior otherwise is very similar to the <varname>ListenFIFO=</varname>
directive above. Use this to open the FunctionFS endpoint
<filename>ep0</filename>. When using this option, the
activated service has to have the
specified network interfaces. This controls the
SO_BINDTODEVICE socket option (see <citerefentry
project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
- for details). If this option is used, an automatic dependency
+ for details). If this option is used, an implicit dependency
from this socket unit on the network interface device unit
(<citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>
is created. Note that setting this parameter might result in
</varlistentry>
<varlistentry>
+ <term><varname>MaxConnectionsPerSource=</varname></term>
+ <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>
+ </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
and the kernel will ignore initial ACK packets without any
data. The argument specifies the approximate amount of time
the kernel should wait for incoming data before falling back
- to the normal behavior of honouring empty ACK packets. This
+ to the normal behavior of honoring empty ACK packets. This
option is beneficial for protocols where the client sends the
data first (e.g. HTTP, in contrast to SMTP), because the
server process will not be woken up unnecessarily before it
<varlistentry>
<term><varname>Symlinks=</varname></term>
- <listitem><para>Takes a list of file system paths. The
- specified paths will be created as symlinks to the AF_UNIX
- socket path or FIFO path of this socket unit. If this setting
- is used, only one AF_UNIX socket in the file system or one
- FIFO may be configured for the socket unit. Use this option to
- manage one or more symlinked alias names for a socket, binding
- their lifecycle together. Defaults to the empty
+ <listitem><para>Takes a list of file system paths. The specified paths will be created as symlinks to the
+ <constant>AF_UNIX</constant> socket path or FIFO path of this socket unit. If this setting is used, only one
+ <constant>AF_UNIX</constant> socket in the file system or one FIFO may be configured for the socket unit. Use
+ 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>
</varlistentry>
suffix.</para></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>
+ </varlistentry>
+
</variablelist>
<para>Check