Merging upstream version 4.23.0.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 72 insertions, 6 deletions

diff --git a/upstream/opensuse-tumbleweed/man5/systemd.socket.5 b/upstream/opensuse-tumbleweed/man5/systemd.socket.5
index 1fb6d77d..f8d4a7cd 100644
--- a/upstream/opensuse-tumbleweed/man5/systemd.socket.5
+++ b/upstream/opensuse-tumbleweed/man5/systemd.socket.5
@@ -1,5 +1,5 @@
 '\" t
-.TH "SYSTEMD\&.SOCKET" "5" "" "systemd 254" "systemd.socket"
+.TH "SYSTEMD\&.SOCKET" "5" "" "systemd 255" "systemd.socket"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -320,6 +320,8 @@ ep0\&. When using this option, the activated service has to have the
 and
 \fIUSBFunctionStrings=\fR
 options set\&.
+.sp
+Added in version 227\&.
 .RE
 .PP
 \fISocketProtocol=\fR
@@ -328,6 +330,8 @@ Takes one of
 \fBudplite\fR
 or
 \fBsctp\fR\&. The socket will use the UDP\-Lite (\fBIPPROTO_UDPLITE\fR) or SCTP (\fBIPPROTO_SCTP\fR) protocol, respectively\&.
+.sp
+Added in version 229\&.
 .RE
 .PP
 \fIBindIPv6Only=\fR
@@ -351,9 +355,9 @@ for details)\&. If
 .RS 4
 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
 \fBlisten\fR(2)
-for details\&. Note that this value is silently capped by the
+for details\&. Defaults to 4294967295\&. Note that this value is silently capped by the
 "net\&.core\&.somaxconn"
-sysctl, which typically defaults to 4096\&. By default this is set to 4294967295, so that the sysctl takes full effect\&.
+sysctl, which typically defaults to 4096, so typically the sysctl is the setting that actually matters\&.
 .RE
 .PP
 \fIBindToDevice=\fR
