From 93a0b67496c286bd622ababf0556442d7eeecd62 Mon Sep 17 00:00:00 2001 From: "George V. Neville-Neil" Date: Sun, 1 May 2016 17:55:45 +0000 Subject: [PATCH] Add a manual page for pkt-gen. Sponsored by: EMC / Isilon Storage Division --- tools/tools/netmap/pkt-gen.8 | 179 +++++++++++++++++++++++++++++++++++ 1 file changed, 179 insertions(+) create mode 100644 tools/tools/netmap/pkt-gen.8 diff --git a/tools/tools/netmap/pkt-gen.8 b/tools/tools/netmap/pkt-gen.8 new file mode 100644 index 000000000000..3e6143962800 --- /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 .