1 .\" Copyright (c) 2016, George V. Neville-Neil
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions are met:
7 .\" 1. Redistributions of source code must retain the above copyright notice,
8 .\" this list of conditions and the following disclaimer.
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.
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.
33 .Nd Packet generator for use with
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]]
54 .Op Fl w Ar wait_for_link_time
59 .Op Fl C Ar port_config
65 to generate and receive raw network packets in batches.
66 The arguments are as follows:
69 Show program usage and exit.
71 Name of the network interface that
74 It can be a system network interface (e.g., em0),
77 port (e.g., valeSSS:PPP), the name of a netmap pipe or monitor,
78 or any valid netmap port name accepted by the
80 library function, as documented in
84 The function to be executed by
92 for client-side ping-pong operation, and
94 for server-side ping-pong operation.
96 Number of iterations of the
98 function, with 0 meaning infinite).
104 is the number of packets to receive or transmit.
110 is the number of ping-pong transactions.
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
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.
128 Destination MAC address in colon notation (e.g., aa:bb:cc:dd:ee:00).
130 Source MAC address in colon notation.
132 Pin the first thread of
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,
139 Maximum number of CPUs to use (0 means to use all the available ones).
141 Number of threads to use.
142 By default, only a single thread is used
143 to handle all the netmap rings.
146 is larger than one, each thread handles a single TX ring (in
148 mode), a single RX ring (in
150 mode), or a TX/RX ring couple.
153 must be less or equal than the number of TX (or RX) ring available
154 in the device specified by
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
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
167 Packet transmission rate.
168 Not setting the packet transmission rate tells
170 to transmit packets as quickly as possible.
171 On servers from 2010 on-wards
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.
176 Dump payload of each packet transmitted or received.
178 Add empty virtio-net-header with size
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.
184 Load the packet to be transmitted from a pcap file rather than constructing
188 Use random IPv4/IPv6 src address/port.
190 Use random IPv4/IPv6 dst address/port.
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
197 A multi-slot packet is represented by two or more consecutive netmap slots
200 flag set (except for the last slot).
201 This is useful to transmit or receive packets larger than the netmap
203 .It Fl M Ar frag_size
206 specifies the size of each fragment, if smaller than the packet length
210 Use indirect buffers.
211 It is only valid for transmitting on VALE ports,
212 and it is implemented by setting the
214 flag in the netmap slots.
216 Exit immediately if all the RX rings are empty the first time they are
219 Increase the verbosity level.
223 mode, do not initialize packets, but send whatever the content of
224 the uninitialized netmap buffers is (rubbish mode).
226 Compute mean and standard deviation (over a sliding window) for the
227 transmit or receive rate.
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
244 If there is no fourth number, then the third one is assigned to both
251 is a raw packet generator that can utilize either
255 but which is most often used with
259 used depends upon how the underlying Ethernet driver exposes its
260 transmit and receive rings to
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.
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
269 For example on a system with a Chelsio Network
270 Interface Card (NIC) the interface specification of
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.
278 Capture and count all packets arriving on the operating system's cxl0
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
286 Send a stream of fake DNS packets between two hosts with a packet
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
297 This manual page was written by
298 .An George V. Neville-Neil Aq gnn@FreeBSD.org .