Changeset View
Standalone View
usr.sbin/tcpsso/tcpsso.8
- This file was added.
.\" | |||||||||||
.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD | |||||||||||
.\" | |||||||||||
.\" 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 February 9, 2022 | |||||||||||
.Dt TCPSSO 8 | |||||||||||
.Os | |||||||||||
.Sh NAME | |||||||||||
.Nm tcpsso | |||||||||||
.Nd set a socket option on a TCP endpoint | |||||||||||
.Sh SYNOPSIS | |||||||||||
.Nm | |||||||||||
.Fl i Ar id | |||||||||||
pauamma_gundo.com: If I read https://docs.freebsd.org/en/books/fdp-primer/manual-pages/#manual-pages-markup (and… | |||||||||||
Done Inline ActionsThis is correct. debdrup: This is correct. | |||||||||||
Done Inline ActionsFixed. tuexen: Fixed. | |||||||||||
.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 | |||||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||||
Done Inline ActionsFixed. tuexen: Fixed. | |||||||||||
.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. | |||||||||||
.Pp | |||||||||||
.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 , | |||||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||||
Done Inline ActionsThis is also pointed out by igor. :) debdrup: This is also pointed out by igor. :) | |||||||||||
Done Inline ActionsFixed. tuexen: Fixed. | |||||||||||
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. | |||||||||||
.Pp | |||||||||||
.Ar optname | |||||||||||
can be specified as a non negative number or a symbolic name like | |||||||||||
Done Inline ActionsI think you mean .Nm here. pauamma_gundo.com: I think you mean .Nm here. | |||||||||||
Done Inline ActionsCorrect. Fixed. tuexen: Correct. Fixed. | |||||||||||
.Dv SO_DEBUG , | |||||||||||
Done Inline Actions"apply the option" maybe? pauamma_gundo.com: "apply the option" maybe? | |||||||||||
Done Inline ActionsFixed. tuexen: Fixed. | |||||||||||
.Dv IP_TOS , | |||||||||||
.Dv IPV6_TCLASS , | |||||||||||
.Dv TCP_LOG , | |||||||||||
.Dv TCP_CONGESTION , | |||||||||||
or | |||||||||||
.Dv TCP_FUNCTION_BLK . | |||||||||||
.Pp | |||||||||||
.Ar optval | |||||||||||
can be in 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 | |||||||||||
Done Inline Actions"apply the option" maybe? pauamma_gundo.com: "apply the option" maybe? | |||||||||||
Done Inline ActionsFixed. tuexen: Fixed. | |||||||||||
is | |||||||||||
.Dv TCP_FUNCTION_BLK | |||||||||||
then | |||||||||||
.Ar optval | |||||||||||
is converted to a | |||||||||||
.Vt "struct tcp_function_set" . | |||||||||||
.Pp | |||||||||||
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 . | |||||||||||
.Pp | |||||||||||
If | |||||||||||
.Fl a | |||||||||||
is specified then | |||||||||||
.Nm | |||||||||||
will apply the socket option to all TCP endpoints not being in the state | |||||||||||
.Dv TIME_WAIT . | |||||||||||
.Pp | |||||||||||
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 not being in the state | |||||||||||
.Dv TIME_WAIT . | |||||||||||
.Pp | |||||||||||
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 not being in the state | |||||||||||
.Dv TIME_WAIT . | |||||||||||
.Pp | |||||||||||
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 . | |||||||||||
.Pp | |||||||||||
If multiple of | |||||||||||
.Fl C Ar cc-algo , | |||||||||||
.Fl S Ar stack , | |||||||||||
and | |||||||||||
.Fl s Ar state | |||||||||||
are specified, | |||||||||||
.Nm | |||||||||||
Done Inline Actionstypo? (httpd) rscheff: typo? (httpd) | |||||||||||
Done Inline ActionsYepp. Should be thttpd. tuexen: Yepp. Should be thttpd. | |||||||||||
Done Inline ActionsWell, i assumed this to be a generic stand in for a web demon, rather than a specific one from the ports collection. Perhaps leave this particular reference out from the example completely (its not material to the example itself), just describe it in the text like this. (I assume most people will be familiar with port 80 to be http). If a particular TCP connection to a web server process is behaving in an interesting way, one can determine the .... Or If a particular TCP connection to a web server process ( *thttpd 8* in this example) is behaving in an interesting way, one can determine the .... rscheff: Well, i assumed this to be a generic stand in for a web demon, rather than a specific one from… | |||||||||||
Done Inline ActionsSwitched from thttpd to sshd... This is always installed... tuexen: Switched from thttpd to sshd... This is always installed... | |||||||||||
will apply the socket option to all TCP endpoints not being in the | |||||||||||
Done Inline ActionsI'd reword this to: To diagnose a problem with a particular TCP connection to pauamma_gundo.com: I'd reword this to:
To diagnose a problem with a particular TCP connection to
.Xr thttpd 8… | |||||||||||
Done Inline ActionsDone. tuexen: Done. | |||||||||||
state | |||||||||||
.Dv TIME_WAIT | |||||||||||
Done Inline Actions
To match the above suggestion. pauamma_gundo.com: To match the above suggestion. | |||||||||||
and using the congestion control algorithm | |||||||||||
.Ar cc-algo , | |||||||||||
being in the state | |||||||||||
.Ar state , | |||||||||||
and using the TCP stack | |||||||||||
.Ar stack , | |||||||||||
if specified. | |||||||||||
.Pp | |||||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||||
Done Inline ActionsFixed. tuexen: Fixed. | |||||||||||
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 : | |||||||||||
.Bd -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 | |||||||||||
.Pp | |||||||||||
Then, use the following command to enable Black Box Logging on it: | |||||||||||
.Bd -literal -offset indent | |||||||||||
# tcpsso -i 435 TCP_LOG 4 | |||||||||||
.Ed | |||||||||||
.Pp | |||||||||||
To switch all TCP endpoints from using the freebsd stack to the rack stack use: | |||||||||||
.Bd -literal -offset indent | |||||||||||
# tcpsso -S freebsd TCP_FUNCTION_BLK rack | |||||||||||
.Ed | |||||||||||
.Pp | |||||||||||
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 new-reno: | |||||||||||
.Bd -literal -offset indent | |||||||||||
# tcpsso -C cubic TCP_CONGESTION new-reno | |||||||||||
.Ed | |||||||||||
.Sh SEE ALSO | |||||||||||
.Xr sockstat 1 , | |||||||||||
.Xr setsockopt 2 , | |||||||||||
.Xr tcp 4 , | |||||||||||
.Xr tcp_functions 9 | |||||||||||
.Sh AUTHORS | |||||||||||
.An Michael Tuexen Aq Mt tuexen@FreeBSD.org |
If I read https://docs.freebsd.org/en/books/fdp-primer/manual-pages/#manual-pages-markup (and specifically 10.3.2. Macros) right, you don't need to specify an argument to .Nm after the first time (in the NAME section).