SPDX-License-Identifier: BSD-2-Clause
Copyright (c) 2022 Michael Tuexen <tuexen@FreeBSD.org>
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
.Dd January 14, 2024 .Dt TCPSSO 8 .Os .Sh NAME .Nm tcpsso .Nd set a socket option on a TCP endpoint .Sh SYNOPSIS .Nm .Fl i Ar id .Op Ar level .Ar optname .Ar optval .Nm .Fl a .Op Ar level .Ar optname .Ar optval .Nm .Fl C Ar cc-algo .Op Fl S Ar stack .Op Fl s Ar state .Op Ar level .Ar optname .Ar optval .Nm .Op Fl C Ar cc-algo .Fl S Ar stack .Op Fl s Ar state .Op Ar level .Ar optname .Ar optval .Nm .Op Fl C Ar cc-algo .Op Fl S Ar stack .Fl s Ar state .Op Ar level .Ar optname .Ar optval .Sh DESCRIPTION The .Nm command applies a .Ar level level socket option with name .Ar optname and value .Ar optval on a TCP endpoint from the command line.
p TCP endpoints in the .Dv SYN_RCVD state can only be handled by .Nm if their prior state was .Dv SYN_SENT .
p .Op Ar level can be specified as a non-negative number or a symbolic name like .Dv SOL_SOCKET , .Dv IPPROTO_IP , .Dv IPPROTO_IPV6 , or .Dv IPPROTO_TCP . If not specified, .Nm deduces the level from .Ar optname , if provided as a symbolic name. If that is not the case, .Dv IPPROTO_TCP is used.
p .Ar optname can be specified as a non-negative number or a symbolic name like .Dv SO_DEBUG , .Dv IP_TOS , .Dv IPV6_TCLASS , .Dv TCP_LOG , .Dv TCP_CONGESTION , or .Dv TCP_FUNCTION_BLK .
p .Ar optval can be an integer value, which will be converted to a binary value and passed as an int value. If it cannot be parsed as an integer value, it will be processed as a string. If the .Ar optname is .Dv TCP_FUNCTION_BLK then .Ar optval is converted to a .Vt "struct tcp_function_set" .
p If .Fl i Ar id is specified then .Nm will apply the socket option to the TCP endpoint with the .Dv inp_gencnt provided as .Ar id . The .Dv inp_gencnt for existing TCP endpoints can be determined by using .Xr sockstat 1 .
p If .Fl a is specified then .Nm will apply the socket option to all TCP endpoints subject to the above state restrictions.
p If .Fl C Ar cc-algo is specified then .Nm will apply the socket option to all TCP endpoints using the TCP congestion control algorithm .Ar cc-algo and subject to the above state restrictions.
p If .Fl S Ar stack is specified then .Nm will apply the socket option to all TCP endpoints using the TCP stack .Ar stack and subject to the above state restrictions.
p If .Fl s Ar state is specified then .Nm will apply the socket option to all TCP endpoints being in the state .Ar state . .Ar state is one of .Dv CLOSED , .Dv LISTEN , .Dv SYN_SENT , .Dv SYN_RCVD , .Dv ESTABLISHED , .Dv CLOSE_WAIT , .Dv FIN_WAIT_1 , .Dv CLOSING , .Dv LAST_ACK , .Dv FIN_WAIT_2, or .Dv TIME_WAIT . Using .Dv SYN_RCVD only applies to TCP endpoints in the state .Dv SYN_RCVD if their prior state was .Dv SYN_SENT .
p If multiple of .Fl C Ar cc-algo , .Fl S Ar stack , and .Fl s Ar state are specified, .Nm will apply the socket option to all TCP endpoints using the congestion control algorithm .Ar cc-algo , being in the state .Ar state , and using the TCP stack .Ar stack , if specified.
p If none of the .Fl a , .Fl C , .Fl S , or .Fl s options are specified then the option .Fl i must be specified. .Sh EXIT STATUS .Ex -std .Sh EXAMPLES To diagnose a problem with a particular TCP connection to .Xr sshd 8 , first determine its .Dv inp_gencnt using .Xr sockstat 1 : d -literal -offset indent # sockstat -4 -c -i -p 22 -P tcp -q root sshd 827 4 tcp4 \e 192.168.1.1:22 192.168.1.2:53736 435 .Ed
p Then, use the following command to enable Black Box Logging on it: d -literal -offset indent # tcpsso -i 435 TCP_LOG 4 .Ed
p To switch all TCP endpoints from using the freebsd stack to the rack stack use: d -literal -offset indent # tcpsso -S freebsd TCP_FUNCTION_BLK rack .Ed
p The following command will set the congestion control module of all TCP endpoints currently using cubic as its congestion control algorithm to the congestion control algorithm newreno: d -literal -offset indent # tcpsso -C cubic TCP_CONGESTION newreno .Ed .Sh SEE ALSO .Xr sockstat 1 , .Xr setsockopt 2 , .Xr tcp 4 , .Xr tcp_functions 9 .Sh HISTORY The .Nm command first appeared in .Fx 14 . .Sh AUTHORS .An Michael Tuexen Aq Mt tuexen@FreeBSD.org