TRAFGEN(8)

📦
version 0.6.9 · 2 versions
, in arch rolling, debian trixie, epel 10, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 TRAFGEN 💖

okay bestie, welcome to trafgen, straight out of the netsniff-ng toolkit and living her absolute best life in section 8 of your manual pages. she's a packet generator. she's fast. and she's about to be your new hyperfixation. 🎀

✨ NAME ✨

trafgen — a fast, multithreaded network packet generator 👑

🦋 SYNOPSIS 🦋

trafgen [options] [packet]

🌸 DESCRIPTION 🌸

so. trafgen is a fast, zero-copy network traffic generator for debugging, performance evaluation, and fuzz-testing. periodt. she uses the packet(7) socket interface of Linux, which is the move because it postpones complete control over packet data and packet headers into the user space. and she comes with a powerful packet configuration language that's pretty low-level and not limited to any particular protocols. which means she can be used for so many things, it's giving versatility. ✨

her one limitation? she can't mimic full streams resp. sessions. that's it. that's the only thing. but honestly she's still very useful for all kinds of load testing — analyzing and then improving how systems behave under DoS attack scenarios, for instance. no cap.

trafgen is Linux specific, meaning there's no support for other operating systems, same as netsniff-ng(8). and that's actually on purpose bestie — it keeps the code footprint quite minimal and to the point. 💅 she makes use of packet(7) socket's TX_RING interface of the Linux kernel, which is a mmap(2)'ed ring buffer shared between user and kernel space. iconic behavior honestly.

okay so by default, trafgen starts as many processes as available CPUs, pins each of them to their respective CPU, and sets up the ring buffer each in their own process space after having compiled a list of packets to transmit. so like. this is likely the fastest one can get out of the box in terms of transmission performance from user space, without having to load unsupported or non-mainline third-party kernel modules. 🫶

on Gigabit Ethernet, trafgen has a comparable performance to pktgen, the built-in Linux kernel traffic generator — except that trafgen is more flexible in terms of packet configuration possibilities. ate. on 10-Gigabit-per-second Ethernet, trafgen might be slower than pktgen due to the user/kernel space overhead, but she still has a fairly high performance for out of the box kernels. still slaying, just differently. 💜

now here's where it gets fun. trafgen has the potential to do fuzz testing, meaning a packet configuration can be built with random numbers on all or certain packet offsets that are freshly generated each time a packet is sent out. with a built-in IPv4 ping, trafgen can send out an ICMP probe after each packet injection to the remote host in order to test if it's still responsive/alive. 👀

so assuming there's no answer from the remote host after a certain threshold of probes, the machine is considered dead and the last sent packet is printed together with the random seed that was used by trafgen. you might not really get lucky fuzz-testing the Linux kernel, ngl, but presumably there are buggy closed-source embedded systems or network driver's firmware files that are prone to bugs, where trafgen could help in finding them. 🔥

trafgen's configuration language is quite powerful, also due to the fact that it supports C preprocessor macros. a stddef.h is being shipped with trafgen for this purpose, so that well known defines from Linux kernel or network programming can be reused. 🧚

after a configuration file has passed the C preprocessor stage, it's processed by the trafgen packet compiler. the language itself supports a couple of features that are useful when assembling packets, such as:

  • built-in runtime checksum support for IP, UDP and TCP ✅
  • an expression evaluator where arithmetic (basic operations, bit operations, bit shifting, ...) on constant expressions is being reduced to a single constant on compile time 🧮
  • other features are ''fill'' macros, where a packet can be filled with n bytes by a constant, a compile-time random number or run-time random number (as mentioned with fuzz testing) 🎲

also, netsniff-ng(8) is able to convert a pcap file into a trafgen configuration file, thus such a configuration can be further tweaked for a given scenario. bestie that's a whole workflow right there. 💖

✨ OPTIONS ✨

