.\" Copyright (c) 2016, George V. Neville-Neil
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright notice,
.\"    this list of conditions and the following disclaimer.
.\"
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
.\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd May 1, 2016
.Dt PKT-GEN 8
.Os
.Sh NAME
.Nm pkt-gen
.Nd Packet generator for use with
.Xr netmap 4
.Sh SYNOPSIS
.Bl -item -compact
.It
.Nm
.Op Fl i Ar interface
.Op Fl f Ar function
.Op Fl n Ar count
.Op Fl t Ar pkts_to_send
.Op Fl r Ar pkts_to_receive
.Op Fl l Ar pkt_size
.Op Fl d Ar dst_ip[:port[-dst_ip:port]]
.Op Fl s Ar src_ip[:port[-src_ip:port]]
.Op Fl D Ar dst-mac
.Op Fl S Ar src-mac
.Op Fl a Ar cpu_id
.Op Fl b Ar burst size
.Op Fl c Ar cores
.Op Fl p Ar threads
.Op Fl T Ar report_ms
.Op Fl P
.Op Fl w Ar wait_for_link_time
.Op Fl R Ar rate
.Op Fl X
.Op Fl H Ar len
.Op Fl P Ar xfile
.Op Fl z
.Op Fl Z
.Sh DESCRIPTION
.Nm
generates and receives raw network packets using
.Xr netmap 4 .
The arguments are as follows:
.Pp
.Bl -tag -width Ds
.It Fl i Ar interface
Network interface name.
.It Fl f Ar function tx rx ping pong
Set the function to transmit, receive of ping/pong.
.It Fl n count
Number of iterations (can be 0).
.It Fl t pkts_to_send
Number of packets to send.  Also forces transmit mode.
.It Fl r Ar pkts_to_receive
Number of packets to receive.  Also forces rx mode.
.It Fl l Ar pkt_size
Packet size in bytes excluding CRC.
.It Fl d Ar dst_ip[:port[-dst_ip:port]]
Destination IPv4 address and port, single or range.
.It Fl s Ar src_ip[:port[-src_ip:port]]
Source IPv4 address and port, single or range.
.It Fl D Ar dst-mac
Destination MAC address in colon notation.
.It Fl S Ar src-mac
Source MAC address in colon notation.
.It Fl a Ar cpu_id
Tie
.Nm
to a particular CPU core using
.Xr setaffinity 2.
.It Fl b Ar burst size
Set the size of a burst of packets.
.It Fl c Ar cores
Number of cores to use.
.It Fl p Ar threads
Number of threads to use.
.It Fl T Ar report_ms
Number of milliseconds between reports.
.It Fl P
Use libpcap instead of netmap for reading or writing.
.It Fl w Ar wait_for_link_time
Number of seconds to wait to make sure that the network link is up.  A
network device driver may take some time to create a new
transmit/receive ring pair when
.Xr netmap 4
requests one.
.It Fl R Ar rate
Packet transmission rate.  Not setting the packet transmission rate tells
.Nm
to transmit packets as quickly as possible.  On servers from 2010 on-wards
.Xr 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.
.It Fl X
Dump payload transmitted or received.
.It Fl H Ar len
Add empty virtio-net-header with size 'len'.  This option is only use
with Virtual Machine technologies that use virtio as a network interface.
.It Fl P Ar file
Load the packet from a pcap file rather than constructing it inside of
.Nm
.It Fl z
Use random IPv4 src address/port
.It Fl Z
Use random IPv4 dst address/port
.El
.Pp
.Nm
is a raw packet generator that can utilize either
.Xr netmap 4
or
.Xr bpf 4
but which is most often uses with
.Xr netmap 4 .
The
.Ar interface name
used depends upon how the underlying Ethernet driver exposes its
transmit and receive rings to
.Xr 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.
.Nm
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
.Ar -i netmap:ncxl0
gives
.Nm
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.
.Sh 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.
.Dl
.Pp
.Nm
-i cxl0 -f rx
.Pp
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.
.Pp
.Dl
.Nm
-i netmap:ncxl0 -f tx -s 172.16.0.1:53 -d 172.16.1.3:53 -D 00:07:43:29:2a:e0 
.Sh FILES
.Xr netmap 4
.Sh SEE ALSO
.Xr netmap 4
.Sh AUTHORS
This manual page was written by
.An George V. Neville-Neil Aq gnn@FreeBSD.org .