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 be further tweaked for a given scenario.
70
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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 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 Furthermore, the TX_RING interface does not cope with inter‐
160 packet gaps.
161 -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 -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 -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 -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 -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 -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 /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 -Q, --notouch-irq
200 Do not reassign the NIC's IRQ CPU affinity settings.
201 -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 -V, --verbose
210 Let trafgen be more talkative and let it print the parsed con‐
211 figuration and some ring buffer statistics.
212 -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 -C, --no-cpu-stats
219 Do not print CPU time statistics on exit.
220 -v, --version
222 Show version information and exit.
223 -h, --help
225 Show user help and exit.
226
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 { /* packet 1 content goes here ... */ }
235 { /* packet 2 content goes here ... */ }
236 Alternatively, packets can also be specified directly on the command
238 line, using the same syntax as used in the configuration files.
239 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 cpu(1): { /* packet 1 content goes here ... */ }
246 cpu(2-3): { /* packet 2 content goes here ... */ }
247 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 Packet content is delimited either by a comma or whitespace, or both:
254 { 0xca, 0xfe, 0xba 0xbe }
256 Packet content can be of the following:
258 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 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 { 0xca, 42, 0b11110000, 011, 'a', "hello world",
271 "\x31\xdb\x8d\x43\x17\x99\xcd\x80\x31\xc9" }
272 There are a couple of helper functions in trafgen's language to make
274 life easier to write configurations:
275 i) Fill with garbage functions:
277 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 ii) Checksum helper functions (packet offsets start with 0):
287 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 iii) Multibyte functions, compile-time expression evaluation:
295 const8(<content>), c8(<content>), const16(<content>), c16(<con‐
297 tent>),
298 const32(<content>), c32(<content>), const64(<content>), c64(<con‐
299 tent>)
300 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 iv) Protocol header functions:
308 The protocol header functions allow to fill protocol header fields
309 by using following generic syntax:
310 <proto>(<field>=<value>,<field2>=<value2>,...,<field3>,...)
312 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 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 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 <field> = dinc() | dinc(min, max) | dinc(min, max, step)
332 drnd - randomize field value at runtime. min and max parame‐
334 ters are used to randomize field only in the specified range:
335 <field> = drnd() | drnd(min, max)
337 Example of using dynamic functions:
339 {
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 Fields might be further manipulated with a function at a specific
349 offset:
350 <field>[<index>] | <field>[<index>:<length>]
352 <index> - relative field offset with range 0..<field.len> -
354 1
355 <length> - length/size of the value which will be set;
357 either 1, 2 or 4 bytes (default: 1)
358 The <index> starts from the field's first byte in network
360 order.
361 The syntax is similar to the one used in pcap filters (man
363 pcap-filter) for matching header field at a specified offset.
364 Examples of using field offset (showing the effect in a short‐
366 enet output from netsniff-ng):
367 1) trafgen -o lo --cpus 1 -n 3 '{ eth(da=11:22:33:44:55:66,
369 da[0]=dinc()), tcp() }'
370 [ Eth MAC (00:00:00:00:00:00 => 11:22:33:44:55:66)
372 [ Eth MAC (00:00:00:00:00:00 => 12:22:33:44:55:66)
374 [ Eth MAC (00:00:00:00:00:00 => 13:22:33:44:55:66)
376 2) trafgen -o lo --cpus 1 -n 3 '{ ipv4(da=1.2.3.4,
378 da[0]=dinc()), tcp() }'
379 [ IPv4 Addr (127.0.0.1 => 1.2.3.4)
381 [ IPv4 Addr (127.0.0.1 => 2.2.3.4)
383 [ IPv4 Addr (127.0.0.1 => 3.2.3.4)
385 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 Supported protocol headers:
394 Ethernet : eth(da=<mac>, sa=<mac>, type=<number>)
396 da|daddr - Destination MAC address (default: 00:00:00:00:00:00)
398 sa|saddr - Source MAC address (default: device MAC address)
400 etype|type|prot|proto - Ethernet type (default: 0)
402 PAUSE (IEEE 802.3X) : pause(code=<number>, time=<number>)
405 code - MAC Control opcode (default: 0x0001)
407 time - Pause time (default: 0)
409 By default Ethernet header is added with a fields:
411 Ethernet type - 0x8808
413 Destination MAC address - 01:80:C2:00:00:01
415 PFC : pfc(pri|prio(<number>)=<number>, time(<number>)=<number>)
419 code - MAC Control opcode (default: 0x0101)
421 pri|prio - Priority enable vector (default: 0)
423 pri|prio(<number>) - Enable/disable (0 - disable, 1 - enable)
425 pause for priority <number> (default: 0)
426 time(<number>) - Set pause time for priority <number> (default:
428 0)
429 By default Ethernet header is added with a fields:
431 Ethernet type - 0x8808
433 Destination MAC address - 01:80:C2:00:00:01
435 VLAN : vlan(tpid=<number>, id=<number>, dei=<number>, tci=<number>,
437 pcp=<number>, 1q, 1ad)
438 tpid|prot|proto - Tag Protocol Identifier (TPID) (default:
440 0x8100)
441 tci - Tag Control Information (TCI) field (VLAN Id + PCP + DEI)
443 (default: 0)
444 dei|cfi - Drop Eligible Indicator (DEI), formerly Canonical
446 Format Indicator (CFI) (default: 0)
447 pcp - Priority code point (PCP) (default: 0)
449 id - VLAN Identifier (default: 0)
451 1q - Set 802.1q header (TPID: 0x8100)
453 1ad - Set 802.1ad header (TPID: 0x88a8)
455 By default, if the lower level header is Ethernet, its EtherType is
457 set to 0x8100 (802.1q).
458 MPLS : mpls(label=<number>, tc|exp=<number>, last=<number>,
461 ttl=<number>)
462 label|lbl - MPLS label value (default: 0)
464 tclass|tc|exp - Traffic Class for QoS field (default: 0)
466 last - Bottom of stack S-flag (default: 1 for most last label)
468 ttl - Time To Live (TTL) (default: 0)
470 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 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 htype - ARP hardware type (default: 1 [Ethernet])
482 ptype - ARP protocol type (default: 0x0800 [IPv4])
484 op - ARP operation type (request/reply) (default: request)
486 req|request - ARP Request operation type
488 reply - ARP Reply operation type
490 smac|sha - Sender hardware (MAC) address (default: device MAC
492 address)
493 sip|spa - Sender protocol (IPv4) address (default: device IPv4
495 address)
496 tmac|tha - Target hardware (MAC) address (default:
498 00:00:00:00:00:00)
499 tip|tpa - Target protocol (IPv4) address (default: device IPv4
501 address)
502 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 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 ver|version - Version field (default: 4)
514 ihl - Header length in number of 32-bit words (default: 5)
516 tos - Type of Service (ToS) field (default: 0)
518 dscp - Differentiated Services Code Point (DSCP, DiffServ)
520 field (default: 0)
521 ecn - Explicit Congestion Notification (ECN) field (default: 0)
523 len|length - Total length of header and payload (calculated by
525 default)
526 id - IPv4 datagram identification (default: 0)
528 flags - IPv4 flags value (DF, MF) (default: 0)
530 df - Don't fragment (DF) flag (default: 0)
532 mf - More fragments (MF) flag (default: 0)
534 frag - Fragment offset field in number of 8 byte blocks
536 (default: 0)
537 ttl - Time to live (TTL) field (default: 0)
539 csum - Header checksum (calculated by default)
541 sa|saddr - Source IPv4 address (default: device IPv4 address)
543 da|daddr - Destination IPv4 address (default: 0.0.0.0)
545 prot|proto - IPv4 protocol number (default: 0)
547 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 IPv6 : ip6|ipv6(ver=<number>, class=<number>, flow=<number>
553 len=<number>, nexthdr=<number>, hoplimit=<number>,
554 da=<ip6_addr>, sa=<ip6_addr>)
555 ver|version - Version field (default: 6)
557 tc|tclass - Traffic class (default: 0)
559 fl|flow - Flow label (default: 0)
561 len|length - Payload length (calculated by default)
563 nh|nexthdr - Type of next header, i.e. transport layer protocol
565 number (default: 0)
566 hl|hoplimit|ttl - Hop limit, i.e. time to live (default: 0)
568 sa|saddr - Source IPv6 address (default: device IPv6 address)
570 da|daddr - Destination IPv6 address (default: 0:0:0:0:0:0:0:0)
572 By default, if the lower level header is Ethernet, its EtherType
574 field is set to 0x86DD (IPv6).
575 ICMPv4 : icmp4|icmpv4(type=<number>, code=<number>, echorequest,
577 echoreply, csum=<number>, mtu=<number>, seq=<number>, id=<number>,
578 addr=<ip4_addr>)
579 type - Message type (default: 0 - Echo reply)
581 code - Message code (default: 0)
583 echorequest - ICMPv4 echo (ping) request (type: 8, code: 0)
585 echoreply - ICMPv4 echo (ping) reply (type: 0, code: 0)
587 csum - Checksum of ICMPv4 header and payload (calculated by
589 default)
590 mtu - Next-hop MTU field used in 'Datagram is too big' message
592 type (default; 0)
593 seq - Sequence number used in Echo/Timestamp/Address mask mes‐
595 sages (default: 0)
596 id - Identifier used in Echo/Timestamp/Address mask messages
598 (default: 0)
599 addr - IPv4 address used in Redirect messages (default:
601 0.0.0.0)
602 Example ICMP echo request (ping):
604 { icmpv4(echorequest, seq=1, id=1326) }
606 ICMPv6 : icmp6|icmpv6(type=<number>, echorequest, echoreply,
608 code=<number>, csum=<number>)
609 type - Message type (default: 0)
611 code - Code (default: 0)
613 echorequest - ICMPv6 echo (ping) request
615 echoreply - ICMPv6 echo (ping) reply
617 csum - Message checksum (calculated by default)
619 By default, if the lower level header is IPv6, its Next Header
621 field is set to 58 (ICMPv6).
622 UDP : udp(sp=<number>, dp=<number>, len=<number>, csum=<number>)
624 sp|sport - Source port (default: 0)
626 dp|dport - Destination port (default: 0)
628 len|length - Length of UDP header and data (calculated by
630 default)
631 csum - Checksum field over IPv4 pseudo header (calculated by
633 default)
634 By default, if the lower level header is IPv4, its protocol field
636 is set to 0x11 (UDP).
637 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 sp|sport - Source port (default: 0)
643 dp|dport - Destination port (default: 0)
645 seq - Sequence number (default: 0)
647 aseq|ackseq - Acknowledgement number (default: 0)
649 doff|hlen - Header size (data offset) in number of 32-bit words
651 (default: 5)
652 cwr - Congestion Window Reduced (CWR) flag (default: 0)
654 ece|ecn - ECN-Echo (ECE) flag (default: 0)
656 urg - Urgent flag (default: 0)
658 ack - Acknowledgement flag (default: 0)
660 psh - Push flag (default: 0)
662 rst - Reset flag (default: 0)
664 syn - Synchronize flag (default: 0)
666 fin - Finish flag (default: 0)
668 win|window - Receive window size (default: 0)
670 csum - Checksum field over IPv4 pseudo header (calculated by
672 default)
673 urgptr - Urgent pointer (default: 0)
675 By default, if the lower level header is IPv4, its protocol field
677 is set to 0x6 (TCP).
678 Simple example of a UDP Echo packet:
680 {
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 Furthermore, there are two types of comments in trafgen configuration
689 files:
690 1. Multi-line C-style comments: /* put comment here */
692 2. Single-line Shell-style comments: # put comment here
693 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 /* Note: dynamic elements make trafgen slower! */
700 #include <stddef.h>
701 {
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 Another real-world example by Jesper Dangaard Brouer [1]:
749 {
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 [1] https://marc.info/?l=linux-netdev&m=135903630614184
784 The above example rewritten using the header generation functions:
786 {
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
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 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 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 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 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 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 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 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
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 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 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 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 Traffic model Distribution
874 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 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 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
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 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
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
916 netsniff-ng(8), mausezahn(8), ifpps(8), bpfc(8), flowtop(8), astracer‐
917 oute(8), curvetun(8)
918
920 Manpage was written by Daniel Borkmann.
921
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/.
926Linux 03 March 2013 TRAFGEN(8)