okay bestie, this is the part where trafgen shows you every knob it has. buckle up 💅

  • -i <cfg|pcap|->, -c <cfg|->, --in <cfg|pcap|->, --conf <cfg|-> — tells trafgen which input config file to read. you can hand it a normal plain text file, or pipe it in through stdin by passing - (literally just a dash). heads up tho: right now, if the config comes in through stdin, only 1 CPU gets used, no cap. you can also pass a PCAP file here if it has a .pcap extension — when you do, packets go out at a rate based on the timestamps in the PCAP file by default, and you can reset that rate with -b or -t. 🎀
  • -o <dev|.pcap|.cfg>, -d <dev|.pcap|.cfg>, --out <dev|.pcap|.cfg>, --dev <dev|.pcap|.cfg> — picks the outgoing networking device, like eth0, wlan0 and friends — or a *.pcap / *.cfg file. it knows which is which by the extension, bestie. 🦋
  • -p, --cpp — runs your packet configuration through the C preprocessor before trafgen reads it in. this is what unlocks #define and #include directives in your trafgen config (yes, including definitions from system headers 👑). ✨
  • -D <name>=<definition>, --define <name>=<definition> — adds a macro definition for the C preprocessor to use inside your trafgen file. this one only makes sense alongside the -p/--cpp option, so pair them up. 💫
  • -J, --jumbo-support — by default trafgen's ring buffer frames are a fixed size of 2048 bytes. so if you're expecting jumbo frames, or even super jumbo frames, to come down your line, you're gonna need this option to enable support for that. the tradeoff tho: performance regression plus a bigger memory footprint for the ring buffer. it's giving "worth it only if you need it". 💀
  • -R, --rfraw — if your output networking device is a wireless one, trafgen can flip it into monitor mode and create a mon<X> device that trafgen transmits on instead of wlan<X>, for example. this is the move that lets trafgen inject raw 802.11 frames. and if the output is a pcap file, the link type gets set to 127 (that's ieee80211 radio tap). 🌈
  • -s <ipv4>, --smoke-test <ipv4> — turns on a smoke test. basically trafgen pokes the remote end you're "attacking" (their word, not mine 🙈) at the <ipv4> address you give it, and checks if it's still alive and responsive. after each transmitted packet that's been configured, trafgen fires off ICMP echo requests and waits for an answer before it moves on. if the remote end stays unresponsive, trafgen assumes the machine crashed and prints out the content of the last packet as a trafgen packet configuration, plus the random seed that was used, so you can reproduce a possible bug. super useful when you're testing proprietary embedded devices. recommended setup: have a direct link between the host running trafgen and the host being attacked by trafgen. 🫶
  • -n <0|uint>, --num <0|uint> — process a number of packets and then dip out. if the number is 0, that's equivalent to infinite packets, i.e. it just keeps processing until you interrupt it. otherwise, an unsigned integer limits how much gets processed. ✨
  • -r, --rand — randomizes the packet selection from the configuration file. by default, if more than one packet is defined in a packet configuration, they're scheduled for transmission in a round robin fashion. with this option, they get selected randomly instead. (yes, the original spells it "instread", we're keeping the vibes.) 🎲
  • -P <uint>[-<uint>], --cpus <uint>[-<uint>] — says how many processes trafgen should fork(2) off, or lists the exact CPUs to use. by default trafgen starts as many processes as there are CPUs online and pins them to each one, respectively. a single integer within the interval [1,CPUs] overrides the number of processes, which get spawned starting from the first CPU. a pair of integers within the interval [0,CPUs-1], separated with -, represents an interval of CPUs that'll be used to spawn worker processes. 💅
  • -t <time>, --gap <time> — sets a static inter-packet timegap in seconds, milliseconds, microseconds, or nanoseconds: ''<num>s/ms/us/ns''. no postfix means it defaults to microseconds. if you use this option, then instead of packet(7)'s TX_RING interface, trafgen uses sendto(2) I/O for network packets — even if the <time> argument is 0. this option is useful for a couple of reasons:
    1. comparison between sendto(2) and TX_RING performance,
    2. low-traffic packet probing for a given interval,
    3. ping-like debugging with specific payload patterns.

and one more thing: the TX_RING interface does not cope with interpacket gaps. periodt. 🎀

  • -b <rate>, --rate <rate> — sets the packet send rate in <num>pps/kpps/Mpps/B/kB/MB/GB/kbit/Mbit/Gbit/KiB/MiB/GiB units. just like with -t/--gap, the packets get sent in slow mode. 🐢
  • -S <size>, --ring-size <size> — manually define the TX_RING resp. TX_RING size in ''<num>KiB/MiB/GiB''. by default the size is determined based on the network connectivity rate. 🌸
  • -E <uint>, --seed <uint> — manually set the seed for the pseudo random number generator (PRNG) in trafgen. by default, a random seed from /dev/urandom feeds glibc's PRNG, and if that fails it falls back to the unix timestamp. setting the seed by hand is handy when you wanna reproduce a trafgen session, like after fuzz testing. 🔥
  • -u <uid>, --user <uid> resp. -g <gid>, --group <gid> — after ring setup, drop privileges to a non-root user/group combination. very demure, very mindful. 💜
  • -H, --prio-high — marks this process as a high priority process so it gets a higher scheduling rate resp. CPU time. it's not the default tho, because it could starve other processes — like low priority kernel threads. main character energy, but make it risky. 👑
  • -A, --no-sock-mem — don't touch the system's default socket memory setting during the testrun. the default behaviour is to boost socket buffer memory during the test to:
