1.\" 2.\" SPDX-License-Identifier: BSD-2-Clause 3.\" 4.\" Copyright (c) 2022 Michael Tuexen <tuexen@FreeBSD.org> 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.Dd August 3, 2024 28.Dt TCPSSO 8 29.Os 30.Sh NAME 31.Nm tcpsso 32.Nd set a socket option on a TCP endpoint 33.Sh SYNOPSIS 34.Nm 35.Fl i Ar id 36.Op Ar level 37.Ar optname 38.Ar optval 39.Nm 40.Fl a 41.Op Ar level 42.Ar optname 43.Ar optval 44.Nm 45.Fl C Ar cc-algo 46.Op Fl S Ar stack 47.Op Fl s Ar state 48.Op Ar level 49.Ar optname 50.Ar optval 51.Nm 52.Op Fl C Ar cc-algo 53.Fl S Ar stack 54.Op Fl s Ar state 55.Op Ar level 56.Ar optname 57.Ar optval 58.Nm 59.Op Fl C Ar cc-algo 60.Op Fl S Ar stack 61.Fl s Ar state 62.Op Ar level 63.Ar optname 64.Ar optval 65.Sh DESCRIPTION 66The 67.Nm 68command applies a 69.Ar level 70level socket option with name 71.Ar optname 72and value 73.Ar optval 74on a TCP endpoint from the command line. 75.Pp 76TCP endpoints in the 77.Dv SYN_RCVD 78state can only be handled by 79.Nm 80if their prior state was 81.Dv SYN_SENT . 82.Pp 83.Op Ar level 84can be specified as a non-negative number or a symbolic name like 85.Dv SOL_SOCKET , 86.Dv IPPROTO_IP , 87.Dv IPPROTO_IPV6 , 88or 89.Dv IPPROTO_TCP . 90If not specified, 91.Nm 92deduces the level from 93.Ar optname , 94if provided as a symbolic name. 95If that is not the case, 96.Dv IPPROTO_TCP 97is used. 98.Pp 99.Ar optname 100can be specified as a non-negative number or a symbolic name like 101.Dv SO_DEBUG , 102.Dv IP_TOS , 103.Dv IPV6_TCLASS , 104.Dv TCP_LOG , 105.Dv TCP_CONGESTION , 106or 107.Dv TCP_FUNCTION_BLK . 108.Pp 109.Ar optval 110can be an integer value, which will be converted to a binary value and 111passed as an int value. 112If it cannot be parsed as an integer value, it will be processed as a string. 113If the 114.Ar optname 115is 116.Dv TCP_FUNCTION_BLK 117then 118.Ar optval 119is converted to a 120.Vt "struct tcp_function_set" . 121.Pp 122If 123.Fl i Ar id 124is specified then 125.Nm 126will apply the socket option to the TCP endpoint with the 127.Dv inp_gencnt 128provided as 129.Ar id . 130The 131.Dv inp_gencnt 132for existing TCP endpoints can be determined by using 133.Xr sockstat 1 . 134.Pp 135If 136.Fl a 137is specified then 138.Nm 139will apply the socket option to all TCP endpoints subject to the above state 140restrictions. 141.Pp 142If 143.Fl C Ar cc-algo 144is specified then 145.Nm 146will apply the socket option to all TCP endpoints using the TCP 147congestion control algorithm 148.Ar cc-algo 149and subject to the above state restrictions. 150.Pp 151If 152.Fl S Ar stack 153is specified then 154.Nm 155will apply the socket option to all TCP endpoints using the TCP 156stack 157.Ar stack 158and subject to the above state restrictions. 159.Pp 160If 161.Fl s Ar state 162is specified then 163.Nm 164will apply the socket option to all TCP endpoints being in the state 165.Ar state . 166.Ar state 167is one of 168.Dv CLOSED , 169.Dv LISTEN , 170.Dv SYN_SENT , 171.Dv SYN_RCVD , 172.Dv ESTABLISHED , 173.Dv CLOSE_WAIT , 174.Dv FIN_WAIT_1 , 175.Dv CLOSING , 176.Dv LAST_ACK , 177.Dv FIN_WAIT_2, 178or 179.Dv TIME_WAIT . 180Using 181.Dv SYN_RCVD 182only applies to TCP endpoints in the state 183.Dv SYN_RCVD 184if their prior state was 185.Dv SYN_SENT . 186.Pp 187If multiple of 188.Fl C Ar cc-algo , 189.Fl S Ar stack , 190and 191.Fl s Ar state 192are specified, 193.Nm 194will apply the socket option to all TCP endpoints using the congestion 195control algorithm 196.Ar cc-algo , 197being in the state 198.Ar state , 199and using the TCP stack 200.Ar stack , 201if specified. 202.Pp 203If none of the 204.Fl a , 205.Fl C , 206.Fl S , 207or 208.Fl s 209options are specified then the option 210.Fl i 211must be specified. 212.Sh EXIT STATUS 213.Ex -std 214.Sh EXAMPLES 215To diagnose a problem with a particular TCP connection to 216.Xr sshd 8 , 217first determine its 218.Dv inp_gencnt 219using 220.Xr sockstat 1 : 221.Bd -literal -offset indent 222# sockstat -4 -c -i -p 22 -P tcp -q 223root sshd 827 4 tcp4 \e 224 192.168.1.1:22 192.168.1.2:53736 435 225.Ed 226.Pp 227Then, use the following command to enable Black Box Logging on it: 228.Bd -literal -offset indent 229# tcpsso -i 435 TCP_LOG 4 230.Ed 231.Pp 232To switch all TCP endpoints from using the freebsd stack to the RACK stack use: 233.Bd -literal -offset indent 234# tcpsso -S freebsd TCP_FUNCTION_BLK rack 235.Ed 236.Pp 237Switch all TCP endpoints in the LISTEN state to the RACK stack by using: 238.Bd -literal -offset indent 239# tcpsso -s LISTEN TCP_FUNCTION_BLK rack 240.Ed 241.Pp 242The following command will set the congestion control module of all TCP 243endpoints currently using cubic as its congestion control algorithm to the 244congestion control algorithm newreno: 245.Bd -literal -offset indent 246# tcpsso -C cubic TCP_CONGESTION newreno 247.Ed 248.Sh SEE ALSO 249.Xr sockstat 1 , 250.Xr setsockopt 2 , 251.Xr tcp 4 , 252.Xr tcp_functions 9 253.Sh HISTORY 254The 255.Nm 256command first appeared in 257.Fx 14 . 258.Sh AUTHORS 259.An Michael Tuexen Aq Mt tuexen@FreeBSD.org 260