usr.sbin/tcpsso/tcpsso.8

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