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, 0 insertions, 445 deletions

diff --git a/man/trafgen.8 b/man/trafgen.8
deleted file mode 100644
index 6ead20c..0000000
--- a/man/trafgen.8
+++ /dev/null
@@ -1,445 +0,0 @@
-.\" 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.