summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDaniel Borkmann <dborkman@redhat.com>2013-04-30 16:44:52 +0200
committerDaniel Borkmann <dborkman@redhat.com>2013-04-30 16:44:52 +0200
commitfc1d0ad07313b66e50f202bfe738554f1491fc15 (patch)
tree1b39e53cdd01c7d8ac54a59b5b6f9cb29be8b70f
parenta9e85e99a779eff5ac64b957bb51853404803a33 (diff)
man: trafgen: configuration syntax section
This adds the packet configuration syntax section for trafgen's man page. Signed-off-by: Daniel Borkmann <dborkman@redhat.com>
-rw-r--r--man/trafgen.8164
1 files changed, 160 insertions, 4 deletions
diff --git a/man/trafgen.8 b/man/trafgen.8
index 80c1359..a919ed8 100644
--- a/man/trafgen.8
+++ b/man/trafgen.8
@@ -162,10 +162,166 @@ Show versioning information.
Show user help.
.SH SYNTAX
-TODO
-
-.SH SOURCE EXAMPLES
-TODO
+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()
+ counter: TODO
+
+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
TODO