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