misc: move file to source root

Only have Makefile specific folders in the project root where the
binaries are stored, the rest should be part of the repository root.

Signed-off-by: Daniel Borkmann <dborkman@redhat.com>

1 files changed, 445 insertions, 0 deletions

diff --git a/trafgen.8 b/trafgen.8
new file mode 100644
index 0000000..6ead20c
--- /dev/null
+++ b/trafgen.8
@@ -0,0 +1,445 @@
+.\" netsniff-ng - the packet sniffing beast
+.\" Copyright 2013 Daniel Borkmann.
+.\" Subject to the GPL, version 2.
+
+.TH TRAFGEN 8 "03 March 2013" "Linux" "netsniff-ng toolkit"
+.SH NAME
+trafgen \- a fast, multithreaded network packet generator
+
+.SH SYNOPSIS
+
+\fB trafgen\fR [\fIoptions\fR]
+
+.SH DESCRIPTION
+
+trafgen is a fast, zero-copy network traffic generator for debugging,
+performance evaluation and fuzz-testing purposes. trafgen utilizes the packet(7)
+socket interface of Linux which postpones complete control over packet data
+and packet headers into the user space. It has a powerful packet configuration
+language, which is rather low-level and not limited to particular protocols.
+Thus, trafgen can be used for many purposes. Its only limitation is that it
+cannot mimic full streams resp. sessions. However, it is very useful for
+various kinds of load testing in order to analyze and subsequently improve
+systems behaviour under DoS attack scenarios, for instance.
+
+trafgen is Linux specific only, meaning there is no support for other operating
+systems just as in netsniff-ng(8), thus we can keep the code footprint quite
+minimal and to the point. trafgen 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.
+
+On default, trafgen starts as many processes as CPUs that are online, 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. Thus, 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, only that trafgen is more
+flexible in terms of packet configuration possibilities. On 10-Gigabit-per-second
+Ethernet, trafgen might be slower than pktgen due to the user/kernel space
+overhead but still has a fairly high performance for out of the box kernels.
+
+trafgen has a possibility 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 is still responsive/alive. Assuming there is 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, 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 is 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. Also it has 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 then be further tweaked for a
+given scenario.
+
+.SH OPTIONS
+
+.SS -i <cfg|->, -c <cfg|i>, --in <cfg|->, --conf <cfg|->
+Defines the input configuration file that can either be passed as a normal plain
+text file or via stdin (``-''). Note that currently in case a configuration is
+passed through stdin, only 1 CPU will be used.
+
+.SS -o <dev>, -d <dev>, --out <dev>, --dev <dev>
+Defines the outgoing networking device such as eth0, wlan0 and others.
+
+.SS -p, --cpp
+Pass the packet configuration to
+
+.SS -J, --jumbo-support
+On default trafgen's ring buffer frames are of a fixed size of 2048 bytes.
+This means that if you're expecting jumbo frames or even super jumbo frames to
+pass your line, then you need to enable support for that with the help of this
+option. However, this has the disadvantage of a performance regression and a
+bigger memory footprint for the ring buffer.
+
+.SS -R, --rfraw
+In case the output networking device is a wireless device, it is possible with
+trafgen to turn this into monitor mode and create a mon<X> device that trafgen
+will be transmitting on instead of wlan<X>, for instance. This enables trafgen
+to inject raw 802.11 frames.
+
+.SS -s <ipv4>, --smoke-test <ipv4>
+In case this option is enabled, trafgen will perform a smoke test. In other
+words, it will probe the remote end, specified by an <ipv4> address, that is
+being ``attacked'' with trafgen network traffic, if it is still alive and
+responsive. That means, after each transmitted packet that has been configured,
+trafgen sends out ICMP echo requests and waits for an answer before it continues.
+In case the remote end stays unresponsive, trafgen assumes that the machine
+has crashed and will print out the content of the last packet as a trafgen
+packet configuration and the random seed that has been used in order to
+reproduce a possible bug. This might be useful when testing proprietary embedded
+devices. It is recommended to have a direct link between the host running
+trafgen and the host being attacked by trafgen.
+
+.SS -n <0|uint>, --num <0|uint>
+Process a number of packets and then exit. If the number of packets is 0, then
+this is equivalent to infinite packets resp. processing until interrupted.
+Otherwise, a number given as an unsigned integer will limit processing.
+
+.SS -r, --rand
+Randomize the packet selection of the configuration file. On default, if more
+than one packet is defined in a packet configuration, packets are scheduled for
+transmission in a round robin fashion. With this option, they are selected
+randomly instread.
+
+.SS -P <uint>, --cpus <uint>
+Specify the number of processes trafgen shall fork(2) off. On default trafgen
+will start as many processes as CPUs that are online and pin them to each,
+respectively. Allowed value must be within interval [1,CPUs].
+
+.SS -t <uint>, --gap <uint>
+Specify a static inter-packet timegap in micro-seconds. If this option is given,
+then instead of packet(7)'s TX_RING interface, trafgen will use sendto(2) I/O
+for network packets, even if the <uint> argument is 0. This option is useful for
+a couple of reasons: i) comparison between sendto(2) and TX_RING performance,
+ii) low-traffic packet probing for a given interval, iii) ping-like debugging
+with specific payload patterns. Furthermore, the TX_RING interface does not cope
+with interpacket gaps.
+
+.SS -S <size>, --ring-size <size>
+Manually define the RX_RING resp. TX_RING size in ``<num>KiB/MiB/GiB''. On
+default the size is being determined based on the network connectivity rate.
+
+.SS -k <uint>, --kernel-pull <uint>
+Manually define the interval in micro-seconds where the kernel should be triggered
+to batch process the ring buffer frames. On default, it is every 10us, but it can
+manually be prolonged, for instance..
+
+.SS -E <uint>, --seed <uint>
+Manually set the seed for trafgen. On default, a random seed from /dev/urandom
+is being used to feed glibc's pseudo random number generator. If that fails, it
+falls back to the unix timestamp. It can be useful to set it up manually to be
+able to reproduce a trafgen session, e.g. after fuzz testing.
+
+.SS -u <uid>, --user <uid> resp. -g <gid>, --group <gid>
+After ring setup drop privileges to a non-root user/group combination.
+
+.SS -V, --verbose
+Let trafgen be more talkative and let it print the parsed configuration and
+some ring buffer statistics.
+
+.SS -e, --example
+Show a built-in packet configuration example. This might be a good starting
+point for an initial packet configuration scenario.
+
+.SS -v, --version
+Show versioning information.
+
+.SS -h, --help
+Show user help.
+
+.SH SYNTAX
+trafgen's packet configuration syntax is fairly simple. The very basic things
+one need to know is that a configuration file is a simple plain text file
+where packets are defined. It can contain one or more packets. Packet are
+enclosed by opening '{' and closing '}' braces, for example:
+
+   { /* packet 1 content goes here ... */ }
+   { /* packet 2 content goes here ... */ }
+
+When trafgen is started using multiple CPUs (default), then each of those packets
+will be scheduled for transmission on all CPUs on default. However, it is possible
+to 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 ... */ }
+
+Thus, in case we have a 4 core machine with CPU0-CPU3, packet 1 will be scheduled
+only on CPU1, packet 2 on CPU2 and CPU3. When using trafgen with --num option,
+then these constraints will still be valid 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 of the following:
+
+   hex bytes:   0xca
+   decimal:     42
+   binary:      0b11110000
+   octal:       011
+   character:   'a'
+   string:      "hello world"
+   shellcode:   "\\x31\\xdb\\x8d\\x43\\x17\\x99\\xcd\\x80\\x31\\xc9"
+
+Thus, a quite useless packet packet configuration might look like this (one can
+verify this when running this 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 to make life easier
+to write configurations:
+
+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>, <increment>, <times>)
+                            seqdec(<start-val>, <decrement>, <times>)
+   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>)
+
+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, it is possible to do some arithmetics: -,+,*,/,%,&,|,<<,>>,^
+E.g. const16((((1<<8)+0x32)|0b110)*2) will be evaluated to ``02 6c''.
+
+Furthermore, there are two types of comments in trafgen configuration files:
+
+  1. Multi-line C-style comments:        /* put comment here */
+  2. Single-line Shell-style comments:   #  put comment here
+
+Next to all of this, a configuration can be passed through the C preprocessor
+before the trafgen compiler gets to see it with option --cpp. To give you a
+taste of a more advanced example, run ``trafgen -e'', fields are commented:
+
+   /* 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(58),
+     /* 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] http://thread.gmane.org/gmane.linux.network/257155
+
+.SH USAGE EXAMPLE
+
+.SS trafgen --dev eth0 --conf trafgen.cfg
+This is the most simple and probably also most used command for trafgen. It
+will generate traffic defined in the configuration file ``trafgen.cfg'' and
+transmit this via the ``eth0'' networking device. All online CPUs are used.
+
+.SS trafgen -e | trafgen -i - -o lo --cpp -n 1
+This is an example where we send one packet of the built-in example through
+the loopback device. The example configuration is passed via stdin and also
+through the C preprocessor before trafgen's packet compiler will see it.
+
+.SS trafgen --dev eth0 --conf fuzzing.cfg --smoke-test 10.0.0.1
+Read the ``fuzzing.cfg'' packet configuration file (which contains drnd()
+calls) and send out the generated packets to the ``eth0'' device. After each
+sent packet, ping probe the attacked host with address 10.0.0.1 to check if
+it's still alive. This also means, that we utilize 1 CPU only, and do not
+use the TX_RING, but sendto(2) packet I/O due to ``slow mode''.
+
+.SS trafgen --dev wlan0 --rfraw --conf beacon-test.txf -V --cpus 2
+As an output device ``wlan0'' is used and put into monitoring mode, thus we
+are going to transmit raw 802.11 frames through the air. Use the
+``beacon-test.txf'' configuration file, set trafgen into verbose mode and
+use only 2 CPUs.
+
+.SS trafgen --dev em1 --conf frag_dos.cfg --rand --gap 1000
+Use trafgen in sendto(2) mode instead of TX_RING mode and sleep after each
+sent packet a static timegap for 1000us. Generate packets from ``frag_dos.cfg''
+and select next packets to send randomly instead of a round-robin fashion.
+The output device for packets is ``em1''.
+
+.SS trafgen --dev eth0 --conf icmp.cfg --rand --num 1400000 -k1000
+Send only 1400000 packets using the ``icmp.cfg'' configuration file and then
+exit trafgen. Select packets randomly from that file for transmission and
+send them out via ``eth0''. Also, trigger the kernel every 1000us for batching
+the ring frames from user space (default is 10us).
+
+.SS trafgen --dev eth0 --conf tcp_syn.cfg -u `id -u bob` -g `id -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 to the non-root user/group bob/bob.
+
+.SH NOTE
+trafgen can saturate a Gigabit Ethernet link without problems. As always,
+of course, this depends on your hardware as well. Not everywhere where it
+says Gigabit Ethernet on the box, you'll 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 intend to use trafgen on a 10-Gbit/s Ethernet NIC, make sure you
+are using a multiqueue tc(8) discipline, and make sure that the packets
+you generate with trafgen will 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. Rather, one 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 is recommended to use high-level
+scripting for generating trafgen packet configurations in a more automated
+way, i.e. also to create different traffic distributions that are common for
+industrial benchmarking:
+
+    Traffic model              Distribution
+
+    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 trafgen rather protocol independant
+and therefore useful in many scenarios when stress testing is needed, for
+instance. However, if a traffic generator with higher level packet
+descriptions is desired, netsniff-ng's mausezahn(8) can be of good use as
+well.
+
+For smoke/fuzz testing with trafgen, it is recommended to have a direct
+link between the host you want to analyze (``victim'' machine) and the host
+you run trafgen on (``attacker'' machine). If the ICMP reply from the victim
+fails, we assume that probably its kernel crashed, thus we print the last
+sent packet togther 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 in the wild. Also, fuzz testing can be done
+on raw 802.11 frames, of course. In case you find a ping-of-death, please
+mention that you were using trafgen in your commit message of the fix!
+
+.SH BUGS
+When I start trafgen, my kernel crashes: we have fixed this bug in the
+mainline and stable kernels under commit 7f5c3e3a8 (``af_packet: remove
+BUG statement in tpacket_destruct_skb''). Either update your kernel to
+the latest version, e.g. clone and build it from git.kernel.org, to a
+stable kernel, or don't start multiple trafgen instances at once resp.
+start trafgen with flag -A to disable temporary socket memory adaptation!
+
+.SH LEGAL
+trafgen is licensed under the GNU GPL version 2.0.
+
+.SH HISTORY
+.B 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>.
+
+.SH SEE ALSO
+.BR netsniff-ng (8),
+.BR mausezahn (8),
+.BR ifpps (8),
+.BR bpfc (8),
+.BR flowtop (8),
+.BR astraceroute (8),
+.BR curvetun (8)
+
+.SH AUTHOR
+Manpage was written by Daniel Borkmann.