Annotation of src/usr.bin/tcpbench/tcpbench.1, Revision 1.29
1.29 ! bluhm 1: .\" $OpenBSD: tcpbench.1,v 1.28 2020/05/04 12:13:09 sthen Exp $
1.1 djm 2: .\"
3: .\" Copyright (c) 2008 Damien Miller <djm@mindrot.org>
4: .\"
5: .\" Permission to use, copy, modify, and distribute this software for any
6: .\" purpose with or without fee is hereby granted, provided that the above
7: .\" copyright notice and this permission notice appear in all copies.
8: .\"
9: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16: .\"
1.29 ! bluhm 17: .Dd $Mdocdate: May 4 2020 $
1.9 jmc 18: .Dt TCPBENCH 1
1.1 djm 19: .Os
20: .Sh NAME
21: .Nm tcpbench
1.12 jmc 22: .Nd TCP/UDP benchmarking and measurement tool
1.1 djm 23: .Sh SYNOPSIS
24: .Nm
25: .Fl l
26: .Nm
1.29 ! bluhm 27: .Op Fl 46DRUuv
1.2 jmc 28: .Op Fl B Ar buf
1.26 schwarze 29: .Op Fl b Ar sourceaddr
1.1 djm 30: .Op Fl k Ar kvars
1.3 henning 31: .Op Fl n Ar connections
1.1 djm 32: .Op Fl p Ar port
1.11 claudio 33: .Op Fl r Ar interval
1.1 djm 34: .Op Fl S Ar space
1.13 haesbaer 35: .Op Fl T Ar toskeyword
1.17 henning 36: .Op Fl t Ar secs
1.8 guenther 37: .Op Fl V Ar rtable
1.1 djm 38: .Ar hostname
39: .Nm
1.7 jmc 40: .Bk -words
1.1 djm 41: .Fl s
1.29 ! bluhm 42: .Op Fl 46DUuv
1.2 jmc 43: .Op Fl B Ar buf
1.1 djm 44: .Op Fl k Ar kvars
45: .Op Fl p Ar port
1.11 claudio 46: .Op Fl r Ar interval
1.14 jmc 47: .Op Fl S Ar space
1.13 haesbaer 48: .Op Fl T Ar toskeyword
1.8 guenther 49: .Op Fl V Ar rtable
1.21 claudio 50: .Op Ar hostname
1.7 jmc 51: .Ek
1.1 djm 52: .Sh DESCRIPTION
53: .Nm
54: is a small tool that performs throughput benchmarking and concurrent
55: sampling of kernel network variables.
56: .Pp
57: .Nm
58: is run as a client/server pair.
59: The server must be invoked with the
60: .Fl s
61: flag, which will cause it to listen for incoming connections.
62: The client must be invoked with the
63: .Ar hostname
64: of a listening server to connect to.
65: .Pp
1.11 claudio 66: Once connected, the client will send TCP or UDP traffic as fast as possible to
1.1 djm 67: the server.
1.27 procter 68: Both the client and server will periodically compute and display throughput
69: statistics.
70: The server starts computing these for UDP on receipt of the first datagram,
71: and stops for TCP when it has no connections.
72: This display also includes any kernel variables the user has selected to
1.1 djm 73: sample (using the
74: .Fl k
1.11 claudio 75: option, which is only available in TCP mode).
1.1 djm 76: A list of available kernel variables may be obtained using the
77: .Fl l
78: option.
1.27 procter 79: .Pp
80: A summary over the periodic throughput statistics is displayed on exit.
81: Its accuracy may be increased by decreasing the
82: .Ar interval .
83: The summary bytes and duration cover the interval from transfer start
84: to process exit.
1.28 sthen 85: The summary information can also be displayed while
86: .Nm
87: is running by sending it a
88: .Dv SIGINFO
89: signal (see the
90: .Cm status
91: argument of
92: .Xr stty 1
93: for more information).
1.1 djm 94: .Pp
95: The options are as follows:
96: .Bl -tag -width Ds
1.20 dlg 97: .It Fl 4
1.24 jmc 98: Force
1.20 dlg 99: .Nm
100: to use IPv4 addresses only.
101: .It Fl 6
1.24 jmc 102: Force
1.20 dlg 103: .Nm
104: to use IPv6 addresses only.
1.2 jmc 105: .It Fl B Ar buf
1.5 jmc 106: Specify the size of the internal read/write buffer used by
1.1 djm 107: .Nm .
1.11 claudio 108: The default is 262144 bytes for TCP client/server and UDP server.
1.12 jmc 109: In UDP client mode this may be used to specify the packet size on the test
1.11 claudio 110: stream.
1.26 schwarze 111: .It Fl b Ar sourceaddr
112: Specify the IP address to send the packets from,
113: which is useful on machines with multiple interfaces.
1.29 ! bluhm 114: .It Fl D
! 115: Enable debugging on the socket.
1.1 djm 116: .It Fl k Ar kvars
1.2 jmc 117: Specify one or more kernel variables to monitor; multiple variables must be
1.12 jmc 118: separated with commas.
119: This option is only valid in TCP mode.
1.1 djm 120: The default is not to monitor any variables.
1.5 jmc 121: Using this option requires read access to
1.23 deraadt 122: .Pa /dev/kmem ,
123: which may be restricted based upon the value of the
124: .Ar kern.allowkmem
125: .Xr sysctl 8 .
1.2 jmc 126: .It Fl l
127: List the name of kernel variables available for monitoring and exit.
1.3 henning 128: .It Fl n Ar connections
1.12 jmc 129: Use the given number of TCP connections (default: 1).
130: UDP is connectionless so this option isn't valid.
1.1 djm 131: .It Fl p Ar port
1.12 jmc 132: Specify the port used for the test stream (default: 12345).
1.21 claudio 133: .It Fl R
134: In client mode the write buffer size is randomized up to the size specified via
135: .Fl B .
1.11 claudio 136: .It Fl r Ar interval
137: Specify the statistics interval reporting rate in milliseconds (default: 1000).
1.25 bluhm 138: If set to 0, nothing is printed.
1.2 jmc 139: .It Fl S Ar space
1.12 jmc 140: Set the size of the socket buffer used for the test stream.
1.2 jmc 141: On the client this option will resize the send buffer;
142: on the server it will resize the receive buffer.
1.1 djm 143: .It Fl s
144: Place
145: .Nm
146: in server mode, where it will listen on all interfaces for incoming
1.12 jmc 147: connections.
148: It defaults to using TCP if
1.11 claudio 149: .Fl u
1.12 jmc 150: is not specified.
1.13 haesbaer 151: .It Fl T Ar toskeyword
152: Change the IPv4 TOS or IPv6 TCLASS value.
153: .Ar toskeyword
154: may be one of
155: .Ar critical ,
156: .Ar inetcontrol ,
157: .Ar lowdelay ,
158: .Ar netcontrol ,
159: .Ar throughput ,
160: .Ar reliability ,
161: or one of the DiffServ Code Points:
162: .Ar ef ,
163: .Ar af11 ... af43 ,
164: .Ar cs0 ... cs7 ;
165: or a number in either hex or decimal.
1.17 henning 166: .It Fl t Ar secs
167: Stop after
168: .Ar secs
169: seconds.
1.21 claudio 170: .It Fl U
171: Use AF_UNIX sockets instead of IPv4 or IPv6 sockets.
1.22 jmc 172: In client and server mode
1.21 claudio 173: .Ar hostname
174: is used as the path to the AF_UNIX socket.
1.11 claudio 175: .It Fl u
1.12 jmc 176: Use UDP instead of TCP; this must be specified on both the client
177: and the server.
178: Transmitted packets per second (TX PPS) will be accounted on the client
1.16 haesbaer 179: side, while received packets per second (RX PPS) will be accounted on the
1.12 jmc 180: server side.
181: UDP has no Protocol Control Block (PCB) so the
1.11 claudio 182: .Fl k
183: flags don't apply.
1.8 guenther 184: .It Fl V Ar rtable
185: Set the routing table to be used.
1.1 djm 186: .It Fl v
187: Display verbose output.
188: If specified more than once, increase the detail of information displayed.
189: .El
190: .Sh SEE ALSO
1.2 jmc 191: .Xr netstat 1 ,
1.1 djm 192: .Xr pstat 8
1.10 fkr 193: .Sh HISTORY
194: The
195: .Nm
196: program first appeared in
197: .Ox 4.4 .
198: .Sh AUTHORS
1.12 jmc 199: .An -nosplit
1.10 fkr 200: The
201: .Nm
202: program was written by
1.18 schwarze 203: .An Damien Miller Aq Mt djm@openbsd.org .
1.12 jmc 204: .Pp
1.11 claudio 205: UDP mode and libevent port by
1.18 schwarze 206: .An Christiano F. Haesbaert Aq Mt haesbaert@haesbaert.org .