* [patch v2] tcp.7: Add description for TCP_FASTOPEN and TCP_FASTOPEN_CONNECT options @ 2021-09-17 4:17 Wei Wang 2021-09-20 19:50 ` Alejandro Colomar (man-pages) 0 siblings, 1 reply; 3+ messages in thread From: Wei Wang @ 2021-09-17 4:17 UTC (permalink / raw) To: linux-man, Alejandro Colomar, Michael Kerrisk; +Cc: netdev, Yuchung Cheng TCP_FASTOPEN socket option was added by: commit 8336886f786fdacbc19b719c1f7ea91eb70706d4 TCP_FASTOPEN_CONNECT socket option was added by the following patch series: commit 065263f40f0972d5f1cd294bb0242bd5aa5f06b2 commit 25776aa943401662617437841b3d3ea4693ee98a commit 19f6d3f3c8422d65b5e3d2162e30ef07c6e21ea2 commit 3979ad7e82dfe3fb94a51c3915e64ec64afa45c3 Add detailed description for these 2 options. Also add descriptions for /proc entry tcp_fastopen and tcp_fastopen_key. Signed-off-by: Wei Wang <weiwan@google.com> Reviewed-by: Yuchung Cheng <ycheng@google.com> --- Change in v2: corrected some format issues man7/tcp.7 | 110 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 110 insertions(+) diff --git a/man7/tcp.7 b/man7/tcp.7 index 0a7c61a37..5a6fa7f50 100644 --- a/man7/tcp.7 +++ b/man7/tcp.7 @@ -423,6 +423,28 @@ option. .\" Since 2.4.0-test7 Enable RFC\ 2883 TCP Duplicate SACK support. .TP +.IR tcp_fastopen " (Bitmask; default: 0x1; since Linux 3.7)" +Enables RFC\ 7413 Fast Open support. +The flag is used as a bitmap with the following values: +.RS +.IP 0x1 +Enables client side Fast Open support +.IP 0x2 +Enables server side Fast Open support +.IP 0x4 +Allows client side to transmit data in SYN without Fast Open option +.IP 0x200 +Allows server side to accept SYN data without Fast Open option +.IP 0x400 +Enables Fast Open on all listeners without +.B TCP_FASTOPEN +socket option +.RE +.TP +.IR tcp_fastopen_key " (since Linux 3.7)" +Set server side RFC\ 7413 Fast Open key to generate Fast Open cookie +when server side Fast Open support is enabled. +.TP .IR tcp_ecn " (Integer; default: see below; since Linux 2.4)" .\" Since 2.4.0-test7 Enable RFC\ 3168 Explicit Congestion Notification. @@ -1202,6 +1224,94 @@ Bound the size of the advertised window to this value. The kernel imposes a minimum size of SOCK_MIN_RCVBUF/2. This option should not be used in code intended to be portable. +.TP +.BR TCP_FASTOPEN " (since Linux 3.6)" +This option enables Fast Open (RFC\ 7413) on the listener socket. +The value specifies the maximum length of pending SYNs +(similar to the backlog argument in +.BR listen (2)). +Once enabled, +the listener socket grants the TCP Fast Open cookie on incoming +SYN with TCP Fast Open option. +.IP +More importantly it accepts the data in SYN with a valid Fast Open cookie +and responds SYN-ACK acknowledging both the data and the SYN sequence. +.BR accept (2) +returns a socket that is available for read and write when the handshake +has not completed yet. +Thus the data exchange can commence before the handshake completes. +This option requires enabling the server-side support on sysctl +.IR net.ipv4.tcp_fastopen +(see above). +For TCP Fast Open client-side support, +see +.BR send (2) +.B MSG_FASTOPEN +or +.B TCP_FASTOPEN_CONNECT +below. +.TP +.BR TCP_FASTOPEN_CONNECT " (since Linux 4.11)" +This option enables an alternative way to perform Fast Open on the active +side (client). +When this option is enabled, +.BR connect (2) +would behave differently depending if a Fast Open cookie is available for +the destination. +.IP +If a cookie is not available (i.e. first contact to the destination), +.BR connect (2) +behaves as usual by sending a SYN immediately, +except the SYN would include an empty Fast Open cookie option to solicit a +cookie. +.IP +If a cookie is available, +.BR connect (2) +would return 0 immediately but the SYN transmission is defered. +A subsequent +.BR write (2) +or +.BR sendmsg (2) +would trigger a SYN with data plus cookie in the Fast Open option. +In other words, +the actual connect operation is deferred until data is supplied. +.IP +.B Note: +While this option is designed for convenience, +enabling it does change the behaviors and might set new +.I errnos +of socket calls. +With cookie present, +.BR write (2) +/ +.BR sendmsg (2) +must be called right after +.BR connect (2) +in order to send out SYN+data to complete 3WHS and establish connection. +Calling +.BR read (2) +right after +.BR connect (2) +without +.BR write (2) +will cause the blocking socket to be blocked forever. +The application should use either +.B TCP_FASTOPEN_CONNECT +or +.BR send (2) +with +.B MSG_FASTOPEN , +instead of both on the same connection. +.IP +Here is the typical call flow with this new option: + s = socket(); + setsockopt(s, IPPROTO_TCP, TCP_FASTOPEN_CONNECT, 1, ...); + connect(s); + write(s); // write() should always follow connect() in order to + // trigger SYN to go out + read(s)/write(s); + ... + close(s); .SS Sockets API TCP provides limited support for out-of-band data, in the form of (a single byte of) urgent data. -- 2.33.0.464.g1972c5931b-goog ^ permalink raw reply related [flat|nested] 3+ messages in thread
* Re: [patch v2] tcp.7: Add description for TCP_FASTOPEN and TCP_FASTOPEN_CONNECT options 2021-09-17 4:17 [patch v2] tcp.7: Add description for TCP_FASTOPEN and TCP_FASTOPEN_CONNECT options Wei Wang @ 2021-09-20 19:50 ` Alejandro Colomar (man-pages) 2021-09-24 22:01 ` Wei Wang 0 siblings, 1 reply; 3+ messages in thread From: Alejandro Colomar (man-pages) @ 2021-09-20 19:50 UTC (permalink / raw) To: Wei Wang; +Cc: netdev, Yuchung Cheng, Michael Kerrisk, linux-man Hello Wei, On 9/17/21 6:17 AM, Wei Wang wrote: > TCP_FASTOPEN socket option was added by: > commit 8336886f786fdacbc19b719c1f7ea91eb70706d4 > TCP_FASTOPEN_CONNECT socket option was added by the following patch > series: > commit 065263f40f0972d5f1cd294bb0242bd5aa5f06b2 > commit 25776aa943401662617437841b3d3ea4693ee98a > commit 19f6d3f3c8422d65b5e3d2162e30ef07c6e21ea2 > commit 3979ad7e82dfe3fb94a51c3915e64ec64afa45c3 > Add detailed description for these 2 options. > Also add descriptions for /proc entry tcp_fastopen and tcp_fastopen_key. > > Signed-off-by: Wei Wang <weiwan@google.com> > Reviewed-by: Yuchung Cheng <ycheng@google.com> Thanks for the patch (and the review, Yuchung)! Please see some comments below. Cheers, Alex > --- > Change in v2: corrected some format issues > > man7/tcp.7 | 110 +++++++++++++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 110 insertions(+) > > diff --git a/man7/tcp.7 b/man7/tcp.7 > index 0a7c61a37..5a6fa7f50 100644 > --- a/man7/tcp.7 > +++ b/man7/tcp.7 > @@ -423,6 +423,28 @@ option. > .\" Since 2.4.0-test7 > Enable RFC\ 2883 TCP Duplicate SACK support. > .TP > +.IR tcp_fastopen " (Bitmask; default: 0x1; since Linux 3.7)" > +Enables RFC\ 7413 Fast Open support. > +The flag is used as a bitmap with the following values: > +.RS > +.IP 0x1 > +Enables client side Fast Open support > +.IP 0x2 > +Enables server side Fast Open support > +.IP 0x4 > +Allows client side to transmit data in SYN without Fast Open option > +.IP 0x200 > +Allows server side to accept SYN data without Fast Open option > +.IP 0x400 > +Enables Fast Open on all listeners without > +.B TCP_FASTOPEN > +socket option > +.RE > +.TP > +.IR tcp_fastopen_key " (since Linux 3.7)" > +Set server side RFC\ 7413 Fast Open key to generate Fast Open cookie > +when server side Fast Open support is enabled. > +.TP > .IR tcp_ecn " (Integer; default: see below; since Linux 2.4)" > .\" Since 2.4.0-test7 > Enable RFC\ 3168 Explicit Congestion Notification. > @@ -1202,6 +1224,94 @@ Bound the size of the advertised window to this value. > The kernel imposes a minimum size of SOCK_MIN_RCVBUF/2. > This option should not be used in code intended to be > portable. > +.TP > +.BR TCP_FASTOPEN " (since Linux 3.6)" > +This option enables Fast Open (RFC\ 7413) on the listener socket. > +The value specifies the maximum length of pending SYNs > +(similar to the backlog argument in > +.BR listen (2)). > +Once enabled, > +the listener socket grants the TCP Fast Open cookie on incoming > +SYN with TCP Fast Open option. > +.IP > +More importantly it accepts the data in SYN with a valid Fast Open cookie > +and responds SYN-ACK acknowledging both the data and the SYN sequence. > +.BR accept (2) > +returns a socket that is available for read and write when the handshake > +has not completed yet. > +Thus the data exchange can commence before the handshake completes. > +This option requires enabling the server-side support on sysctl > +.IR net.ipv4.tcp_fastopen > +(see above). > +For TCP Fast Open client-side support, > +see > +.BR send (2) > +.B MSG_FASTOPEN > +or > +.B TCP_FASTOPEN_CONNECT > +below. > +.TP > +.BR TCP_FASTOPEN_CONNECT " (since Linux 4.11)" > +This option enables an alternative way to perform Fast Open on the active > +side (client). > +When this option is enabled, > +.BR connect (2) > +would behave differently depending if a Fast Open cookie is available for > +the destination. > +.IP > +If a cookie is not available (i.e. first contact to the destination), > +.BR connect (2) > +behaves as usual by sending a SYN immediately, > +except the SYN would include an empty Fast Open cookie option to solicit a > +cookie. > +.IP > +If a cookie is available, > +.BR connect (2) > +would return 0 immediately but the SYN transmission is defered. > +A subsequent > +.BR write (2) > +or > +.BR sendmsg (2) > +would trigger a SYN with data plus cookie in the Fast Open option. > +In other words, > +the actual connect operation is deferred until data is supplied. > +.IP > +.B Note: > +While this option is designed for convenience, > +enabling it does change the behaviors and might set new > +.I errnos typo? errno values? > +of socket calls. The above is not very clear to me. > +With cookie present, > +.BR write (2) > +/ Does this mean an "or"? If so, prefer the "or". > +.BR sendmsg (2) > +must be called right after > +.BR connect (2) > +in order to send out SYN+data to complete 3WHS and establish connection. > +Calling > +.BR read (2) > +right after > +.BR connect (2) > +without > +.BR write (2) > +will cause the blocking socket to be blocked forever. > +The application should use either > +.B TCP_FASTOPEN_CONNECT > +or > +.BR send (2) This is not clear to me. So TCP_FASTOPEN_CONNECT can use write(2) and sendmsg(2) (mentioned above), and TCP_FASTOPEN can only use send(2)? Or what did you mean? > +with > +.B MSG_FASTOPEN , > +instead of both on the same connection. From "The application ...": Does this have relation with the text just above it? It appears to me to be a more generic statement that both options shouldn't be mixed, so maybe a new paragraph is more appropriate. > +.IP > +Here is the typical call flow with this new option: > + s = socket(); > + setsockopt(s, IPPROTO_TCP, TCP_FASTOPEN_CONNECT, 1, ...); > + connect(s); > + write(s); // write() should always follow connect() in order to > + // trigger SYN to go out > + read(s)/write(s); > + ... > + close(s); See man-pages(7): Indentation of structure definitions, shell session logs, and so on When structure definitions, shell session logs, and so on are included in running text, indent them by 4 spaces (i.e., a block enclosed by .in +4n and .in), format them using the .EX and EE macros, and surround them with suit‐ able paragraph markers (either .PP or .IP). For example: .PP .in +4n .EX int main(int argc, char *argv[]) { return 0; } .EE .in .PP > .SS Sockets API > TCP provides limited support for out-of-band data, > in the form of (a single byte of) urgent data. > -- Alejandro Colomar Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/ http://www.alejandro-colomar.es/ ^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: [patch v2] tcp.7: Add description for TCP_FASTOPEN and TCP_FASTOPEN_CONNECT options 2021-09-20 19:50 ` Alejandro Colomar (man-pages) @ 2021-09-24 22:01 ` Wei Wang 0 siblings, 0 replies; 3+ messages in thread From: Wei Wang @ 2021-09-24 22:01 UTC (permalink / raw) To: Alejandro Colomar (man-pages) Cc: netdev, Yuchung Cheng, Michael Kerrisk, linux-man On Mon, Sep 20, 2021 at 12:50 PM Alejandro Colomar (man-pages) <alx.manpages@gmail.com> wrote: > > Hello Wei, > > On 9/17/21 6:17 AM, Wei Wang wrote: > > TCP_FASTOPEN socket option was added by: > > commit 8336886f786fdacbc19b719c1f7ea91eb70706d4 > > TCP_FASTOPEN_CONNECT socket option was added by the following patch > > series: > > commit 065263f40f0972d5f1cd294bb0242bd5aa5f06b2 > > commit 25776aa943401662617437841b3d3ea4693ee98a > > commit 19f6d3f3c8422d65b5e3d2162e30ef07c6e21ea2 > > commit 3979ad7e82dfe3fb94a51c3915e64ec64afa45c3 > > Add detailed description for these 2 options. > > Also add descriptions for /proc entry tcp_fastopen and tcp_fastopen_key. > > > > Signed-off-by: Wei Wang <weiwan@google.com> > > Reviewed-by: Yuchung Cheng <ycheng@google.com> > > Thanks for the patch (and the review, Yuchung)! > > Please see some comments below. > > Cheers, > > Alex > > > --- > > Change in v2: corrected some format issues > > > > man7/tcp.7 | 110 +++++++++++++++++++++++++++++++++++++++++++++++++++++ > > 1 file changed, 110 insertions(+) > > > > diff --git a/man7/tcp.7 b/man7/tcp.7 > > index 0a7c61a37..5a6fa7f50 100644 > > --- a/man7/tcp.7 > > +++ b/man7/tcp.7 > > @@ -423,6 +423,28 @@ option. > > .\" Since 2.4.0-test7 > > Enable RFC\ 2883 TCP Duplicate SACK support. > > .TP > > +.IR tcp_fastopen " (Bitmask; default: 0x1; since Linux 3.7)" > > +Enables RFC\ 7413 Fast Open support. > > +The flag is used as a bitmap with the following values: > > +.RS > > +.IP 0x1 > > +Enables client side Fast Open support > > +.IP 0x2 > > +Enables server side Fast Open support > > +.IP 0x4 > > +Allows client side to transmit data in SYN without Fast Open option > > +.IP 0x200 > > +Allows server side to accept SYN data without Fast Open option > > +.IP 0x400 > > +Enables Fast Open on all listeners without > > +.B TCP_FASTOPEN > > +socket option > > +.RE > > +.TP > > +.IR tcp_fastopen_key " (since Linux 3.7)" > > +Set server side RFC\ 7413 Fast Open key to generate Fast Open cookie > > +when server side Fast Open support is enabled. > > +.TP > > .IR tcp_ecn " (Integer; default: see below; since Linux 2.4)" > > .\" Since 2.4.0-test7 > > Enable RFC\ 3168 Explicit Congestion Notification. > > @@ -1202,6 +1224,94 @@ Bound the size of the advertised window to this value. > > The kernel imposes a minimum size of SOCK_MIN_RCVBUF/2. > > This option should not be used in code intended to be > > portable. > > +.TP > > +.BR TCP_FASTOPEN " (since Linux 3.6)" > > +This option enables Fast Open (RFC\ 7413) on the listener socket. > > +The value specifies the maximum length of pending SYNs > > +(similar to the backlog argument in > > +.BR listen (2)). > > +Once enabled, > > +the listener socket grants the TCP Fast Open cookie on incoming > > +SYN with TCP Fast Open option. > > +.IP > > +More importantly it accepts the data in SYN with a valid Fast Open cookie > > +and responds SYN-ACK acknowledging both the data and the SYN sequence. > > +.BR accept (2) > > +returns a socket that is available for read and write when the handshake > > +has not completed yet. > > +Thus the data exchange can commence before the handshake completes. > > +This option requires enabling the server-side support on sysctl > > +.IR net.ipv4.tcp_fastopen > > +(see above). > > +For TCP Fast Open client-side support, > > +see > > +.BR send (2) > > +.B MSG_FASTOPEN > > +or > > +.B TCP_FASTOPEN_CONNECT > > +below. > > +.TP > > +.BR TCP_FASTOPEN_CONNECT " (since Linux 4.11)" > > +This option enables an alternative way to perform Fast Open on the active > > +side (client). > > +When this option is enabled, > > +.BR connect (2) > > +would behave differently depending if a Fast Open cookie is available for > > +the destination. > > +.IP > > +If a cookie is not available (i.e. first contact to the destination), > > +.BR connect (2) > > +behaves as usual by sending a SYN immediately, > > +except the SYN would include an empty Fast Open cookie option to solicit a > > +cookie. > > +.IP > > +If a cookie is available, > > +.BR connect (2) > > +would return 0 immediately but the SYN transmission is defered. > > +A subsequent > > +.BR write (2) > > +or > > +.BR sendmsg (2) > > +would trigger a SYN with data plus cookie in the Fast Open option. > > +In other words, > > +the actual connect operation is deferred until data is supplied. > > +.IP > > +.B Note: > > +While this option is designed for convenience, > > +enabling it does change the behaviors and might set new > > +.I errnos > > typo? > > errno values? > > > +of socket calls. > > The above is not very clear to me. > Will update. > > +With cookie present, > > +.BR write (2) > > +/ > > Does this mean an "or"? If so, prefer the "or". > Yes. Ack. > > +.BR sendmsg (2) > > +must be called right after > > +.BR connect (2) > > +in order to send out SYN+data to complete 3WHS and establish connection. > > +Calling > > +.BR read (2) > > +right after > > +.BR connect (2) > > +without > > +.BR write (2) > > +will cause the blocking socket to be blocked forever. > > > > +The application should use either > > +.B TCP_FASTOPEN_CONNECT > > +or > > +.BR send (2) > > This is not clear to me. So TCP_FASTOPEN_CONNECT can use write(2) and > sendmsg(2) (mentioned above), and TCP_FASTOPEN can only use send(2)? Or > what did you mean? > The application should either set TCP_FASTOPEN_CONNECT socket option before calling write() or sendmsg(), or call write() or sendmsg() with MSG_FASTOPEN flag directly, but not both at the same time. > > +with > > +.B MSG_FASTOPEN , > > +instead of both on the same connection. > > From "The application ...": > Does this have relation with the text just above it? It appears to me > to be a more generic statement that both options shouldn't be mixed, so > maybe a new paragraph is more appropriate. > I think a new line does make sense, since this is a general statement for TCP_FASTOPEN_CONNECT option. > > +.IP > > +Here is the typical call flow with this new option: > > + s = socket(); > > + setsockopt(s, IPPROTO_TCP, TCP_FASTOPEN_CONNECT, 1, ...); > > + connect(s); > > + write(s); // write() should always follow connect() in order to > > + // trigger SYN to go out > > + read(s)/write(s); > > + ... > + close(s); > > See man-pages(7): > > Indentation of structure definitions, shell session logs, and > so on > When structure definitions, shell session logs, and so on > are included in running text, indent them by 4 spaces > (i.e., a block enclosed by .in +4n and .in), format them > using the .EX and EE macros, and surround them with suit‐ > able paragraph markers (either .PP or .IP). For example: > > .PP > .in +4n > .EX > int > main(int argc, char *argv[]) > { > return 0; > } > .EE > .in > .PP > > Ack. Thanks. Will send out a new version with the above addressed. > > .SS Sockets API > > TCP provides limited support for out-of-band data, > > in the form of (a single byte of) urgent data. > > > > > -- > Alejandro Colomar > Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/ > http://www.alejandro-colomar.es/ ^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2021-09-24 22:01 UTC | newest] Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2021-09-17 4:17 [patch v2] tcp.7: Add description for TCP_FASTOPEN and TCP_FASTOPEN_CONNECT options Wei Wang 2021-09-20 19:50 ` Alejandro Colomar (man-pages) 2021-09-24 22:01 ` Wei Wang
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).