/proc/sys/net/core/rmem_default:4194304
/proc/sys/net/core/wmem_default:4194304
/proc/sys/net/core/rmem_max:104857600
/proc/sys/net/core/wmem_max:104857600
  • -Q, --notouch-irq — don't reassign the NIC's IRQ CPU affinity settings. leave that IRQ exactly where it is, bestie. 🦋
  • -q, --qdisc-path — since Linux 3.14 the kernel supports a socket option called PACKET_QDISC_BYPASS, and trafgen enables it by default. this option disables the qdisc bypass and uses the normal send path through the kernel's qdisc (traffic control) layer, which is useful for testing the qdisc path. ✨
  • -V, --verbose — makes trafgen more talkative and lets it print the parsed configuration plus some ring buffer statistics. the yapper mode we deserve. 🗣️
  • -e, --example — shows a built-in packet configuration example. lowkey a great starting point for your first packet configuration scenario. 🌱
  • -C, --no-cpu-stats — don't print CPU time statistics on exit. 📊
  • -v, --version — show version information and exit.
  • -h, --help — show user help and exit.

🧚 SYNTAX 🧚

trafgen's packet configuration syntax is pretty simple, fr fr. the very basic thing you need to know is that a configuration file is a simple plain text file where packets are defined, and it can hold one or more packets. packets are wrapped in opening { and closing } braces, like this:

{ /* packet 1 content goes here ... */ }
{ /* packet 2 content goes here ... */ }

alternatively, packets can also be specified directly on the command line, using the same syntax as the configuration files. ✨

when trafgen starts up using multiple CPUs (which is the default), then each of those packets gets scheduled for transmission on all CPUs by default. but you can tell trafgen to schedule a packet only on a particular CPU:

cpu(1): { /* packet 1 content goes here ... */ }
cpu(2-3): { /* packet 2 content goes here ... */ }

so say we have a 4 core machine with CPU0–CPU3: packet 1 gets scheduled only on CPU1, and packet 2 goes on CPU2 and CPU3. when you're running trafgen with the --num option, those constraints still hold and the packet is fairly distributed among those CPUs. 💅

packet content is delimited either by a comma or whitespace, or both:

{ 0xca, 0xfe, 0xba 0xbe }

packet content can be any of the following:

hex bytes:   0xca, xff
decimal:     42
binary:      0b11110000, b11110000
octal:       011
character:   'a'
string:      "hello world"
shellcode:   "\x31\xdb\x8d\x43\x17\x99\xcd\x80\x31\xc9"

so a quite useless packet configuration might look like this — and you can verify it when you run it with trafgen in combination with -V:

{ 0xca, 42, 0b11110000, 011, 'a', "hello world",
  "\x31\xdb\x8d\x43\x17\x99\xcd\x80\x31\xc9" }

there are a couple of helper functions in trafgen's language that make writing configurations way easier, bestie: 🌸

i) Fill with garbage functions:

byte fill function:      fill(<content>, <times>): fill(0xca, 128)
compile-time random:     rnd(<times>): rnd(128), rnd()
runtime random numbers:  drnd(<times>): drnd(128), drnd()
compile-time counter:    seqinc(<start-val>, <times>, <increment>)
                         seqdec(<start-val>, <times>, <decrement>)
runtime counter (1byte): dinc(<min-val>, <max-val>, <increment>)
                         ddec(<min-val>, <max-val>, <decrement>)

ii) Checksum helper functions (packet offsets start with 0):

IP/ICMP checksum:        csumip/csumicmp(<off-from>, <off-to>)
UDP checksum:            csumudp(<off-iphdr>, <off-udpdr>)
TCP checksum:            csumtcp(<off-iphdr>, <off-tcphdr>)
UDP checksum (IPv6):     csumudp6(<off-ip6hdr>, <off-udpdr>)
TCP checksum (IPv6):     csumtcp6(<off-ip6hdr>, <off-tcphdr>)

iii) Multibyte functions, compile-time expression evaluation:

const8(<content>), c8(<content>), const16(<content>), c16(<content>),
const32(<content>), c32(<content>), const64(<content>), c64(<content>)

