man: mausezahn: add howto for interactive mode

It is quite useful to have an initial walkthrough for the interactive
mode documented, so add a first version of this [1] into the man page.

  [1] original here: http://pub.netsniff-ng.org/docs/Mausezahn

Formatting still needs to be fixed up in follow-up commits.

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

1 files changed, 871 insertions, 0 deletions

diff --git a/mausezahn.8 b/mausezahn.8
index 1c89b29..25e47ea 100644
--- a/mausezahn.8
+++ b/mausezahn.8
@@ -209,6 +209,877 @@ simultaneously and sweep through the whole TCP sequence number space with an
 increment of 1500. Finally set the urgent pointer to 666, i.e. pointing to
 nowhere.
 
+.SH INTERACTIVE MODE HOWTO
+Using the interactive mode requires to start mausezahn as server:
+
+  mausezahn -x
+
+Now you can telnet to that server using the default port number 25542, but also
+an arbitrary port number can be specified:
+
+  mausezahn -x 99
+
+mausezahn accepts incoming telnet connections on port 99.
+
+  mz: Problems opening config file. Will use defaults
+
+Either from another terminal or from another host try to telnet to the
+mausezahn server:
+
+  caprica$ telnet galactica 99
+  Trying 192.168.0.4...
+  Connected to galactica.
+  Escape character is '^]'.
+  mausezahn 0.5.8-rc0
+
+  Username: mz
+  Password: mz
+
+  mz> enable
+  Password: mops
+  mz#
+
+It is recommended to configure your own login credentials in
+/etc/mausezahn/mz.cfg, such as:
+
+  user = foo
+  password = bar
+  enable = bla
+
+Since you reached the mausezahn prompt, lets try some first commands. You can
+use the '?' character at any time for a content-sensitive help.
+
+First try out the show command:
+
+  mz# show ?
+
+mausezahn maintains its own ARP table and observes anomalies. There is an entry
+for every physical interface (however this host has only one):
+
+  mz# sh arp
+  Intf    Index     IP address     MAC address       last       Ch  UCast BCast Info
+  ----------------------------------------------------------------------------------
+  eth0    [1] D     192.168.0.1  00:09:5b:9a:15:84  23:44:41     1     1     0  0000
+
+The column Ch tells us that the announced MAC address has only changed one time
+(= when it was learned). The columns Ucast and BCast tell us how often this
+entry was announced via unicast or broadcast respectively.
+
+Let's check our interfaces:
+
+  mz# show interface
+  Available network interfaces:
+                 real             real                  used (fake)      used (fake)
+   device        IPv4 address     MAC address           IPv4 address     MAC address
+  ---------------------------------------------------------------------------------------
+  > eth0         192.168.0.4      00:30:05:76:2e:8d     192.168.0.4      00:30:05:76:2e:8d
+    lo           127.0.0.1        00:00:00:00:00:00     127.0.0.1        00:00:00:00:00:00
+  2 interfaces found.
+  Default interface is eth0.
+
+Defining packets:
+
+Let's check the current packet list:
+
+  mz# sh packet
+  Packet layer flags: E=Ethernet, S=SNAP, Q=802.1Q, M=MPLS, I/i=IP/delivery_off, U=UDP, T=TCP
+  PktID  PktName           Layers  Proto    Size  State      Device      Delay       Count/CntX
+      1  sysARP_servic...  E-----  ARP        60  config     lo          100 msec        1/0 (100%)
+  1 packets defined, 0 active.
+
+We notice that there is already one system-defined packet process; it has been
+created and used only once (during startup) by mausezahn's ARP service.
+Currently, its state is config which means that the process is sleeping.
+
+General packet options:
+
+Now let's create our own packet process and therefore switch into the global
+configuration mode:
+
+  mz# configure term
+  mz(config)# packet
+  Allocated new packet PKT0002 at slot 2
+  mz(config-pkt-2)# ?
+  ...
+  name                 Assign a unique name
+  description          Assign a packet description text
+  bind                 Select the network interface
+  count                Configure the packet count value
+  delay                Configure the inter-packet delay
+  interval             Configure a greater interval
+  type                 Specify packet type
+  mac                  Configure packet's MAC addresses
+  tag                  Configure tags
+  payload              Configure a payload
+  port                 Configure packet's port numbers
+  end                  End packet configuration mode
+  ethernet             Configure frame's Ethernet, 802.2, 802.3, or SNAP settings
+  ip                   Configure packet's IP settings
+  udp                  Configure packet's UDP header parameters
+  tcp                  Configure packet's TCP header parameters
+
+Here are a lot of options but normally you only need a few of them. When you
+configure lots of different packets you might assign a reasonable name and
+description for them:
+
+  mz(config-pkt-2)# name Test
+  mz(config-pkt-2)# desc This is just a test
+
+You can e.g. change the default settings for the source and destination MAC/IP
+addresses using the mac and ip commands:
+
+  mz(config-pkt-2)# ip address dest 10.1.1.0 /24
+  mz(config-pkt-2)# ip addr source random
+
+In the example above, we configured a range of addresses (all hosts in the
+network 10.1.1.0 should be addressed). Additionally we spoof our source IP
+address. Of course, we can also add one or more VLAN and/or MPLS tag(s):
+
+  mz(config-pkt-2)# tag ?
+  dot1q                Configure 802.1Q (and 802.1P) parameters
+  mpls                 Configure MPLS label stack
+  mz(config-pkt-2)# tag dot ?
+  Configure 802.1Q tags:
+  VLAN[:CoS] [VLAN[:CoS]] ...   The leftmost tag is the outer tag in the frame
+  remove <tag-nr> | all         Remove one or more tags (<tag-nr> starts with 1),
+                                by default the first (=leftmost,outer) tag is removed,
+                                keyword 'all' can be used instead of tag numbers.
+  cfi | nocfi [<tag-nr>]        Set or unset the CFI-bit in any tag (by default
+                                assuming the first tag).
+  mz(config-pkt-2)# tag dot 1:7 200:5
+
+Configure count and delay:
+
+  mz(config-pkt-2)# count 1000
+  mz(config-pkt-2)# delay ?
+  delay <value> [hour | min | sec | msec | usec | nsec]
+
+Specify the inter-packet delay in hours, minutes, seconds, milliseconds,
+microseconds or nanoseconds. The default unit is milliseconds (i.e. when no
+unit is given).
+
+  mz(config-pkt-2)# delay 1 msec
+  Inter-packet delay set to 0 sec and 1000000 nsec
+  mz(config-pkt-2)#
+
+Configuring protocol types:
+
+mausezahn's interactive mode supports a growing list of protocols and only
+relies on the MOPS architecture (and not on libnet as it is the case with
+the legacy direct mode):
+
+  mz(config-pkt-2)# type
+  Specify a packet type from the following list:
+  arp
+  bpdu
+  igmp
+  ip
+  lldp
+  tcp
+  udp
+  mz(config-pkt-2)# type tcp
+  mz(config-pkt-2-tcp)#
+  ....
+  seqnr                Configure the TCP sequence number
+  acknr                Configure the TCP acknowledgement number
+  hlen                 Configure the TCP header length
+  reserved             Configure the TCP reserved field
+  flags                Configure a combination of TCP flags at once
+  cwr                  Set or unset the TCP CWR flag
+  ece                  Set or unset the TCP ECE flag
+  urg                  Set or unset the TCP URG flag
+  ack                  set or unset the TCP ACK flag
+  psh                  set or unset the TCP PSH flag
+  rst                  set or unset the TCP RST flag
+  syn                  set or unset the TCP SYN flag
+  fin                  set or unset the TCP FIN flag
+  window               Configure the TCP window size
+  checksum             Configure the TCP checksum
+  urgent-pointer       Configure the TCP urgend pointer
+  options              Configure TCP options
+  end                  End TCP configuration mode
+  mz(config-pkt-2-tcp)# flags syn fin rst
+  Current setting is: --------------------RST-SYN-FIN
+  mz(config-pkt-2-tcp)# end
+  mz(config-pkt-2)# paylo ascii This is a dummy payload for my first packet
+  mz(config-pkt-2)# end
+
+Now configure another packet, for example let's assume we want an LLDP process:
+
+  mz(config)# packet
+  Allocated new packet PKT0003 at slot 3
+  mz(config-pkt-3)# ty lldp
+  mz(config-pkt-3-lldp)# exit
+  mz(config)# exit
+
+In the above example we only use the default LLDP settings and don't configure
+further LLDP options or TLVs. Back in the top level of the CLI let's verify
+what we had done:
+
+  mz# sh pa
+  Packet layer flags: E=Ethernet, S=SNAP, Q=802.1Q, M=MPLS, I/i=IP/delivery_off, U=UDP, T=TCP
+  PktID  PktName            Layers  Proto    Size  State      Device   Delay      Count/CntX
+     1   sysARP_servic...   E-----  ARP        60  config     lo       100 msec       1/0 (100%)
+     2   Test               E-Q-IT            125  config     eth0    1000 usec    1000/1000 (0%)
+     3   PKT0003            E-----  LLDP       36  config     eth0      30 sec        0/0 (0%)
+  3 packets defined, 0 active.
+
+The column Layers indicates which major protocols have been combined. For
+example the packet with packet-id 2 ("Test") utilizes Ethernet (E),
+IP (I), and TCP (T). Additionally an 802.1Q tag (Q) has been inserted. Now
+start one of these packet processes:
+
+  mz# start slot 3
+  Activate [3]
+  mz# sh pac
+  Packet layer flags: E=Ethernet, S=SNAP, Q=802.1Q, M=MPLS, I/i=IP/delivery_off, U=UDP, T=TCP
+  PktID  PktName            Layers  Proto    Size  State      Device   Delay      Count/CntX
+     1   sysARP_servic...   E-----  ARP        60  config     lo       100 msec       1/0 (100%)
+     2   Test               E-Q-IT            125  config     eth0    1000 usec    1000/1000 (0%)
+     3   PKT0003            E-----  LLDP       36  config     eth0      30 sec        0/1 (0%)
+  3 packets defined, 1 active.
+
+Let's have a more detailed look at a specific packet process:
+
+  mz# sh pac 2
+  Packet [2] Test
+  Description: This is just a test
+  State: config, Count=1000, delay=1000 usec (0 s 1000000 nsec), interval= (undefined)
+  Headers:
+   Ethernet: 00-30-05-76-2e-8d => ff-ff-ff-ff-ff-ff  [0800 after 802.1Q tag]
+   Auto-delivery is ON (that is, the actual MAC is adapted upon transmission)
+   802.1Q: 0 tag(s);  (VLAN:CoS)
+   IP:  SA=192.168.0.4 (not random) (no range)
+        DA=255.255.255.255 (no range)
+        ToS=0x00  proto=17  TTL=255  ID=0  offset=0  flags: -|-|-
+        len=49664(correct)  checksum=0x2e8d(correct)
+   TCP: 83 bytes segment size (including TCP header)
+        SP=0 (norange) (not random), DP=0 (norange) (not random)
+        SQNR=3405691582 (start 0, stop 4294967295, delta 0) -- ACKNR=0 (invalid)
+        Flags: ------------------------SYN----, reserved field is 00, urgent pointer= 0
+        Announced window size= 100
+        Offset= 0 (times 32 bit; value is valid), checksum= ffff (valid)
+        (No TCP options attached) - 0 bytes defined
+   Payload size: 43 bytes
+   Frame size: 125 bytes
+    1  ff:ff:ff:ff:ff:ff:00:30  05:76:2e:8d:81:00:e0:01  81:00:a0:c8:08:00:45:00  00:67:00:00:00:00:ff:06
+   33  fa:e4:c0:a8:00:04:ff:ff  ff:ff:00:00:00:00:ca:fe  ba:be:00:00:00:00:a0:07  00:64:f7:ab:00:00:02:04
+   65  05:ac:04:02:08:0a:19:35  90:c3:00:00:00:00:01:03  03:05:54:68:69:73:20:69  73:20:61:20:64:75:6d:6d
+   97  79:20:70:61:79:6c:6f:61  64:20:66:6f:72:20:6d:79  20:66:69:72:73:74:20:70  61:63:6b:65:74
+  mz#
+
+If you want to stop one or more packet processes, use the stop command. The
+"emergency stop" is when you use stop all:
+
+  mz# stop all
+  Stopping
+  [3] PKT0003
+  Stopped 1 transmission processe(s)
+
+The launch command provides a shortcut for commonly used packet processes. For
+example to behave like a STP-capable bridge we want to start an BPDU process
+with typical parameters:
+
+  mz# laun bpdu
+  Allocated new packet sysBPDU at slot 5
+  mz# sh pac
+  Packet layer flags: E=Ethernet, S=SNAP, Q=802.1Q, M=MPLS, I/i=IP/delivery_off, U=UDP, T=TCP
+  PktID  PktName           Layers  Proto    Size  State      Device      Delay       Count/CntX
+      1  sysARP_servic...  E-----  ARP        60  config     lo          100 msec        1/0 (100%)
+      2  Test              E-Q-IT            125  config     eth0       1000 usec     1000/1000 (0%)
+      3  PKT0003           E-----  LLDP       36  config     eth0          30 sec        0/12 (0%)
+      4  PKT0004           E---I-  IGMP       46  config     eth0        100 msec        0/0 (0%)
+      5  sysBPDU           ES----  BPDU       29  active     eth0           2 sec        0/1 (0%)
+  5 packets defined, 1 active.
+
+Now a Configuration BPDU is sent every 2 seconds, claiming to be the root
+bridge (and usually confusing the LAN. Note that only packet 5 (i.e. the
+last row) is active and therefore sending packets while all other packets
+are in state config (i.e. they have been configured but they are not doing
+anything at the moment).
+
+Configuring a greater interval:
+
+Sometimes you may want to send a burst of packets at a greater interval:
+
+  mz(config)# pac 2
+  Modify packet parameters for packet Test [2]
+  mz(config-pkt-2)# interv
+  Configure a greater packet interval in days, hours, minutes, or seconds
+  Arguments: <value>  <days | hours | minutes | seconds>
+  Use a zero value to disable an interval.
+  mz(config-pkt-2)# interv 1 h
+  mz(config-pkt-2)# count 10
+  mz(config-pkt-2)# delay 15 usec
+  Inter-packet delay set to 0 sec and 15000 nsec
+
+Now this packet is sent ten times with an inter-packet delay of 15 microsecond
+and this is repeated every hour. When you look at the packet list, an interval
+is indicated with the additional flag 'i' when inactive or 'I' when active:
+
+  mz# sh pa
+  Packet layer flags: E=Ethernet, S=SNAP, Q=802.1Q, M=MPLS, I/i=IP/delivery_off, U=UDP, T=TCP
+  PktID  PktName           Layers  Proto    Size  State      Device      Delay       Count/CntX
+      1  sysARP_servic...  E-----  ARP        60  config     lo          100 msec        1/0 (100%)
+      2  Test              E-Q-IT            125  config-i   eth0         15 usec       10/10 (0%)
+      3  PKT0003           E-----  LLDP       36  config     eth0          30 sec        0/12 (0%)
+      4  PKT0004           E---I-  IGMP       46  config     eth0        100 msec        0/0 (0%)
+      5  sysBPDU           ES----  BPDU       29  active     eth0           2 sec        0/251 (0%)
+  5 packets defined, 1 active.
+  mz# start sl 2
+  Activate [2]
+  mz# sh pa
+  Packet layer flags: E=Ethernet, S=SNAP, Q=802.1Q, M=MPLS, I/i=IP/delivery_off, U=UDP, T=TCP
+  PktID  PktName           Layers  Proto    Size  State      Device      Delay       Count/CntX
+      1  sysARP_servic...  E-----  ARP        60  config     lo          100 msec        1/0 (100%)
+      2  Test              E-Q-IT            125  config+I   eth0         15 usec       10/0 (100%)
+      3  PKT0003           E-----  LLDP       36  config     eth0          30 sec        0/12 (0%)
+      4  PKT0004           E---I-  IGMP       46  config     eth0        100 msec        0/0 (0%)
+      5  sysBPDU           ES----  BPDU       29  active     eth0           2 sec        0/256 (0%)
+  5 packets defined, 1 active.
+
+Note that the flag 'I' indicates that an interval has been specified for
+packet 2. The process is not active at the moment (only packet 5 is active
+here) but it will become active in a regular interval. You can verify the
+actual interval when viewing the packet details via the show packet 2 command.
+
+Load prepared configurations:
+
+You can prepare packet configurations using the same commands as you would
+type them in on the CLI and then load them to the CLI. For example assume we
+have prepared a file 'test.mops' containing:
+
+  configure terminal
+  packet
+  name IGMP_TEST
+  desc This is only a demonstration how to load a file to mops
+  type igmp
+
+Then we can add this packet configuration to our packet list using the load
+command:
+
+  mz# load test.mops
+  Read commands from test.mops...
+  Allocated new packet PKT0002 at slot 2
+  mz# sh pa
+  Packet layer flags: E=Ethernet, S=SNAP, Q=802.1Q, M=MPLS, I/i=IP/delivery_off, U=UDP, T=TCP
+  PktID  PktName           Layers  Proto    Size  State      Device      Delay       Count/CntX
+      1  sysARP_servic...  E-----  ARP        60  config     lo          100 msec        1/0 (100%)
+      2  IGMP_TEST         E---I-  IGMP       46  config     eth0        100 msec        0/0 (0%)
+  2 packets defined, 0 active.
+
+The file src/examples/mausezahn/example_lldp.conf contains another example
+list of commands to create a bogus LLDP packet. You can load this
+configuration from the mausezahn command line, e.g. via:
+
+  mz-0.39# load /home/hh/tmp/example_lldp.conf
+
+In case you copied the file in that path. Now when you enter 'show packet' you
+will see a new packet entry in the packet list. Use the 'start slot <nr>'
+command to activate this packet.
+
+You can store your own packet creations in such file and easily load them when
+you need them. Every command within such configuration files is executed on the
+command line interface as if you had typed it in -- so be careful about the
+order and don't forget to use 'configure terminal' as first command.
+
+You can even load other files from within a central config file.
+
+.SH DIRECT MODE HOWTO
+How to specify hex digits:
+
+Many arguments allow direct byte input. Bytes are represented as two
+hexadecimal digits. Multiple bytes must be separated either by spaces, colons,
+or dashes - whatever you prefer. The following byte strings are equivalent:
+
+  "aa:bb cc-dd-ee ff 01 02 03-04 05"
+  "aa bb cc dd ee ff:01:02:03:04 05"
+
+As first example, you may want to send an arbitrary fancy (possibly invalid)
+frame right through your network card:
+
+  mausezahn ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:08:00:ca:fe:ba:be
+
+ or equivalently but more readable:
+
+  mausezahn ff:ff:ff:ff:ff:ff-ff:ff:ff:ff:ff:ff-08:00-ca:fe:ba:be
+
+Basic operations:
+
+All major command line options are listed when you execute mausezahn without
+arguments. For practical usage keep the following special (not so widely
+known) options in mind:
+
+  -r                    Multiplies the specified delay with a random value.
+  -p <length>           Pad the raw frame to specified length (using random
+                        bytes).
+  -P <ASCII Payload>    Use the specified ASCII payload.
+  -f <filename>         Read the ASCII payload from a file.
+  -F <filename>         Read the hexadecimal payload from a file.
+  -S                    Simulation mode: DOES NOT put anything on the wire.
+                        This is typically combined with one of the verbose
+                        modes (-v or V).
+
+Many options require a keyword or a number but the -t option is an exception
+since it requires both a packet type (such as ip, udp, dns, etc) and an
+argument string which is specific for that packet type. Here are some simple
+examples:
+
+  mausezahn -t help
+  mausezahn -t tcp help
+  mausezahn eth3 -t udp sp=69,dp=69,p=ca:fe:ba:be
+
+Note: Don't forget that on the CLI the Linux shell (usually the Bash)
+interprets spaces as a delimiter character. That is, if you are specifying
+an argument that consists of multiple words with spaces in between, you MUST
+group this with quotes. For example, instead of
+
+  mausezahn eth0 -t udp sp=1,dp=80,p=00:11:22:33
+
+ you could either omit the spaces
+
+  mausezahn eth0 -t udp sp=1,dp=80,p=00:11:22:33
+
+ or, even more safe, use quotes:
+
+  mausezahn eth0 -t udp "sp=1,dp=80,p=00:11:22:33"
+
+In order to monitor what's going on, you can enable the verbose mode using
+the -v option. The opposite is the quiet mode (-q) which will keep mausezahn
+absolutely quiet (except for error messages and warnings.)
+
+Don't confuse the payload argument p=... with the padding option -p. The latter
+is used outside the quotes!
+
+The automatic packet builder:
+
+An important argument is "-t" which invokes a packet builder. Currently there
+are packet builders for ARP, BPDU, CDP, IP, partly ICMP, UDP, TCP, RTP, DNS,
+and SYSLOG. (Additionally you can insert a VLAN tag or a MPLS label stack but
+this works independent of the packet builder.)
+
+You get context specific help of every packet builder using the help keyword,
+such as:
+
+  mausezahn -t bpdu help
+  mausezahn -t tcp help
+
+For every packet you may specify an optional payload. This can be done either
+via HEX notation using the payload (or short p) argument or directly as ASCII
+text using the -P option:
+
+  mausezahn eth0 -t ip -P "Hello World"                           # ASCII payload
+  mausezahn eth0 -t ip p=68:65:6c:6c:6f:20:77:6f:72:6c:64         # hex payload
+  mausezahn eth0 -t ip "proto=89,                           \
+                        p=68:65:6c:6c:6f:20:77:6f:72:6c:64, \     # same with other
+                        ttl=1"                                    # IP arguments
+
+Note: The raw link access mode only accepts hex payloads (because you specify
+everything in hex here.)
+
+Packet count and delay:
+
+Per default only one packet is sent. If you want to send more packets then
+use the count option -c <count>. When count is zero then mausezahn will send
+forever. Per default mausezahn sends at maximum speed (and this is really 
+fast ;-)). If you don't want to overwhelm your network devices or have other
+reasons to send at a slower rate then you might want to specify a delay using
+the -d <delay> option.
+
+If you only specify a numeric value it is interpreted in microsecond units.
+Alternatively, for easier use, you might specify units such as seconds sec or
+milliseconds msec. (You can also abbreviate this with s or m.) Note: Don't use
+spaces between the value and the unit! Here are typical examples:
+
+Send infinite frames as fast as possible:
+
+  mausezahn -c 0  "aa bb cc dd ...."
+
+Send 100,000 frames with a 50 msec interval:
+
+  mausezahn -c 100000  -d 50msec "aa bb cc dd ...."
+
+Send infinite BPDU frames in a 2 second interval:
+
+  mausezahn -c 0 -d 2s -t bpdu conf
+
+Note: mausezahn does not support fractional numbers. If you want to specify for
+example 2.5 seconds then express this e.g. in milliseconds (2500 msec).
+
+Source and destination addresses:
+
+As mnemonic trick keep in mind that all packets run from "A" to "B". You can
+always specify source and/or destination MAC addresses using the -a and -b
+options, respectively. These options also allow keywords such as rand, own,
+bpdu, cisco, and others.
+
+Similarly, you can specify source and destination IP addresses using the -A
+and -B options, respectively. These options also support FQDNs (i.e. domain
+names) and ranges such as 192.168.0.0/24 or 10.0.0.11-10.0.3.22. Additionally
+(only) the source address supports the rand keyword (ideal for "attacks").
+
+Note: When you use the packet builder for IP-based packets (e.g. UDP or TCP)
+then mausezahn automatically cares about correct MAC and IP addresses (i.e.
+it performs ARP, DHCP, and DNS for you). But when you specify at least a single
+link-layer address (or any other L2 option such as a VLAN tag or MPLS header)
+then ARP is disabled and you must care for the Ethernet destination address for
+yourself.
+
+Layer-2:
+
+* Direct link access:
+
+mausezahn allows you to send ANY chain of bytes directly through your Ethernet
+interface:
+
+  mausezahn eth0 "ff:ff:ff:ff:ff:ff ff:ff:ff:ff:ff:ff 00:00 ca:fe:ba:be"
+
+This way you can craft every packet you want but you must do it by hand. Note:
+On WiFi interfaces the header is much more complicated and automatically
+created by the WiFi-driver. As example to introduce some interesting options,
+lets continuously send frames at max speed with random source MAC address and
+broadcast destination address, additionally pad the frame to 1000 bytes:
+
+  mausezahn eth0 -c 0 -a rand -b bcast -p 1000 "08 00 aa bb cc dd"
+
+The direct link access supports automatic padding using the -p <total frame
+length> option. This allows you to pad a raw L2 frame to the desired length.
+You must specify the total length and the total frame length must have at
+least 15 bytes for technical reasons. Zero bytes are used for this padding.
+
+* ARP:
+
+mausezahn provides a simple interface to the ARP packet. You can specify the
+ARP method (request|reply) and up to four arguments: sendermac, targetmac,
+senderip, targetip, or short smac, tmac, sip, tip. By default an ARP reply is
+sent with your own interface addresses as source MAC and IP address, and a
+broadcast destination MAC/IP address. Send a gratitious ARP (as used for
+duplicate IP detection):
+
+  mausezahn eth0 -t arp
+
+ARP cache poisoning:
+
+  mausezahn eth0 -t arp "reply, senderip=192.168.0.1, targetmac=00:00:0c:01:02:03, \
+                         targetip=172.16.1.50"
+
+ where by default your interface MAC address will be used as sendermac,
+senderip denotes the spoofed IP, targetmac and targetip identifies the
+receiver. By default the Ethernet source address is your interface MAC and the
+destination address is broadcast. Of course you can change this using again the
+flags -a and -b.
+
+* BPDU:
+
+mausezahn provides a simple interface to the 802.1d BPDU frame format (used to
+create the Spanning Tree in bridged networks). By default standard IEEE 802.1d
+(CST) BPDUs are sent and it is assumed that your computer wants to become the
+root bridge (rid=bid). Optionally the 802.3 destination address can be a
+specified MAC address, broadcast, own MAC, or Cisco's PVST+ MAC address. The
+destination MAC can be specified using the -b command which (besides MAC
+addresses) accepts keywords such as bcast, own, pvst, or stp (default). Since
+version 0.16 PVST+ is supported. Simply specify the VLAN for which you want
+to send a BPDU:
+
+  mausezahn eth0 -t bpdu "vlan=123, rid=2000"
+
+See mausezahn -t bpdu help for more details.
+
+* CDP:
+
+mausezahn can send Cisco Discovery Protocol (CDP) messages since this protocol
+has security relevance. Of course lots of dirty tricks are possible; for
+example arbitrary TLVs can be created (using the hex-payload argument for
+example p=00:0e:00:07:01:01:90) and if you want to stress the CDP database of
+some device, mausezahn can send each CDP message with another system-id using
+the change keyword:
+
+  mausezahn -t cdp change -c 0
+
+Some routers and switches may run into deep problems ;-) See
+mausezahn -t cdp help for more details.
+
+* 802.1Q VLAN Tags:
+
+mausezahn allows simple VLAN tagging for IP (and other higher layer) packets.
+Simply use the option -Q <[CoS:]VLAN>, such as -Q 10 or -Q 3:921. By
+default CoS=0. For example send a TCP packet in VLAN 500 using CoS=7:
+
+  mausezahn eth0 -t tcp -Q 7:500 "dp=80, flags=rst, p=aa:aa:aa"
+
+You can create as many VLAN tags as you want! This is interesting to create
+QinQ encapsulations or VLAN hopping: Send a UDP packet with VLAN tags 100
+(outer) and 651 (inner):
+
+  mausezahn eth0 -t udp "dp=8888, sp=13442" -P "Mausezahn is great" -Q 100,651
+
+Don't know if this is useful anywhere but at least it is possible:
+
+  mausezahn eth0 -t udp "dp=8888, sp=13442" -P "Mausezahn is great"  \
+                 -Q 6:5,7:732,5:331,5,6
+
+Mix it with MPLS:
+
+  mausezahn eth0 -t udp "dp=8888, sp=13442" -P "Mausezahn is great" -Q 100,651 -M 314
+
+Only in raw Layer 2 mode you must create the VLAN tag completely by yourself.
+For example if you want to send a frame in VLAN 5 using CoS 0 simply specify
+81:00 as type field and for the next two bytes the CoS (, CFI) and VLAN values:
+
+  mausezahn eth0 -b bc -a rand "81:00 00:05 08:00 aa-aa-aa-aa-aa-aa-aa-aa-aa"
+
+* MPLS labels:
+
+mausezahn allows you to insert one or more MPLS headers. Simply use the option
+-M <label:CoS:TTL:BoS> where only the label is mandatory. If you specify a
+second number it is interpreted as the experimental bits (the CoS usually). If
+you specify a third number it is interpreted as TTL. Per default the TTL is
+set to 255. The Bottom of Stack flag is set automatically (otherwise the frame
+would be invalid) but if you want you can also set or unset it using the
+S (set) and s (unset) argument. Note that the BoS must be the last argument in
+each MPLS header definition. Here are some examples:
+
+Use MPLS label 214:
+
+  mausezahn eth0 -M 214 -t tcp "dp=80" -P "HTTP..." -B myhost.com
+
+Use three labels (the 214 is now the outer):
+
+  mausezahn eth0 -M 9999,51,214 -t tcp "dp=80" -P "HTTP..." -B myhost.com
+
+Use two labels, one with CoS=5 and TTL=1, the other with CoS=7:
+
+  mausezahn eth0 -M 100:5:1,500:7 -t tcp "dp=80" -P "HTTP..." -B myhost.com
+
+Unset the BoS flag (which will result in an invalid frame):
+
+  mausezahn eth0 -M 214:s -t tcp "dp=80" -P "HTTP..." -B myhost.com
+
+Layer 3-7:
+
+IP, UDP, and TCP packets can be padded using the -p option. Currently 0x42 is
+used as padding byte ('the answer'). You cannot pad DNS packets (would be
+useless anyway).
+
+* IP:
+
+mausezahn allows you to send any (malformed or correct) IP packet. Every field
+in the IP header can be manipulated. The IP addresses can be specified via
+the -A and -B options, denoting the source and destination address,
+respectively. You can also specify an address range or a host name (FQDN).
+Additionally, the source address can also be random. By default the source
+address is your interface IP address and the destination address is a
+broadcast. Here are some examples:
+
+Ascii payload:
+
+  mausezahn eth0 -t ip -A rand -B 192.168.1.0/24  -P "hello world"
+
+Hex payload:
+
+  mausezahn eth0 -t ip -A 10.1.0.1-10.1.255.254 -B 255.255.255.255 p=ca:fe:ba:be
+
+Will use correct source IP address:
+
+  mausezahn eth0 -t ip -B www.xyz.com
+
+The Type of Service (ToS) byte can either be specified directly by two
+hexadecimal digits (which means you can also easily set the Explicit
+Congestion Notification (ECN) bits (LSB 1 and 2) or you may only want to
+specify a common DSCP value (bits 3-8) using a decimal number (0..63):
+
+Packet sent with DSCP = Expedited Forwarding (EF):
+
+  mausezahn eth0 -t ip dscp=46,ttl=1,proto=1,p=08:00:5a:a2:de:ad:be:af
+
+If you leave the checksum zero (or unspecified) the correct checksum will
+be automatically computed. Note that you can only use a wrong checksum when
+you also specify at least one L2 field manually.
+
+* UDP:
+
+mausezahn support easy UDP datagram generation. Simply specify the
+destination address (-B option) and optionally an arbitrary source address
+(-A option) and as arguments you may specify the port numbers using the
+dp (destination port) and sp (source port) arguments and a payload. You can
+also easily specify a whole port range which will result in sending multiple
+packets. Here are some examples:
+
+Send test packets to the RTP port range:
+
+  mausezahn eth0 -B 192.168.1.1 -t udp "dp=16384-32767, \
+                 p=A1:00:CC:00:00:AB:CD:EE:EE:DD:DD:00"
+
+Send a DNS request as local broadcast (often a local router replies):
+
+  mausezahn eth0 -t udp dp=53,p=c5-2f-01-00-00-01-00-00-00-00-00-00-03-77-77-\
+                                77-03-78-79-7a-03-63-6f-6d-00-00-01-00-01"
+
+Additionally you may specify the lenght and checksum using the len and sum
+arguments (will be set correctly by default). Note: several protocols have same
+arguments such as len (length) and sum (checksum). If you specified a udp type
+packet (via -t udp) and want to modify the IP length, then use the alternate
+keyword iplen and ipsum. Also note that you must specify at least one L2 field
+which tells mausezahn to build everything without help of your kernel (the
+kernel would not allow to modify the IP checksum and the IP length).
+
+* ICMP:
+
+mausezahn currently only supports the following ICMP methods: PING (echo
+request), Redirect (various types), Unreachable (various types). Additional
+ICMP types will be supported in future. Currently you would need to tailor them
+by your own, e.g. using the IP packet builder (setting proto=1). Use the
+mausezahn -t icmp help for help on actually implemented options.
+
+* TCP:
+
+mausezahn allows you to easily tailor any TCP packet. Similar as with UDP you
+can specify source and destination port (ranges) using the sp and dp arguments.
+Then you can directly specify the desired flags using an "|" as delimiter if
+you want to specify multiple flags. For example, a SYN-Flood attack against
+host 1.1.1.1 using a random source IP address and periodically using all 1023
+well-known ports could be created via:
+
+  mausezahn eth0 -A rand -B 1.1.1.1 -c 0 -t tcp "dp=1-1023, flags=syn"  \
+                 -P "Good morning! This is a SYN Flood Attack.          \
+                     We apologize for any inconvenience."
+
+Be careful with such SYN floods and only use them for firewall testing. Check
+your legal position! Remember that a host with an open TCP session only accepts
+packets with correct socket information (addresses and ports) and a valid TCP
+sequence number (SQNR). If you want to try a DoS attack by sending a RST-flood
+and you do NOT know the target's initial SQNR (which is normally the case) then
+you may want to sweep through a range of sequence numbers:
+
+  mausezahn eth0 -A legal.host.com -B target.host.com \
+                 -t tcp "sp=80,dp=80,s=1-4294967295"
+
+Fortunately, the SQNR must match the target host's acknowledgement number plus
+the announced window size. Since the typical window size is something between
+40000 and 65535 you are MUCH quicker when using an increment using the ds
+argument:
+
+  mausezahn eth0 -A legal.host.com -B target.host.com \
+                 -t tcp "sp=80, dp=80, s=1-4294967295, ds=40000"
+
+In the latter case mausezahn will only send 107375 packets instead of
+4294967295 (which results in a duration of approximately 1 second compared to
+11 hours!). Of course you can tailor any TCP packet you like. As with other L4
+protocols mausezahn builds a correct IP header but you can additionally access
+every field in the IP packet (also in the Ethernet frame).
+
+* DNS:
+
+mausezahn supports UDP-based DNS requests or responses. Typically you may want
+to send a query or an answer. As usual you can modify every flag in the header.
+Here is an example of a simple query:
+
+  mausezahn eth0 -B mydns-server.com -t dns "q=www.ibm.com"
+
+You can also create server-type messages:
+
+  mausezahn eth0 -A spoofed.dns-server.com -B target.host.com \
+                 "q=www.topsecret.com, a=172.16.1.1"
+
+The syntax according to the online help (-t dns help) is:
+
+  query|q = <name>[:<type>]  ............. where type is per default "A"
+                                           (and class is always "IN")
+  answer|a = [<type>:<ttl>:]<rdata> ...... ttl is per default 0.
+           = [<type>:<ttl>:]<rdata>/[<type>:<ttl>:]<rdata>/...
+
+Note: If you only use the 'query' option then a query is sent. If you
+additionally add an 'answer' then an answer is sent. Examples:
+
+  q = www.xyz.com
+  q = www.xyz.com, a=192.168.1.10
+  q = www.xyz.com, a=A:3600:192.168.1.10
+  q = www.xyz.com, a=CNAME:3600:abc.com/A:3600:192.168.1.10
+
+Please try out mausezahn -t dns help to see the many other optional command
+line options.
+
+* RTP and VoIP path measurements:
+
+mausezahn can send arbitrary Real Time Protocol (RTP) packets. Per default a
+classical G.711 codec (20 ms segment size, 160 bytes) is assumed. You can
+measure jitter, packet loss and reordering along a path between two hosts
+running mausezahn. The jitter measurement is either done following the variance
+low-pass filtered estimation specified in RFC 3550 or using an alternative
+"real-time" method which is even more precise (the RFC-method is used by
+default). For example on Host1 you start a transmission process:
+
+  mausezahn -t rtp -B 192.168.1.19
+
+And on Host2 (192.168.1.19) a receiving process which performs the measurement:
+
+  mausezahn -T rtp
+
+Note that the option flag with the capital "T" means that it is a server RTP
+process, waiting for incoming RTP packets from any mausezahn source. In case
+you want to restrict the measurement to a specific source or you want to
+perform a bidirectional measurement, you must specify a stream identifier.
+Here is an example for bidirectional measurements which logs the running
+jitter average in a file:
+
+  Host1# mausezahn -t rtp id=11:11:11:11 -B 192.168.2.2 &
+  Host1# mausezahn -T rtp id=22:22:22:22 "log, path=/tmp/mz/"
+
+  Host2# mausezahn -t rtp id=22:22:22:22 -B 192.168.1.1 &
+  Host2# mausezahn -T rtp id=11:11:11:11 "log, path=/tmp/mz/"
+
+In any case the measurements are printed continuously onto the screen; by
+default it looks like this:
+
+  0.00                     0.19                      0.38                      0.57
+  |-------------------------|-------------------------|-------------------------|
+  #########                                                                      0.07 msec
+  ####################                                                           0.14 msec
+  ##                                                                             0.02 msec
+  ###                                                                            0.02 msec
+  #########                                                                      0.07 msec
+  ####                                                                           0.03 msec
+  #########                                                                      0.07 msec
+  #############                                                                  0.10 msec
+  ##                                                                             0.02 msec
+  ###########################################                                    0.31 msec
+  #########                                                                      0.07 msec
+  ##############################################                                 0.33 msec
+  ###############                                                                0.11 msec
+  ##########                                                                     0.07 msec
+  ###############                                                                0.11 msec
+  ##########################################################                     0.42 msec
+  #####                                                                          0.04 msec
+
+More information is shown using the txt keyword:
+
+  mausezahn -T rtp txt
+  Got 100 packets from host 192.168.0.3: 0 lost (0 absolute lost), 1 out of order
+    Jitter_RFC (low pass filtered) = 30 usec
+    Samples jitter (min/avg/max)   = 1/186/2527 usec
+    Delta-RX (min/avg/max)         = 2010/20167/24805 usec
+  Got 100 packets from host 192.168.0.3: 0 lost (0 absolute lost), 1 out of order
+    Jitter_RFC (low pass filtered) = 17 usec
+    Samples jitter (min/avg/max)   = 1/53/192 usec
+    Delta-RX (min/avg/max)         = 20001/20376/20574 usec
+  Got 100 packets from host 192.168.0.3: 0 lost (0 absolute lost), 1 out of order
+    Jitter_RFC (low pass filtered) = 120 usec
+    Samples jitter (min/avg/max)   = 0/91/1683 usec
+    Delta-RX (min/avg/max)         = 18673/20378/24822 usec
+
+See mausezahn -t rtp help and mz -T rtp help for more details.
+
+* Syslog:
+
+The traditional Syslog protocol is widely used even in professional networks
+and is sometimes vulnerable. For example you might insert forged Syslog
+messages by spoofing your source address (e.g. impersonate the address of a
+legit network device):
+
+  mausezahn -t syslog sev=3 -P "You have been mausezahned." -A 10.1.1.109 -B 192.168.7.7
+
+See mausezahn -t syslog help for more details.
+
 .SH NOTE
 When multiple ranges are specified, e.g. destination port ranges and
 destination address ranges, then all possible combinations of ports and