@@ -371,6 +375,8 @@ for details)\&. If this option is used, an implicit dependency from this socket
 Takes a UNIX user/group name\&. When specified, all
 \fBAF_UNIX\fR
 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\*(Aqs default group\&.
+.sp
+Added in version 214\&.
 .RE
 .PP
 \fISocketMode=\fR
@@ -423,6 +429,8 @@ for service instances activated via
 .RS 4
 Takes a boolean argument\&. May only be used in conjunction with
 \fIListenSpecial=\fR\&. If true, the specified special file is opened in read\-write mode, if false, in read\-only mode\&. Defaults to false\&.
+.sp
+Added in version 227\&.
 .RE
 .PP
 \fIFlushPending=\fR
@@ -430,6 +438,8 @@ Takes a boolean argument\&. May only be used in conjunction with
 Takes a boolean argument\&. May only be used when
 \fBAccept=no\fR\&. If yes, the socket\*(Aqs buffers are cleared after the triggered service exited\&. This causes any pending data to be flushed and any pending incoming connections to be rejected\&. If no, the socket\*(Aqs buffers won\*(Aqt be cleared, permitting the service to handle any pending connections after restart, which is the usually expected behaviour\&. Defaults to
 \fBno\fR\&.
+.sp
+Added in version 247\&.
 .RE
 .PP
 \fIMaxConnections=\fR
@@ -446,6 +456,8 @@ or datagram sockets\&. Defaults to 64\&.
 The maximum number of connections for a service per source IP address\&. This is very similar to the
 \fIMaxConnections=\fR
 directive above\&. Disabled by default\&.
+.sp
+Added in version 232\&.
 .RE
 .PP
 \fIKeepAlive=\fR
@@ -468,6 +480,8 @@ Takes time (in seconds) as argument\&. The connection needs to remain idle befor
 and the
 \m[blue]\fBTCP Keepalive HOWTO\fR\m[]\&\s-2\u[2]\d\s+2
 for details\&.) Default value is 7200 seconds (2 hours)\&.
+.sp
+Added in version 216\&.
 .RE
 .PP
 \fIKeepAliveIntervalSec=\fR
@@ -481,6 +495,8 @@ socket option (see
 and the
 \m[blue]\fBTCP Keepalive HOWTO\fR\m[]\&\s-2\u[2]\d\s+2
 for details\&.) Default value is 75 seconds\&.
+.sp
+Added in version 216\&.
 .RE
 .PP
 \fIKeepAliveProbes=\fR
@@ -490,6 +506,8 @@ Takes an integer as argument\&. It is the number of unacknowledged probes to sen
 and the
 \m[blue]\fBTCP Keepalive HOWTO\fR\m[]\&\s-2\u[2]\d\s+2
 for details\&.) Default value is 9\&.
+.sp
+Added in version 216\&.
 .RE
 .PP
 \fINoDelay=\fR
@@ -497,6 +515,8 @@ for details\&.) Default value is 9\&.
 Takes a boolean argument\&. TCP Nagle\*(Aqs algorithm works by combining a number of small outgoing messages, and sending them all at once\&. This controls the TCP_NODELAY socket option (see
 \fBtcp\fR(7))\&. Defaults to
 \fBfalse\fR\&.
+.sp
+Added in version 216\&.
 .RE
 .PP
 \fIPriority=\fR
@@ -520,6 +540,8 @@ If the client also uses the
 option, the latency of the initial connection may be reduced, because the kernel will send data in the final packet establishing the connection (the third packet in the "three\-way handshake")\&.
 .sp
 Disabled by default\&.
+.sp
+Added in version 216\&.
 .RE
 .PP
 \fIReceiveBuffer=\fR, \fISendBuffer=\fR
@@ -576,6 +598,8 @@ Takes a boolean value\&. If true, allows multiple
 socket option\&. See
 \fBsocket\fR(7)
 for details\&.
+.sp
+Added in version 206\&.
 .RE
 .PP
 \fISmackLabel=\fR, \fISmackLabelIPIn=\fR, \fISmackLabelIPOut=\fR
@@ -587,6 +611,8 @@ and
 "security\&.SMACK64IPOUT", respectively, i\&.e\&. the security label of the FIFO, or the security label for the incoming or outgoing connections of the socket, respectively\&. See
 \m[blue]\fBSmack\fR\m[]\&\s-2\u[3]\d\s+2
 for details\&.
+.sp
+Added in version 196\&.
 .RE
 .PP
 \fISELinuxContextFromNet=\fR
@@ -595,6 +621,8 @@ Takes a boolean argument\&. When true, systemd will attempt to figure out the SE
 \fISELinuxContext=\fR
 option\&. 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
 "false"\&.
+.sp
+Added in version 217\&.
 .RE
 .PP
 \fIPipeSize=\fR
@@ -671,6 +699,8 @@ and
 \fBAF_PACKET\fR
 sockets\&. Defaults to
 \fBfalse\fR\&.
+.sp
+Added in version 246\&.
 .RE
 .PP
 \fITimestamping=\fR
@@ -689,13 +719,15 @@ or
 \fBSO_TIMESTAMPNS\fR
 socket options, and enables whether ingress network traffic shall carry timestamping metadata\&. Defaults to
 \fBoff\fR\&.
+.sp
+Added in version 247\&.
 .RE
 .PP
 \fITCPCongestion=\fR
 .RS 4
 Takes a string value\&. Controls the TCP congestion algorithm used by this socket\&. Should be one of
 "westwood",
-"veno",
+"reno",
 "cubic",
 "lp"
 or any other available algorithm supported by the IP stack\&. This setting applies only to stream sockets\&.
@@ -748,6 +780,8 @@ Takes a boolean argument\&. If enabled, any file nodes created by this socket un
 \fBAF_UNIX\fR
 sockets in the file system, POSIX message queues, FIFOs, as well as any symlinks to them configured with
 \fISymlinks=\fR\&. 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\&.
+.sp
+Added in version 214\&.
 .RE
 .PP
 \fISymlinks=\fR
@@ -757,6 +791,8 @@ Takes a list of file system paths\&. The specified paths will be created as syml
 socket path or FIFO path of this socket unit\&. If this setting is used, only one
 \fBAF_UNIX\fR
 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\&.
+.sp
+Added in version 214\&.
 .RE
 .PP
 \fIFileDescriptorName=\fR
@@ -767,13 +803,15 @@ call to acquire the names configured for the received file descriptors\&. Names
 ":", and must 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
 \&.socket
 suffix\&.
+.sp
+Added in version 227\&.
 .RE
 .PP
 \fITriggerLimitIntervalSec=\fR, \fITriggerLimitBurst=\fR
 .RS 4
 Configures a limit on how often this socket unit may be activated within a specific time interval\&. The
 \fITriggerLimitIntervalSec=\fR
-may be used to configure the length of the time interval in the usual time units
+setting may be used to configure the length of the time interval in the usual time units
 "us",
 "ms",
 "s",
@@ -784,7 +822,35 @@ for details on the various time units understood)\&. The
 \fITriggerLimitBurst=\fR
 setting takes a positive integer value and specifies the number of permitted activations per time interval, and defaults to 200 for
 \fIAccept=yes\fR
-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\&.
+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\&.
+.sp
+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\&.
+.sp
+Compare with
+\fIPollLimitIntervalSec=\fR/\fIPollLimitBurst=\fR
+described below, which implements a temporary slowdown if a socket unit is flooded with incoming traffic, as opposed to the permanent failure state
+\fITriggerLimitIntervalSec=\fR/\fITriggerLimitBurst=\fR
+results in\&.
+.sp
+Added in version 230\&.
+.RE
+.PP
+\fIPollLimitIntervalSec=\fR, \fIPollLimitBurst=\fR
+.RS 4
+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
+\fITriggerLimitIntervalSec=\fR/\fITriggerLimitBurst=\fR
+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\&.
+.sp
+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\*(Aqt cause permanent failures\&. It\*(Aqs the recommended mechanism to deal with DoS attempts through packet flooding\&.
+.sp
+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
+\fIListenXYZ=\fR
+stanzas)\&.
+.sp
+These setting defaults to 150 (in case of
+\fIAccept=yes\fR) 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\&.
+.sp
+Added in version 255\&.
 .RE
 .PP
 Check