these functions write their result in network byte order into the packet configuration, e.g. const16(0xaa) will result in ''00 aa''. within c*() functions you can do some arithmetics: -,+,*,/,%,&,|,<<,>>,^. e.g. const16((((1<<8)+0x32)|0b110)*2) will be evaluated to ''02 6c''. math girlies rise up 🧮✨

iv) Protocol header functions 💅✨

okay so bestie, these protocol header functions let you fill protocol header fields with this generic syntax:

<proto>(<field>=<value>,<field2>=<value2>,...,<field3>,...)

If a field isn't specified, a default value gets used (usually 0). Protocol fields can be set in any order, but the offset of the fields in the resulting packet follows the respective protocol. no cap.

Each field can be set with a function that generates field value at runtime by increment or randomize it. For L3/L4 protocols the checksum is calculated automatically if the field was changed dynamically by specified function. The following field functions are supported:

  • dinc — increment field value at runtime. By default increment step is '1'. min and max parameters are used to increment field only in the specified range, by default original field value is used. If the field length is greater than 4 then last 4 bytes are incremented only (useful for MAC and IPv6 addresses):
<field> = dinc() | dinc(min, max) | dinc(min, max, step)
  • drnd — randomize field value at runtime. min and max parameters are used to randomize field only in the specified range:
<field> = drnd() | drnd(min, max)

Example of using dynamic functions:

{
      eth(saddr=aa:bb:cc:dd:ee:ff, saddr=dinc()),
      ipv4(saddr=dinc()),
      udp(sport=dinc(1, 13, 2), dport=drnd(80, 100))
}

Fields might be further manipulated with a function at a specific offset:

<field>[<index>] | <field>[<index>:<length>]
  • <index> — relative field offset with range 0..<field.len> - 1
  • <length> — length/size of the value which will be set; either 1, 2 or 4 bytes (default: 1)

The <index> starts from the field's first byte in network order.

The syntax is similar to the one used in pcap filters (man pcap-filter) for matching header field at a specified offset.

Examples of using field offset (showing the effect in a shortenet output from netsniff-ng):

trafgen -o lo --cpus 1 -n 3 '{ eth(da=11:22:33:44:55:66, da[0]=dinc()), tcp() }'

Output:

