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