git: 7aa030f7ccf4 - stable/12 - tcp: document TCP Fast Open (RFC 7413) in tcp(4)
Philip Paeps
philip at FreeBSD.org
Mon Sep 6 01:16:59 UTC 2021
The branch stable/12 has been updated by philip:
URL: https://cgit.FreeBSD.org/src/commit/?id=7aa030f7ccf48d639e5c7e10cdd0392515890541
commit 7aa030f7ccf48d639e5c7e10cdd0392515890541
Author: Philip Paeps <philip at FreeBSD.org>
AuthorDate: 2021-09-03 02:33:12 +0000
Commit: Philip Paeps <philip at FreeBSD.org>
CommitDate: 2021-09-06 01:13:47 +0000
tcp: document TCP Fast Open (RFC 7413) in tcp(4)
Adds documentation for the TCP_FASTOPEN socket option
and related MIB variables to the tcp(4) manual page.
PR: 257907
Reviewed by: gbe
Differential Revision: https://reviews.freebsd.org/D31764
(cherry picked from commit 71611b0c688568d513c665e1af3d95fcd50605fa)
---
share/man/man4/tcp.4 | 134 +++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 134 insertions(+)
diff --git a/share/man/man4/tcp.4 b/share/man/man4/tcp.4
index ad7e3f117d68..d8f481697879 100644
--- a/share/man/man4/tcp.4
+++ b/share/man/man4/tcp.4
@@ -148,6 +148,54 @@ connection.
See
.Xr mod_cc 4
for details.
+.It Dv TCP_FASTOPEN
+Enable or disable TCP Fast Open (TFO).
+To use this option, the kernel must be built with the
+.Dv TCP_RFC7413
+option.
+.Pp
+This option can be set on the socket either before or after the
+.Xr listen 2
+is invoked.
+Clearing this option on a listen socket after it has been set has no effect on
+existing TFO connections or TFO connections in progress; it only prevents new
+TFO connections from being established.
+.Pp
+For passively-created sockets, the
+.Dv TCP_FASTOPEN
+socket option can be queried to determine whether the connection was established
+using TFO.
+Note that connections that are established via a TFO
+.Tn SYN ,
+but that fall back to using a non-TFO
+.Tn SYN|ACK
+will have the
+.Dv TCP_FASTOPEN
+socket option set.
+.Pp
+In addition to the facilities defined in RFC7413, this implementation supports a
+pre-shared key (PSK) mode of operation in which the TFO server requires the
+client to be in posession of a shared secret in order for the client to be able
+to successfully open TFO connections with the server.
+This is useful, for example, in environments where TFO servers are exposed to
+both internal and external clients and only wish to allow TFO connections from
+internal clients.
+.Pp
+In the PSK mode of operation, the server generates and sends TFO cookies to
+requesting clients as usual.
+However, when validating cookies received in TFO SYNs from clients, the server
+requires the client-supplied cookie to equal
+.Bd -literal -offset left
+SipHash24(key=\fI16-byte-psk\fP, msg=\fIcookie-sent-to-client\fP)
+.Ed
+.Pp
+Multiple concurrent valid pre-shared keys are supported so that time-based
+rolling PSK invalidation policies can be implemented in the system.
+The default number of concurrent pre-shared keys is 2.
+.Pp
+This can be adjusted with the
+.Dv TCP_RFC7413_MAX_PSKS
+kernel option.
.It Dv TCP_FUNCTION_BLK
Select or query the set of functions that TCP will use for this connection.
This allows a user to select an alternate TCP stack.
@@ -613,6 +661,92 @@ Enable path MTU blackhole detection only for IPv6.
MSS to try for IPv4 if PMTU blackhole detection is turned on.
.It Va v6pmtud_blackhole_mss
MSS to try for IPv6 if PMTU blackhole detection is turned on.
+.It Va fastopen.acceptany
+When non-zero, all client-supplied TFO cookies will be considered to be valid.
+The default is 0.
+.It Va fastopen.autokey
+When this and
+.Va net.inet.tcp.fastopen.server_enable
+are non-zero, a new key will be automatically generated after this specified
+seconds.
+The default is 120.
+.It Va fastopen.ccache_bucket_limit
+The maximum number of entries in a client cookie cache bucket.
+The default value can be tuned with the
+.Dv TCP_FASTOPEN_CCACHE_BUCKET_LIMIT_DEFAULT
+kernel option or by setting
+.Va net.inet.tcp.fastopen_ccache_bucket_limit
+in the
+.Xr loader 8 .
+.It Va fastopen.ccache_buckets
+The number of client cookie cache buckets.
+Read-only.
+The value can be tuned with the
+.Dv TCP_FASTOPEN_CCACHE_BUCKETS_DEFAULT
+kernel option or by setting
+.Va fastopen.ccache_buckets
+in the
+.Xr loader 8 .
+.It Va fastopen.ccache_list
+Print the client cookie cache.
+Read-only.
+.It Va fastopen.client_enable
+When zero, no new active (i.e., client) TFO connections can be created.
+On the transition from enabled to disabled, the client cookie cache is cleared
+and disabled.
+The transition from enabled to disabled does not affect any active TFO
+connections in progress; it only prevents new ones from being established.
+The default is 0.
+.It Va fastopen.keylen
+The key length in bytes.
+Read-only.
+.It Va fastopen.maxkeys
+The maximum number of keys supported.
+Read-only,
+.It Va fastopen.maxpsks
+The maximum number of pre-shared keys supported.
+Read-only.
+.It Va fastopen.numkeys
+The current number of keys installed.
+Read-only.
+.It Va fastopen.numpsks
+The current number of pre-shared keys installed.
+Read-only.
+.It Va fastopen.path_disable_time
+When a failure occurs while trying to create a new active (i.e., client) TFO
+connection, new active connections on the same path, as determined by the tuple
+.Brq client_ip, server_ip, server_port ,
+will be forced to be non-TFO for this many seconds.
+Note that the path disable mechanism relies on state stored in client cookie
+cache entries, so it is possible for the disable time for a given path to be
+reduced if the corresponding client cookie cache entry is reused due to resource
+pressure before the disable period has elapsed.
+The default is
+.Dv TCP_FASTOPEN_PATH_DISABLE_TIME_DEFAULT .
+.It Va fastopen.psk_enable
+When non-zero, pre-shared key (PSK) mode is enabled for all TFO servers.
+On the transition from enabled to disabled, all installed pre-shared keys are
+removed.
+The default is 0.
+.It Va fastopen.server_enable
+When zero, no new passive (i.e., server) TFO connections can be created.
+On the transition from enabled to disabled, all installed keys and pre-shared
+keys are removed.
+On the transition from disabled to enabled, if
+.Va fastopen.autokey
+is non-zero and there are no keys installed, a new key will be generated
+immediately.
+The transition from enabled to disabled does not affect any passive TFO
+connections in progress; it only prevents new ones from being established.
+The default is 0.
+.It Va fastopen.setkey
+Install a new key by writing
+.Va net.inet.tcp.fastopen.keylen
+bytes to this sysctl.
+.It Va fastopen.setpsk
+Install a new pre-shared key by writing
+.Va net.inet.tcp.fastopen.keylen
+bytes to this sysctl.
.It Va functions_available
List of available TCP function blocks (TCP stacks).
.It Va functions_default
More information about the dev-commits-src-branches
mailing list