diff options
| author | Daniel Borkmann <dborkman@redhat.com> | 2013-05-05 13:15:10 +0200 |
|---|---|---|
| committer | Daniel Borkmann <dborkman@redhat.com> | 2013-05-05 13:15:10 +0200 |
| commit | 9ea8663420e2b591ff7e43176fbfb2137aacf79c (patch) | |
| tree | 5d33957f3eda84ff8d1469af7ca809690b415c51 /man | |
| parent | bdfd22ceea4ba6dba113b1ac8514abb2839b94e4 (diff) | |
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>
Diffstat (limited to 'man')
| -rw-r--r-- | man/bpfc.8 | 320 | ||||
| -rw-r--r-- | man/curvetun.8 | 196 | ||||
| -rw-r--r-- | man/flowtop.8 | 132 | ||||
| -rw-r--r-- | man/ifpps.8 | 105 | ||||
| -rw-r--r-- | man/netsniff-ng.8 | 497 | ||||
| -rw-r--r-- | man/trafgen.8 | 445 |
6 files changed, 0 insertions, 1695 deletions
diff --git a/man/bpfc.8 b/man/bpfc.8 deleted file mode 100644 index 622014c..0000000 --- a/man/bpfc.8 +++ /dev/null @@ -1,320 +0,0 @@ -.\" netsniff-ng - the packet sniffing beast -.\" Copyright 2013 Daniel Borkmann. -.\" Subject to the GPL, version 2. - -.TH BPFC 8 "03 March 2013" "Linux" "netsniff-ng toolkit" -.SH NAME -bpfc \- a Berkeley Packet Filter assembler/compiler - -.SH SYNOPSIS - -\fB bpfc\fR { [\fIoptions\fR] | [\fIsource-file\fR] } - -.SH DESCRIPTION - -bpfc is a small Berkeley Packet Filter assembler/compiler which is able to -translate BPF assembler-like mnemonics into a numerical or C-like format, -that can be read by tools such as netsniff-ng, iptables (xt_bpf) and many -others. BPF is the one and only upstream filtering construct that is used -in combination with packet(7) sockets. The Linux kernel and also BSD kernels -implement ``virtual machine'' like constructs and JIT compilers that mimic -a small register-based machine in BPF architecture and execute filter code -that is e.g. composed by bpfc on a data buffer that is given by network -packets. The purpose of this is to shift computation in time, so that the -kernel can drop (or truncate) incoming packets as early as possible without -having to push them to user space for further analysis first. Meanwhile, -BPF constructs also find application in other areas like the communication -between user and kernel space. - -By the time of writing this man page, the only available BPF compiler is -part of the pcap(3) library and accessible through a high-level filter -language that might be familiar for many people as tcpdump-like filters. - -However, quite often, it is useful to bypass that compiler and write -optimized code that couldn't be produced by the pcap(3) compiler, was -wrongly optimized, or is defective on purpose in order to debug test kernel -code. Also, a reason to use bpfc could be to try out some new BPF extensions -that are not supported by other compilers. Furthermore, bpfc can be of good -use to verify JIT compiler behaviour or to find possible bugs that need -to be fixed. - -bpfc is implemented with the help of flex(1) and bison(1), tokenizes the -source file in a first stage and parses it's content into an AST. In two -code generation stages it emits target opcodes. bpfc furthermore supports -Linux kernel BPF extensions. More about that can be found in the syntax -section. - -The Linux kernel BPF JIT compiler is automatically turned on if detected -by netsniff-ng. However, it can also be manually turned on through the -command ``echo "1" > /proc/sys/net/core/bpf_jit_enable'' (normal working -mode) or ``echo "2" > /proc/sys/net/core/bpf_jit_enable'' (debug mode -where emitted opcodes of the image are printed to the kernel log). An -architecture generic BPF JIT image disassembler can be found in the kernel -source tree under: tools/net/bpf_jit_disasm.c - -.SH OPTIONS - -.SS -i <source-file/->, --input <source-file/-> -Read BPF assembly instruction from an input file or from stdin. - -.SS -f <format>, --format <format> -Specify a different output format than the default that is netsniff-ng -compatible. The <format> specifier can be: C, netsniff-ng, xt_bpf, tcpdump. - -.SS -b, --bypass -Bypass basic filter validation when emitting opcodes. This can be useful -for explicitly creating malformed BPF expressions that should be injected -into the kernel, e.g. for bug testing. - -.SS -V, --verbose -Be more verbose and display some bpfc debugging information. - -.SS -d, --dump -Dump all supported instructions to stdout. - -.SS -v, --version -Show versioning information. - -.SS -h, --help -Show user help. - -.SH SYNTAX - -The BPF architecture resp. register machine consists of the following -elements: - - Element Description - - A 32 bit wide accumulator - X 32 bit wide X register - M[] 16 x 32 bit wide misc registers aka ``scratch -memory store'', addressable from 0 to 15 - -A program, that is translated by bpfc into ``opcodes'' is an array that -consists of the following elements: - - o:16, jt:8, jf:8, k:32 - -The element o is a 16 bit wide opcode that has a particular instruction -encoded, jt and jf are two 8 bit wide jump targets, one for condition -``true'', one for condition ``false''. Last but not least the 32 bit wide -element k contains a miscellaneous argument that can be interpreted in -different ways depending on the given instruction resp. opcode. - -The instruction set consists of load, store, branch, alu, miscellaneous -and return instructions that are also represented in bpfc syntax. This -table also includes own bpfc extensions. All operations are based on -unsigned data structures: - - Instruction Addressing mode Description - - ld 1, 2, 3, 4, 10 Load word into A - ldi 4 Load word into A - ldh 1, 2 Load half-word into A - ldb 1, 2 Load byte into A - ldx 3, 4, 5, 10 Load word into X - ldxi 4 Load word into X - ldxb 5 Load byte into X - - st 3 Copy A into M[] - stx 3 Copy X into M[] - - jmp 6 Jump to label - ja 6 Jump to label - jeq 7, 8 Jump on k == A - jneq 8 Jump on k != A - jne 8 Jump on k != A - jlt 8 Jump on k < A - jle 8 Jump on k <= A - jgt 7, 8 Jump on k > A - jge 7, 8 Jump on k >= A - jset 7, 8 Jump on k & A - - add 0, 4 A + <x> - sub 0, 4 A - <x> - mul 0, 4 A * <x> - div 0, 4 A / <x> - mod 0, 4 A % <x> - neg 0, 4 !A - and 0, 4 A & <x> - or 0, 4 A | <x> - xor 0, 4 A ^ <x> - lsh 0, 4 A << <x> - rsh 0, 4 A >> <x> - - tax Copy A into X - txa Copy X into A - - ret 4, 9 Return - - Addressing mode Syntax Description - - 0 x Register X - 1 [k] BHW at byte offset k in the packet - 2 [x + k] BHW at the offset X + k in the packet - 3 M[k] Word at offset k in M[] - 4 #k Literal value stored in k - 5 4*([k]&0xf) Lower nibble * 4 at byte offset k in the packet - 6 L Jump label L - 7 #k,Lt,Lf Jump to Lt if true, otherwise jump to Lf - 8 #k,Lt Jump to Lt if predicate is true - 9 a Accumulator A - 10 extension BPF extension (see next table) - - Extension (and alias) Description - - #len, len, #pktlen, pktlen Length of packet (skb->len) - #pto, pto, #proto, proto Ethernet type field (skb->protocol) - #type, type Packet type (**) (skb->pkt_type) - #poff, poff Detected payload start offset - #ifx, ifx, #ifidx, ifidx Interface index (skb->dev->ifindex) - #nla, nla Netlink attribute of type X with offset A - #nlan, nlan Nested Netlink attribute of type X with offset A - #mark, mark Packet mark (skb->mark) - #que, que, #queue, queue, #Q, Q NIC queue index (skb->queue_mapping) - #hat, hat, #hatype, hatype NIC hardware type (**) (skb->dev->type) - #rxh, rxh, #rxhash, rxhash Receive hash (skb->rxhash) - #cpu, cpu Current CPU (raw_smp_processor_id()) - #vlant, vlant, #vlan_tci, vlan_tci VLAN TCI value (vlan_tx_tag_get(skb)) - #vlanp, vlanp VLAN present (vlan_tx_tag_present(skb)) - - Further extension details (**) Value - - #type, type 0 - to us / host - 1 - to all / broadcast - 2 - to group / multicast - 3 - to others (promiscuous mode) - 4 - outgoing of any type - - #hat, hat, #hatype, hatype 1 - Ethernet 10Mbps - 8 - APPLEtalk - 19 - ATM - 24 - IEEE 1394 IPv4 - RFC 2734 - 32 - InfiniBand - 768 - IPIP tunnel - 769 - IP6IP6 tunnel - 772 - Loopback device - 778 - GRE over IP - 783 - Linux-IrDA - 801 - IEEE 802.11 - 802 - IEEE 802.11 + Prism2 header - 803 - IEEE 802.11 + radiotap header - 823 - GRE over IP6 - [...] See include/uapi/linux/if_arp.h - -Note that the majority of BPF extensions are available on Linux only. - -There are two types of comments in bpfc source-files: - - 1. Multi-line C-style comments: /* put comment here */ - 2. Single-line ASM-style comments: ; put comment here - -Used Abbreviations: - - BHW: byte, half-word, or word - -.SH SOURCE EXAMPLES - -In this section, we give a couple of examples for bpfc source-files, in other -words, some small example filter programs: - -.SS Only return packet headers (truncate packets): - - ld poff - ret a - -.SS Only allow ARP packets: - - ldh [12] - jne #0x806, drop - ret #-1 - drop: ret #0 - -.SS Only allow IPv4 TCP packets: - - ldh [12] - jne #0x800, drop - ldb [23] - jneq #6, drop - ret #-1 - drop: ret #0 - -.SS Only allow IPv4 TCP, SSH traffic: - - ldh [12] - jne #0x800, drop - ldb [23] - jneq #6, drop - ldh [20] - jset #0x1fff, drop - ldxb 4 * ([14] & 0xf) - ldh [x + 14] - jeq #0x16, pass - ldh [x + 16] - jne #0x16, drop - pass: ret #-1 - drop: ret #0 - -.SS Allow any (hardware accelerated) VLAN: - - ld vlanp - jeq #0, drop - ret #-1 - drop: ret #0 - -.SS Only allow traffic for (hardware accelerated) VLAN 10: - - ld vlant - jneq #10, drop - ret #-1 - drop: ret #0 - -.SS More pedantic check for the above VLAN example: - - ld vlanp - jeq #0, drop - ld vlant - jneq #10, drop - ret #-1 - drop: ret #0 - -.SH USAGE EXAMPLE - -.SS bpfc fubar -Compile the source file ``fubar'' into BPF opcodes. Opcodes will be -directed to stdout. - -.SS bpfc -f xt_bpf -b -i fubar, resp. iptables -A INPUT -m bpf --bytecode "`bpfc -f xt_bpf -i fubar`" -j LOG -Compile the source file ``fubar'' into BPF opcodes, bypass basic filter -validation and emit opcodes in netfilter's xt_bpf readable format. - -.SS bpfc - -Read bpfc instruction from stdin and emit opcodes to stdout. - -.SS bpfc foo > bar, resp. netsniff-ng -f bar ... -Compile filter instructions from file foo and redirect bpfc's output into -the file bar, that can then be read by netsniff-ng(8) through option -f. - -.SS bpfc -f tcpdump -i fubar -Output opcodes from source file fubar in the same behaviour as ``tcpdump -ddd''. - -.SH LEGAL -bpfc is licensed under the GNU GPL version 2.0. - -.SH HISTORY -.B bpfc -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 trafgen (8), -.BR mausezahn (8), -.BR ifpps (8), -.BR flowtop (8), -.BR astraceroute (8), -.BR curvetun (8) - -.SH AUTHOR -Manpage was written by Daniel Borkmann. diff --git a/man/curvetun.8 b/man/curvetun.8 deleted file mode 100644 index 37208b4..0000000 --- a/man/curvetun.8 +++ /dev/null @@ -1,196 +0,0 @@ -.\" netsniff-ng - the packet sniffing beast -.\" Copyright 2013 Daniel Borkmann. -.\" Subject to the GPL, version 2. - -.TH CURVETUN 8 "03 March 2013" "Linux" "netsniff-ng toolkit" -.SH NAME -curvetun \- a lightweight Curve25519 IP tunnel - -.SH SYNOPSIS - -\fB curvetun\fR [\fIoptions\fR] - -.SH DESCRIPTION -curvetun is a lightweight, high-speed ECDH multiuser IP tunnel for Linux -that is based on epoll(2). curvetun uses the Linux TUN/TAP interface and -supports {IPv4, IPv6} over {IPv4, IPv6} with UDP or TCP as carrier protocols. - -It has an integrated packet forwarding trie, thus multiple users with -different IPs can be handled via a single tunnel device on the server side -and flows are scheduled for processing in a CPU affine way, at least in case -of TCP as a carrier protocol. - -As key management, public-key cryptography based on elliptic curves are being -used and packets are encrypted end-to-end by the symmetric stream cipher -Salsa20 and authenticated by the MAC Poly1305, where keys have previously -been computed with the ECDH key agreement protocol Curve25519. - -Cryptography is based on Daniel J. Bernstein's networking and cryptography -library ``NaCl''. By design, curvetun does not provide any particular pattern -or default port numbers that gives certainty that the connection from a -particular flow is actually running curvetun. - -However, if you have further needs to bypass censorship, you can try using -curvetun in combination with Tor's obfsproxy or Telex. Furthermore, curvetun -also protects you against replay attacks and DH man in the middle. -Additionally, server-side syslog event logging can also be disabled to not -reveal any critical user connection data. - -.IP " 1." 4 -obfsproxy from the TOR project -.RS 4 -\%https://www.torproject.org/projects/obfsproxy.html.en -.RE - -.IP " 2." 4 -Telex, anticensorship in the network infrastructure -.RS 4 -\%https://telex.cc/ -.RE - -.SH OPTIONS - -todo - -.SH CRYPTOGRAPHY -IP tunnels are usually used to create virtual private networks (VPN), where -parts of the network can only be reached via an unsecure or untrusted underlay -network like the Internet. Only few software exists to create such tunnels, -or, VPNs. Two popular representatives of such software are OpenVPN and VTUN. - -The latter also introduced the TUN/TAP interfaces into the Linux kernel. VTUN -only has a rather basic encryption module, that doesn't fit into todays -cryptographic needs. By default MD5 is used to create 128-Bit wide keys for -the symmetric BlowFish cipher in ECB mode [1]. - -Although OpenSSL is used in both, VTUN and OpenVPN, OpenVPN is much more -feature rich regarding ciphers and user authentication. Nevertheless, letting -people choose ciphers or authentication methods does not necessarily mean a -good thing: administrators could either prefer speed over security and -therefore choose weak ciphers, so that the communication system will be as -good as without any cipher; they could choose weak passwords for symmetric -encryption or they could misconfigure the communication system by having too -much choices of ciphers and too little experience for picking the right one. - -Next to the administration issues, there are also software development issues. -Cryptographic libraries like OpenSSL are a huge mess and too low-level and -complex to probably fully understand or correctly apply, so that they form a -further ground for vulnerabilities of such software. - -In 2010, the cryptographers Tanja Lange and Daniel J. Bernstein have therefore -created and published a cryptography library for networking, which is called -NaCl (pronounced ``salt''). NaCl challenges such addressed problems as in -OpenSSL and, in contrast to the rather generic use of OpenSSL, was created -with a strong focus on public-key authenticated encryption based on elliptic -curve cryptography, which is used in curvetun. Partially quoting Daniel J. -Bernstein: - -RSA is somewhat older than elliptic-curve cryptography: RSA was introduced -in 1977, while elliptic-curve cryptography was introduced in 1985. However, -RSA has shown many more weaknesses than elliptic-curve cryptography. RSA's -effective security level was dramatically reduced by the linear sieve in the -late 1970s, by the quadratic sieve and ECM in the 1980s, and by the -number-field sieve in the 1990s. For comparison, a few attacks have been -developed against some rare elliptic curves having special algebraic -structures, and the amount of computer power available to attackers has -predictably increased, but typical elliptic curves require just as much -computer power to break today as they required twenty years ago. - -IEEE P1363 standardized elliptic-curve cryptography in the late 1990s, -including a stringent list of security criteria for elliptic curves. NIST -used the IEEE P1363 criteria to select fifteen specific elliptic curves at -five different security levels. In 2005, NSA issued a new ``Suite B'' -standard, recommending the NIST elliptic curves (at two specific security -levels) for all public-key cryptography and withdrawing previous -recommendations of RSA. - -curvetun uses a particular elliptic curve, Curve25519, introduced in the -following paper: Daniel J. Bernstein, ``Curve25519: new Diffie-Hellman speed -records,'' pages 207-228 in Proceedings of PKC 2006, edited by Moti Yung, -Yevgeniy Dodis, Aggelos Kiayias, and Tal Malkin, Lecture Notes in Computer -Science 3958, Springer, 2006, ISBN 3-540-33851-9. - -This elliptic curve follows all of the standard IEEE P1363 security criteria. -It also follows new recommendations that achieve ``side-channel immunity'' -and ``twist security'' while improving speed. What this means is that secure -implementations of Curve25519 are considerably simpler and faster than secure -implementations of (e.g.) NIST P-256; there are fewer opportunities for -implementors to make mistakes that compromise security, and mistakes are -more easily caught by reviewers. - -An attacker who spends a billion dollars on special-purpose chips to attack -Curve25519, using the best attacks available today, has about 1 chance in -1000000000000000000000000000 of breaking Curve25519 after a year of computation. -One could achieve similar levels of security with 3000-bit RSA, but -encryption and authentication with 3000-bit RSA are not nearly fast enough -to handle tunnel traffic and would require much more space in network -packets. - -.IP " 1." 4 -Security analysis of VTun -.RS 4 -\%http://www.off.net/~jme/vtun_secu.html -.RE - -.IP " 2." 4 -NaCl: Networking and Cryptography library -.RS 4 -\%http://nacl.cr.yp.to/ -.RE - -.SH SETUP EXAMPLE -If you've never run curvetun before, you need to do an initial setup once. - -At first, make sure that the servers and clients clocks are periodically -synced, for instance, by running a ntp daemon. This is necessary to protect -against replay attacks. Also, make sure if you have read and write access to -/dev/net/tun. You should not run curvetun as root! Then, after you assured -this, the first step is to generate keys and config files. On both, the client -and server do: - -.B curvetun -k - -You are asked for a username. You can use an email address or whatever suits -you. Here, we assume, you've entered 'mysrv1' on the server and 'myclient1' -on the client side. - -Now, all necessary file have been created under ~/.curvetun. Files include -``priv.key'', ``pub.key'', ``username', ``clients'' and ``servers''. - -``clients'' and ``servers'' are empty at the beginning and need to be filled. -The ``clients'' file is meant for the server, so that it knows what clients -are allowed to connect. The ``servers'' file is for the client, where it can -select curvetun servers to connect to. Both files are kept very simple, so that -a single configuration line per client or server is sufficient. - -The client needs to export it's public key data for the server: - -.B curvetun -x - -todo - -.SH NOTE -This software is an experimental prototype intended for researchers. Likely, -it will mature over time, but it is currently not advised using this software -when life is put at risk. - -.SH LEGAL -curvetun is licensed under the GNU GPL version 2.0. - -.SH HISTORY -.B curvetun -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 trafgen (8), -.BR mausezahn (8), -.BR bpfc (8), -.BR ifpps (8), -.BR flowtop (8), -.BR astraceroute (8) - -.SH AUTHOR -Manpage was written by Daniel Borkmann. diff --git a/man/flowtop.8 b/man/flowtop.8 deleted file mode 100644 index 5a4465d..0000000 --- a/man/flowtop.8 +++ /dev/null @@ -1,132 +0,0 @@ -.\" netsniff-ng - the packet sniffing beast -.\" Copyright 2013 Daniel Borkmann. -.\" Subject to the GPL, version 2. - -.TH FLOWTOP 8 "03 March 2013" "Linux" "netsniff-ng toolkit" -.SH NAME -flowtop \- top-like netfilter TCP/UDP/SCTP/DCCP/ICMP(v6) flow tracking - -.SH SYNOPSIS - -\fB flowtop\fR { [\fIoptions\fR] } - -.SH DESCRIPTION - -flowtop is a top-like connection tracking tool that can run on an end host or -small home router. It is able to present TCP, UDP/UDP-lite, SCTP, DCCP, ICMP(v6) -flows that have been collected by the kernel's netfilter connection tracking -framework, thus no packet capturing in user space needs to be done. - -flowtop is able to give you a quick overview of current connections on your -local system, e.g. for debugging purposes or to answer questions like: - - * If you access website X, what other connections are being opened in -the background that I'm not aware of? - * What connections are active that pass ones router? - * I have this proprietary binary Y, where does it connect to? - * To which countries am I sending my data? - * Are there any suspicious background connections on my machine? - * How many connections has binary Z currently active? - -The following information will be presented in flowtop's output: - - * Application name and PID when run on local machine - * Reverse DNS for source and destination - * Geo-location information (country, city) - * Used protocols (IPv4, IPv6, TCP, UDP, SCTP, ICMP, ...) - * Flow port's service name heuristic - * Transport protocol state machine information - -In order for flowtop to work, netfilter/iptables must be active resp. running -on your machine, thus kernel-side connection tracking is active. - -flowtop's intention is just to get a quick look over your active connections. -If you want to have logging, have a look at netfilter's conntrack(8) tools -instead. - -.SH OPTIONS - -.SS -4, --ipv4 -Display IPv4 flows. That's default when flowtop is started without -any arguments. - -.SS -6, --ipv6 -Display IPv6 flows. That's default when flowtop is started without -any arguments. - -.SS -T, --tcp -Display TCP flows. That's default when flowtop is started without -any arguments. - -.SS -U, --udp -Display UDP and UDP-lite flows. - -.SS -D, --dccp -Display DCCP flows. - -.SS -I, --icmp -Display ICMP version 4 and version 6 flows. - -.SS -S, --sctp -Display SCTP flows. - -.SS -s, --show-src -Also show source information of the flow, not only destination information. - -.SS -u, --update -The built-in database update mechanism will be invoked to get Maxmind's -latest database. To configure search locations for databases, the file -/etc/netsniff-ng/geoip.conf contains possible addresses. Thus, to save -bandwidth or for mirroring Maxmind's databases (to bypass their traffic -limit policy), different hosts or IP addresses can be placed into geoip.conf, -separated by a newline. - -.SS -v, --version -Show versioning information. - -.SS -h, --help -Show user help. - -.SH USAGE EXAMPLE - -.SS flowtop -Default ncurses output for flowtop that tracks IPv4, IPv6 flows for TCP. - -.SS flowtop -46UTDISs -This example enables maximum display options for flowtop. - -.SH CONFIG FILES - -Under /etc/netsniff-ng/ there are the following files stored that are used -by flowtop and can be extended if wished: - - * tcp.conf - TCP port/services map - * udp.conf - UDP port/services map - * geoip.conf - GeoIP database mirrors - -.SH BUGS -During fairly high till high connection tracking updates, flowtop's scrolling -can become shortly unresponsive. The right fix would be to replace flowtop's -connection management backend with a better design resp. locking approach. -Still on todo. - -.SH LEGAL -flowtop is licensed under the GNU GPL version 2.0. - -.SH HISTORY -.B flowtop -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 trafgen (8), -.BR mausezahn (8), -.BR ifpps (8), -.BR bpfc (8), -.BR astraceroute (8), -.BR curvetun (8) - -.SH AUTHOR -Manpage was written by Daniel Borkmann. diff --git a/man/ifpps.8 b/man/ifpps.8 deleted file mode 100644 index 46088dd..0000000 --- a/man/ifpps.8 +++ /dev/null @@ -1,105 +0,0 @@ -.\" netsniff-ng - the packet sniffing beast -.\" Copyright 2013 Daniel Borkmann. -.\" Subject to the GPL, version 2. - -.TH IFPPS 8 "03 March 2013" "Linux" "netsniff-ng toolkit" -.SH NAME -ifpps \- top-like networking and system statistics - -.SH SYNOPSIS - -\fB ifpps\fR { [\fIoptions\fR] | [\fIdevice\fR] } - -.SH DESCRIPTION - -ifpps is a small utility which periodically provides top-like networking -and system statistics from the kernel. ifpps gathers its data directly -from procfs files and does not apply any user space monitoring libraries -which would falsify statistics on high load. - -For instance, consider the following scenario: two directly connected -Linux machines with Intel Core 2 Quad Q6600 2.40GHz CPUs, 4 GB RAM, and -an Intel 82566DC-2 Gigabit Ethernet NIC are used for performance evaluation. -One machine generates 64 byte network packets by using the kernel space -packet generator pktgen with a maximum possible packet rate. The other -machine displays statistics about incoming network packets by using i) -iptraf(8) and ii) ifpps. - -iptraf that incorporates pcap(3) shows an average packet rate of -246,000 pps while on the other hand ifpps shows an average packet rate of -1,378,000 pps. Hence, due to copying packets and deferring statistics -creation into user space, measurement error of approx. 460 per cent -occurs. Tools like iptraf might display much more information such as -TCP per flow statistics (therefore the use of the pcap library), which -is not implemented in ifpps, because overall networking statistics are -in our focus; statistics, which are also fairly reliable under high packet -load. - -.SH OPTIONS - -.SS -d <netdev>, --dev <netdev> -Networking device to fetch statistics from, e.g. eth0, wlan0. - -.SS -t <time>, --interval <time> -Statistics refresh interval in milliseconds, default is 1000 ms. - -.SS -p, --promisc -Turn on promiscuous mode for the given networking device. - -.SS -c, --csv -Output (once) the ncurses data to the terminal as gnuplot(1)-ready data. - -.SS -l, --loop -Continuously output the terminal data after a refresh interval. This option -only is available, if option ``-c'' is given. For ``-l'' it is usually -recommended to redirect the output into a file that is later being processed -with gnuplot(1). - -.SS -v, --version -Show versioning information. - -.SS -h, --help -Show user help. - -.SH USAGE EXAMPLE - -.SS ifpps eth0 -Default ncurses output for the eth0 device. - -.SS ifpps -pd eth0 -Ncurses output for the eth0 device in promiscuous mode. - -.SS ifpps -lpcd wlan0 > plot.dat -Continuous terminal output for the wlan0 device in promiscuous mode. - -.SH NOTE -On 10Gbit/s cards or higher, receive and transmit statistics are usually -accumulated each > 1sec. Thus, it might be advised to alter the timing -option to a higher accumulation interval for such cards. - -.SH BUGS -Systems with a failry high number of cores (> 32) are currently not -supported. This should however not be a big deal to fix that. The only -challenge would be to display the presented information in a sane way, -probably by selectively hiding uninteresting statistics. - -.SH LEGAL -ifpps is licensed under the GNU GPL version 2.0. - -.SH HISTORY -.B ifpps -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 trafgen (8), -.BR mausezahn (8), -.BR bpfc (8), -.BR flowtop (8), -.BR astraceroute (8), -.BR curvetun (8) - -.SH AUTHOR -Manpage was written by Daniel Borkmann. diff --git a/man/netsniff-ng.8 b/man/netsniff-ng.8 deleted file mode 100644 index 023f777..0000000 --- a/man/netsniff-ng.8 +++ /dev/null @@ -1,497 +0,0 @@ -.\" netsniff-ng - the packet sniffing beast -.\" Copyright 2013 Daniel Borkmann. -.\" Subject to the GPL, version 2. - -.TH NETSNIFF-NG 8 "03 March 2013" "Linux" "netsniff-ng toolkit" -.SH NAME -netsniff-ng \- the packet sniffing beast - -.SH SYNOPSIS - -\fB netsniff-ng\fR { [\fIoptions\fR] [\fIfilter-expression\fR] } - -.SH DESCRIPTION - -netsniff-ng is a fast, minimal tool to i) analyze network packets, ii) capture -pcap files, iii) replay pcap files or iv) redirect traffic between interfaces -with the help of zero-copy packet(7) sockets. netsniff-ng uses both, Linux -specific RX_RING and TX_RING interfaces to perform zero-copy, that is, to avoid -copies and system call overhead between kernel and user address space. At the -time, we started hacking on netsniff-ng, the pcap(3) library did not use this -zero-copy facility. - -netsniff-ng is Linux specific only, meaning there is no support for other -operating systems, thus we can keep the code footprint quite minimal and to -the point. Linux' packet(7) sockets and its RX_RING and TX_RING interfaces -bypass the normal packet processing path through the networking stack. Thus, -this is the fastest one can get out of the box in terms of capturing or -transmission performance from user space, without having to load unsupported -or non-mainline third-party kernel modules. We explicitly refuse to build -netsniff-ng on top of ntop/PF_RING. Not because we do not like it (we do find -it interesting), but because of the fact that it is not part of the mainline -kernel. Therefore, the ntop project has to maintain/sync out-of-tree drivers -to adapt them to their DNA. Eventually, we went for untainted Linux kernel, -since its code has a higher rate of reviews, maintenance, security and bug -fixes. - -netsniff-ng also supports early packet filtering in the kernel. It has support -for low-level and high-level packet filters that are translated into Berkeley -Packet Filter instructions. - -netsniff-ng can capture pcap files in several different pcap formats that -are interoperable with other tools. It has different pcap I/O methods supported -(scatter-gather, mmap(2), read(2)/write(2)) for efficient to-disc capturing. -netsniff-ng is also able to rotate pcap files based on data size or time -intervals, thus, making it a useful backend tool for subsequent traffic -analysis. - -netsniff-ng itself also supports analysis, dumping or replay of raw 802.11 -frames. For online or offline analysis netsniff-ng has a built-in packet -dissector for currently 802.3 (Ethernet), 802.11* (WLAN), ARP, MPLS, 802.1Q -(VLAN), 802.1QinQ, LLDP, IPv4, IPv6, ICMPv4, ICMPv6, IGMP, TCP and UDP, -including GeoIP location analysis. Since netsniff-ng does not establish any -state or reassembly during packet dissection, its memory footprint is quite -low, thus, making netsniff-ng quite efficient for offline analysis of large -pcap files as well. - -.SH OPTIONS - -.SS -i <dev|pcap|->, -d <dev|pcap|->, --in <dev|pcap|->, --dev <dev|pcap|-> -Defines an input device, that can either be a networking device, a pcap file -or stdin (``-''). In case of a pcap file, the pcap type (``-D'' option) is -determined automatically by the pcap file magic. In case of stdin, it is -assumed that the input stream is a pcap file. - -.SS -o <dev|pcap|dir|cfg|->, --out <dev|pcap|dir|cfg|-> -Defines the output device, that can either be a networking device, a pcap file, -a folder, a trafgen(8) configuration file or stdout (``-''). In case of a pcap -file, that should not have the default pcap type (0xa1b2c3d4), the additional -option ``-T'' must be provided. If a directory is given, then, instead of a -single pcap file, multiple pcap files are generated with rotation based on -maximum file size or a given interval (``-F'' option). A trafgen configuration -file can currently only be specified if the input device is a pcap file. If -stdout is given as a device, then a trafgen configuration will be written to -stdout if the input device is a pcap file, or a pcap file if the input device -is a networking device. - -.SS -f, --filter <bpf-file|expr> -Specifies to not dump all traffic, but to filter the network packet haystack. -As a filter, either a bpfc(8) compiled file can be passed as a parameter or -a tcpdump(1)-like filter expression in quotes. For details regarding the -bpf-file have a look at bpfc(8), for details regarding a tcpdump(1)-like filter -have a look at section ``filter example'' or at pcap-filter(7). A filter -expression may also be passed to netsniff-ng without option ``-f'' in case -there is no subsequent option following after the command-line filter expression. - -.SS -t, --type <type> -This defines some sort of filtering mechanisms in terms of addressing. Possible -values for type are ``host'' (to us), ``broadcast'' (to all), ``multicast'' (to -group), ``others'' (promiscuous mode) or ``outgoing'' (from us). - -.SS -F, --interval <size|time> -If the output device is a folder, with ``-F'' it is possible to define the pcap -file rotation interval either in terms of size or time. Thus, when the interval -limit has been reached, a new pcap file will be started. As size parameter, the -following values are possible ``<num>KiB/MiB/GiB'' while as a time parameter -it can be ``<num>s/sec/min/hrs''. - -.SS -J, --jumbo-support -On default netsniff-ng'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 input or output networking device is a wireless device, it is -possible with netsniff-ng to turn this into monitor mode and create a mon<X> -device that netsniff-ng will be listening on instead of wlan<X>, for instance. -This enables netsniff-ng to analyze, dump, or even replay raw 802.11 frames. - -.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 -P <name>, --prefix <name> -When dumping pcap files into a folder, a file name prefix can be defined with -this option. If not otherwise specified, the default prefix is ``dump-'' followed -by a unix timestamp. - -.SS -T <pcap-magic>, --magic <pcap-magic> -Specify a pcap type for storage. Different pcap types with their various meta -data capabilities are shown with option ``-D''. If not otherwise specified, the -pcap-magic 0xa1b2c3d4, also known as a standard tcpdump-capable pcap format, is -used. Pcap files with swapped endianess are also supported. - -.SS -D, --dump-pcap-types -Dump all available pcap types with their capabilities and magic numbers that -can be used with option ``-T'' and exit. - -.SS -B, --dump-bpf -If a Berkeley Packet Filter is given, e.g. via option ``-f'', then dump the BPF -disassembly to stdout during ring setup. This only serves for informative or -verification purposes. - -.SS -r, --rand -If the input and output device are both networking devices, then this option will -randomize packet order in the output ring buffer. - -.SS -M, --no-promisc -The networking interface will not be put into promiscuous mode. On default, -promiscuous mode is turned on. - -.SS -A, --no-sock-mem -On startup (and shutdown), netsniff-ng is trying to increase socket read and -write buffers if appropriate. This option will prevent netsniff-ng from doing -that. - -.SS -m, --mmap -Use mmap(2) as pcap file I/O. This is default in case of replaying pcap files. - -.SS -G, --sg -Use scatter-gather as pcap file I/O. This is default in case when capturing -pcap files. - -.SS -c, --clrw -Use slower read(2)/write(2) I/O. This is not the default case anywhere, but in -some situations it could be preferred as it has a lower latency on write-back -to disc. - -.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 -b <cpu>, --bind-cpu <cpu> -Pin netsniff-ng to a specific CPU and also pin resp. migrate the NIC's IRQ -CPU affinity to this CPU. This option should be preferred in combination with -``-s'' in case a middle till high packet rate is expected. - -.SS -u <uid>, --user <uid> resp. -g <gid>, --group <gid> -After ring setup drop privileges to a non-root user/group combination. - -.SS -H, --prio-high -Set this process as a high priority process in order to achieve a higher -scheduling rate resp. CPU time. This is however not default setting, since -it could lead to starvation of other processes, e.g. low priority kernel -threads. - -.SS -Q, --notouch-irq -Do not reassign the NIC's IRQ CPU affinity settings. - -.SS -s, --silent -Do not enter the packet dissector at all and do not print any packet information -to the terminal. Just shut up and be silent. This option should be preferred in -combination with pcap recording or replay, since it will not flood your terminal -which causes a significant performance regression. - -.SS -q, --less -Print a less verbose one-line information for each packet to the terminal. - -.SS -X, --hex -Only dump packets in hex format to the terminal. - -.SS -l, --ascii -Only display ASCII prinable characters. - -.SS -U, --update -If geographical IP locationing should be used, the built-in database update -mechanism will be invoked to get Maxmind's latest database. To configure -search locations for databases, the file /etc/netsniff-ng/geoip.conf contains -possible addresses. Thus, to save bandwidth or for mirroring Maxmind's -databases (to bypass their traffic limit policy), different hosts or IP -addresses can be placed into geoip.conf, separated by a newline. - -.SS -V, --verbose -Be more verbose during startup, i.e. show detailled ring setup information. - -.SS -v, --version -Show versioning information. - -.SS -h, --help -Show user help. - -.SH USAGE EXAMPLE - -.SS netsniff-ng -The most simple command is to just run ``netsniff-ng''. This will start -listening on all available networking devices in promiscuous mode and dump -the packet dissector output to the terminal. No files will be recorded. - -.SS netsniff-ng --in eth0 --out dump.pcap -s -T 0xa1e2cb12 -b 0 tcp or udp -Capture TCP or UDP traffic from the networking device eth0 into the pcap file -named dump.pcap, which has netsniff-ng specific pcap extensions (see -``netsniff-ng -D'' for capabilities). Also, do not print the content to the -terminal and pin the process and NIC IRQ affinity to CPU 0. The pcap write -method is scatter-gather I/O. - -.SS netsniff-ng --in wlan0 --rfraw --out dump.pcap --silent --bind-cpu 0 -Put the wlan0 device into monitoring mode and capture all raw 802.11 frames -into the file dump.pcap. Do not dissect and print the content to the terminal -and pin the process and NIC IRQ affinity to CPU 0. The pcap write method is -scatter-gather I/O. - -.SS netsniff-ng --in dump.pcap --mmap --out eth0 -k1000 --silent --bind-cpu 0 -Replay the pcap file dump.pcap which is read through mmap(2) I/O and send -the packets out via the eth0 networking device. Do not dissect and print the -content to the terminal and pin the process and NIC IRQ affinity to CPU 0. -Also trigger the kernel every 1000us to traverse the TX_RING instead of every -10us. Note that the pcap magic type is detected automatically from the pcap -file header. - -.SS netsniff-ng --in eth0 --out eth1 --silent --bind-cpu 0 --type host -r -Redirect network traffic from the networking device eth0 to eth1 for traffic -that is destined for our host, thus ignore broadcast, multicast and promiscuous -traffic. Randomize the order of packets for the outgoing device and do not -print any packet contents to the terminal. Also, pin the process and NIC IRQ -affinity to CPU 0. - -.SS netsniff-ng --in team0 --out /opt/probe/ -s -m -J --interval 100MiB -b 0 -Capture on an aggregated team0 networking device and dump packets into multiple -pcap files that are split into 100MiB each. Use mmap(2) I/O as a pcap write -method, enable support for super jumbo frames up to 64KB, and do not print -the captured data to the terminal. Pin netsniff-ng to and NIC IRQ affinity to -CPU 0. The default pcap magic type is 0xa1b2c3d4 (tcpdump-capable pcap). - -.SS netsniff-ng --in vlan0 --out dump.pcap -c -u `id -u bob` -g `id -g bob` -Capture network traffic on device wlan0 into a pcap file called dump.pcap -by using normal read(2), write(2) I/O for the pcap file (slower but less -latency). Also, after setting up the RX_RING for capture, drop privileges -from root to the user/group ``bob''. Invoke the packet dissector and print -packet contents to the terminal for further analysis. - -.SS netsniff-ng --in any --filter http.bpf -B --jumbo-support --ascii -V -Capture from all available networking interfaces and install a low-level -filter that was previously compiled by bpfc(8) into http.bpf in order to -filter HTTP traffic. Enable super jumbo frame support and only print -human readable packet data to the terminal, and also be more verbose during -setup phase. Moreover, dump a BPF disassembly of http.bpf. - -.SS netsniff-ng --in dump.pcap --out dump.cfg --silent -Convert the pcap file dump.pcap into a trafgen(8) configuration file dump.cfg. -Do not print pcap contents to the terminal. - -.SS netsniff-ng -i dump.pcap -f beacon.bpf -o - -Convert the pcap file dump.pcap into a trafgen(8) configuration file and write -it to stdout. However, do not dump all of its content, but only the one that -passes the low-level filter for raw 802.11 from beacon.bpf. The BPF engine -here is invoked in user space inside of netsniff-ng, so Linux extensions -are not available. - -.SS cat foo.pcap | netsniff-ng -i - -o - -Read a pcap file from stdin and convert it into a trafgen(8) configuration -file to stdout. - -.SH CONFIG FILES - -Under /etc/netsniff-ng/ there are the following files stored that are used -by netsniff-ng and can be extended if wished: - - * oui.conf - OUI/MAC vendor database - * ether.conf - Ethernet type descriptions - * tcp.conf - TCP port/services map - * udp.conf - UDP port/services map - * geoip.conf - GeoIP database mirrors - -.SH FILTER EXAMPLE - -netsniff-ng supports both, low-level and high-level filters that are -attached to its packet(7) socket. Low-level filters are described in -the bpfc(8) man page. - -Low-level filters can be used with netsniff-ng in the following way: - - 1. bpfc foo > bar - 2. netsniff-ng -f bar - -Here, foo is the bpfc program that will be translated into a netsniff-ng -readable ``opcodes'' file and passed to netsniff-ng through the -f option. - -Similarly, high-level filter can be either passed through the -f option, -e.g. -f "tcp or udp" or at the end of all options without the ``-f''. - -The filter syntax is the same as in tcpdump(8), which is described in -the man page pcap-filter(7). Just to quote some examples from pcap-filter(7): - -.SS host sundown -To select all packets arriving at or departing from sundown. - -.SS host helios and \( hot or ace \) -To select traffic between helios and either hot or ace. - -.SS ip host ace and not helios -To select all IP packets between ace and any host except helios. - -.SS net ucb-ether -To select all traffic between local hosts and hosts at Berkeley. - -.SS gateway snup and (port ftp or ftp-data) -To select all ftp traffic through internet gateway snup. - -.SS ip and not net localnet -To select traffic neither sourced from nor destined for local hosts (if you -gateway to one other net, this stuff should never make it onto your local net). - -.SS tcp[tcpflags] & (tcp-syn|tcp-fin) != 0 and not src and dst net localnet -To select the start and end packets (the SYN and FIN packets) of each TCP -conversation that involve a non-local host. - -.SS tcp port 80 and (((ip[2:2] - ((ip[0]&0xf)<<2)) - ((tcp[12]&0xf0)>>2)) != 0) -To select all IPv4 HTTP packets to and from port 80, i.e. print only packets -that contain data, not, for example, SYN and FIN packets and ACK-only packets. -(IPv6 is left as an exercise for the reader.) - -.SS gateway snup and ip[2:2] > 576 -To select IP packets longer than 576 bytes sent through gateway snup. - -.SS ether[0] & 1 = 0 and ip[16] >= 224 -To select IP broadcast or multicast packets that were not sent via Ethernet -broadcast or multicast. - -.SS icmp[icmptype] != icmp-echo and icmp[icmptype] != icmp-echoreply -To select all ICMP packets that are not echo requests/replies (i.e., not -ping packets). - -.SH NOTE -For introducing bit errors, delays with random variation and more -while replaying pcaps, make use of tc(8) with its disciplines such -as netem. - -netsniff-ng does only some basic, architecture generic tuning on -startup. If you are considering to do high performance capturing, -you need to carefully tune your machine, hardware and software-wise. -Simply letting netsniff-ng run without thinking about your underlying -system might not necessarily give you the desired performance. Note -that tuning your system is always a tradeoff and fine-grained -balancing act (e.g. throughput vs. latency). You should know what -you're doing! - -One recommendation for software-based tuning is tuned(8). Besides -that, there are many other things to consider. Just to throw you -a few things that you might want to look at: NAPI networking drivers, -tickless kernel, I/OAT DMA engine, Direct Cache Access, RAM-based -file systems, multi-queues, and many more things. Also, you might -want to read the kernel's Documentation/networking/scaling.txt file -regarding technologies such as RSS, RPS, RFS, aRFS and XPS. Also -check your ethtool(8) settings, e.g. regarding offloading or -Ethernet pause frames etc. - -Moreover, to get a deeper understanding of netsniff-ng internals -and how it interacts with the Linux kernel, the kernel documentation -under Documentation/networking/{packet_mmap.txt, filter.txt, -multiqueue.txt} might be of interest. - -How do you sniff in a switched environment? I rudely refer to dSniff's -documentation that says: - -The easiest route is simply to impersonate the local gateway, stealing -client traffic en route to some remote destination. Of course, the traffic -must be forwarded by your attacking machine, either by enabling kernel IP -forwarding or with a userland program that acccomplishes the same -(fragrouter -B1). - -Several people have reportedly destroyed connectivity on their LAN to the -outside world by arpspoof'ing the gateway, and forgetting to enable IP -forwarding on the attacking machine. Don't do this. You have been warned. - -If you do not need to dump all possible traffic, you have to consider -running netsniff-ng with a BPF filter for the ingress path. For that -purpose, read the bpfc(8) man page. - -Also, to aggregate multiple NICs that you want to capture on, you -should consider using team devices, further explained in libteam resp. -teamd(8). - -The following netsniff-ng pcap magic numbers are compatible with other -tools, at least tcpdump or Wireshark: - - 0xa1b2c3d4 (tcpdump-capable pcap) - 0xa1b23c4d (tcpdump-capable pcap with ns resolution) - 0xa1b2cd34 (Alexey Kuznetzov's pcap) - -Pcap files with different meta data endianess are supported by netsniff-ng -as well. - -.SH BUGS - -When replaying pcap files, the timing information from the pcap packet -header is currently ignored. - -Also, when replaying pcap files, demultiplexing traffic among multiple -networking interfaces does not work. Currently, it is only sent via the -interface that is given by the --out parameter. - -When performing traffic capture on the Ethernet interface, the pcap file -is created and packets are received but without a 802.1Q header. When one -uses tshark, all headers are visible, but netsniff-ng removes 802.1Q -headers. Is that normal behavior? - -Yes and no. The way how VLAN headers are handled in PF_PACKET sockets by the -kernel is somewhat ``problematic'' [1]. The problem in the Linux kernel is that -some drivers already handle VLAN, others not. Those who handle it can have -different implementations, i.e. hardware acceleration and so on. So in some -cases the VLAN tag is even stripped before entering the protocol stack, in -some cases probably not. Bottom line is that a "hack" was introduced in -PF_PACKET so that a VLAN ID is visible in some helper data structure that is -accessible from the RX_RING. - -And then it gets really messy in the user space to artificially put the VLAN -header back into the right place. Not mentioning about the resulting performance -implications on that of all libpcap(3) tools since parts of the packet need to -be copied for reassembly via memmove(3). - -A user reported the following, just to demonstrate this mess: some tests were -made with two machines, and it seems that results depends on the driver ... - AR8131: - ethtool -k eth0 gives "rx-vlan-offload: on" - - wireshark gets the vlan header - - netsniff-ng doesn't get the vlan header - ethtool -K eth0 rxvlan off - - wireshark gets a QinQ header even though noone sent QinQ - - netsniff-ng gets the vlan header - RTL8111/8168B: - ethtool -k eth0 gives "rx-vlan-offload: on" - - wireshark gets the vlan header - - netsniff-ng doesn't get the vlan header - ethtool -K eth0 rxvlan off - - wireshark gets the vlan header - - netsniff-ng doesn't get the vlan header -Even if we would agree on doing the same workaround as libpcap, we still will -not be able to see QinQ, for instance, due to the fact that only one VLAN tag -is stored in the kernel helper data structure. We think that there should be -a good consensus on the kernel space side about what gets transferred to the -userland first. - -Update (28.11.2012): the Linux kernel and also bpfc(8) has built-in support -for hardware accelerated VLAN filtering, even though tags might not be visible -in the payload itself as reported here. However, the filtering for VLANs works -reliable if your NIC supports it. See bpfc(8) for an example. - - [1] http://lkml.indiana.edu/hypermail/linux/kernel/0710.3/3816.html - -.SH LEGAL -netsniff-ng is licensed under the GNU GPL version 2.0. - -.SH HISTORY -.B netsniff-ng -was originally written for the netsniff-ng toolkit by Daniel Borkmann. Bigger -contributions were made by Emmanuel Roullit, Markus Amend, Tobias Klauser and -Christoph Jaeger. It is currently maintained by Tobias Klauser -<tklauser@distanz.ch> and Daniel Borkmann <dborkma@tik.ee.ethz.ch>. - -.SH SEE ALSO -.BR trafgen (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. 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. |