1TRAFGEN(8)                    netsniff-ng toolkit                   TRAFGEN(8)
2
3
4

NAME

6       trafgen - a fast, multithreaded network packet generator
7

SYNOPSIS

9       trafgen [options] [packet]
10

DESCRIPTION

12       trafgen  is  a fast, zero-copy network traffic generator for debugging,
13       performance  evaluation,  and  fuzz-testing.   trafgen   utilizes   the
14       packet(7)  socket  interface  of Linux which postpones complete control
15       over packet data and packet headers into the user space. It has a  pow‐
16       erful  packet configuration language, which is rather low-level and not
17       limited to particular protocols.  Thus, trafgen can be  used  for  many
18       purposes.  Its  only  limitation  is  that it cannot mimic full streams
19       resp. sessions. However, it is very useful for various  kinds  of  load
20       testing  in order to analyze and subsequently improve systems behaviour
21       under DoS attack scenarios, for instance.
22
23       trafgen is Linux specific, meaning there is no support for other  oper‐
24       ating  systems, same as netsniff-ng(8), thus we can keep the code foot‐
25       print quite minimal and to the point. trafgen makes  use  of  packet(7)
26       socket's  TX_RING  interface of the Linux kernel, which is a mmap(2)'ed
27       ring buffer shared between user and kernel space.
28
29       By default, trafgen starts as many processes as  available  CPUs,  pins
30       each  of  them to their respective CPU and sets up the ring buffer each
31       in their own process space after having compiled a list of  packets  to
32       transmit.  Thus,  this is likely the fastest one can get out of the box
33       in terms of transmission performance from user space, without having to
34       load unsupported or non-mainline third-party kernel modules. On Gigabit
35       Ethernet, trafgen has a comparable performance to pktgen, the  built-in
36       Linux kernel traffic generator, except that trafgen is more flexible in
37       terms of packet configuration possibilities.  On  10-Gigabit-per-second
38       Ethernet,  trafgen  might  be slower than pktgen due to the user/kernel
39       space overhead but still has a fairly high performance for out  of  the
40       box kernels.
41
42       trafgen has the potential to do fuzz testing, meaning a packet configu‐
43       ration can be built with random numbers on all or certain  packet  off‐
44       sets  that are freshly generated each time a packet is sent out. With a
45       built-in IPv4 ping, trafgen can send  out  an  ICMP  probe  after  each
46       packet  injection  to  the  remote host in order to test if it is still
47       responsive/alive. Assuming there is no  answer  from  the  remote  host
48       after a certain threshold of probes, the machine is considered dead and
49       the last sent packet is printed together with the random seed that  was
50       used  by trafgen. You might not really get lucky fuzz-testing the Linux
51       kernel, but presumably there are buggy closed-source  embedded  systems
52       or  network driver's firmware files that are prone to bugs, where traf‐
53       gen could help in finding them.
54
55       trafgen's configuration language is quite powerful,  also  due  to  the
56       fact,  that  it  supports  C  preprocessor  macros. A stddef.h is being
57       shipped with trafgen for this purpose, so that well known defines  from
58       Linux  kernel  or network programming can be reused. After a configura‐
59       tion file has passed the C preprocessor stage, it is processed  by  the
60       trafgen  packet compiler. The language itself supports a couple of fea‐
61       tures that are useful when assembling packets, such as built-in runtime
62       checksum support for IP, UDP and TCP. Also it has an expression evalua‐
63       tor where arithmetic (basic operations, bit operations,  bit  shifting,
64       ...)  on  constant expressions is being reduced to a single constant on
65       compile time. Other features are ''fill'' macros, where a packet can be
66       filled with n bytes by a constant, a compile-time random number or run-
67       time random number (as mentioned with fuzz  testing).  Also,  netsniff-
68       ng(8) is able to convert a pcap file into a trafgen configuration file,
69       thus such a configuration can be further tweaked for a given scenario.
70

OPTIONS

