TCP_CONGESTION documentation

Hello Stephen,

Back in 2.6.13, you added the TCP_CONGESTION sockopt, but provided no man-page patch...

Below is my attempt to document this sockopt. Could you please review. Please don't assume I've well understood the code: I may well have messed up in my reading of it, so review what I've written with care.

Also, a question: was the silent truncation of the returned string on getsockopt() if optlen is too small really intended? Would it not be/have been better to error on this case?

Cheers,

Michael

TCP_CONGESTION (since Linux 2.6.13)
Get or set the congestion-control algorithm for this
socket. The optval argument is a pointer to a
character-string buffer.

For getsockopt() *optlen specifies the amount of space available in the buffer pointed to by optval, which should be at least 16 bytes (defined by the kernel-
internal constant TCP_CA_NAME_MAX). On return, the
buffer pointed to by optval is set to a null-terminated string containing the name of the congestion-control algorithm for this socket, and *optlen is set to the
minimum of its original value and TCP_CA_NAME_MAX. If
the value passed in *optlen is too small, then the string returned in *optval is silently truncated, and no terminating null byte is added. If an empty string is returned, then the socket is using the default conges- tion-control algorithm, determined as described under tcp_congestion_control above.

For setsockopt() optlen specifies the length of the con- gestion-control algorithm name contained in the buffer pointed to by optval; this length need not include any terminating null byte. The algorithm "reno" is always permitted; other algorithms may be available, depending on kernel configuration. Possible errors from setsock- opt() include: algorithm not found/available (ENOENT); setting this algorithm requires the CAP_NET_ADMIN capa-
bility (EPERM); and failure getting kernel module
(EBUSY).

tcp.7.TCP_CONGESTION.patch 2008-11-21 10:53:36.000000000 -0500 renamed from tcp.7 2008-11-21 10:54:08.000000000 -0500 +52 -1

@@ -733,7 +733,58 @@
 socket options are valid on TCP sockets.
 For more information see
 .BR ip (7).
-.\" FIXME Document TCP_CONGESTION (new in 2.6.13)
+.TP
+.BR TCP_CONGESTION " (since Linux 2.6.13)"
+Get or set the congestion-control algorithm for this socket.
+The
+.I optval
+argument is a pointer to a character-string buffer.
+
+For
+.BR getsockopt ()
+.I *optlen
+specifies the amount of space available in the buffer pointed to by
+.IR optval ,
+which should be at least 16 bytes (defined by the kernel-internal constant
+.BR TCP_CA_NAME_MAX ).
+On return, the buffer pointed to by
+.I optval
+is set to a null-terminated string containing the name of the
+congestion-control algorithm for this socket, and
+.I *optlen
+is set to the minimum of its original value and
+.BR TCP_CA_NAME_MAX .
+If the value passed in
+.I *optlen
+is too small, then the string returned in
+.I *optval
+is silently truncated, and no terminating null byte is added.
+If an empty string is returned, then the socket is using the default
+congestion-control algorithm, determined as described under
+.I tcp_congestion_control
+above.
+
+For
+.BR setsockopt ()
+.I optlen
+specifies the length of the congestion-control algorithm name
+contained in the buffer pointed to by
+.IR optval ;
+this length need not include any terminating null byte.
+The algorithm "reno" is always permitted;
+other algorithms may be available, depending on kernel configuration.
+Possible errors from
+.BR setsockopt ()
+include:
+algorithm not found/available
+.RB ( ENOENT );
+setting this algorithm requires the
+.B CAP_NET_ADMIN
+capability
+.RB ( EPERM );
+and failure getting kernel module
+.RB ( EBUSY ).
+.I
 .TP
 .B TCP_CORK
 If set, don't send out partial frames.

Hello Stephen,

Back in 2.6.13, you added the TCP_CONGESTION sockopt, but provided no man-page patch...

Below is my attempt to document this sockopt. Could you please review. Please don't assume I've well understood the code: I may well have messed up in my reading of it, so review what I've written with care.

Also, a question: was the silent truncation of the returned string on getsockopt() if optlen is too small really intended? Would it not be/have been better to error on this case?

Cheers,

Michael

TCP_CONGESTION (since Linux 2.6.13)
Get or set the congestion-control algorithm for this
socket. The optval argument is a pointer to a
character-string buffer.

