Add a manual page for pkt-gen.

Sponsored by: EMC / Isilon Storage Division

1 files changed, 179 insertions, 0 deletions

diff --git a/tools/tools/netmap/pkt-gen.8 b/tools/tools/netmap/pkt-gen.8
new file mode 100644
index 0000000..3e61439
--- /dev/null
+++ b/tools/tools/netmap/pkt-gen.8
@@ -0,0 +1,179 @@
+.\" 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 .