72       -i <cfg|pcap|->, -c <cfg|->, --in <cfg|pcap|->, --conf <cfg|->
73              Defines the input configuration file that can either  be  passed
74              as a normal plain text file or via stdin (''-''). Note that cur‐
75              rently, if a configuration is passed through stdin, only  1  CPU
76              will  be  used.   It  is also possible to specify PCAP file with
77              .pcap extension via -i/--in option, by default packets  will  be
78              sent at rate considering timestamp from PCAP file which might be
79              reset via the -b or -t option.
80
81       -o <dev|.pcap|.cfg>, -d <dev|.pcap|.cfg>, --out <dev|.pcap|.cfg>, --dev
82       <dev|.pcap|.cfg>
83              Defines  the  outgoing networking device such as eth0, wlan0 and
84              others or a *.pcap or *.cfg file. Pcap and  configuration  files
85              are identified by extension.
86
87       -p, --cpp
88              Pass the packet configuration to the C preprocessor before read‐
89              ing it into trafgen. This allows #define and #include directives
90              (e.g.  to include definitions from system headers) to be used in
91              the trafgen configuration file.
92
93       -D <name>=<definition>, --define <name>=<definition>
94              Add macro definition for the C preprocessor  to  use  it  within
95              trafgen  file.  This  option  is  used  in  combination with the
96              -p/--cpp option.
97
98       -J, --jumbo-support
99              By default trafgen's ring buffer frames are of a fixed  size  of
100              2048 bytes.  This means that if you're expecting jumbo frames or
101              even super jumbo frames to pass your line, then you will need to
102              enable  support  for that with the help of this option. However,
103              this has the disadvantage of a performance regression and a big‐
104              ger memory footprint for the ring buffer.
105
106       -R, --rfraw
107              In case the output networking device is a wireless device, it is
108              possible with trafgen to turn this into monitor mode and  create
109              a  mon<X> device that trafgen will be transmitting on instead of
110              wlan<X>, for instance. This enables trafgen to inject raw 802.11
111              frames.  In  case  if the output is a pcap file the link type is
112              set to 127 (ieee80211 radio tap).
113
114       -s <ipv4>, --smoke-test <ipv4>
115              In case this option is enabled, trafgen  will  perform  a  smoke
116              test. In other words, it will probe the remote end, specified by
117              an <ipv4> address, that is being ''attacked'' with trafgen  net‐
118              work  traffic,  if it is still alive and responsive. That means,
119              after each transmitted packet that has been configured,  trafgen
120              sends  out  ICMP echo requests and waits for an answer before it
121              continues.  In case the remote end stays  unresponsive,  trafgen
122              assumes that the machine has crashed and will print out the con‐
123              tent of the last packet as a trafgen  packet  configuration  and
124              the  random seed that has been used in order to reproduce a pos‐
125              sible bug. This might be useful when testing proprietary  embed‐
126              ded devices. It is recommended to have a direct link between the
127              host running trafgen and the host being attacked by trafgen.
128
129       -n <0|uint>, --num <0|uint>
130              Process a number of packets and then  exit.  If  the  number  of
131              packets  is 0, then this is equivalent to infinite packets resp.
132              processing until interrupted.  Otherwise, a number given  as  an
133              unsigned integer will limit processing.
134
135       -r, --rand
136              Randomize  the  packet  selection  of the configuration file. By
137              default, if more than one packet is defined in a packet configu‐
138              ration,  packets are scheduled for transmission in a round robin
139              fashion. With this option, they are selected randomly instread.
140
141       -P <uint>, --cpus <uint>
142              Specify the number of processes trafgen shall  fork(2)  off.  By
143              default  trafgen  will  start as many processes as CPUs that are
144              online and pin them to each, respectively. Allowed value must be
145              within interval [1,CPUs].
146
147       -t <time>, --gap <time>
148              Specify  a static inter-packet timegap in seconds, milliseconds,
149              microseconds, or nanoseconds: ''<num>s/ms/us/ns''. If no postfix
150              is  given default to microseconds. If this option is given, then
151              instead of  packet(7)'s  TX_RING  interface,  trafgen  will  use
152              sendto(2)  I/O  for network packets, even if the <time> argument
153              is 0. This option is useful for a couple of reasons:
154
155                1) comparison between sendto(2) and TX_RING performance,
156                2) low-traffic packet probing for a given interval,
157                3) ping-like debugging with specific payload patterns.
158
159              Furthermore, the TX_RING interface does  not  cope  with  inter‐
160              packet gaps.
161
162       -b <rate>, --rate <rate>
163              Specify          the          packet          send          rate
164              <num>pps/B/kB/MB/GB/kbit/Mbit/Gbit/KiB/MiB/GiB units.  Like with
165              the -t/--gap option, the packets are sent in slow mode.
166
167       -S <size>, --ring-size <size>
168              Manually    define   the   TX_RING   resp.   TX_RING   size   in
169              ''<num>KiB/MiB/GiB''. By default the size  is  being  determined
170              based on the network connectivity rate.
171
172       -E <uint>, --seed <uint>
173              Manually  set the seed for pseudo random number generator (PRNG)
174              in trafgen. By default, a random seed from /dev/urandom is  used
175              to  feed  glibc's PRNG. If that fails, it falls back to the unix
176              timestamp. It can be useful to set the seed manually in order to
177              be able to reproduce a trafgen session, e.g. after fuzz testing.
178
179       -u <uid>, --user <uid> resp. -g <gid>, --group <gid>
180              After  ring setup, drop privileges to a non-root user/group com‐
181              bination.
182
183       -H, --prio-high
184              Set this process as a high priority process in order to  achieve
185              a higher scheduling rate resp. CPU time. This is however not the
186              default setting, since it could lead to starvation of other pro‐
187              cesses, for example low priority kernel threads.
188
189       -A, --no-sock-mem
190              Do  not  change  systems  default  socket  memory setting during
191              testrun.  Default is to boost socket buffer  memory  during  the
192              test to:
193
194                /proc/sys/net/core/rmem_default:4194304
195                /proc/sys/net/core/wmem_default:4194304
196                /proc/sys/net/core/rmem_max:104857600
197                /proc/sys/net/core/wmem_max:104857600
198
199       -Q, --notouch-irq
200              Do not reassign the NIC's IRQ CPU affinity settings.
201
202       -q, --qdisc-path
203              Since   Linux   3.14,   the  kernel  supports  a  socket  option
204              PACKET_QDISC_BYPASS, which  trafgen  enables  by  default.  This
205              options disables the qdisc bypass, and uses the normal send path
206              through the kernel's qdisc (traffic control) layer, which can be
207              usefully for testing the qdisc path.
208
209       -V, --verbose
210              Let  trafgen  be more talkative and let it print the parsed con‐
211              figuration and some ring buffer statistics.
212
213       -e, --example
214              Show a built-in packet configuration example. This  might  be  a
215              good  starting  point  for  an initial packet configuration sce‐
216              nario.
217
218       -C, --no-cpu-stats
219              Do not print CPU time statistics on exit.
220
221       -v, --version
222              Show version information and exit.
223
224       -h, --help
225              Show user help and exit.
226

