tools/tools/netmap/pkt-gen.8

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