usr.sbin/tcpsso/tcpsso.8

   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
  66 The
  67 .Nm
  68 command applies a
  69 .Ar level
  70 level socket option with name
  71 .Ar optname
  72 and value
  73 .Ar optval
  74 on a TCP endpoint from the command line.
  75 .Pp
  76 TCP endpoints in the
  77 .Dv TIME_WAIT
  78 state can not be handled by
  79 .Nm .
  80 TCP endpoints in the
  81 .Dv SYN_RCVD
  82 state can only be handled if their prior state was
  83 .Dv SYN_SENT .
  84 .Pp
  85 .Op Ar level
  86 can be specified as a non negative number or a symbolic name like
  87 .Dv SOL_SOCKET ,
  88 .Dv IPPROTO_IP ,
  89 .Dv IPPROTO_IPV6 ,
  90 or
  91 .Dv IPPROTO_TCP .
  92 If not specified,
  93 .Nm
  94 deduces the level from
  95 .Ar optname ,
  96 if provided as a symbolic name.
  97 If that is not the case,
  98 .Dv IPPROTO_TCP
  99 is used.
 100 .Pp
 101 .Ar optname
 102 can 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 ,
 108 or
 109 .Dv TCP_FUNCTION_BLK .
 110 .Pp
 111 .Ar optval
 112 can be in integer value, which will be converted to a binary value and
 113 passed as an int value.
 114 If it cannot be parsed as an integer value, it will be processed as a string.
 115 If the
 116 .Ar optname
 117 is
 118 .Dv TCP_FUNCTION_BLK
 119 then
 120 .Ar optval
 121 is converted to a
 122 .Vt "struct tcp_function_set" .
 123 .Pp
 124 If
 125 .Fl i Ar id
 126 is specified then
 127 .Nm
 128 will apply the socket option to the TCP endpoint with the
 129 .Dv inp_gencnt
 130 provided as
 131 .Ar id .
 132 The
 133 .Dv inp_gencnt
 134 for existing TCP endpoints can be determined by using
 135 .Xr sockstat 1 .
 136 .Pp
 137 If
 138 .Fl a
 139 is specified then
 140 .Nm
 141 will apply the socket option to all TCP endpoints subject to the above state
 142 restrictions.
 143 .Pp
 144 If
 145 .Fl C Ar cc-algo
 146 is specified then
 147 .Nm
 148 will apply the socket option to all TCP endpoints using the TCP
 149 congestion control algorithm
 150 .Ar cc-algo
 151 and subject to the above state restrictions.
 152 .Pp
 153 If
 154 .Fl S Ar stack
 155 is specified then
 156 .Nm
 157 will apply the socket option to all TCP endpoints using the TCP
 158 stack
 159 .Ar stack
 160 and subject to the above state restrictions.
 161 .Pp
 162 If
 163 .Fl s Ar state
 164 is specified then
 165 .Nm
 166 will apply the socket option to all TCP endpoints being in the state
 167 .Ar state .
 168 .Ar state
 169 is 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 .
 180 Using
 181 .Dv SYN_RCVD
 182 only applies to TCP endpoints in the state
 183 .Dv SYN_RCVD
 184 if their prior state was
 185 .Dv SYN_SENT .
 186 .Pp
 187 If multiple of
 188 .Fl C Ar cc-algo ,
 189 .Fl S Ar stack ,
 190 and
 191 .Fl s Ar state
 192 are specified,
 193 .Nm
 194 will apply the socket option to all TCP endpoints not being in the
 195 state
 196 .Dv TIME_WAIT
 197 and using the congestion control algorithm
 198 .Ar cc-algo ,
 199 being in the state
 200 .Ar state ,
 201 and using the TCP stack
 202 .Ar stack ,
 203 if specified.
 204 .Pp
 205 If none of the
 206 .Fl a ,
 207 .Fl C ,
 208 .Fl S ,
 209 or
 210 .Fl s
 211 options are specified then the option
 212 .Fl i
 213 must be specified.
 214 .Sh EXIT STATUS
 215 .Ex -std
 216 .Sh EXAMPLES
 217 To diagnose a problem with a particular TCP connection to
 218 .Xr sshd 8 ,
 219 first determine its
 220 .Dv inp_gencnt
 221 using
 222 .Xr sockstat 1 :
 223 .Bd -literal -offset indent
 224 # sockstat -4 -c -i -p 22 -P tcp -q
 225 root     sshd       827   4  tcp4 \e
 226         192.168.1.1:22        192.168.1.2:53736     435
 227 .Ed
 228 .Pp
 229 Then, 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
 234 To 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
 239 The following command will set the congestion control module of all TCP
 240 endpoints currently using cubic as its congestion control algorithm to the
 241 congestion 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
 251 The
 252 .Nm
 253 command first appeared in
 254 .Fx 14 .
 255 .Sh AUTHORS
 256 .An Michael Tuexen Aq Mt tuexen@FreeBSD.org