[ Eth MAC (00:00:00:00:00:00 => 11:22:33:44:55:66)

[ Eth MAC (00:00:00:00:00:00 => 12:22:33:44:55:66)

[ Eth MAC (00:00:00:00:00:00 => 13:22:33:44:55:66)
trafgen -o lo --cpus 1 -n 3 '{ ipv4(da=1.2.3.4, da[0]=dinc()), tcp() }'

Output:

[ IPv4 Addr (127.0.0.1 => 1.2.3.4)

[ IPv4 Addr (127.0.0.1 => 2.2.3.4)

[ IPv4 Addr (127.0.0.1 => 3.2.3.4)

All required lower layer headers will be filled automatically if they were not specified by the user. The headers will be filled in the order they were specified. Each header will be filled with some mimimum required set of fields.

Supported protocol headers 🌈

Ethernet 🦋

eth(da=<mac>, sa=<mac>, type=<number>)

  • da|daddr — Destination MAC address (default: 00:00:00:00:00:00)
  • sa|saddr — Source MAC address (default: device MAC address)
  • etype|type|prot|proto — Ethernet type (default: 0)

PAUSE (IEEE 802.3X) ⏸️

pause(code=<number>, time=<number>)

  • code — MAC Control opcode (default: 0x0001)
  • time — Pause time (default: 0)

By default Ethernet header is added with these fields:

  • Ethernet type — 0x8808
  • Destination MAC address — 01:80:C2:00:00:01

PFC 🎀

pfc(pri|prio(<number>)=<number>, time(<number>)=<number>)

  • code — MAC Control opcode (default: 0x0101)
  • pri|prio — Priority enable vector (default: 0)
  • pri|prio(<number>) — Enable/disable (0 - disable, 1 - enable) pause for priority <number> (default: 0)
  • time(<number>) — Set pause time for priority <number> (default: 0)

By default Ethernet header is added with these fields:

  • Ethernet type — 0x8808
  • Destination MAC address — 01:80:C2:00:00:01

VLAN 🌸

vlan(tpid=<number>, id=<number>, dei=<number>, tci=<number>, pcp=<number>, 1q, 1ad)

  • tpid|prot|proto — Tag Protocol Identifier (TPID) (default: 0x8100)
  • tci — Tag Control Information (TCI) field (VLAN Id + PCP + DEI) (default: 0)
  • dei|cfi — Drop Eligible Indicator (DEI), formerly Canonical Format Indicator (CFI) (default: 0)
  • pcp — Priority code point (PCP) (default: 0)
  • id — VLAN Identifier (default: 0)
  • 1q — Set 802.1q header (TPID: 0x8100)
  • 1ad — Set 802.1ad header (TPID: 0x88a8)

By default, if the lower level header is Ethernet, its EtherType is set to 0x8100 (802.1q).

MPLS 🔥

mpls(label=<number>, tc|exp=<number>, last=<number>, ttl=<number>)

  • label|lbl — MPLS label value (default: 0)
  • tclass|tc|exp — Traffic Class for QoS field (default: 0)
  • last — Bottom of stack S-flag (default: 1 for most last label)
  • ttl — Time To Live (TTL) (default: 0)

By default, if the lower level header is Ethernet, its EtherType is set to 0x8847 (MPLS Unicast). S-flag is set automatically to 1 for the last label and resets to 0 if the lower MPLS label was added after.

ARP 💌

arp(htype=<number>, ptype=<number>, op=<request|reply|number>, request, reply, smac=<mac>, sip=<ip4_addr>, tmac=<mac>, tip=<ip4_addr>)

  • htype — ARP hardware type (default: 1 [Ethernet])
  • ptype — ARP protocol type (default: 0x0800 [IPv4])
  • op — ARP operation type (request/reply) (default: request)
  • req|request — ARP Request operation type
  • reply — ARP Reply operation type
  • smac|sha — Sender hardware (MAC) address (default: device MAC address)
  • sip|spa — Sender protocol (IPv4) address (default: device IPv4 address)
  • tmac|tha — Target hardware (MAC) address (default: 00:00:00:00:00:00)
  • tip|tpa — Target protocol (IPv4) address (default: device IPv4 address)

By default, the ARP operation field is set to request and the Ethernet destination MAC address is set to the broadcast address (ff:ff:ff:ff:ff:ff).

IPv4 👑

ip4|ipv4(ihl=<number>, ver=<number>, len=<number>,
csum=<number>, ttl=<number>, tos=<number>, dscp=<number>,
ecn=<number>,
                id=<number>, flags=<number>, frag=<number>, df, mf,
                da=<ip4_addr>, sa=<ip4_addr>, prot[o]=<number>)
  • ver|version — Version field (default: 4)
  • ihl — Header length in number of 32-bit words (default: 5)
  • tos — Type of Service (ToS) field (default: 0)
  • dscp — Differentiated Services Code Point (DSCP, DiffServ) field (default: 0)
  • ecn — Explicit Congestion Notification (ECN) field (default: 0)
  • len|length — Total length of header and payload (calculated by default)
  • id — IPv4 datagram identification (default: 0)
  • flags — IPv4 flags value (DF, MF) (default: 0)
  • df — Don't fragment (DF) flag (default: 0)
  • mf — More fragments (MF) flag (default: 0)
  • frag — Fragment offset field in number of 8 byte blocks (default: 0)
  • ttl — Time to live (TTL) field (default: 0)
  • csum — Header checksum (calculated by default)
  • sa|saddr — Source IPv4 address (default: device IPv4 address)
  • da|daddr — Destination IPv4 address (default: 0.0.0.0)
  • prot|proto — IPv4 protocol number (default: 0)

By default, if the lower level header is Ethernet, its EtherType field is set to 0x0800 (IPv4). If the lower level header is IPv4, its protocol field is set to 0x4 (IP-in-IP).

IPv6 🦋✨

ip6|ipv6(ver=<number>, class=<number>, flow=<number> len=<number>, nexthdr=<number>, hoplimit=<number>,
                da=<ip6_addr>, sa=<ip6_addr>)
  • ver|version — Version field (default: 6)
  • tc|tclass — Traffic class (default: 0)
  • fl|flow — Flow label (default: 0)
  • len|length — Payload length (calculated by default)
  • nh|nexthdr — Type of next header, i.e. transport layer protocol number (default: 0)
  • hl|hoplimit|ttl — Hop limit, i.e. time to live (default: 0)
  • sa|saddr — Source IPv6 address (default: device IPv6 address)
  • da|daddr — Destination IPv6 address (default: 0:0:0:0:0:0:0:0)

By default, if the lower level header is Ethernet, its EtherType field is set to 0x86DD (IPv6).

ICMPv4 😭

icmp4|icmpv4(type=<number>, code=<number>, echorequest, echoreply, csum=<number>, mtu=<number>, seq=<number>, id=<number>, addr=<ip4_addr>)
  • type — Message type (default: 0 - Echo reply)
  • code — Message code (default: 0)
  • echorequest — ICMPv4 echo (ping) request (type: 8, code: 0)
  • echoreply — ICMPv4 echo (ping) reply (type: 0, code: 0)
  • csum — Checksum of ICMPv4 header and payload (calculated by default)
  • mtu — Next-hop MTU field used in 'Datagram is too big' message type (default; 0)
  • seq — Sequence number used in Echo/Timestamp/Address mask messages (default: 0)
  • id — Identifier used in Echo/Timestamp/Address mask messages (default: 0)
  • addr — IPv4 address used in Redirect messages (default: 0.0.0.0)

Example ICMP echo request (ping):

{ icmpv4(echorequest, seq=1, id=1326) }

ICMPv6 🌈

icmp6|icmpv6(type=<number>, echorequest, echoreply, code=<number>, csum=<number>)
  • type — Message type (default: 0)
  • code — Code (default: 0)
  • echorequest — ICMPv6 echo (ping) request
  • echoreply — ICMPv6 echo (ping) reply
  • csum — Message checksum (calculated by default)

By default, if the lower level header is IPv6, its Next Header field is set to 58 (ICMPv6).

UDP 🍓

udp(sp=<number>, dp=<number>, len=<number>, csum=<number>)
  • sp|sport — Source port (default: 0)
  • dp|dport — Destination port (default: 0)
  • len|length — Length of UDP header and data (calculated by default)
  • csum — Checksum field over IPv4 pseudo header (calculated by default)

By default, if the lower level header is IPv4, its protocol field is set to 0x11 (UDP).

TCP : tcp(sp=<number>, dp=<number>, seq=<number>,
aseq|ackseq=<number>, doff|hlen=<number>, cwr, ece|ecn, urg, ack,
psh, rst, syn, fin, win|window=<number>, csum=<number>,
urgptr=<number>)
  • sp, sport — source port (default: 0) 💌
  • dp, dport — destination port (default: 0) 💌
  • seq — sequence number (default: 0)
  • aseq, ackseq — acknowledgement number (default: 0)
  • doff, hlen — header size (a.k.a. data offset), counted in 32-bit words (default: 5)
  • cwr — the Congestion Window Reduced (CWR) flag (default: 0)
  • ece, ecn — the ECN-Echo (ECE) flag (default: 0)
  • urg — the Urgent flag (default: 0)
  • ack — the Acknowledgement flag (default: 0)
  • psh — the Push flag (default: 0)
  • rst — the Reset flag (default: 0)
  • syn — the Synchronize flag (default: 0)
  • fin — the Finish flag (default: 0)
  • win, window — receive window size (default: 0)
  • csum — the checksum field, computed over the IPv4 pseudo header (calculated for you by default ✨)
  • urgptr — urgent pointer (default: 0)

okay so bestie, here's a lil default behavior tea: if the lower level header is IPv4, its protocol field gets set to 0x6 (that's TCP, obviously 💅).

And here's a super simple UDP Echo packet, just so you can see the shape of things:

{
  eth(da=11:22:33:44:55:66),
  ipv4(daddr=1.2.3.4)
  udp(dp=7),
  "Hello world"
}

💬 Comments, bestie, we love them 💬

There are two types of comments you can drop in trafgen configuration files:

  1. Multi-line C-style comments: /* put comment here */
  2. Single-line Shell-style comments: # put comment here

And on top of all that, a configuration can be passed through the C preprocessor before the trafgen compiler even gets to see it, using option --cpp. 🧚

To give you a taste of a more advanced example, run trafgen -e — the fields come all commented up:

/* Note: dynamic elements make trafgen slower! */
#include <stddef.h>

{
  /* MAC Destination */
  fill(0xff, ETH_ALEN),
  /* MAC Source */
  0x00, 0x02, 0xb3, drnd(3),
  /* IPv4 Protocol */
  c16(ETH_P_IP),
  /* IPv4 Version, IHL, TOS */
  0b01000101, 0,
  /* IPv4 Total Len */
  c16(59),
  /* IPv4 Ident */
  drnd(2),
  /* IPv4 Flags, Frag Off */
  0b01000000, 0,
  /* IPv4 TTL */
  64,
  /* Proto TCP */
  0x06,
  /* IPv4 Checksum (IP header from, to) */
  csumip(14, 33),
  /* Source IP */
  drnd(4),
  /* Dest IP */
  drnd(4),
  /* TCP Source Port */
  drnd(2),
  /* TCP Dest Port */
  c16(80),
  /* TCP Sequence Number */
  drnd(4),
  /* TCP Ackn. Number */
  c32(0),
  /* TCP Header length + TCP SYN/ECN Flag */
  c16((8 << 12) | TCP_FLAG_SYN | TCP_FLAG_ECE)
  /* Window Size */
  c16(16),
  /* TCP Checksum (offset IP, offset TCP) */
  csumtcp(14, 34),
  /* TCP Options */
  0x00, 0x00, 0x01, 0x01, 0x08, 0x0a, 0x06,
  0x91, 0x68, 0x7d, 0x06, 0x91, 0x68, 0x6f,
  /* Data blob */
  "gotcha!",
}

Another real-world example by Jesper Dangaard Brouer [1]:

{
  # --- ethernet header ---
  0x00, 0x1b, 0x21, 0x3c, 0x9d, 0xf8,  # mac destination
  0x90, 0xe2, 0xba, 0x0a, 0x56, 0xb4,  # mac source
  const16(0x0800), # protocol
  # --- ip header ---
  # ipv4 version (4-bit) + ihl (4-bit), tos
  0b01000101, 0,
  # ipv4 total len
  const16(40),
  # id (note: runtime dynamic random)
  drnd(2),
  # ipv4 3-bit flags + 13-bit fragment offset
  # 001 = more fragments
  0b00100000, 0,
  64, # ttl
  17, # proto udp
  # dynamic ip checksum (note: offsets are zero indexed)
  csumip(14, 33),
  192, 168, 51, 1, # source ip
  192, 168, 51, 2, # dest ip
  # --- udp header ---
  # as this is a fragment the below stuff does not matter too much
  const16(48054), # src port
  const16(43514), # dst port
  const16(20),    # udp length
  # udp checksum can be dyn calc via csumudp(offset ip, offset tcp)
  # which is csumudp(14, 34), but for udp its allowed to be zero
  const16(0),
  # payload
  'A',  fill(0x41, 11),
}

[1] https://marc.info/?l=linux-netdev&m=135903630614184

And the same example rewritten using the header generation functions:

{
  # --- ethernet header ---
  eth(da=00:1b:21:3c:9d:f8, sa=90:e2:ba:0a:56:b4)
  # --- ip header ---
  ipv4(id=drnd(), mf, ttl=64, sa=192.168.51.1, da=192.168.51.2)
  # --- udp header ---
  udp(sport=48054, dport=43514, csum=0)
  # payload
  'A',  fill(0x41, 11),
}

🌈 USAGE EXAMPLE 🌈

  • trafgen --dev eth0 --conf trafgen.cfg — this is the most simple and, honestly, probably the most common way to run trafgen. It generates the traffic defined in the configuration file trafgen.cfg and transmits it out the eth0 networking device. All online CPUs get put to work. 💪
  • trafgen --dev eth0 --conf trafgen.cfg --cpus 2-4 — instead of using every online CPU, transmit traffic from CPUs 2, 3, and 4 only.
  • trafgen -e | trafgen -i - -o lo --cpp -n 1 — here we send one packet of the built-in example through the loopback device. The example configuration gets passed in via stdin and through the C preprocessor before trafgen's packet compiler ever sees it. ✨
  • trafgen --dev eth0 --conf fuzzing.cfg --smoke-test 10.0.0.1 — read the fuzzing.cfg packet configuration file (it's full of drnd() calls, bestie) and send the generated packets out to the eth0 device. After each sent packet, ping-probe the attacked host at 10.0.0.1 to check if it's still alive. Heads up: this also means we utilize only 1 CPU, and we do not use the TX_RING — instead it's sendto(2) packet I/O, because of slow mode. 🐌
  • trafgen --dev wlan0 --rfraw --conf beacon-test.txf -V --cpus 2 — wlan0 is used as the output device and gets put into monitoring mode, so we're transmitting raw 802.11 frames through the air. Use the beacon-test.txf configuration file, put trafgen into verbose mode, and use only 2 CPUs starting from CPU 0. 🦋
  • trafgen --dev em1 --conf frag_dos.cfg --rand --gap 1000us — run trafgen in sendto(2) mode instead of TX_RING mode, and sleep for a static timegap of 1000us after every sent packet. Generate packets from frag_dos.cfg and pick the next packets to send randomly instead of in round-robin fashion. The output device for packets is em1.
  • trafgen --dev eth0 --conf icmp.cfg --rand --num 1400000 -k1000 — send only 1400000 packets using the icmp.cfg configuration file, then exit trafgen. Pick packets randomly from that file for transmission and send them out via eth0. Also, trigger the kernel every 1000us to batch the ring frames from user space (default is 10us).
  • trafgen --dev eth0 --conf tcp_syn.cfg -u id -u bob-gid -g bob`` — send out packets generated from the configuration file tcp_syn.cfg via the eth0 networking device. After setting up the ring for transmission, drop credentials down to the non-root user/group bob/bob. 🫶
  • trafgen --dev eth0 '{ fill(0xff, 6), 0x00, 0x02, 0xb3, rnd(3), c16(0x0800), fill(0xca, 64) }' -n 1 — send out 1 invalid IPv4 packet, built straight from the command line, to all hosts. 💀

📢 NOTE 📢

trafgen can saturate a Gigabit Ethernet link without any problems whatsoever. As always, of course, this depends on your hardware too. Not everywhere it says Gigabit Ethernet on the box will you actually reach almost physical line rate! Please also read the netsniff-ng(8) man page, section NOTE, for further details about tuning your system, e.g. with tuned(8). 🔧

If you're planning to use trafgen on a 10-Gbit/s Ethernet NIC, make sure you're using a multiqueue tc(8) discipline, and make sure the packets you generate with trafgen have a good distribution among tx_hashes so that you'll actually make use of multiqueues. 👑

For introducing bit errors, delays with random variation and more, there is no built-in option in trafgen. Instead, you should reuse existing methods for that which integrate nicely with trafgen, such as tc(8) with its different disciplines, i.e. netem.

For more complex packet configurations, it's recommended to use high-level scripting to generate trafgen packet configurations in a more automated way — i.e. also to create different traffic distributions that are common for industrial benchmarking:

  • IMIX — 64:7, 570:4, 1518:1
  • Tolly — 64:55, 78:5, 576:17, 1518:23
  • Cisco — 64:7, 594:4, 1518:1
  • RPR Trimodal — 64:60, 512:20, 1518:20
  • RPR Quadrimodal — 64:50, 512:15, 1518:15, 9218:20

The low-level nature of trafgen makes it rather protocol independent, and therefore useful in many scenarios when stress testing is needed, for instance. However, if you want a traffic generator with higher level packet descriptions, netsniff-ng's mausezahn(8) can be of good use as well. 🌸

For smoke/fuzz testing with trafgen, it's recommended to have a direct link between the host you want to analyze (the victim machine) and the host you run trafgen on (the attacker machine). If the ICMP reply from the victim fails, we assume its kernel probably crashed — so we print the last sent packet together with the seed and quit probing. It might be very unlikely to find such a ping-of-death on modern Linux systems. However, there might be a good chance to find it on some proprietary (e.g. embedded) systems or buggy driver firmwares that are out there in the wild. Also, fuzz testing can be done on raw 802.11 frames, of course. And in case you do find a ping-of-death — please mention that you were using trafgen in your commit message of the fix! 🏆

💀 BUGS 💀

For old trafgen versions only, kernel crashes could occur. We have fixed this bug in the mainline and stable kernels under commit 7f5c3e3a8 (af_packet: remove BUG statement in tpacket_destruct_skb) and also in trafgen itself.

Probably the best thing you can do is upgrade trafgen to the latest version. no cap. ✨

trafgen is licensed under the GNU GPL version 2.0.

📜 HISTORY 📜

trafgen was originally written for the netsniff-ng toolkit by Daniel Borkmann. It is currently maintained by Tobias Klauser <tklauser@distanz.ch> and Daniel Borkmann <dborkma@tik.ee.ethz.ch>.

👀 SEE ALSO 👀

netsniff-ng(8), mausezahn(8), ifpps(8), bpfc(8), flowtop(8), astraceroute(8), curvetun(8)

💖 AUTHOR 💖

okay so the whole entire manpage you just read? written by Daniel Borkmann. yes bestie, one person, one icon, one legend. give them their flowers fr fr 💐👑

🌸 COLOPHON 🌸

so this page is part of the Linux netsniff-ng toolkit project 🦋 — like, the whole squad, not just trafgen. if you wanna read all about the project, or you found a bug and need to snitch (kindly, respectfully, with repro steps 🫶), the info lives at:

http://netsniff-ng.org/

that's the spot. go there. bookmark it. tell your friends. ✨

and that's the whole page, bestie!! we did it!! 🎀 this one came from the Linux section of the manual, dated 03 March 2013, filed under TRAFGEN(8) — so if you ever need to look it back up, that's your little address for it. now go forth and craft some packets 💅🔥 mwah, bye!! 💜

✨💖 slay responsibly 💖✨

📦 where this page comes from