NAME

pkt-gen — Packet generator for use with netmap(4)

SYNOPSIS

• pkt-gen

  [-h46XzZNIWvrAB] [-i interface] [-f function] [-n count] [-l pkt_size] [-b burst_size] [-d dst_ip[:port[-dst_ip:port]]] [-s src_ip[:port[-src_ip:port]]] [-D dst_mac] [-S src_mac] [-a cpu_id] [-c cpus] [-p threads] [-T report_ms] [-P file] [-w wait_for_link_time] [-R rate] [-H len] [-F num_frags] [-M frag_size] [-C port_config]

DESCRIPTION

pkt-gen leverages netmap(4) to generate and receive raw network packets in batches. The arguments are as follows:

-h

Show program usage and exit.

-i interface

Name of the network interface that pkt-gen operates on. It can be a system network interface (e.g., em0), the name of a vale(4) port (e.g., valeSSS:PPP), the name of a netmap pipe or monitor, or any valid netmap port name accepted by the nm_open library function, as documented in netmap(4) (NIOCREGIF section).

-f function

The function to be executed by pkt-gen. Specify tx for transmission, rx for reception, ping for client-side ping-pong operation, and pong for server-side ping-pong operation.

-n count

Number of iterations of the pkt-gen function (with 0 meaning infinite). In case of tx or rx, count is the number of packets to receive or transmit. In case of ping or pong, count is the number of ping-pong transactions.

-l pkt_size

Packet size in bytes excluding CRC. If passed a second time, use random sizes larger or equal than the second one and lower than the first one.

-b burst_size

Transmit or receive up to burst_size packets at a time.

-4

Use IPv4 addresses.

-6

Use IPv6 addresses.

-d dst_ip[:port[-dst_ip:port]]

Destination IPv4/IPv6 address and port, single or range.

-s src_ip[:port[-src_ip:port]]

Source IPv4/IPv6 address and port, single or range.

-D dst_mac

Destination MAC address in colon notation (e.g., aa:bb:cc:dd:ee:00).

-S src_mac

Source MAC address in colon notation.

-a cpu_id

Pin the first thread of pkt-gen to a particular CPU using pthread_setaffinity_np(3). If more threads are used, they are pinned to the subsequent CPUs, one per thread.

-c cpus

Maximum number of CPUs to use (0 means to use all the available ones).

-p threads

Number of threads to use. By default, only a single thread is used to handle all the netmap rings. If threads is larger than one, each thread handles a single TX ring (in tx mode), a single RX ring (in rx mode), or a TX/RX ring pair. The number of threads must be less than or equal to the number of TX (or RX) rings available in the device specified by interface.

-T report_ms

Number of milliseconds between reports.

-w wait_for_link_time

Number of seconds to wait before starting the pkt-gen function, useful to make sure that the network link is up. A network device driver may take some time to enter netmap mode, or to create a new transmit/receive ring pair when netmap(4) requests one.

-R rate

Packet transmission rate. Not setting the packet transmission rate tells pkt-gen to transmit packets as quickly as possible. On servers from 2010 onward netmap(4) is able to completely use all of the bandwidth of a 10 or 40Gbps link, so this option should be used unless your intention is to saturate the link.

-X

Dump payload of each packet transmitted or received.

-H len

Add empty virtio-net-header with size len. Valid sizes are 0, 10 and 12. This option is only used with Virtual Machine technologies that use virtio as a network interface.

-P file

Load the packet to be transmitted from a pcap file rather than constructing it within pkt-gen.

-z

Use random IPv4/IPv6 src address/port.

-Z

Use random IPv4/IPv6 dst address/port.

-N

Do not normalize units (i.e., use bps, pps instead of Mbps, Kpps, etc.).

-F num_frags

Send multi-slot packets, each one with num_frags fragments. A multi-slot packet is represented by two or more consecutive netmap slots with the NS_MOREFRAG flag set (except for the last slot). This is useful to transmit or receive packets larger than the netmap buffer size.

-M frag_size

In multi-slot mode, frag_size specifies the size of each fragment, if smaller than the packet length divided by num_frags.

-I

Use indirect buffers. It is only valid for transmitting on VALE ports, and it is implemented by setting the NS_INDIRECT flag in the netmap slots.

-W

Exit immediately if all the RX rings are empty the first time they are examined.

-v

Increase the verbosity level.

-r

In tx mode, do not initialize packets, but send whatever the content of the uninitialized netmap buffers is (rubbish mode).

-A

Compute mean and standard deviation (over a sliding window) for the transmit or receive rate.

-B

Take Ethernet framing and CRC into account when computing the average bps. This adds 4 bytes of CRC and 20 bytes of framing to each packet.

-C tx_slots[,rx_slots[,tx_rings[,rx_rings]]]

Configuration in terms of number of rings and slots to be used when opening the netmap port. Such configuration has an effect on software ports created on the fly, such as VALE ports and netmap pipes. The configuration may consist of 1 to 4 numbers separated by commas: “tx_slots,rx_slots,tx_rings,rx_rings”. Missing numbers or zeroes stand for default values. As an additional convenience, if exactly one number is specified, then this is assigned to both tx_slots and rx_slots. If there is no fourth number, then the third one is assigned to both tx_rings and rx_rings.

pkt-gen is a raw packet generator that can utilize either netmap(4) or bpf(4) but which is most often used with netmap(4). The interface name used depends upon how the underlying Ethernet driver exposes its transmit and receive rings to netmap(4). Most modern network interfaces that support 10Gbps and higher speeds have several transmit and receive rings that are used by the operating system to balance traffic across the interface. pkt-gen can peel off one or more of the transmit or receive rings for its own use without interfering with packets that might otherwise be destined for the host. For example on a system with a Chelsio Network Interface Card (NIC) the interface specification of -i netmap:ncxl0 gives pkt-gen access to a pair of transmit and receive rings that are separate from the more commonly known cxl0 interface, which is used by the operating system's TCP/IP stack.

EXAMPLES

Capture and count all packets arriving on the operating system's cxl0 interface. Using this will block packets from reaching the operating system's network stack.

pkt-gen -i cxl0 -f rx

Send a stream of fake DNS packets between two hosts with a packet length of 128 bytes. You must set the destination MAC address for packets to be received by the target host.

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

SEE ALSO

netmap(4), bridge(8)

AUTHORS

This manual page was written by George V. Neville-Neil ⟨gnn@FreeBSD.org⟩.