1.\" $OpenBSD: tcpbench.1,v 1.25 2018/09/28 19:01:52 bluhm Exp $ 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.\" 17.Dd $Mdocdate: September 28 2018 $ 18.Dt TCPBENCH 1 19.Os 20.Sh NAME 21.Nm tcpbench 22.Nd TCP/UDP benchmarking and measurement tool 23.Sh SYNOPSIS 24.Nm 25.Fl l 26.Nm 27.Op Fl 46RUuv 28.Op Fl B Ar buf 29.Op Fl b Ar addr 30.Op Fl k Ar kvars 31.Op Fl n Ar connections 32.Op Fl p Ar port 33.Op Fl r Ar interval 34.Op Fl S Ar space 35.Op Fl T Ar toskeyword 36.Op Fl t Ar secs 37.Op Fl V Ar rtable 38.Ar hostname 39.Nm 40.Bk -words 41.Fl s 42.Op Fl 46Uuv 43.Op Fl B Ar buf 44.Op Fl k Ar kvars 45.Op Fl p Ar port 46.Op Fl r Ar interval 47.Op Fl S Ar space 48.Op Fl T Ar toskeyword 49.Op Fl V Ar rtable 50.Op Ar hostname 51.Ek 52.Sh DESCRIPTION 53.Nm 54is a small tool that performs throughput benchmarking and concurrent 55sampling of kernel network variables. 56.Pp 57.Nm 58is run as a client/server pair. 59The server must be invoked with the 60.Fl s 61flag, which will cause it to listen for incoming connections. 62The client must be invoked with the 63.Ar hostname 64of a listening server to connect to. 65.Pp 66Once connected, the client will send TCP or UDP traffic as fast as possible to 67the server. 68Both the client and server will periodically display throughput 69statistics along with any kernel variables the user has selected to 70sample (using the 71.Fl k 72option, which is only available in TCP mode). 73A list of available kernel variables may be obtained using the 74.Fl l 75option. 76.Pp 77The options are as follows: 78.Bl -tag -width Ds 79.It Fl 4 80Force 81.Nm 82to use IPv4 addresses only. 83.It Fl 6 84Force 85.Nm 86to use IPv6 addresses only. 87.It Fl B Ar buf 88Specify the size of the internal read/write buffer used by 89.Nm . 90The default is 262144 bytes for TCP client/server and UDP server. 91In UDP client mode this may be used to specify the packet size on the test 92stream. 93.It Fl b Ar addr 94Specify the IP address of the interface which is used to send the packets. 95.It Fl k Ar kvars 96Specify one or more kernel variables to monitor; multiple variables must be 97separated with commas. 98This option is only valid in TCP mode. 99The default is not to monitor any variables. 100Using this option requires read access to 101.Pa /dev/kmem , 102which may be restricted based upon the value of the 103.Ar kern.allowkmem 104.Xr sysctl 8 . 105.It Fl l 106List the name of kernel variables available for monitoring and exit. 107.It Fl n Ar connections 108Use the given number of TCP connections (default: 1). 109UDP is connectionless so this option isn't valid. 110.It Fl p Ar port 111Specify the port used for the test stream (default: 12345). 112.It Fl R 113In client mode the write buffer size is randomized up to the size specified via 114.Fl B . 115.It Fl r Ar interval 116Specify the statistics interval reporting rate in milliseconds (default: 1000). 117If set to 0, nothing is printed. 118.It Fl S Ar space 119Set the size of the socket buffer used for the test stream. 120On the client this option will resize the send buffer; 121on the server it will resize the receive buffer. 122.It Fl s 123Place 124.Nm 125in server mode, where it will listen on all interfaces for incoming 126connections. 127It defaults to using TCP if 128.Fl u 129is not specified. 130.It Fl T Ar toskeyword 131Change the IPv4 TOS or IPv6 TCLASS value. 132.Ar toskeyword 133may be one of 134.Ar critical , 135.Ar inetcontrol , 136.Ar lowdelay , 137.Ar netcontrol , 138.Ar throughput , 139.Ar reliability , 140or one of the DiffServ Code Points: 141.Ar ef , 142.Ar af11 ... af43 , 143.Ar cs0 ... cs7 ; 144or a number in either hex or decimal. 145.It Fl t Ar secs 146Stop after 147.Ar secs 148seconds. 149.It Fl U 150Use AF_UNIX sockets instead of IPv4 or IPv6 sockets. 151In client and server mode 152.Ar hostname 153is used as the path to the AF_UNIX socket. 154.It Fl u 155Use UDP instead of TCP; this must be specified on both the client 156and the server. 157Transmitted packets per second (TX PPS) will be accounted on the client 158side, while received packets per second (RX PPS) will be accounted on the 159server side. 160UDP has no Protocol Control Block (PCB) so the 161.Fl k 162flags don't apply. 163.It Fl V Ar rtable 164Set the routing table to be used. 165.It Fl v 166Display verbose output. 167If specified more than once, increase the detail of information displayed. 168.El 169.Sh SEE ALSO 170.Xr netstat 1 , 171.Xr pstat 8 172.Sh HISTORY 173The 174.Nm 175program first appeared in 176.Ox 4.4 . 177.Sh AUTHORS 178.An -nosplit 179The 180.Nm 181program was written by 182.An Damien Miller Aq Mt djm@openbsd.org . 183.Pp 184UDP mode and libevent port by 185.An Christiano F. Haesbaert Aq Mt haesbaert@haesbaert.org . 186