tools/tools/netmap/pkt-gen.8

   1 .\" Copyright (c) 2016, George V. Neville-Neil
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions are met:
   6 .\"
   7 .\" 1. Redistributions of source code must retain the above copyright notice,
   8 .\"    this list of conditions and the following disclaimer.
   9 .\"
  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.
  13 .\"
  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.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd October 23, 2018
  29 .Dt PKT-GEN 8
  30 .Os
  31 .Sh NAME
  32 .Nm pkt-gen
  33 .Nd Packet generator for use with
  34 .Xr netmap 4
  35 .Sh SYNOPSIS
  36 .Bl -item -compact
  37 .It
  38 .Nm
  39 .Op Fl i Ar interface
  40 .Op Fl f Ar function
  41 .Op Fl n Ar count
  42 .Op Fl t Ar pkts_to_send
  43 .Op Fl r Ar pkts_to_receive
  44 .Op Fl l Ar pkt_size
  45 .Op Fl d Ar dst_ip[:port[-dst_ip:port]]
  46 .Op Fl s Ar src_ip[:port[-src_ip:port]]
  47 .Op Fl D Ar dst-mac
  48 .Op Fl S Ar src-mac
  49 .Op Fl a Ar cpu_id
  50 .Op Fl b Ar burst size
  51 .Op Fl c Ar cores
  52 .Op Fl p Ar threads
  53 .Op Fl T Ar report_ms
  54 .Op Fl P
  55 .Op Fl w Ar wait_for_link_time
  56 .Op Fl R Ar rate
  57 .Op Fl X
  58 .Op Fl H Ar len
  59 .Op Fl P Ar xfile
  60 .Op Fl z
  61 .Op Fl Z
  62 .Sh DESCRIPTION
  63 .Nm
  64 generates and receives raw network packets using
  65 .Xr netmap 4 .
  66 The arguments are as follows:
  67 .Pp
  68 .Bl -tag -width Ds
  69 .It Fl i Ar interface
  70 Network interface name.
  71 .It Fl f Ar function tx rx ping pong
  72 Set the function to transmit, receive of ping/pong.
  73 .It Fl n count
  74 Number of iterations (can be 0).
  75 .It Fl t pkts_to_send
  76 Number of packets to send.  Also forces transmit mode.
  77 .It Fl r Ar pkts_to_receive
  78 Number of packets to receive.  Also forces rx mode.
  79 .It Fl l Ar pkt_size
  80 Packet size in bytes excluding CRC.
  81 .It Fl d Ar dst_ip[:port[-dst_ip:port]]
  82 Destination IPv4 address and port, single or range.
  83 .It Fl s Ar src_ip[:port[-src_ip:port]]
  84 Source IPv4 address and port, single or range.
  85 .It Fl D Ar dst-mac
  86 Destination MAC address in colon notation.
  87 .It Fl S Ar src-mac
  88 Source MAC address in colon notation.
  89 .It Fl a Ar cpu_id
  90 Tie
  91 .Nm
  92 to a particular CPU core using
  93 .Xr setaffinity 2.
  94 .It Fl b Ar burst size
  95 Set the size of a burst of packets.
  96 .It Fl c Ar cores
  97 Number of cores to use.
  98 .It Fl p Ar threads
  99 Number of threads to use.
 100 .It Fl T Ar report_ms
 101 Number of milliseconds between reports.
 102 .It Fl P
 103 Use libpcap instead of netmap for reading or writing.
 104 .It Fl w Ar wait_for_link_time
 105 Number of seconds to wait to make sure that the network link is up.  A
 106 network device driver may take some time to create a new
 107 transmit/receive ring pair when
 108 .Xr netmap 4
 109 requests one.
 110 .It Fl R Ar rate
 111 Packet transmission rate.  Not setting the packet transmission rate tells
 112 .Nm
 113 to transmit packets as quickly as possible.  On servers from 2010 on-wards
 114 .Xr netmap 4
 115 is able to completely use all of the bandwidth of a 10 or 40Gbps link,
 116 so this option should be used unless your intention is to saturate the link.
 117 .It Fl X
 118 Dump payload transmitted or received.
 119 .It Fl H Ar len
 120 Add empty virtio-net-header with size 'len'.  This option is only use
 121 with Virtual Machine technologies that use virtio as a network interface.
 122 .It Fl P Ar file
 123 Load the packet from a pcap file rather than constructing it inside of
 124 .Nm
 125 .It Fl z
 126 Use random IPv4 src address/port
 127 .It Fl Z
 128 Use random IPv4 dst address/port
 129 .El
 130 .Pp
 131 .Nm
 132 is a raw packet generator that can utilize either
 133 .Xr netmap 4
 134 or
 135 .Xr bpf 4
 136 but which is most often uses with
 137 .Xr netmap 4 .
 138 The
 139 .Ar interface name
 140 used depends upon how the underlying Ethernet driver exposes its
 141 transmit and receive rings to
 142 .Xr netmap 4 .
 143 Most modern network interfaces that support 10Gbps and higher speeds
 144 have several transmit and receive rings that are used by the operating
 145 system to balance traffic across the interface.
 146 .Nm
 147 can peel off one or more of the transmit or receive rings for its own
 148 use without interfering with packets that might otherwise be destined
 149 for the host.  For example on a system with a Chelsio Network
 150 Interface Card (NIC) the interface specification of
 151 .Ar -i netmap:ncxl0
 152 gives
 153 .Nm
 154 access to a pair of transmit and receive rings that are separate from
 155 the more commonly known cxl0 interface, which is used by the operating
 156 system's TCP/IP stack.
 157 .Sh EXAMPLES
 158 Capture and count all packets arriving on the operating system's cxl0
 159 interface.  Using this will block packets from reaching the operating
 160 system's network stack.
 161 .Dl
 162 .Pp
 163 .Nm
 164 -i cxl0 -f rx
 165 .Pp
 166 Send a stream of fake DNS packets between two hosts with a packet
 167 length of 128 bytes.  You must set the destination MAC address for
 168 packets to be received by the target host.
 169 .Pp
 170 .Dl
 171 .Nm
 172 -i netmap:ncxl0 -f tx -s 172.16.0.1:53 -d 172.16.1.3:53 -D 00:07:43:29:2a:e0
 173 .Sh SEE ALSO
 174 .Xr netmap 4 ,
 175 .Xr bridge 8
 176 .Sh AUTHORS
 177 This manual page was written by
 178 .An George V. Neville-Neil Aq gnn@FreeBSD.org .