1.\" Copyright (c) 2016, George V. Neville-Neil 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions are met: 6.\" 7.\" 1. Redistributions of source code must retain the above copyright notice, 8.\" this list of conditions and the following disclaimer. 9.\" 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 15.\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 18.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 19.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 20.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 21.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 22.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 23.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 24.\" POSSIBILITY OF SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" 28.Dd November 21, 2020 29.Dt PKT-GEN 8 30.Os 31.Sh NAME 32.Nm pkt-gen 33.Nd Packet generator for use with 34.Xr netmap 4 35.Sh SYNOPSIS 36.Bl -item -compact 37.It 38.Nm 39.Op Fl h46XzZNIWvrAB 40.Op Fl i Ar interface 41.Op Fl f Ar function 42.Op Fl n Ar count 43.Op Fl l Ar pkt_size 44.Op Fl b Ar burst_size 45.Op Fl d Ar dst_ip[:port[-dst_ip:port]] 46.Op Fl s Ar src_ip[:port[-src_ip:port]] 47.Op Fl D Ar dst_mac 48.Op Fl S Ar src_mac 49.Op Fl a Ar cpu_id 50.Op Fl c Ar cpus 51.Op Fl p Ar threads 52.Op Fl T Ar report_ms 53.Op Fl P Ar file 54.Op Fl w Ar wait_for_link_time 55.Op Fl R Ar rate 56.Op Fl H Ar len 57.Op Fl F Ar num_frags 58.Op Fl M Ar frag_size 59.Op Fl C Ar port_config 60.El 61.Sh DESCRIPTION 62.Nm 63leverages 64.Xr netmap 4 65to generate and receive raw network packets in batches. 66The arguments are as follows: 67.Bl -tag -width Ds 68.It Fl h 69Show program usage and exit. 70.It Fl i Ar interface 71Name of the network interface that 72.Nm 73operates on. 74It can be a system network interface (e.g., em0), 75the name of a 76.Xr vale 4 77port (e.g., valeSSS:PPP), the name of a netmap pipe or monitor, 78or any valid netmap port name accepted by the 79.Ar nm_open 80library function, as documented in 81.Xr netmap 4 82(NIOCREGIF section). 83.It Fl f Ar function 84The function to be executed by 85.Nm . 86Specify 87.Cm tx 88for transmission, 89.Cm rx 90for reception, 91.Cm ping 92for client-side ping-pong operation, and 93.Cm pong 94for server-side ping-pong operation. 95.It Fl n Ar count 96Number of iterations of the 97.Nm 98function (with 0 meaning infinite). 99In case of 100.Cm tx 101or 102.Cm rx , 103.Ar count 104is the number of packets to receive or transmit. 105In case of 106.Cm ping 107or 108.Cm pong , 109.Ar count 110is the number of ping-pong transactions. 111.It Fl l Ar pkt_size 112Packet size in bytes excluding CRC. 113If passed a second time, use random sizes larger or equal than the 114second one and lower than the first one. 115.It Fl b Ar burst_size 116Transmit or receive up to 117.Ar burst_size 118packets at a time. 119.It Fl 4 120Use IPv4 addresses. 121.It Fl 6 122Use IPv6 addresses. 123.It Fl d Ar dst_ip[:port[-dst_ip:port]] 124Destination IPv4/IPv6 address and port, single or range. 125.It Fl s Ar src_ip[:port[-src_ip:port]] 126Source IPv4/IPv6 address and port, single or range. 127.It Fl D Ar dst_mac 128Destination MAC address in colon notation (e.g., aa:bb:cc:dd:ee:00). 129.It Fl S Ar src_mac 130Source MAC address in colon notation. 131.It Fl a Ar cpu_id 132Pin the first thread of 133.Nm 134to a particular CPU using 135.Xr pthread_setaffinity_np 3 . 136If more threads are used, they are pinned to the subsequent CPUs, 137one per thread. 138.It Fl c Ar cpus 139Maximum number of CPUs to use (0 means to use all the available ones). 140.It Fl p Ar threads 141Number of threads to use. 142By default, only a single thread is used 143to handle all the netmap rings. 144If 145.Ar threads 146is larger than one, each thread handles a single TX ring (in 147.Cm tx 148mode), a single RX ring (in 149.Cm rx 150mode), or a TX/RX ring pair. 151The number of 152.Ar threads 153must be less than or equal to the number of TX (or RX) ring available 154in the device specified by 155.Ar interface . 156.It Fl T Ar report_ms 157Number of milliseconds between reports. 158.It Fl w Ar wait_for_link_time 159Number of seconds to wait before starting the 160.Nm 161function, useful to make sure that the network link is up. 162A network device driver may take some time to enter netmap mode, or 163to create a new transmit/receive ring pair when 164.Xr netmap 4 165requests one. 166.It Fl R Ar rate 167Packet transmission rate. 168Not setting the packet transmission rate tells 169.Nm 170to transmit packets as quickly as possible. 171On servers from 2010 onward 172.Xr netmap 4 173is able to completely use all of the bandwidth of a 10 or 40Gbps link, 174so this option should be used unless your intention is to saturate the link. 175.It Fl X 176Dump payload of each packet transmitted or received. 177.It Fl H Ar len 178Add empty virtio-net-header with size 179.Ar len . 180Valid sizes are 0, 10 and 12. 181This option is only used with Virtual Machine technologies that use virtio 182as a network interface. 183.It Fl P Ar file 184Load the packet to be transmitted from a pcap file rather than constructing 185it within 186.Nm . 187.It Fl z 188Use random IPv4/IPv6 src address/port. 189.It Fl Z 190Use random IPv4/IPv6 dst address/port. 191.It Fl N 192Do not normalize units (i.e., use bps, pps instead of Mbps, Kpps, etc.). 193.It Fl F Ar num_frags 194Send multi-slot packets, each one with 195.Ar num_frags 196fragments. 197A multi-slot packet is represented by two or more consecutive netmap slots 198with the 199.Ar NS_MOREFRAG 200flag set (except for the last slot). 201This is useful to transmit or receive packets larger than the netmap 202buffer size. 203.It Fl M Ar frag_size 204In multi-slot mode, 205.Ar frag_size 206specifies the size of each fragment, if smaller than the packet length 207divided by 208.Ar num_frags . 209.It Fl I 210Use indirect buffers. 211It is only valid for transmitting on VALE ports, 212and it is implemented by setting the 213.Ar NS_INDIRECT 214flag in the netmap slots. 215.It Fl W 216Exit immediately if all the RX rings are empty the first time they are 217examined. 218.It Fl v 219Increase the verbosity level. 220.It Fl r 221In 222.Cm tx 223mode, do not initialize packets, but send whatever the content of 224the uninitialized netmap buffers is (rubbish mode). 225.It Fl A 226Compute mean and standard deviation (over a sliding window) for the 227transmit or receive rate. 228.It Fl B 229Take Ethernet framing and CRC into account when computing the average bps. 230This adds 4 bytes of CRC and 20 bytes of framing to each packet. 231.It Fl C Ar tx_slots Ns Oo Cm \&, Ns Ar rx_slots Ns Oo Cm \&, Ns Ar tx_rings Ns Oo Cm \&, Ns Ar rx_rings Oc Oc Oc 232Configuration in terms of number of rings and slots to be used when 233opening the netmap port. 234Such configuration has an effect on software ports 235created on the fly, such as VALE ports and netmap pipes. 236The configuration may consist of 1 to 4 numbers separated by commas: 237.Dq tx_slots,rx_slots,tx_rings,rx_rings . 238Missing numbers or zeroes stand for default values. 239As an additional convenience, if exactly one number is specified, 240then this is assigned to both 241.Ar tx_slots 242and 243.Ar rx_slots . 244If there is no fourth number, then the third one is assigned to both 245.Ar tx_rings 246and 247.Ar rx_rings . 248.El 249.Pp 250.Nm 251is a raw packet generator that can utilize either 252.Xr netmap 4 253or 254.Xr bpf 4 255but which is most often used with 256.Xr netmap 4 . 257The 258.Ar interface name 259used depends upon how the underlying Ethernet driver exposes its 260transmit and receive rings to 261.Xr netmap 4 . 262Most modern network interfaces that support 10Gbps and higher speeds 263have several transmit and receive rings that are used by the operating 264system to balance traffic across the interface. 265.Nm 266can peel off one or more of the transmit or receive rings for its own 267use without interfering with packets that might otherwise be destined 268for the host. 269For example on a system with a Chelsio Network 270Interface Card (NIC) the interface specification of 271.Ar -i netmap:ncxl0 272gives 273.Nm 274access to a pair of transmit and receive rings that are separate from 275the more commonly known cxl0 interface, which is used by the operating 276system's TCP/IP stack. 277.Sh EXAMPLES 278Capture and count all packets arriving on the operating system's cxl0 279interface. 280Using this will block packets from reaching the operating 281system's network stack. 282.Bd -literal -offset indent 283pkt-gen -i cxl0 -f rx 284.Ed 285.Pp 286Send a stream of fake DNS packets between two hosts with a packet 287length of 128 bytes. 288You must set the destination MAC address for 289packets to be received by the target host. 290.Bd -literal -offset indent 291pkt-gen -i netmap:ncxl0 -f tx -s 172.16.0.1:53 -d 172.16.1.3:53 -D 00:07:43:29:2a:e0 292.Ed 293.Sh SEE ALSO 294.Xr netmap 4 , 295.Xr bridge 8 296.Sh AUTHORS 297This manual page was written by 298.An George V. Neville-Neil Aq gnn@FreeBSD.org . 299