SYNTAX

228       trafgen's packet configuration syntax is fairly simple. The very  basic
229       things one needs to know is that a configuration file is a simple plain
230       text file where packets are defined. It can contain one or  more  pack‐
231       ets.  Packets  are  enclosed by opening '{' and closing '}' braces, for
232       example:
233
234          { /* packet 1 content goes here ... */ }
235          { /* packet 2 content goes here ... */ }
236
237       Alternatively, packets can also be specified directly  on  the  command
238       line, using the same syntax as used in the configuration files.
239
240       When  trafgen  is  started  using multiple CPUs (default), then each of
241       those packets will  be  scheduled  for  transmission  on  all  CPUs  by
242       default.  However,  it is possible to tell trafgen to schedule a packet
243       only on a particular CPU:
244
245          cpu(1): { /* packet 1 content goes here ... */ }
246          cpu(2-3): { /* packet 2 content goes here ... */ }
247
248       Thus, in case we have a 4 core machine with CPU0-CPU3, packet 1 will be
249       scheduled  only  on CPU1, packet 2 on CPU2 and CPU3. When using trafgen
250       with --num option, then these constraints will still be valid  and  the
251       packet is fairly distributed among those CPUs.
252
253       Packet content is delimited either by a comma or whitespace, or both:
254
255          { 0xca, 0xfe, 0xba 0xbe }
256
257       Packet content can be of the following:
258
259          hex bytes:   0xca, xff
260          decimal:     42
261          binary:      0b11110000, b11110000
262          octal:       011
263          character:   'a'
264          string:      "hello world"
265          shellcode:   "\x31\xdb\x8d\x43\x17\x99\xcd\x80\x31\xc9"
266
267       Thus,  a  quite  useless packet configuration might look like this (one
268       can verify this when running this with trafgen in combination with -V):
269
270          { 0xca, 42, 0b11110000, 011, 'a', "hello world",
271            "\x31\xdb\x8d\x43\x17\x99\xcd\x80\x31\xc9" }
272
273       There are a couple of helper functions in trafgen's  language  to  make
274       life easier to write configurations:
275
276       i) Fill with garbage functions:
277
278          byte fill function:      fill(<content>, <times>): fill(0xca, 128)
279          compile-time random:     rnd(<times>): rnd(128), rnd()
280          runtime random numbers:  drnd(<times>): drnd(128), drnd()
281          compile-time counter:    seqinc(<start-val>, <increment>, <times>)
282                                   seqdec(<start-val>, <decrement>, <times>)
283          runtime counter (1byte): dinc(<min-val>, <max-val>, <increment>)
284                                   ddec(<min-val>, <max-val>, <decrement>)
285
286       ii) Checksum helper functions (packet offsets start with 0):
287
288          IP/ICMP checksum:        csumip/csumicmp(<off-from>, <off-to>)
289          UDP checksum:            csumudp(<off-iphdr>, <off-udpdr>)
290          TCP checksum:            csumtcp(<off-iphdr>, <off-tcphdr>)
291          UDP checksum (IPv6):     csumudp6(<off-ip6hdr>, <off-udpdr>)
292          TCP checksum (IPv6):     csumtcp6(<off-ip6hdr>, <off-tcphdr>)
293
294       iii) Multibyte functions, compile-time expression evaluation:
295
296          const8(<content>),   c8(<content>),   const16(<content>),  c16(<con‐
297       tent>),
298          const32(<content>),  c32(<content>),  const64(<content>),  c64(<con‐
299       tent>)
300
301          These  functions  write  their result in network byte order into the
302       packet configuration, e.g. const16(0xaa)  will  result  in  ''00  aa''.
303       Within   c*()  functions,  it  is  possible  to  do  some  arithmetics:
304       -,+,*,/,%,&,|,<<,>>,^  E.g.  const16((((1<<8)+0x32)|0b110)*2)  will  be
305       evaluated to ''02 6c''.
306
307       iv) Protocol header functions:
308           The  protocol header functions allow to fill protocol header fields
309           by using following generic syntax:
310
311               <proto>(<field>=<value>,<field2>=<value2>,...,<field3>,...)
312
313           If a field is not specified, then a  default  value  will  be  used
314           (usually  0).   Protocol fields might be set in any order. However,
315           the offset of the fields in the resulting packet  is  according  to
316           the respective protocol.
317
318           Each field might be set with a function which generates field value
319           at runtime by increment or randomize it. For  L3/L4  protocols  the
320           checksum  is  calculated  automatically  if  the  field was changed
321           dynamically by specified function.  The following  field  functions
322           are supported:
323
324               dinc  -  increment field value at runtime. By default increment
325               step is '1'.  min and max  parameters  are  used  to  increment
326               field  only  in  the specified range, by default original field
327               value is used. If the field length is greater than 4 then  last
328               4   bytes  are  incremented  only  (useful  for  MAC  and  IPv6
329               addresses):
330
331                   <field> = dinc() | dinc(min, max) | dinc(min, max, step)
332
333               drnd - randomize field value at runtime.  min and  max  parame‐
334               ters are used to randomize field only in the specified range:
335
336                   <field> = drnd() | drnd(min, max)
337
338               Example of using dynamic functions:
339
340               {
341                     eth(saddr=aa:bb:cc:dd:ee:ff, saddr=dinc()),
342                     ipv4(saddr=dinc()),
343                     udp(sport=dinc(1, 13, 2), dport=drnd(80, 100))
344               }
345
346
347
348           Fields  might  be further manipulated with a function at a specific
349           offset:
350
351               <field>[<index>] | <field>[<index>:<length>]
352
353                   <index> - relative field offset with range 0..<field.len> -
354                   1
355
356                   <length>  -  length/size  of  the  value which will be set;
357                   either 1, 2 or 4 bytes (default: 1)
358
359               The <index> starts from  the  field's  first  byte  in  network
360               order.
361
362               The  syntax  is  similar  to  the one used in pcap filters (man
363               pcap-filter) for matching header field at a specified offset.
364
365               Examples of using field offset (showing the effect in a  short‐
366               enet output from netsniff-ng):
367
368                   1) trafgen -o lo --cpus 1 -n 3 '{ eth(da=11:22:33:44:55:66,
369                   da[0]=dinc()), tcp() }'
370
371                       [ Eth MAC (00:00:00:00:00:00 => 11:22:33:44:55:66)
372
373                       [ Eth MAC (00:00:00:00:00:00 => 12:22:33:44:55:66)
374
375                       [ Eth MAC (00:00:00:00:00:00 => 13:22:33:44:55:66)
376
377                   2)  trafgen  -o  lo  --cpus  1  -n  3  '{  ipv4(da=1.2.3.4,
378                   da[0]=dinc()), tcp() }'
379
380                       [ IPv4 Addr (127.0.0.1 => 1.2.3.4)
381
382                       [ IPv4 Addr (127.0.0.1 => 2.2.3.4)
383
384                       [ IPv4 Addr (127.0.0.1 => 3.2.3.4)
385
386
387
388           All  required  lower  layer headers will be filled automatically if
389           they were not specified by the user. The headers will be filled  in
390           the order they were specified. Each header will be filled with some
391           mimimum required set of fields.
392
393           Supported protocol headers:
394
395           Ethernet : eth(da=<mac>, sa=<mac>, type=<number>)
396
397               da|daddr - Destination MAC address (default: 00:00:00:00:00:00)
398
399               sa|saddr - Source MAC address (default: device MAC address)
400
401               etype|type|prot|proto - Ethernet type (default: 0)
402
403
404           PAUSE (IEEE 802.3X) : pause(code=<number>, time=<number>)
405
406               code - MAC Control opcode (default: 0x0001)
407
408               time - Pause time (default: 0)
409
410               By default Ethernet header is added with a fields:
411
412                   Ethernet type - 0x8808
413
414                   Destination MAC address - 01:80:C2:00:00:01
415
416
417
418           PFC : pfc(pri|prio(<number>)=<number>, time(<number>)=<number>)
419
420               code - MAC Control opcode (default: 0x0101)
421
422               pri|prio - Priority enable vector (default: 0)
423
424               pri|prio(<number>) - Enable/disable (0 - disable, 1  -  enable)
425               pause for priority <number> (default: 0)
426
427               time(<number>) - Set pause time for priority <number> (default:
428               0)
429
430               By default Ethernet header is added with a fields:
431
432                   Ethernet type - 0x8808
433
434                   Destination MAC address - 01:80:C2:00:00:01
435
436           VLAN : vlan(tpid=<number>, id=<number>, dei=<number>, tci=<number>,
437           pcp=<number>, 1q, 1ad)
438
439               tpid|prot|proto  -  Tag  Protocol  Identifier  (TPID) (default:
440               0x8100)
441
442               tci - Tag Control Information (TCI) field (VLAN Id + PCP + DEI)
443               (default: 0)
444
445               dei|cfi  -  Drop  Eligible  Indicator (DEI), formerly Canonical
446               Format Indicator (CFI) (default: 0)
447
448               pcp - Priority code point (PCP) (default: 0)
449
450               id - VLAN Identifier (default: 0)
451
452               1q - Set 802.1q header (TPID: 0x8100)
453
454               1ad - Set 802.1ad header (TPID: 0x88a8)
455
456           By default, if the lower level header is Ethernet, its EtherType is
457           set to 0x8100 (802.1q).
458
459
460           MPLS   :   mpls(label=<number>,   tc|exp=<number>,   last=<number>,
461           ttl=<number>)
462
463               label|lbl - MPLS label value (default: 0)
464
465               tclass|tc|exp - Traffic Class for QoS field (default: 0)
466
467               last - Bottom of stack S-flag (default: 1 for most last label)
468
469               ttl - Time To Live (TTL) (default: 0)
470
471           By default, if the lower level header is Ethernet, its EtherType is
472           set  to 0x8847 (MPLS Unicast). S-flag is set automatically to 1 for
473           the last label and resets to 0 if the lower MPLS  label  was  added
474           after.
475
476
477           ARP  :  arp(htype=<number>,  ptype=<number>, op=<request|reply|num‐
478           ber>,  request,  reply,  smac=<mac>,  sip=<ip4_addr>,   tmac=<mac>,
479           tip=<ip4_addr>)
480
481               htype - ARP hardware type (default: 1 [Ethernet])
482
483               ptype - ARP protocol type (default: 0x0800 [IPv4])
484
485               op - ARP operation type (request/reply) (default: request)
486
487               req|request - ARP Request operation type
488
489               reply - ARP Reply operation type
490
491               smac|sha  -  Sender hardware (MAC) address (default: device MAC
492               address)
493
494               sip|spa - Sender protocol (IPv4) address (default: device  IPv4
495               address)
496
497               tmac|tha    -   Target   hardware   (MAC)   address   (default:
498               00:00:00:00:00:00)
499
500               tip|tpa - Target protocol (IPv4) address (default: device  IPv4
501               address)
502
503           By  default, the ARP operation field is set to request and the Eth‐
504           ernet destination MAC address  is  set  to  the  broadcast  address
505           (ff:ff:ff:ff:ff:ff).
506
507           IPv4    :    ip4|ipv4(ihl=<number>,   ver=<number>,   len=<number>,
508           csum=<number>, ttl=<number>, tos=<number>, dscp=<number>, ecn=<num‐
509           ber>,
510                           id=<number>, flags=<number>, frag=<number>, df, mf,
511                           da=<ip4_addr>, sa=<ip4_addr>, prot[o]=<number>)
512
513               ver|version - Version field (default: 4)
514
515               ihl - Header length in number of 32-bit words (default: 5)
516
517               tos - Type of Service (ToS) field (default: 0)
518
519               dscp - Differentiated  Services  Code  Point  (DSCP,  DiffServ)
520               field (default: 0)
521
522               ecn - Explicit Congestion Notification (ECN) field (default: 0)
523
524               len|length  - Total length of header and payload (calculated by
525               default)
526
527               id - IPv4 datagram identification (default: 0)
528
529               flags - IPv4 flags value (DF, MF) (default: 0)
530
531               df - Don't fragment (DF) flag (default: 0)
532
533               mf - More fragments (MF) flag (default: 0)
534
535               frag - Fragment  offset  field  in  number  of  8  byte  blocks
536               (default: 0)
537
538               ttl - Time to live (TTL) field (default: 0)
539
540               csum - Header checksum (calculated by default)
541
542               sa|saddr - Source IPv4 address (default: device IPv4 address)
543
544               da|daddr - Destination IPv4 address (default: 0.0.0.0)
545
546               prot|proto - IPv4 protocol number (default: 0)
547
548           By  default,  if  the lower level header is Ethernet, its EtherType
549           field is set to 0x0800 (IPv4). If the lower level header  is  IPv4,
550           its protocol field is set to 0x4 (IP-in-IP).
551
552           IPv6   :   ip6|ipv6(ver=<number>,   class=<number>,   flow=<number>
553           len=<number>, nexthdr=<number>, hoplimit=<number>,
554                           da=<ip6_addr>, sa=<ip6_addr>)
555
556               ver|version - Version field (default: 6)
557
558               tc|tclass - Traffic class (default: 0)
559
560               fl|flow - Flow label (default: 0)
561
562               len|length - Payload length (calculated by default)
563
564               nh|nexthdr - Type of next header, i.e. transport layer protocol
565               number (default: 0)
566
567               hl|hoplimit|ttl - Hop limit, i.e. time to live (default: 0)
568
569               sa|saddr - Source IPv6 address (default: device IPv6 address)
570
571               da|daddr - Destination IPv6 address (default: 0:0:0:0:0:0:0:0)
572
573           By  default,  if  the lower level header is Ethernet, its EtherType
574           field is set to 0x86DD (IPv6).
575
576           ICMPv4 :  icmp4|icmpv4(type=<number>,  code=<number>,  echorequest,
577           echoreply,  csum=<number>, mtu=<number>, seq=<number>, id=<number>,
578           addr=<ip4_addr>)
579
580               type - Message type (default: 0 - Echo reply)
581
582               code - Message code (default: 0)
583
584               echorequest - ICMPv4 echo (ping) request (type: 8, code: 0)
585
586               echoreply - ICMPv4 echo (ping) reply (type: 0, code: 0)
587
588               csum - Checksum of ICMPv4 header  and  payload  (calculated  by
589               default)
590
591               mtu  - Next-hop MTU field used in 'Datagram is too big' message
592               type (default; 0)
593
594               seq - Sequence number used in Echo/Timestamp/Address mask  mes‐
595               sages (default: 0)
596
597               id  -  Identifier  used in Echo/Timestamp/Address mask messages
598               (default: 0)
599
600               addr  -  IPv4  address  used  in  Redirect  messages  (default:
601               0.0.0.0)
602
603           Example ICMP echo request (ping):
604
605               { icmpv4(echorequest, seq=1, id=1326) }
606
607           ICMPv6   :   icmp6|icmpv6(type=<number>,   echorequest,  echoreply,
608           code=<number>, csum=<number>)
609
610               type - Message type (default: 0)
611
612               code - Code (default: 0)
613
614               echorequest - ICMPv6 echo (ping) request
615
616               echoreply - ICMPv6 echo (ping) reply
617
618               csum - Message checksum (calculated by default)
619
620           By default, if the lower level header  is  IPv6,  its  Next  Header
621           field is set to 58 (ICMPv6).
622
623           UDP : udp(sp=<number>, dp=<number>, len=<number>, csum=<number>)
624
625               sp|sport - Source port (default: 0)
626
627               dp|dport - Destination port (default: 0)
628
629               len|length  -  Length  of  UDP  header  and data (calculated by
630               default)
631
632               csum - Checksum field over IPv4 pseudo  header  (calculated  by
633               default)
634
635           By  default,  if the lower level header is IPv4, its protocol field
636           is set to 0x11 (UDP).
637
638           TCP : tcp(sp=<number>, dp=<number>, seq=<number>, aseq|ackseq=<num‐
639           ber>,  doff|hlen=<number>,  cwr,  ece|ecn, urg, ack, psh, rst, syn,
640           fin, win|window=<number>, csum=<number>, urgptr=<number>)
641
642               sp|sport - Source port (default: 0)
643
644               dp|dport - Destination port (default: 0)
645
646               seq - Sequence number (default: 0)
647
648               aseq|ackseq - Acknowledgement number (default: 0)
649
650               doff|hlen - Header size (data offset) in number of 32-bit words
651               (default: 5)
652
653               cwr - Congestion Window Reduced (CWR) flag (default: 0)
654
655               ece|ecn - ECN-Echo (ECE) flag (default: 0)
656
657               urg - Urgent flag (default: 0)
658
659               ack - Acknowledgement flag (default: 0)
660
661               psh - Push flag (default: 0)
662
663               rst - Reset flag (default: 0)
664
665               syn - Synchronize flag (default: 0)
666
667               fin - Finish flag (default: 0)
668
669               win|window - Receive window size (default: 0)
670
671               csum  -  Checksum  field over IPv4 pseudo header (calculated by
672               default)
673
674               urgptr - Urgent pointer (default: 0)
675
676           By default, if the lower level header is IPv4, its  protocol  field
677           is set to 0x6 (TCP).
678
679           Simple example of a UDP Echo packet:
680
681               {
682                 eth(da=11:22:33:44:55:66),
683                 ipv4(daddr=1.2.3.4)
684                 udp(dp=7),
685                 "Hello world"
686               }
687
688       Furthermore,  there  are two types of comments in trafgen configuration
689       files:
690
691         1. Multi-line C-style comments:        /* put comment here */
692         2. Single-line Shell-style comments:   #  put comment here
693
694       Next to all of this, a configuration can be passed through the  C  pre‐
695       processor before the trafgen compiler gets to see it with option --cpp.
696       To give you a taste of a more advanced  example,  run  ''trafgen  -e'',
697       fields are commented:
698
699          /* Note: dynamic elements make trafgen slower! */
700          #include <stddef.h>
701
702          {
703            /* MAC Destination */
704            fill(0xff, ETH_ALEN),
705            /* MAC Source */
706            0x00, 0x02, 0xb3, drnd(3),
707            /* IPv4 Protocol */
708            c16(ETH_P_IP),
709            /* IPv4 Version, IHL, TOS */
710            0b01000101, 0,
711            /* IPv4 Total Len */
712            c16(59),
713            /* IPv4 Ident */
714            drnd(2),
715            /* IPv4 Flags, Frag Off */
716            0b01000000, 0,
717            /* IPv4 TTL */
718            64,
719            /* Proto TCP */
720            0x06,
721            /* IPv4 Checksum (IP header from, to) */
722            csumip(14, 33),
723            /* Source IP */
724            drnd(4),
725            /* Dest IP */
726            drnd(4),
727            /* TCP Source Port */
728            drnd(2),
729            /* TCP Dest Port */
730            c16(80),
731            /* TCP Sequence Number */
732            drnd(4),
733            /* TCP Ackn. Number */
734            c32(0),
735            /* TCP Header length + TCP SYN/ECN Flag */
736            c16((8 << 12) | TCP_FLAG_SYN | TCP_FLAG_ECE)
737            /* Window Size */
738            c16(16),
739            /* TCP Checksum (offset IP, offset TCP) */
740            csumtcp(14, 34),
741            /* TCP Options */
742            0x00, 0x00, 0x01, 0x01, 0x08, 0x0a, 0x06,
743            0x91, 0x68, 0x7d, 0x06, 0x91, 0x68, 0x6f,
744            /* Data blob */
745            "gotcha!",
746          }
747
748       Another real-world example by Jesper Dangaard Brouer [1]:
749
750          {
751            # --- ethernet header ---
752            0x00, 0x1b, 0x21, 0x3c, 0x9d, 0xf8,  # mac destination
753            0x90, 0xe2, 0xba, 0x0a, 0x56, 0xb4,  # mac source
754            const16(0x0800), # protocol
755            # --- ip header ---
756            # ipv4 version (4-bit) + ihl (4-bit), tos
757            0b01000101, 0,
758            # ipv4 total len
759            const16(40),
760            # id (note: runtime dynamic random)
761            drnd(2),
762            # ipv4 3-bit flags + 13-bit fragment offset
763            # 001 = more fragments
764            0b00100000, 0,
765            64, # ttl
766            17, # proto udp
767            # dynamic ip checksum (note: offsets are zero indexed)
768            csumip(14, 33),
769            192, 168, 51, 1, # source ip
770            192, 168, 51, 2, # dest ip
771            # --- udp header ---
772            # as this is a fragment the below stuff does not matter too much
773            const16(48054), # src port
774            const16(43514), # dst port
775            const16(20),    # udp length
776            # udp checksum can be dyn calc via csumudp(offset ip, offset tcp)
777            # which is csumudp(14, 34), but for udp its allowed to be zero
778            const16(0),
779            # payload
780            'A',  fill(0x41, 11),
781          }
782
783          [1] https://marc.info/?l=linux-netdev&m=135903630614184
784
785       The above example rewritten using the header generation functions:
786
787          {
788            # --- ethernet header ---
789            eth(da=00:1b:21:3c:9d:f8, da=90:e2:ba:0a:56:b4)
790            # --- ip header ---
791            ipv4(id=drnd(), mf, ttl=64, sa=192.168.51.1, da=192.168.51.2)
792            # --- udp header ---
793            udp(sport=48054, dport=43514, csum=0)
794            # payload
795            'A',  fill(0x41, 11),
796          }
797

USAGE EXAMPLE

799       trafgen --dev eth0 --conf trafgen.cfg
800              This  is  the  most simple and, probably, the most common use of
801              trafgen. It will generate traffic defined in  the  configuration
802              file ''trafgen.cfg'' and transmit this via the ''eth0'' network‐
803              ing device. All online CPUs are used.
804
805       trafgen -e | trafgen -i - -o lo --cpp -n 1
806              This is an example where we send  one  packet  of  the  built-in
807              example  through  the loopback device. The example configuration
808              is passed via stdin and also through the C  preprocessor  before
809              trafgen's packet compiler will see it.
810
811       trafgen --dev eth0 --conf fuzzing.cfg --smoke-test 10.0.0.1
812              Read  the  ''fuzzing.cfg'' packet configuration file (which con‐
813              tains drnd() calls) and send out the generated  packets  to  the
814              ''eth0'' device. After each sent packet, ping probe the attacked
815              host with address 10.0.0.1 to check if it's  still  alive.  This
816              also  means,  that  we  utilize  1  CPU only, and do not use the
817              TX_RING, but sendto(2) packet I/O due to ''slow mode''.
818
819       trafgen --dev wlan0 --rfraw --conf beacon-test.txf -V --cpus 2
820              As an output device ''wlan0'' is used and  put  into  monitoring
821              mode,  thus  we  are going to transmit raw 802.11 frames through
822              the air. Use the  ''beacon-test.txf''  configuration  file,  set
823              trafgen into verbose mode and use only 2 CPUs.
824
825       trafgen --dev em1 --conf frag_dos.cfg --rand --gap 1000us
826              Use  trafgen in sendto(2) mode instead of TX_RING mode and sleep
827              after each sent packet a static  timegap  for  1000us.  Generate
828              packets  from  ''frag_dos.cfg''  and select next packets to send
829              randomly instead of a round-robin fashion.   The  output  device
830              for packets is ''em1''.
831
832       trafgen --dev eth0 --conf icmp.cfg --rand --num 1400000 -k1000
833              Send  only  1400000 packets using the ''icmp.cfg'' configuration
834              file and then exit trafgen. Select packets  randomly  from  that
835              file  for  transmission  and  send  them out via ''eth0''. Also,
836              trigger the kernel every 1000us for  batching  the  ring  frames
837              from user space (default is 10us).
838
839       trafgen --dev eth0 --conf tcp_syn.cfg -u `id -u bob` -g `id -g bob`
840              Send   out   packets   generated  from  the  configuration  file
841              ''tcp_syn.cfg'' via the ''eth0'' networking device.  After  set‐
842              ting  up the ring for transmission, drop credentials to the non-
843              root user/group bob/bob.
844
845       trafgen  --dev  eth0  '{  fill(0xff,  6),  0x00,  0x02,  0xb3,  rnd(3),
846       c16(0x0800), fill(0xca, 64) }' -n 1
847              Send  out  1  invaid  IPv4 packet built from command line to all
848              hosts.
849

NOTE

851       trafgen can saturate a  Gigabit  Ethernet  link  without  problems.  As
852       always,  of  course,  this depends on your hardware as well. Not every‐
853       where where it says Gigabit Ethernet on the box, will you reach  almost
854       physical line rate!  Please also read the netsniff-ng(8) man page, sec‐
855       tion NOTE for further  details  about  tuning  your  system  e.g.  with
856       tuned(8).
857
858       If you intend to use trafgen on a 10-Gbit/s Ethernet NIC, make sure you
859       are using a multiqueue tc(8) discipline, and make sure that the packets
860       you generate with trafgen will have a good distribution among tx_hashes
861       so that you'll actually make use of multiqueues.
862
863       For introducing bit errors, delays  with  random  variation  and  more,
864       there is no built-in option in trafgen. Rather, one should reuse exist‐
865       ing methods for that which integrate nicely with trafgen, such as tc(8)
866       with its different disciplines, i.e. netem.
867
868       For  more complex packet configurations, it is recommended to use high-
869       level scripting for generating trafgen packet configurations in a  more
870       automated way, i.e. also to create different traffic distributions that
871       are common for industrial benchmarking:
872
873           Traffic model              Distribution
874
875           IMIX                       64:7,  570:4,  1518:1
876           Tolly                      64:55,  78:5,   576:17, 1518:23
877           Cisco                      64:7,  594:4,  1518:1
878           RPR Trimodal               64:60, 512:20, 1518:20
879           RPR Quadrimodal            64:50, 512:15, 1518:15, 9218:20
880
881       The low-level nature of trafgen makes trafgen rather protocol  indepen‐
882       dent  and  therefore  useful  in  many scenarios when stress testing is
883       needed, for instance. However, if a traffic generator with higher level
884       packet  descriptions  is  desired, netsniff-ng's mausezahn(8) can be of
885       good use as well.
886
887       For smoke/fuzz testing with trafgen, it is recommended to have a direct
888       link  between the host you want to analyze (''victim'' machine) and the
889       host you run trafgen on (''attacker'' machine). If the ICMP reply  from
890       the  victim  fails, we assume that probably its kernel crashed, thus we
891       print the last sent packet together with the seed and quit probing.  It
892       might  be  very  unlikely  to find such a ping-of-death on modern Linux
893       systems. However, there might be a good chance to find it on some  pro‐
894       prietary  (e.g. embedded) systems or buggy driver firmwares that are in
895       the wild. Also, fuzz testing can be  done  on  raw  802.11  frames,  of
896       course.  In case you find a ping-of-death, please mention that you were
897       using trafgen in your commit message of the fix!
898

BUGS

900       For old trafgen versions only, there could  occur  kernel  crashes:  we
901       have  fixed  this  bug  in the mainline and stable kernels under commit
902       7f5c3e3a8 (''af_packet: remove BUG statement in tpacket_destruct_skb'')
903       and also in trafgen.
904
905       Probably the best is if you upgrade trafgen to the latest version.
906
908       trafgen is licensed under the GNU GPL version 2.0.
909

HISTORY

911       trafgen  was  originally  written for the netsniff-ng toolkit by Daniel
912       Borkmann. It is currently maintained by Tobias  Klauser  <tklauser@dis‐
913       tanz.ch> and Daniel Borkmann <dborkma@tik.ee.ethz.ch>.
914

SEE ALSO

916       netsniff-ng(8),  mausezahn(8), ifpps(8), bpfc(8), flowtop(8), astracer‐
917       oute(8), curvetun(8)
918

AUTHOR

920       Manpage was written by Daniel Borkmann.
921

COLOPHON

923       This page is part of the Linux netsniff-ng toolkit project. A  descrip‐
924       tion of the project, and information about reporting bugs, can be found
925       at http://netsniff-ng.org/.
926
927
928
929Linux                            03 March 2013                      TRAFGEN(8)
Impressum