1TRAFGEN(8) netsniff-ng toolkit TRAFGEN(8)
2
6 trafgen - a fast, multithreaded network packet generator
7
9 trafgen [options] [packet]
10
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 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 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 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 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 then be further tweaked for a given sce‐
70 nario.
71
73 -i <cfg|pcap|->, -c <cfg|->, --in <cfg|pcap|->, --conf <cfg|->
74 Defines the input configuration file that can either be passed as a
75 normal plain text file or via stdin (''-''). Note that currently, if a
76 configuration is passed through stdin, only 1 CPU will be used. It is
77 also possible to specify PCAP file with .pcap extension via -i,--in
78 option, by default packets will be sent at rate considering timestamp
79 from PCAP file which might be reset via -b/-t options.
80 -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 others
84 or a *.pcap or *.cfg file. Pcap and configuration files are identified
85 by extension.
86 -p, --cpp
88 Pass the packet configuration to the C preprocessor before reading it
89 into trafgen. This allows #define and #include directives (e.g. to
90 include definitions from system headers) to be used in the trafgen con‐
91 figuration file.
92 -D <name>=<definition>, --define <name>=<definition>
94 Add macro definition for the C preprocessor to use it within trafgen
95 file. This option is used in combination with the -p,--cpp option.
96 -J, --jumbo-support
98 By default trafgen's ring buffer frames are of a fixed size of 2048
99 bytes. This means that if you're expecting jumbo frames or even super
100 jumbo frames to pass your line, then you will need to enable support
101 for that with the help of this option. However, this has the disadvan‐
102 tage of a performance regression and a bigger memory footprint for the
103 ring buffer.
104 -R, --rfraw
106 In case the output networking device is a wireless device, it is possi‐
107 ble with trafgen to turn this into monitor mode and create a mon<X>
108 device that trafgen will be transmitting on instead of wlan<X>, for
109 instance. This enables trafgen to inject raw 802.11 frames. In case if
110 the output is a pcap file the link type is set to 127 (ieee80211 radio
111 tap).
112 -s <ipv4>, --smoke-test <ipv4>
114 In case this option is enabled, trafgen will perform a smoke test. In
115 other words, it will probe the remote end, specified by an <ipv4>
116 address, that is being ''attacked'' with trafgen network traffic, if it
117 is still alive and responsive. That means, after each transmitted
118 packet that has been configured, trafgen sends out ICMP echo requests
119 and waits for an answer before it continues. In case the remote end
120 stays unresponsive, trafgen assumes that the machine has crashed and
121 will print out the content of the last packet as a trafgen packet con‐
122 figuration and the random seed that has been used in order to reproduce
123 a possible bug. This might be useful when testing proprietary embedded
124 devices. It is recommended to have a direct link between the host run‐
125 ning trafgen and the host being attacked by trafgen.
126 -n <0|uint>, --num <0|uint>
128 Process a number of packets and then exit. If the number of packets is
129 0, then this is equivalent to infinite packets resp. processing until
130 interrupted. Otherwise, a number given as an unsigned integer will
131 limit processing.
132 -r, --rand
134 Randomize the packet selection of the configuration file. By default,
135 if more than one packet is defined in a packet configuration, packets
136 are scheduled for transmission in a round robin fashion. With this
137 option, they are selected randomly instread.
138 -P <uint>, --cpus <uint>
140 Specify the number of processes trafgen shall fork(2) off. By default
141 trafgen will start as many processes as CPUs that are online and pin
142 them to each, respectively. Allowed value must be within interval
143 [1,CPUs].
144 -t <time>, --gap <time>
146 Specify a static inter-packet timegap in seconds, milliseconds,
147 microseconds, or nanoseconds: ''<num>s/ms/us/ns''. If no postfix is
148 given default to microseconds. If this option is given, then instead of
149 packet(7)'s TX_RING interface, trafgen will use sendto(2) I/O for net‐
150 work packets, even if the <time> argument is 0. This option is useful
151 for a couple of reasons: i) comparison between sendto(2) and TX_RING
152 performance, ii) low-traffic packet probing for a given interval, iii)
153 ping-like debugging with specific payload patterns. Furthermore, the
154 TX_RING interface does not cope with interpacket gaps.
155 -b <rate>, --rate <rate>
157 Specify the packet send rate
158 <num>pps/B/kB/MB/GB/kbit/Mbit/Gbit/KiB/MiB/GiB units. Like with the
159 -t,--gap option, the packets are sent in slow mode.
160 -S <size>, --ring-size <size>
162 Manually define the TX_RING resp. TX_RING size in ''<num>KiB/MiB/GiB''.
163 On default the size is being determined based on the network connectiv‐
164 ity rate.
165 -E <uint>, --seed <uint>
167 Manually set the seed for pseudo random number generator (PRNG) in
168 trafgen. By default, a random seed from /dev/urandom is used to feed
169 glibc's PRNG. If that fails, it falls back to the unix timestamp. It
170 can be useful to set the seed manually in order to be able to reproduce
171 a trafgen session, e.g. after fuzz testing.
172 -u <uid>, --user <uid> resp. -g <gid>, --group <gid>
174 After ring setup, drop privileges to a non-root user/group combination.
175 -H, --prio-high
177 Set this process as a high priority process in order to achieve a
178 higher scheduling rate resp. CPU time. This is however not the default
179 setting, since it could lead to starvation of other processes, for
180 example low priority kernel threads.
181 -A, --no-sock-mem
183 Do not change systems default socket memory setting during testrun.
184 Default is to boost socket buffer memory during the test to:
185 /proc/sys/net/core/rmem_default:4194304
187 /proc/sys/net/core/wmem_default:4194304
188 /proc/sys/net/core/rmem_max:104857600
189 /proc/sys/net/core/wmem_max:104857600
190 -Q, --notouch-irq
192 Do not reassign the NIC's IRQ CPU affinity settings.
193 -q, --qdisc-path
195 Since Linux 3.14, the kernel supports a socket option
196 PACKET_QDISC_BYPASS, which trafgen enables by default. This options
197 disables the qdisc bypass, and uses the normal send path through the
198 kernel's qdisc (traffic control) layer, which can be usefully for test‐
199 ing the qdisc path.
200 -V, --verbose
202 Let trafgen be more talkative and let it print the parsed configuration
203 and some ring buffer statistics.
204 -e, --example
206 Show a built-in packet configuration example. This might be a good
207 starting point for an initial packet configuration scenario.
208 -C, --no-cpu-stats
210 Do not print CPU time statistics on exit.
211 -v, --version
213 Show version information and exit.
214 -h, --help
216 Show user help and exit.
217
219 trafgen's packet configuration syntax is fairly simple. The very basic
220 things one needs to know is that a configuration file is a simple plain
221 text file where packets are defined. It can contain one or more pack‐
222 ets. Packets are enclosed by opening '{' and closing '}' braces, for
223 example:
224 { /* packet 1 content goes here ... */ }
226 { /* packet 2 content goes here ... */ }
227 Alternatively, packets can also be specified directly on the command
229 line, using the same syntax as used in the configuration files.
230 When trafgen is started using multiple CPUs (default), then each of
232 those packets will be scheduled for transmission on all CPUs by
233 default. However, it is possible to tell trafgen to schedule a packet
234 only on a particular CPU:
235 cpu(1): { /* packet 1 content goes here ... */ }
237 cpu(2-3): { /* packet 2 content goes here ... */ }
238 Thus, in case we have a 4 core machine with CPU0-CPU3, packet 1 will be
240 scheduled only on CPU1, packet 2 on CPU2 and CPU3. When using trafgen
241 with --num option, then these constraints will still be valid and the
242 packet is fairly distributed among those CPUs.
243 Packet content is delimited either by a comma or whitespace, or both:
245 { 0xca, 0xfe, 0xba 0xbe }
247 Packet content can be of the following:
249 hex bytes: 0xca, xff
251 decimal: 42
252 binary: 0b11110000, b11110000
253 octal: 011
254 character: 'a'
255 string: "hello world"
256 shellcode: "\x31\xdb\x8d\x43\x17\x99\xcd\x80\x31\xc9"
257 Thus, a quite useless packet configuration might look like this (one
259 can verify this when running this with trafgen in combination with -V):
260 { 0xca, 42, 0b11110000, 011, 'a', "hello world",
262 "\x31\xdb\x8d\x43\x17\x99\xcd\x80\x31\xc9" }
263 There are a couple of helper functions in trafgen's language to make
265 life easier to write configurations:
266 i) Fill with garbage functions:
268 byte fill function: fill(<content>, <times>): fill(0xca, 128)
270 compile-time random: rnd(<times>): rnd(128), rnd()
271 runtime random numbers: drnd(<times>): drnd(128), drnd()
272 compile-time counter: seqinc(<start-val>, <increment>, <times>)
273 seqdec(<start-val>, <decrement>, <times>)
274 runtime counter (1byte): dinc(<min-val>, <max-val>, <increment>)
275 ddec(<min-val>, <max-val>, <decrement>)
276 ii) Checksum helper functions (packet offsets start with 0):
278 IP/ICMP checksum: csumip/csumicmp(<off-from>, <off-to>)
280 UDP checksum: csumudp(<off-iphdr>, <off-udpdr>)
281 TCP checksum: csumtcp(<off-iphdr>, <off-tcphdr>)
282 UDP checksum (IPv6): csumudp6(<off-ip6hdr>, <off-udpdr>)
283 TCP checksum (IPv6): csumtcp6(<off-ip6hdr>, <off-tcphdr>)
284 iii) Multibyte functions, compile-time expression evaluation:
286 const8(<content>), c8(<content>), const16(<content>), c16(<con‐
288 tent>),
289 const32(<content>), c32(<content>), const64(<content>), c64(<con‐
290 tent>)
291 These functions write their result in network byte order into the
293 packet configuration, e.g. const16(0xaa) will result in ''00 aa''.
294 Within c*() functions, it is possible to do some arithmetics:
295 -,+,*,/,%,&,|,<<,>>,^ E.g. const16((((1<<8)+0x32)|0b110)*2) will be
296 evaluated to ''02 6c''.
297 iv) Protocol header functions:
299 The protocol header functions allow to fill protocol header fields
300 by using following generic syntax:
301 <proto>(<field>=<value>,<field2>=<value2>,...,<field3>,...)
303 If a field is not specified, then a default value will be used
305 (usually 0). Protocol fields might be set in any order. However,
306 the offset of the fields in the resulting packet is according to
307 the respective protocol.
308 Each field might be set with a function which generates field value
310 at runtime by increment or randomize it. For L3/L4 protocols the
311 checksum is calculated automatically if the field was changed
312 dynamically by specified function. The following field functions
313 are supported:
314 dinc - increment field value at runtime. By default increment
316 step is '1'. min and max parameters are used to increment
317 field only in the specified range, by default original field
318 value is used. If the field length is greater than 4 then last
319 4 bytes are incremented only (useful for MAC and IPv6
320 addresses):
321 <field> = dinc() | dinc(min, max) | dinc(min, max, step)
323 drnd - randomize field value at runtime. min and max parame‐
325 ters are used to randomize field only in the specified range:
326 <field> = drnd() | drnd(min, max)
328 Example of using dynamic functions:
330 {
332 eth(saddr=aa:bb:cc:dd:ee:ff, saddr=dinc()),
333 ipv4(saddr=dinc()),
334 udp(sport=dinc(1, 13, 2), dport=drnd(80, 100))
335 }
336 Fields might be further manipulated with a function at a specific
340 offset:
341 <field>[<index>] | <field>[<index>:<length>]
343 <index> - relative field offset with range 0..<field.len> -
345 1
346 <length> - length/size of the value which will be set;
348 either 1, 2 or 4 bytes (default: 1)
349 The <index> starts from the field's first byte in network
351 order.
352 The syntax is similar to the one used in pcap filters (man
354 pcap-filter) for matching header field at a specified offset.
355 Examples of using field offset (showing the effect in a short‐
357 enet output from netsniff-ng):
358 1) trafgen -o lo --cpus 1 -n 3 '{ eth(da=11:22:33:44:55:66,
360 da[0]=dinc()), tcp() }'
361 [ Eth MAC (00:00:00:00:00:00 => 11:22:33:44:55:66)
363 [ Eth MAC (00:00:00:00:00:00 => 12:22:33:44:55:66)
365 [ Eth MAC (00:00:00:00:00:00 => 13:22:33:44:55:66)
367 2) trafgen -o lo --cpus 1 -n 3 '{ ipv4(da=1.2.3.4,
369 da[0]=dinc()), tcp() }'
370 [ IPv4 Addr (127.0.0.1 => 1.2.3.4)
372 [ IPv4 Addr (127.0.0.1 => 2.2.3.4)
374 [ IPv4 Addr (127.0.0.1 => 3.2.3.4)
376 All required lower layer headers will be filled automatically if
380 they were not specified by the user. The headers will be filled in
381 the order they were specified. Each header will be filled with some
382 mimimum required set of fields.
383 Supported protocol headers:
385 Ethernet : eth(da=<mac>, sa=<mac>, type=<number>)
387 da|daddr - Destination MAC address (default: 00:00:00:00:00:00)
389 sa|saddr - Source MAC address (default: device MAC address)
391 etype|type|prot|proto - Ethernet type (default: 0)
393 PAUSE (IEEE 802.3X) : pause(code=<number>, time=<number>)
396 code - MAC Control opcode (default: 0x0001)
398 time - Pause time (default: 0)
400 By default Ethernet header is added with a fields:
402 Ethernet type - 0x8808
404 Destination MAC address - 01:80:C2:00:00:01
406 PFC : pfc(pri|prio(<number>)=<number>, time(<number>)=<number>)
410 code - MAC Control opcode (default: 0x0101)
412 pri|prio - Priority enable vector (default: 0)
414 pri|prio(<number>) - Enable/disable (0 - disable, 1 - enable)
416 pause for priority <number> (default: 0)
417 time(<number>) - Set pause time for priority <number> (default:
419 0)
420 By default Ethernet header is added with a fields:
422 Ethernet type - 0x8808
424 Destination MAC address - 01:80:C2:00:00:01
426 VLAN : vlan(tpid=<number>, id=<number>, dei=<number>, tci=<number>,
428 pcp=<number>, 1q, 1ad)
429 tpid|prot|proto - Tag Protocol Identifier (TPID) (default:
431 0x8100)
432 tci - Tag Control Information (TCI) field (VLAN Id + PCP + DEI)
434 (default: 0)
435 dei|cfi - Drop Eligible Indicator (DEI), formerly Canonical
437 Format Indicator (CFI) (default: 0)
438 pcp - Priority code point (PCP) (default: 0)
440 id - VLAN Identifier (default: 0)
442 1q - Set 802.1q header (TPID: 0x8100)
444 1ad - Set 802.1ad header (TPID: 0x88a8)
446 By default, if the lower level header is Ethernet, its EtherType is
448 set to 0x8100 (802.1q).
449 MPLS : mpls(label=<number>, tc|exp=<number>, last=<number>,
452 ttl=<number>)
453 label|lbl - MPLS label value (default: 0)
455 tclass|tc|exp - Traffic Class for QoS field (default: 0)
457 last - Bottom of stack S-flag (default: 1 for most last label)
459 ttl - Time To Live (TTL) (default: 0)
461 By default, if the lower level header is Ethernet, its EtherType is
463 set to 0x8847 (MPLS Unicast). S-flag is set automatically to 1 for
464 the last label and resets to 0 if the lower MPLS label was added
465 after.
466 ARP : arp(htype=<number>, ptype=<number>, op=<request|reply|num‐
469 ber>, request, reply, smac=<mac>, sip=<ip4_addr>, tmac=<mac>,
470 tip=<ip4_addr>)
471 htype - ARP hardware type (default: 1 [Ethernet])
473 ptype - ARP protocol type (default: 0x0800 [IPv4])
475 op - ARP operation type (request/reply) (default: request)
477 req|request - ARP Request operation type
479 reply - ARP Reply operation type
481 smac|sha - Sender hardware (MAC) address (default: device MAC
483 address)
484 sip|spa - Sender protocol (IPv4) address (default: device IPv4
486 address)
487 tmac|tha - Target hardware (MAC) address (default:
489 00:00:00:00:00:00)
490 tip|tpa - Target protocol (IPv4) address (default: device IPv4
492 address)
493 By default, the ARP operation field is set to request and the Eth‐
495 ernet destination MAC address is set to the broadcast address
496 (ff:ff:ff:ff:ff:ff).
497 IPv4 : ip4|ipv4(ihl=<number>, ver=<number>, len=<number>,
499 csum=<number>, ttl=<number>, tos=<number>, dscp=<number>, ecn=<num‐
500 ber>,
501 id=<number>, flags=<number>, frag=<number>, df, mf,
502 da=<ip4_addr>, sa=<ip4_addr>, prot[o]=<number>)
503 ver|version - Version field (default: 4)
505 ihl - Header length in number of 32-bit words (default: 5)
507 tos - Type of Service (ToS) field (default: 0)
509 dscp - Differentiated Services Code Point (DSCP, DiffServ)
511 field (default: 0)
512 ecn - Explicit Congestion Notification (ECN) field (default: 0)
514 len|length - Total length of header and payload (calculated by
516 default)
517 id - IPv4 datagram identification (default: 0)
519 flags - IPv4 flags value (DF, MF) (default: 0)
521 df - Don't fragment (DF) flag (default: 0)
523 mf - More fragments (MF) flag (default: 0)
525 frag - Fragment offset field in number of 8 byte blocks
527 (default: 0)
528 ttl - Time to live (TTL) field (default: 0)
530 csum - Header checksum (calculated by default)
532 sa|saddr - Source IPv4 address (default: device IPv4 address)
534 da|daddr - Destination IPv4 address (default: 0.0.0.0)
536 prot|proto - IPv4 protocol number (default: 0)
538 By default, if the lower level header is Ethernet, its EtherType
540 field is set to 0x0800 (IPv4). If the lower level header is IPv4,
541 its protocol field is set to 0x4 (IP-in-IP).
542 IPv6 : ip6|ipv6(ver=<number>, class=<number>, flow=<number>
544 len=<number>, nexthdr=<number>, hoplimit=<number>,
545 da=<ip6_addr>, sa=<ip6_addr>)
546 ver|version - Version field (default: 6)
548 tc|tclass - Traffic class (default: 0)
550 fl|flow - Flow label (default: 0)
552 len|length - Payload length (calculated by default)
554 nh|nexthdr - Type of next header, i.e. transport layer protocol
556 number (default: 0)
557 hl|hoplimit|ttl - Hop limit, i.e. time to live (default: 0)
559 sa|saddr - Source IPv6 address (default: device IPv6 address)
561 da|daddr - Destination IPv6 address (default: 0:0:0:0:0:0:0:0)
563 By default, if the lower level header is Ethernet, its EtherType
565 field is set to 0x86DD (IPv6).
566 ICMPv4 : icmp4|icmpv4(type=<number>, code=<number>, echorequest,
568 echoreply, csum=<number>, mtu=<number>, seq=<number>, id=<number>,
569 addr=<ip4_addr>)
570 type - Message type (default: 0 - Echo reply)
572 code - Message code (default: 0)
574 echorequest - ICMPv4 echo (ping) request (type: 8, code: 0)
576 echoreply - ICMPv4 echo (ping) reply (type: 0, code: 0)
578 csum - Checksum of ICMPv4 header and payload (calculated by
580 default)
581 mtu - Next-hop MTU field used in 'Datagram is too big' message
583 type (default; 0)
584 seq - Sequence number used in Echo/Timestamp/Address mask mes‐
586 sages (default: 0)
587 id - Identifier used in Echo/Timestamp/Address mask messages
589 (default: 0)
590 addr - IPv4 address used in Redirect messages (default:
592 0.0.0.0)
593 Example ICMP echo request (ping):
595 { icmpv4(echorequest, seq=1, id=1326) }
597 ICMPv6 : icmp6|icmpv6(type=<number>, echorequest, echoreply,
599 code=<number>, csum=<number>)
600 type - Message type (default: 0)
602 code - Code (default: 0)
604 echorequest - ICMPv6 echo (ping) request
606 echoreply - ICMPv6 echo (ping) reply
608 csum - Message checksum (calculated by default)
610 By default, if the lower level header is IPv6, its Next Header
612 field is set to 58 (ICMPv6).
613 UDP : udp(sp=<number>, dp=<number>, len=<number>, csum=<number>)
615 sp|sport - Source port (default: 0)
617 dp|dport - Destination port (default: 0)
619 len|length - Length of UDP header and data (calculated by
621 default)
622 csum - Checksum field over IPv4 pseudo header (calculated by
624 default)
625 By default, if the lower level header is IPv4, its protocol field
627 is set to 0x11 (UDP).
628 TCP : tcp(sp=<number>, dp=<number>, seq=<number>, aseq|ackseq=<num‐
630 ber>, doff|hlen=<number>, cwr, ece|ecn, urg, ack, psh, rst, syn,
631 fin, win|window=<number>, csum=<number>, urgptr=<number>)
632 sp|sport - Source port (default: 0)
634 dp|dport - Destination port (default: 0)
636 seq - Sequence number (default: 0)
638 aseq|ackseq - Acknowledgement number (default: 0)
640 doff|hlen - Header size (data offset) in number of 32-bit words
642 (default: 5)
643 cwr - Congestion Window Reduced (CWR) flag (default: 0)
645 ece|ecn - ECN-Echo (ECE) flag (default: 0)
647 urg - Urgent flag (default: 0)
649 ack - Acknowledgement flag (default: 0)
651 psh - Push flag (default: 0)
653 rst - Reset flag (default: 0)
655 syn - Synchronize flag (default: 0)
657 fin - Finish flag (default: 0)
659 win|window - Receive window size (default: 0)
661 csum - Checksum field over IPv4 pseudo header (calculated by
663 default)
664 urgptr - Urgent pointer (default: 0)
666 By default, if the lower level header is IPv4, its protocol field
668 is set to 0x6 (TCP).
669 Simple example of a UDP Echo packet:
671 {
673 eth(da=11:22:33:44:55:66),
674 ipv4(daddr=1.2.3.4)
675 udp(dp=7),
676 "Hello world"
677 }
678 Furthermore, there are two types of comments in trafgen configuration
680 files:
681 1. Multi-line C-style comments: /* put comment here */
683 2. Single-line Shell-style comments: # put comment here
684 Next to all of this, a configuration can be passed through the C pre‐
686 processor before the trafgen compiler gets to see it with option --cpp.
687 To give you a taste of a more advanced example, run ''trafgen -e'',
688 fields are commented:
689 /* Note: dynamic elements make trafgen slower! */
691 #include <stddef.h>
692 {
694 /* MAC Destination */
695 fill(0xff, ETH_ALEN),
696 /* MAC Source */
697 0x00, 0x02, 0xb3, drnd(3),
698 /* IPv4 Protocol */
699 c16(ETH_P_IP),
700 /* IPv4 Version, IHL, TOS */
701 0b01000101, 0,
702 /* IPv4 Total Len */
703 c16(59),
704 /* IPv4 Ident */
705 drnd(2),
706 /* IPv4 Flags, Frag Off */
707 0b01000000, 0,
708 /* IPv4 TTL */
709 64,
710 /* Proto TCP */
711 0x06,
712 /* IPv4 Checksum (IP header from, to) */
713 csumip(14, 33),
714 /* Source IP */
715 drnd(4),
716 /* Dest IP */
717 drnd(4),
718 /* TCP Source Port */
719 drnd(2),
720 /* TCP Dest Port */
721 c16(80),
722 /* TCP Sequence Number */
723 drnd(4),
724 /* TCP Ackn. Number */
725 c32(0),
726 /* TCP Header length + TCP SYN/ECN Flag */
727 c16((8 << 12) | TCP_FLAG_SYN | TCP_FLAG_ECE)
728 /* Window Size */
729 c16(16),
730 /* TCP Checksum (offset IP, offset TCP) */
731 csumtcp(14, 34),
732 /* TCP Options */
733 0x00, 0x00, 0x01, 0x01, 0x08, 0x0a, 0x06,
734 0x91, 0x68, 0x7d, 0x06, 0x91, 0x68, 0x6f,
735 /* Data blob */
736 "gotcha!",
737 }
738 Another real-world example by Jesper Dangaard Brouer [1]:
740 {
742 # --- ethernet header ---
743 0x00, 0x1b, 0x21, 0x3c, 0x9d, 0xf8, # mac destination
744 0x90, 0xe2, 0xba, 0x0a, 0x56, 0xb4, # mac source
745 const16(0x0800), # protocol
746 # --- ip header ---
747 # ipv4 version (4-bit) + ihl (4-bit), tos
748 0b01000101, 0,
749 # ipv4 total len
750 const16(40),
751 # id (note: runtime dynamic random)
752 drnd(2),
753 # ipv4 3-bit flags + 13-bit fragment offset
754 # 001 = more fragments
755 0b00100000, 0,
756 64, # ttl
757 17, # proto udp
758 # dynamic ip checksum (note: offsets are zero indexed)
759 csumip(14, 33),
760 192, 168, 51, 1, # source ip
761 192, 168, 51, 2, # dest ip
762 # --- udp header ---
763 # as this is a fragment the below stuff does not matter too much
764 const16(48054), # src port
765 const16(43514), # dst port
766 const16(20), # udp length
767 # udp checksum can be dyn calc via csumudp(offset ip, offset tcp)
768 # which is csumudp(14, 34), but for udp its allowed to be zero
769 const16(0),
770 # payload
771 'A', fill(0x41, 11),
772 }
773 [1] https://marc.info/?l=linux-netdev&m=135903630614184
775 The above example rewritten using the header generation functions:
777 {
779 # --- ethernet header ---
780 eth(da=00:1b:21:3c:9d:f8, da=90:e2:ba:0a:56:b4)
781 # --- ip header ---
782 ipv4(id=drnd(), mf, ttl=64, sa=192.168.51.1, da=192.168.51.2)
783 # --- udp header ---
784 udp(sport=48054, dport=43514, csum=0)
785 # payload
786 'A', fill(0x41, 11),
787 }
788
790 trafgen --dev eth0 --conf trafgen.cfg
791 This is the most simple and, probably, the most common use of trafgen.
792 It will generate traffic defined in the configuration file ''traf‐
793 gen.cfg'' and transmit this via the ''eth0'' networking device. All
794 online CPUs are used.
795 trafgen -e | trafgen -i - -o lo --cpp -n 1
797 This is an example where we send one packet of the built-in example
798 through the loopback device. The example configuration is passed via
799 stdin and also through the C preprocessor before trafgen's packet com‐
800 piler will see it.
801 trafgen --dev eth0 --conf fuzzing.cfg --smoke-test 10.0.0.1
803 Read the ''fuzzing.cfg'' packet configuration file (which contains
804 drnd() calls) and send out the generated packets to the ''eth0''
805 device. After each sent packet, ping probe the attacked host with
806 address 10.0.0.1 to check if it's still alive. This also means, that we
807 utilize 1 CPU only, and do not use the TX_RING, but sendto(2) packet
808 I/O due to ''slow mode''.
809 trafgen --dev wlan0 --rfraw --conf beacon-test.txf -V --cpus 2
811 As an output device ''wlan0'' is used and put into monitoring mode,
812 thus we are going to transmit raw 802.11 frames through the air. Use
813 the
814 ''beacon-test.txf'' configuration file, set trafgen into verbose mode
815 and use only 2 CPUs.
816 trafgen --dev em1 --conf frag_dos.cfg --rand --gap 1000us
818 Use trafgen in sendto(2) mode instead of TX_RING mode and sleep after
819 each sent packet a static timegap for 1000us. Generate packets from
820 ''frag_dos.cfg'' and select next packets to send randomly instead of a
821 round-robin fashion. The output device for packets is ''em1''.
822 trafgen --dev eth0 --conf icmp.cfg --rand --num 1400000 -k1000
824 Send only 1400000 packets using the ''icmp.cfg'' configuration file and
825 then exit trafgen. Select packets randomly from that file for transmis‐
826 sion and send them out via ''eth0''. Also, trigger the kernel every
827 1000us for batching the ring frames from user space (default is 10us).
828 trafgen --dev eth0 --conf tcp_syn.cfg -u `id -u bob` -g `id -g bob`
830 Send out packets generated from the configuration file ''tcp_syn.cfg''
831 via the ''eth0'' networking device. After setting up the ring for
832 transmission, drop credentials to the non-root user/group bob/bob.
833 trafgen --dev eth0 '{ fill(0xff, 6), 0x00, 0x02, 0xb3, rnd(3), c16(0x0800),
835 fill(0xca, 64) }' -n 1
836 Send out 1 invaid IPv4 packet built from command line to all hosts.
837
839 trafgen can saturate a Gigabit Ethernet link without problems. As
840 always, of course, this depends on your hardware as well. Not every‐
841 where where it says Gigabit Ethernet on the box, will you reach almost
842 physical line rate! Please also read the netsniff-ng(8) man page, sec‐
843 tion NOTE for further details about tuning your system e.g. with
844 tuned(8).
845 If you intend to use trafgen on a 10-Gbit/s Ethernet NIC, make sure you
847 are using a multiqueue tc(8) discipline, and make sure that the packets
848 you generate with trafgen will have a good distribution among tx_hashes
849 so that you'll actually make use of multiqueues.
850 For introducing bit errors, delays with random variation and more,
852 there is no built-in option in trafgen. Rather, one should reuse exist‐
853 ing methods for that which integrate nicely with trafgen, such as tc(8)
854 with its different disciplines, i.e. netem.
855 For more complex packet configurations, it is recommended to use high-
857 level scripting for generating trafgen packet configurations in a more
858 automated way, i.e. also to create different traffic distributions that
859 are common for industrial benchmarking:
860 Traffic model Distribution
862 IMIX 64:7, 570:4, 1518:1
864 Tolly 64:55, 78:5, 576:17, 1518:23
865 Cisco 64:7, 594:4, 1518:1
866 RPR Trimodal 64:60, 512:20, 1518:20
867 RPR Quadrimodal 64:50, 512:15, 1518:15, 9218:20
868 The low-level nature of trafgen makes trafgen rather protocol indepen‐
870 dent and therefore useful in many scenarios when stress testing is
871 needed, for instance. However, if a traffic generator with higher level
872 packet descriptions is desired, netsniff-ng's mausezahn(8) can be of
873 good use as well.
874 For smoke/fuzz testing with trafgen, it is recommended to have a direct
876 link between the host you want to analyze (''victim'' machine) and the
877 host you run trafgen on (''attacker'' machine). If the ICMP reply from
878 the victim fails, we assume that probably its kernel crashed, thus we
879 print the last sent packet together with the seed and quit probing. It
880 might be very unlikely to find such a ping-of-death on modern Linux
881 systems. However, there might be a good chance to find it on some pro‐
882 prietary (e.g. embedded) systems or buggy driver firmwares that are in
883 the wild. Also, fuzz testing can be done on raw 802.11 frames, of
884 course. In case you find a ping-of-death, please mention that you were
885 using trafgen in your commit message of the fix!
886
888 For old trafgen versions only, there could occur kernel crashes: we
889 have fixed this bug in the mainline and stable kernels under commit
890 7f5c3e3a8 (''af_packet: remove BUG statement in tpacket_destruct_skb'')
891 and also in trafgen.
892 Probably the best is if you upgrade trafgen to the latest version.
894
896 trafgen is licensed under the GNU GPL version 2.0.
897
899 trafgen was originally written for the netsniff-ng toolkit by Daniel
900 Borkmann. It is currently maintained by Tobias Klauser <tklauser@dis‐
901 tanz.ch> and Daniel Borkmann <dborkma@tik.ee.ethz.ch>.
902
904 netsniff-ng(8), mausezahn(8), ifpps(8), bpfc(8), flowtop(8), astracer‐
905 oute(8), curvetun(8)
906
908 Manpage was written by Daniel Borkmann.
909
911 This page is part of the Linux netsniff-ng toolkit project. A descrip‐
912 tion of the project, and information about reporting bugs, can be found
913 at http://netsniff-ng.org/.
914Linux 03 March 2013 TRAFGEN(8)