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 June 30, 2022 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 TIME_WAIT 78state can not be handled by 79.Nm . 80TCP endpoints in the 81.Dv SYN_RCVD 82state can only be handled if their prior state was 83.Dv SYN_SENT . 84.Pp 85.Op Ar level 86can be specified as a non negative number or a symbolic name like 87.Dv SOL_SOCKET , 88.Dv IPPROTO_IP , 89.Dv IPPROTO_IPV6 , 90or 91.Dv IPPROTO_TCP . 92If not specified, 93.Nm 94deduces the level from 95.Ar optname , 96if provided as a symbolic name. 97If that is not the case, 98.Dv IPPROTO_TCP 99is used. 100.Pp 101.Ar optname 102can be specified as a non negative number or a symbolic name like 103.Dv SO_DEBUG , 104.Dv IP_TOS , 105.Dv IPV6_TCLASS , 106.Dv TCP_LOG , 107.Dv TCP_CONGESTION , 108or 109.Dv TCP_FUNCTION_BLK . 110.Pp 111.Ar optval 112can be in integer value, which will be converted to a binary value and 113passed as an int value. 114If it cannot be parsed as an integer value, it will be processed as a string. 115If the 116.Ar optname 117is 118.Dv TCP_FUNCTION_BLK 119then 120.Ar optval 121is converted to a 122.Vt "struct tcp_function_set" . 123.Pp 124If 125.Fl i Ar id 126is specified then 127.Nm 128will apply the socket option to the TCP endpoint with the 129.Dv inp_gencnt 130provided as 131.Ar id . 132The 133.Dv inp_gencnt 134for existing TCP endpoints can be determined by using 135.Xr sockstat 1 . 136.Pp 137If 138.Fl a 139is specified then 140.Nm 141will apply the socket option to all TCP endpoints subject to the above state 142restrictions. 143.Pp 144If 145.Fl C Ar cc-algo 146is specified then 147.Nm 148will apply the socket option to all TCP endpoints using the TCP 149congestion control algorithm 150.Ar cc-algo 151and subject to the above state restrictions. 152.Pp 153If 154.Fl S Ar stack 155is specified then 156.Nm 157will apply the socket option to all TCP endpoints using the TCP 158stack 159.Ar stack 160and subject to the above state restrictions. 161.Pp 162If 163.Fl s Ar state 164is specified then 165.Nm 166will apply the socket option to all TCP endpoints being in the state 167.Ar state . 168.Ar state 169is one of 170.Dv CLOSED , 171.Dv LISTEN , 172.Dv SYN_SENT , 173.Dv SYN_RCVD , 174.Dv ESTABLISHED , 175.Dv CLOSE_WAIT , 176.Dv FIN_WAIT_1 , 177.Dv CLOSING , 178.Dv LAST_ACK , 179.Dv FIN_WAIT_2 . 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 not being in the 195state 196.Dv TIME_WAIT 197and using the congestion control algorithm 198.Ar cc-algo , 199being in the state 200.Ar state , 201and using the TCP stack 202.Ar stack , 203if specified. 204.Pp 205If none of the 206.Fl a , 207.Fl C , 208.Fl S , 209or 210.Fl s 211options are specified then the option 212.Fl i 213must be specified. 214.Sh EXIT STATUS 215.Ex -std 216.Sh EXAMPLES 217To diagnose a problem with a particular TCP connection to 218.Xr sshd 8 , 219first determine its 220.Dv inp_gencnt 221using 222.Xr sockstat 1 : 223.Bd -literal -offset indent 224# sockstat -4 -c -i -p 22 -P tcp -q 225root sshd 827 4 tcp4 \e 226 192.168.1.1:22 192.168.1.2:53736 435 227.Ed 228.Pp 229Then, use the following command to enable Black Box Logging on it: 230.Bd -literal -offset indent 231# tcpsso -i 435 TCP_LOG 4 232.Ed 233.Pp 234To switch all TCP endpoints from using the freebsd stack to the rack stack use: 235.Bd -literal -offset indent 236# tcpsso -S freebsd TCP_FUNCTION_BLK rack 237.Ed 238.Pp 239The following command will set the congestion control module of all TCP 240endpoints currently using cubic as its congestion control algorithm to the 241congestion control algorithm newreno: 242.Bd -literal -offset indent 243# tcpsso -C cubic TCP_CONGESTION newreno 244.Ed 245.Sh SEE ALSO 246.Xr sockstat 1 , 247.Xr setsockopt 2 , 248.Xr tcp 4 , 249.Xr tcp_functions 9 250.Sh HISTORY 251The 252.Nm 253command first appeared in 254.Fx 14 . 255.Sh AUTHORS 256.An Michael Tuexen Aq Mt tuexen@FreeBSD.org 257