For getsockopt() *optlen specifies the amount of space available in the buffer pointed to by optval, which should be at least 16 bytes (defined by the kernel-
internal constant TCP_CA_NAME_MAX). On return, the
buffer pointed to by optval is set to a null-terminated string containing the name of the congestion-control algorithm for this socket, and *optlen is set to the
minimum of its original value and TCP_CA_NAME_MAX. If
the value passed in *optlen is too small, then the string returned in *optval is silently truncated, and no terminating null byte is added. If an empty string is returned, then the socket is using the default conges- tion-control algorithm, determined as described under tcp_congestion_control above.

For setsockopt() optlen specifies the length of the con- gestion-control algorithm name contained in the buffer pointed to by optval; this length need not include any terminating null byte. The algorithm "reno" is always permitted; other algorithms may be available, depending on kernel configuration. Possible errors from setsock- opt() include: algorithm not found/available (ENOENT); setting this algorithm requires the CAP_NET_ADMIN capa-
bility (EPERM); and failure getting kernel module
(EBUSY).

Quoted 5 lines · On Fri, 21 Nov 2008 11:06:19 -0500 Michael Kerrisk…

Hello Stephen,

Back in 2.6.13, you added the TCP_CONGESTION sockopt, but provided no man-page patch...

Quoted 8 lines

Below is my attempt to document this sockopt. Could you please review. Please don't assume I've well understood the code: I may well have messed up in my reading of it, so review what I've written with care.

Also, a question: was the silent truncation of the returned string on getsockopt() if optlen is too small really intended? Would it not be/have been better to error on this case?

Quoted 20 lines

TCP_CONGESTION (since Linux 2.6.13)
Get or set the congestion-control algorithm for this
socket. The optval argument is a pointer to a
character-string buffer.

For getsockopt() *optlen specifies the amount of space available in the buffer pointed to by optval, which should be at least 16 bytes (defined by the kernel-
internal constant TCP_CA_NAME_MAX). On return, the
buffer pointed to by optval is set to a null-terminated string containing the name of the congestion-control algorithm for this socket, and *optlen is set to the
minimum of its original value and TCP_CA_NAME_MAX. If
the value passed in *optlen is too small, then the string returned in *optval is silently truncated, and no terminating null byte is added. If an empty string is returned, then the socket is using the default conges- tion-control algorithm, determined as described under tcp_congestion_control above.

Quoted 10 lines

For setsockopt() optlen specifies the length of the con- gestion-control algorithm name contained in the buffer pointed to by optval; this length need not include any terminating null byte. The algorithm "reno" is always permitted; other algorithms may be available, depending on kernel configuration. Possible errors from setsock- opt() include: algorithm not found/available (ENOENT); setting this algorithm requires the CAP_NET_ADMIN capa-
bility (EPERM); and failure getting kernel module
(EBUSY).

The tcp(7) man page is related

and seems out of date as well.

At least on this sytem (Ubuntu 8.04).it seems to be stuck back in pre 2.6.12

timewarp (see tcp_bic, tcp_bic_low_window, ...) values that no longer exist.

Should be updated as well.

Hi Stephen,

Quoted 8 lines · Stephen Hemminger

Quoted 5 lines · On Fri, 21 Nov 2008 11:06:19 -0500 Michael Kerrisk…

Hello Stephen,

Back in 2.6.13, you added the TCP_CONGESTION sockopt, but provided no man-page patch...

Quoted 8 lines

Quoted 8 lines

Below is my attempt to document this sockopt. Could you please review. Please don't assume I've well understood the code: I may well have messed up in my reading of it, so review what I've written with care.

Also, a question: was the silent truncation of the returned string on getsockopt() if optlen is too small really intended? Would it not be/have been better to error on this case?

You added some other stuff below, but I got no response to the review request and the question above?

Quoted 31 lines

Quoted 20 lines

TCP_CONGESTION (since Linux 2.6.13)
Get or set the congestion-control algorithm for this
socket. The optval argument is a pointer to a
character-string buffer.

For getsockopt() *optlen specifies the amount of space available in the buffer pointed to by optval, which should be at least 16 bytes (defined by the kernel-
internal constant TCP_CA_NAME_MAX). On return, the
buffer pointed to by optval is set to a null-terminated string containing the name of the congestion-control algorithm for this socket, and *optlen is set to the
minimum of its original value and TCP_CA_NAME_MAX. If
the value passed in *optlen is too small, then the string returned in *optval is silently truncated, and no terminating null byte is added. If an empty string is returned, then the socket is using the default conges- tion-control algorithm, determined as described under tcp_congestion_control above.

Quoted 10 lines

For setsockopt() optlen specifies the length of the con- gestion-control algorithm name contained in the buffer pointed to by optval; this length need not include any terminating null byte. The algorithm "reno" is always permitted; other algorithms may be available, depending on kernel configuration. Possible errors from setsock- opt() include: algorithm not found/available (ENOENT); setting this algorithm requires the CAP_NET_ADMIN capa-
bility (EPERM); and failure getting kernel module
(EBUSY).

Quoted 1 line

The tcp(7) man page is related

(I'm a little confused by that remark: the patch at the end of my mail was *for* the tcp(7) man page; maybe you missed that.)

Quoted 1 line

and seems out of date as well.

Yes, many things on it are out of date. (I've made occasional requests to linux-net for help on this point, but have had little response.)

Quoted 1 line

At least on this sytem (Ubuntu 8.04).it seems to be stuck back in pre 2.6.12

Yes, 2.6.12 sounds about right.

Quoted 2 lines

timewarp (see tcp_bic, tcp_bic_low_window, ...) values that no longer exist.

And when they disappear, no one CCs the man-page maintainer :-(.

Anyway, thanks for the heads up

tcp_bic* is now fixed (disappeared in 2.6.13) and
tcp_westwood is now fixed (disappeared in 2.6.13) and
tcp_vegas_cong_avoid is now fixed (disappeared in 2.6.13)

Quoted 1 line

Should be updated as well.

I'm working on it. Many updates to tcp(7) will be in man-pages-3.14.

Cheers,

Michael

--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
git://git.kernel.org/pub/scm/docs/man-pages/man-pages.git
man-pages online: http://www.kernel.org/doc/man-pages/online_pages.html
Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html

[CC+= Andi, this time with the right address]

Quoted 1 line · Michael Kerrisk

[CC+= Andi, this time with the right address]

Just a general comment. The initial DESCRIPTION in tcp should be probably adapted to mentioned that Linux has pluggable congestion avoidance modules now and also that the defaults have changed (from NewReno to CUBIC etc.)

Hi Andi,

Quoted 7 lines · Andi Kleen

Quoted 1 line · Michael Kerrisk

[CC+= Andi, this time with the right address]

Just a general comment. The initial DESCRIPTION in tcp should be probably adapted to mentioned that Linux has pluggable congestion avoidance modules now and also that the defaults have changed (from NewReno to CUBIC etc.)

If I try to do this, I'm going to create rubbish, because I know next to nothing about these details...

Could I ask a favor? Below is the DESCRIPTION text. Could you note write some sentences in the rough location where you think they below, and I will turn that into a *roff patch.

Does this help get it started in right direction??

--------------------------------------------

This is an implementation of the TCP protocol defined in RFC 793, RFC 1122 and RFC 2001 with the NewReno and SACK
extensions. It provides a reliable, stream-oriented,

Note that TCP actually allocates twice the size of the buffer requested in

socket option is enabled, urgent data is put into the normal data stream (a program can test for its location using the SIOCATMARK ioctl described below), otherwise it can be only received when the MSG_OOB flag is set for recv(2) or recvmsg(2).

Linux supports multiple different congestion control algorithms. The default choice of congestion control is controlled by net.ipv4.tcp_congestion_control sysctl. This value can be overridden by TCP_CONGESTION socket option. The actual choices of congestion control available vary according between release as more are added, and depend on the configuration choices

made when the kernel was built. The list of congestion control protocols currently loaded is in net.ipv4.tcp_available_congestion_control.

Quoted 1 line · Stephen Hemminger

Does this help get it started in right direction??

Yes.

Quoted 5 lines

--------------------------------------------

This is an implementation of the TCP protocol defined in RFC 793, RFC 1122 and RFC 2001 with the NewReno and SACK
extensions. It provides a reliable, stream-oriented,

Perhaps drop NewReno, it's really obsolete because Linux is so far beyond.

Quoted 3 lines

Note that TCP actually allocates twice the size of the buffer requested in

The "twice" is obsolete, it's far more complicated now. So it should be just "more" I think

Quoted 6 lines

socket option is enabled, urgent data is put into the normal data stream (a program can test for its location using the SIOCATMARK ioctl described below), otherwise it can be only received when the MSG_OOB flag is set for recv(2) or recvmsg(2).

Quoted 6 lines

Linux supports multiple different congestion control algorithms. The default choice of congestion control is controlled by net.ipv4.tcp_congestion_control sysctl. This value can be overridden by TCP_CONGESTION socket option. The actual choices of congestion control available vary according between release as more are added, and depend on the configuration choices

Hmm perhaps mention the current standard default?

There is no "standard default" it is a kernel config option.

And it may change in future, so writing it into the manual page seems being short sighted.