Documentation/Mausezahn

   1 What is mausezahn ([ˈmauzəˌtsa:n], ``mouse tooth'')?
   2 ////////////////////////////////////////////////////
   3
   4 We have decided to take over further development and maintenance of Herbert
   5 Haas' mausezahn traffic generator since he passed away 25.6.2011 [1]. We
   6 believe that mausezahn is a great tool for packet generation and analysis. It
   7 will take quite a long process to cleanly merge it into the netsniff-ng
   8 toolkit, to fix code quality and some bugs. However, after this process, we
   9 are going to add further protocols and features to mausezahn. How does it fit
  10 into the big picture of the toolkit? There's netsniff-ng and trafgen. Both
  11 tools are mostly used on host-side on the development machine for debugging
  12 and other purposes and controlled directly from command-line. Then, there is
  13 mauseszahn, which is intended to be used on a HW/SW appliance that runs on a
  14 dedicated box/server in your network lab. E.g. on a server with a couple of
  15 Ethernet interfaces where you simply connect a cable to one of those interfaces
  16 and to your development server's input. Then, you'll login to mausezahn
  17 management interface through telnet in your local lab, configure mausezahn and
  18 run test packets respectively analyze your server's output.
  19
  20 So, now to the actual question: what is mausezahn? mausezahn is a fast traffic
  21 generator and analyzer for HW/SW appliances, which allows you to send nearly
  22 every possible and impossible packet. mausezahn can be used for example ...
  23
  24   * As a traffic generator (e.g. to stress multicast networks)
  25   * For penetration testing of firewalls and IDS
  26   * For DoS attacks on networks (for audit purposes of course)
  27   * To find bugs in network software or appliances
  28   * For reconnaissance attacks using ping sweeps and port scans
  29   * To test network behaviour under strange circumstances (stress test,
  30     malformed packets, ...)
  31   * As didactical tool during lab exercises
  32
  33 ... and more. mausezahn is basically a versatile packet creation tool on the
  34 command line with a simple configuration syntax. It could also be used within
  35 (bash-)scripts to perform combination of tests.
  36
  37 First steps:
  38
  39 Using the interactive mode requires to start mausezahn as server:
  40
  41   # mausezahn -x
  42
  43 Now you can telnet to that server using the default port number 25542, but also
  44 an arbitrary port number can be specified:
  45
  46   # mausezahn -x 99
  47
  48 mausezahn accepts incoming telnet connections on port 99.
  49
  50   mz: Problems opening config file. Will use defaults
  51
  52 Either from another terminal or from another host try to telnet to the
  53 mausezahn server:
  54
  55   caprica$ telnet galactica 99
  56   Trying 192.168.0.4...
  57   Connected to galactica.
  58   Escape character is '^]'.
  59
  60   ------------------------------------------
  61   Mausezahn, version 0.38
  62   Copyright (C) 2007-2009 by Herbert Haas.
  63   ------------------------------------------
  64
  65   Username: mz
  66   Password: mz
  67
  68   mz-0.38> enable
  69   Password: mops
  70   mz-0.38#
  71
  72 It is recommended to configure your own login credentials in
  73 /etc/mausezahn/mz.cfg, such as:
  74
  75   user = herbert
  76   password = TopSecret
  77   enable = MauseZa#n42
  78
  79 Since you reached the mausezahn prompt, lets try some first commands. You can
  80 use the '?' character at any time for a content-sensitive help.
  81
  82 First try out the show command:
  83
  84   mz-0.38# show ?
  85
  86 mausezahn maintains its own ARP table and observes anomalies. There is an entry
  87 for every physical interface (however this host has only one):
  88
  89   mz-0.38# sh arp
  90   Intf    Index     IP address     MAC address       last       Ch  UCast BCast Info
  91   ----------------------------------------------------------------------------------
  92   eth0    [1] D     192.168.0.1  00:09:5b:9a:15:84  23:44:41     1     1     0  0000
  93
  94 The column Ch tells us that the announced MAC address has only changed one time
  95 (= when it was learned). The columns Ucast and BCast tell us how often this
  96 entry was announced via unicast or broadcast respectively.
  97
  98 Let's check our interfaces:
  99
 100   mz-0.38# show interface
 101   Available network interfaces:
 102                  real             real                  used (fake)      used (fake)
 103    device        IPv4 address     MAC address           IPv4 address     MAC address
 104   ---------------------------------------------------------------------------------------
 105   > eth0         192.168.0.4      00:30:05:76:2e:8d     192.168.0.4      00:30:05:76:2e:8d
 106     lo           127.0.0.1        00:00:00:00:00:00     127.0.0.1        00:00:00:00:00:00
 107   2 interfaces found.
 108   Default interface is eth0.
 109
 110 Defining packets:
 111
 112 Let's check the current packet list:
 113
 114   mz-0.38# sh packet
 115   Packet layer flags: E=Ethernet, S=SNAP, Q=802.1Q, M=MPLS, I/i=IP/delivery_off, U=UDP, T=TCP
 116   PktID  PktName           Layers  Proto    Size  State      Device      Delay       Count/CntX
 117       1  sysARP_servic...  E-----  ARP        60  config     lo          100 msec        1/0 (100%)
 118   1 packets defined, 0 active.
 119
 120 We notice that there is already one system-defined packet process; it has been
 121 created and used only once (during startup) by mausezahn's ARP service.
 122 Currently, its state is config which means that the process is sleeping.
 123
 124 General packet options:
 125
 126 Now let's create our own packet process and therefore switch into the global
 127 configuration mode:
 128
 129   mz-0.38# configure term
 130   mz-0.38(config)# packet
 131   Allocated new packet PKT0002 at slot 2
 132   mz-0.38(config-pkt-2)# ?
 133   ...
 134   name                 Assign a unique name
 135   description          Assign a packet description text
 136   bind                 Select the network interface
 137   count                Configure the packet count value
 138   delay                Configure the inter-packet delay
 139   interval             Configure a greater interval
 140   type                 Specify packet type
 141   mac                  Configure packet's MAC addresses
 142   tag                  Configure tags
 143   payload              Configure a payload
 144   port                 Configure packet's port numbers
 145   end                  End packet configuration mode
 146   ethernet             Configure frame's Ethernet, 802.2, 802.3, or SNAP settings
 147   ip                   Configure packet's IP settings
 148   udp                  Configure packet's UDP header parameters
 149   tcp                  Configure packet's TCP header parameters
 150
 151 Here are a lot of options but normally you only need a few of them. When you
 152 configure lots of different packets you might assign a reasonable name and
 153 description for them:
 154
 155   mz-0.38(config-pkt-2)# name Test
 156   mz-0.38(config-pkt-2)# desc This is just a test
 157
 158 You can e.g. change the default settings for the source and destination MAC/IP
 159 addresses using the mac and ip commands:
 160
 161   mz-0.38(config-pkt-2)# ip address dest 10.1.1.0 /24
 162   mz-0.38(config-pkt-2)# ip addr source random
 163
 164 In the example above, we configured a range of addresses (all hosts in the
 165 network 10.1.1.0 should be addressed). Additionally we spoof our source IP
 166 address. Of course, we can also add one or more VLAN and/or MPLS tag(s):
 167
 168   mz-0.38(config-pkt-2)# tag ?
 169   dot1q                Configure 802.1Q (and 802.1P) parameters
 170   mpls                 Configure MPLS label stack
 171   mz-0.38(config-pkt-2)# tag dot ?
 172   Configure 802.1Q tags:
 173   VLAN[:CoS] [VLAN[:CoS]] ...   The leftmost tag is the outer tag in the frame
 174   remove <tag-nr> | all         Remove one or more tags (<tag-nr> starts with 1),
 175                                 by default the first (=leftmost,outer) tag is removed,
 176                                 keyword 'all' can be used instead of tag numbers.
 177   cfi | nocfi [<tag-nr>]        Set or unset the CFI-bit in any tag (by default
 178                                 assuming the first tag).
 179   mz-0.38(config-pkt-2)# tag dot 1:7 200:5
 180
 181 Configure count and delay:
 182
 183   mz-0.38(config-pkt-2)# count 1000
 184   mz-0.38(config-pkt-2)# delay ?
 185   delay <value> [hour | min | sec | msec | usec | nsec]
 186
 187 Specify the inter-packet delay in hours, minutes, seconds, milliseconds,
 188 microseconds or nanoseconds. The default unit is milliseconds (i.e. when no
 189 unit is given).
 190
 191   mz-0.38(config-pkt-2)# delay 1 msec
 192   Inter-packet delay set to 0 sec and 1000000 nsec
 193   mz-0.38(config-pkt-2)#
 194
 195 Configuring protocol types:
 196
 197 mausezahn's interactive mode supports a growing list of protocols and only
 198 relies on the MOPS architecture (and not on libnet as it is the case with
 199 the legacy direct mode):
 200
 201   mz-0.38(config-pkt-2)# type
 202   Specify a packet type from the following list:
 203   arp
 204   bpdu
 205   igmp
 206   ip
 207   lldp
 208   tcp
 209   udp
 210   mz-0.38(config-pkt-2)# type tcp
 211   mz-0.38(config-pkt-2-tcp)#
 212   ....
 213   seqnr                Configure the TCP sequence number
 214   acknr                Configure the TCP acknowledgement number
 215   hlen                 Configure the TCP header length
 216   reserved             Configure the TCP reserved field
 217   flags                Configure a combination of TCP flags at once
 218   cwr                  Set or unset the TCP CWR flag
 219   ece                  Set or unset the TCP ECE flag
 220   urg                  Set or unset the TCP URG flag
 221   ack                  set or unset the TCP ACK flag
 222   psh                  set or unset the TCP PSH flag
 223   rst                  set or unset the TCP RST flag
 224   syn                  set or unset the TCP SYN flag
 225   fin                  set or unset the TCP FIN flag
 226   window               Configure the TCP window size
 227   checksum             Configure the TCP checksum
 228   urgent-pointer       Configure the TCP urgend pointer
 229   options              Configure TCP options
 230   end                  End TCP configuration mode
 231   mz-0.38(config-pkt-2-tcp)# flags syn fin rst
 232   Current setting is: --------------------RST-SYN-FIN
 233   mz-0.38(config-pkt-2-tcp)# end
 234   mz-0.38(config-pkt-2)# paylo ascii This is a dummy payload for my first packet
 235   mz-0.38(config-pkt-2)# end
 236
 237 Now configure another packet, for example let's assume we want an LLDP process:
 238
 239   mz-0.38(config)# packet
 240   Allocated new packet PKT0003 at slot 3
 241   mz-0.38(config-pkt-3)# ty lldp
 242   mz-0.38(config-pkt-3-lldp)# exit
 243   mz-0.38(config)# exit
 244
 245 In the above example we only use the default LLDP settings and don't configure
 246 further LLDP options or TLVs. Back in the top level of the CLI let's verify
 247 what we had done:
 248
 249   mz-0.38# sh pa
 250   Packet layer flags: E=Ethernet, S=SNAP, Q=802.1Q, M=MPLS, I/i=IP/delivery_off, U=UDP, T=TCP
 251   PktID  PktName            Layers  Proto    Size  State      Device   Delay      Count/CntX
 252      1   sysARP_servic...   E-----  ARP        60  config     lo       100 msec       1/0 (100%)
 253      2   Test               E-Q-IT            125  config     eth0    1000 usec    1000/1000 (0%)
 254      3   PKT0003            E-----  LLDP       36  config     eth0      30 sec        0/0 (0%)
 255   3 packets defined, 0 active.
 256
 257 The column Layers indicates which major protocols have been combined. For
 258 example the packet with packet-id 2 ("Test") utilizes Ethernet (E),
 259 IP (I), and TCP (T). Additionally an 802.1Q tag (Q) has been inserted. Now
 260 start one of these packet processes:
 261
 262   mz-0.38# start slot 3
 263   Activate [3]
 264   mz-0.38# sh pac
 265   Packet layer flags: E=Ethernet, S=SNAP, Q=802.1Q, M=MPLS, I/i=IP/delivery_off, U=UDP, T=TCP
 266   PktID  PktName            Layers  Proto    Size  State      Device   Delay      Count/CntX
 267      1   sysARP_servic...   E-----  ARP        60  config     lo       100 msec       1/0 (100%)
 268      2   Test               E-Q-IT            125  config     eth0    1000 usec    1000/1000 (0%)
 269      3   PKT0003            E-----  LLDP       36  config     eth0      30 sec        0/1 (0%)
 270   3 packets defined, 1 active.
 271
 272 Let's have a more detailed look at a specific packet process:
 273
 274   mz-0.38# sh pac 2
 275   Packet [2] Test
 276   Description: This is just a test
 277   State: config, Count=1000, delay=1000 usec (0 s 1000000 nsec), interval= (undefined)
 278   Headers:
 279    Ethernet: 00-30-05-76-2e-8d => ff-ff-ff-ff-ff-ff  [0800 after 802.1Q tag]
 280    Auto-delivery is ON (that is, the actual MAC is adapted upon transmission)
 281    802.1Q: 0 tag(s);  (VLAN:CoS)
 282    IP:  SA=192.168.0.4 (not random) (no range)
 283         DA=255.255.255.255 (no range)
 284         ToS=0x00  proto=17  TTL=255  ID=0  offset=0  flags: -|-|-
 285         len=49664(correct)  checksum=0x2e8d(correct)
 286    TCP: 83 bytes segment size (including TCP header)
 287         SP=0 (norange) (not random), DP=0 (norange) (not random)
 288         SQNR=3405691582 (start 0, stop 4294967295, delta 0) -- ACKNR=0 (invalid)
 289         Flags: ------------------------SYN----, reserved field is 00, urgent pointer= 0
 290         Announced window size= 100
 291         Offset= 0 (times 32 bit; value is valid), checksum= ffff (valid)
 292         (No TCP options attached) - 0 bytes defined
 293    Payload size: 43 bytes
 294    Frame size: 125 bytes
 295     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
 296    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
 297    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
 298    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
 299   mz-0.38#
 300
 301 If you want to stop one or more packet processes, use the stop command. The
 302 "emergency stop" is when you use stop all:
 303
 304   mz-0.38# stop all
 305   Stopping
 306   [3] PKT0003
 307   Stopped 1 transmission processe(s)
 308
 309 The launch command provides a shortcut for commonly used packet processes. For
 310 example to behave like a STP-capable bridge we want to start an BPDU process
 311 with typical parameters:
 312
 313   mz-0.38# laun bpdu
 314   Allocated new packet sysBPDU at slot 5
 315   mz-0.38# sh pac
 316   Packet layer flags: E=Ethernet, S=SNAP, Q=802.1Q, M=MPLS, I/i=IP/delivery_off, U=UDP, T=TCP
 317   PktID  PktName           Layers  Proto    Size  State      Device      Delay       Count/CntX
 318       1  sysARP_servic...  E-----  ARP        60  config     lo          100 msec        1/0 (100%)
 319       2  Test              E-Q-IT            125  config     eth0       1000 usec     1000/1000 (0%)
 320       3  PKT0003           E-----  LLDP       36  config     eth0          30 sec        0/12 (0%)
 321       4  PKT0004           E---I-  IGMP       46  config     eth0        100 msec        0/0 (0%)
 322       5  sysBPDU           ES----  BPDU       29  active     eth0           2 sec        0/1 (0%)
 323   5 packets defined, 1 active.
 324
 325 Now a Configuration BPDU is sent every 2 seconds, claiming to be the root
 326 bridge (and usually confusing the LAN. Note that only packet 5 (i.e. the
 327 last row) is active and therefore sending packets while all other packets
 328 are in state config (i.e. they have been configured but they are not doing
 329 anything at the moment).
 330
 331 Configuring a greater interval:
 332
 333 Sometimes you may want to send a burst of packets at a greater interval:
 334
 335   mz-0.38(config)# pac 2
 336   Modify packet parameters for packet Test [2]
 337   mz-0.38(config-pkt-2)# interv
 338   Configure a greater packet interval in days, hours, minutes, or seconds
 339   Arguments: <value>  <days | hours | minutes | seconds>
 340   Use a zero value to disable an interval.
 341   mz-0.38(config-pkt-2)# interv 1 h
 342   mz-0.38(config-pkt-2)# count 10
 343   mz-0.38(config-pkt-2)# delay 15 usec
 344   Inter-packet delay set to 0 sec and 15000 nsec
 345
 346 Now this packet is sent ten times with an inter-packet delay of 15 microsecond
 347 and this is repeated every hour. When you look at the packet list, an interval
 348 is indicated with the additional flag 'i' when inactive or 'I' when active:
 349
 350   mz-0.38# sh pa
 351   Packet layer flags: E=Ethernet, S=SNAP, Q=802.1Q, M=MPLS, I/i=IP/delivery_off, U=UDP, T=TCP
 352   PktID  PktName           Layers  Proto    Size  State      Device      Delay       Count/CntX
 353       1  sysARP_servic...  E-----  ARP        60  config     lo          100 msec        1/0 (100%)
 354       2  Test              E-Q-IT            125  config-i   eth0         15 usec       10/10 (0%)
 355       3  PKT0003           E-----  LLDP       36  config     eth0          30 sec        0/12 (0%)
 356       4  PKT0004           E---I-  IGMP       46  config     eth0        100 msec        0/0 (0%)
 357       5  sysBPDU           ES----  BPDU       29  active     eth0           2 sec        0/251 (0%)
 358   5 packets defined, 1 active.
 359   mz-0.38# start sl 2
 360   Activate [2]
 361   mz-0.38# sh pa
 362   Packet layer flags: E=Ethernet, S=SNAP, Q=802.1Q, M=MPLS, I/i=IP/delivery_off, U=UDP, T=TCP
 363   PktID  PktName           Layers  Proto    Size  State      Device      Delay       Count/CntX
 364       1  sysARP_servic...  E-----  ARP        60  config     lo          100 msec        1/0 (100%)
 365       2  Test              E-Q-IT            125  config+I   eth0         15 usec       10/0 (100%)
 366       3  PKT0003           E-----  LLDP       36  config     eth0          30 sec        0/12 (0%)
 367       4  PKT0004           E---I-  IGMP       46  config     eth0        100 msec        0/0 (0%)
 368       5  sysBPDU           ES----  BPDU       29  active     eth0           2 sec        0/256 (0%)
 369   5 packets defined, 1 active.
 370
 371 Note that the flag 'I' indicates that an interval has been specified for
 372 packet 2. The process is not active at the moment (only packet 5 is active
 373 here) but it will become active in a regular interval. You can verify the
 374 actual interval when viewing the packet details via the show packet 2 command.
 375
 376 Load prepared configurations:
 377
 378 You can prepare packet configurations using the same commands as you would
 379 type them in on the CLI and then load them to the CLI. For example assume we
 380 have prepared a file 'test.mops' containing:
 381
 382   configure terminal
 383   packet
 384   name IGMP_TEST
 385   desc This is only a demonstration how to load a file to mops
 386   type igmp
 387
 388 Then we can add this packet configuration to our packet list using the load
 389 command:
 390
 391   mz-0.38# load test.mops
 392   Read commands from test.mops...
 393   Allocated new packet PKT0002 at slot 2
 394   mz-0.38# sh pa
 395   Packet layer flags: E=Ethernet, S=SNAP, Q=802.1Q, M=MPLS, I/i=IP/delivery_off, U=UDP, T=TCP
 396   PktID  PktName           Layers  Proto    Size  State      Device      Delay       Count/CntX
 397       1  sysARP_servic...  E-----  ARP        60  config     lo          100 msec        1/0 (100%)
 398       2  IGMP_TEST         E---I-  IGMP       46  config     eth0        100 msec        0/0 (0%)
 399   2 packets defined, 0 active.
 400
 401 The file src/examples/mausezahn/example_lldp.conf contains another example
 402 list of commands to create a bogus LLDP packet. You can load this
 403 configuration from the mausezahn command line, e.g. via:
 404
 405   mz-0.39# load /home/hh/tmp/example_lldp.conf
 406
 407 In case you copied the file in that path. Now when you enter 'show packet' you
 408 will see a new packet entry in the packet list. Use the 'start slot <nr>'
 409 command to activate this packet.
 410
 411 You can store your own packet creations in such file and easily load them when
 412 you need them. Every command within such configuration files is executed on the
 413 command line interface as if you had typed it in -- so be careful about the
 414 order and don't forget to use 'configure terminal' as first command.
 415
 416 You can even load other files from within a central config file.
 417
 418 Direct mode of mausezahn:
 419
 420 How to specify hex digits:
 421
 422 Many arguments allow direct byte input. Bytes are represented as two
 423 hexadecimal digits. Multiple bytes must be separated either by spaces, colons,
 424 or dashes - whatever you prefer. The following byte strings are equivalent:
 425
 426   "aa:bb cc-dd-ee ff 01 02 03-04 05"
 427   "aa bb cc dd ee ff:01:02:03:04 05"
 428
 429 As first example, you may want to send an arbitrary fancy (possibly invalid)
 430 frame right through your network card:
 431
 432   # mausezahn ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:08:00:ca:fe:ba:be
 433
 434  or equivalently but more readable:
 435
 436   # mausezahn ff:ff:ff:ff:ff:ff-ff:ff:ff:ff:ff:ff-08:00-ca:fe:ba:be
 437
 438 Basic operations:
 439
 440 All major command line options are listed when you execute mausezahn without
 441 arguments. For practical usage keep the following special (not so widely
 442 known) options in mind:
 443
 444   -r                    Multiplies the specified delay with a random value.
 445   -p <length>           Pad the raw frame to specified length (using random
 446                         bytes).
 447   -P <ASCII Payload>    Use the specified ASCII payload.
 448   -f <filename>         Read the ASCII payload from a file.
 449   -F <filename>         Read the hexadecimal payload from a file.
 450   -S                    Simulation mode: DOES NOT put anything on the wire.
 451                         This is typically combined with one of the verbose
 452                         modes (-v or V).
 453
 454 Many options require a keyword or a number but the -t option is an exception
 455 since it requires both a packet type (such as ip, udp, dns, etc) and an
 456 argument string which is specific for that packet type. Here are some simple
 457 examples:
 458
 459   # mausezahn -t help
 460   # mausezahn -t tcp help
 461   # mausezahn eth3 -t udp sp=69,dp=69,p=ca:fe:ba:be
 462
 463 Note: Don't forget that on the CLI the Linux shell (usually the Bash)
 464 interprets spaces as a delimiter character. That is, if you are specifying
 465 an argument that consists of multiple words with spaces in between, you MUST
 466 group this with quotes. For example, instead of
 467
 468   # mausezahn eth0 -t udp sp=1,dp=80,p=00:11:22:33
 469
 470  you could either omit the spaces
 471
 472   # mausezahn eth0 -t udp sp=1,dp=80,p=00:11:22:33
 473
 474  or, even more safe, use quotes:
 475
 476   # mausezahn eth0 -t udp "sp=1,dp=80,p=00:11:22:33"
 477
 478 In order to monitor what's going on, you can enable the verbose mode using
 479 the -v option. The opposite is the quiet mode (-q) which will keep mausezahn
 480 absolutely quiet (except for error messages and warnings.)
 481
 482 Don't confuse the payload argument p=... with the padding option -p. The latter
 483 is used outside the quotes!
 484
 485 The automatic packet builder:
 486
 487 An important argument is "-t" which invokes a packet builder. Currently there
 488 are packet builders for ARP, BPDU, CDP, IP, partly ICMP, UDP, TCP, RTP, DNS,
 489 and SYSLOG. (Additionally you can insert a VLAN tag or a MPLS label stack but
 490 this works independent of the packet builder.)
 491
 492 You get context specific help of every packet builder using the help keyword,
 493 such as:
 494
 495   # mausezahn -t bpdu help
 496   # mausezahn -t tcp help
 497
 498 For every packet you may specify an optional payload. This can be done either
 499 via HEX notation using the payload (or short p) argument or directly as ASCII
 500 text using the -P option:
 501
 502   # mausezahn eth0 -t ip -P "Hello World"                           # ASCII payload
 503   # mausezahn eth0 -t ip p=68:65:6c:6c:6f:20:77:6f:72:6c:64         # hex payload
 504   # mausezahn eth0 -t ip "proto=89,                           \
 505                           p=68:65:6c:6c:6f:20:77:6f:72:6c:64, \     # same with other
 506                           ttl=1"                                    # IP arguments
 507
 508 Note: The raw link access mode only accepts hex payloads (because you specify
 509 everything in hex here.)
 510
 511 Packet count and delay:
 512
 513 Per default only one packet is sent. If you want to send more packets then
 514 use the count option -c <count>. When count is zero then mausezahn will send
 515 forever. Per default mausezahn sends at maximum speed (and this is really
 516 fast ;-)). If you don't want to overwhelm your network devices or have other
 517 reasons to send at a slower rate then you might want to specify a delay using
 518 the -d <delay> option.
 519
 520 If you only specify a numeric value it is interpreted in microsecond units.
 521 Alternatively, for easier use, you might specify units such as seconds sec or
 522 milliseconds msec. (You can also abbreviate this with s or m.) Note: Don't use
 523 spaces between the value and the unit! Here are typical examples:
 524
 525 Send infinite frames as fast as possible:
 526
 527   # mausezahn -c 0  "aa bb cc dd ...."
 528
 529 Send 100,000 frames with a 50 msec interval:
 530
 531   # mausezahn -c 100000  -d 50msec "aa bb cc dd ...."
 532
 533 Send infinite BPDU frames in a 2 second interval:
 534
 535   # mausezahn -c 0 -d 2s -t bpdu conf
 536
 537 Note: mausezahn does not support fractional numbers. If you want to specify for
 538 example 2.5 seconds then express this e.g. in milliseconds (2500 msec).
 539
 540 Source and destination addresses:
 541
 542 As mnemonic trick keep in mind that all packets run from "A" to "B". You can
 543 always specify source and/or destination MAC addresses using the -a and -b
 544 options, respectively. These options also allow keywords such as rand, own,
 545 bpdu, cisco, and others.
 546
 547 Similarly, you can specify source and destination IP addresses using the -A
 548 and -B options, respectively. These options also support FQDNs (i.e. domain
 549 names) and ranges such as 192.168.0.0/24 or 10.0.0.11-10.0.3.22. Additionally
 550 (only) the source address supports the rand keyword (ideal for "attacks").
 551
 552 Note: When you use the packet builder for IP-based packets (e.g. UDP or TCP)
 553 then mausezahn automatically cares about correct MAC and IP addresses (i.e.
 554 it performs ARP, DHCP, and DNS for you). But when you specify at least a single
 555 link-layer address (or any other L2 option such as a VLAN tag or MPLS header)
 556 then ARP is disabled and you must care for the Ethernet destination address for
 557 yourself.
 558
 559 Layer-2:
 560
 561 * Direct link access:
 562
 563 mausezahn allows you to send ANY chain of bytes directly through your Ethernet
 564 interface:
 565
 566   # mausezahn eth0 "ff:ff:ff:ff:ff:ff ff:ff:ff:ff:ff:ff 00:00 ca:fe:ba:be"
 567
 568 This way you can craft every packet you want but you must do it by hand. Note:
 569 On WiFi interfaces the header is much more complicated and automatically
 570 created by the WiFi-driver. As example to introduce some interesting options,
 571 lets continuously send frames at max speed with random source MAC address and
 572 broadcast destination address, additionally pad the frame to 1000 bytes:
 573
 574   # mausezahn eth0 -c 0 -a rand -b bcast -p 1000 "08 00 aa bb cc dd"
 575
 576 The direct link access supports automatic padding using the -p <total frame
 577 length> option. This allows you to pad a raw L2 frame to the desired length.
 578 You must specify the total length and the total frame length must have at
 579 least 15 bytes for technical reasons. Zero bytes are used for this padding.
 580
 581 * ARP:
 582
 583 mausezahn provides a simple interface to the ARP packet. You can specify the
 584 ARP method (request|reply) and up to four arguments: sendermac, targetmac,
 585 senderip, targetip, or short smac, tmac, sip, tip. By default an ARP reply is
 586 sent with your own interface addresses as source MAC and IP address, and a
 587 broadcast destination MAC/IP address. Send a gratitious ARP (as used for
 588 duplicate IP detection):
 589
 590   # mausezahn eth0 -t arp
 591
 592 ARP cache poisoning:
 593
 594   # mausezahn eth0 -t arp "reply, senderip=192.168.0.1, targetmac=00:00:0c:01:02:03, \
 595                            targetip=172.16.1.50"
 596
 597  where by default your interface MAC address will be used as sendermac,
 598 senderip denotes the spoofed IP, targetmac and targetip identifies the
 599 receiver. By default the Ethernet source address is your interface MAC and the
 600 destination address is broadcast. Of course you can change this using again the
 601 flags -a and -b.
 602
 603 * BPDU:
 604
 605 mausezahn provides a simple interface to the 802.1d BPDU frame format (used to
 606 create the Spanning Tree in bridged networks). By default standard IEEE 802.1d
 607 (CST) BPDUs are sent and it is assumed that your computer wants to become the
 608 root bridge (rid=bid). Optionally the 802.3 destination address can be a
 609 specified MAC address, broadcast, own MAC, or Cisco's PVST+ MAC address. The
 610 destination MAC can be specified using the -b command which (besides MAC
 611 addresses) accepts keywords such as bcast, own, pvst, or stp (default). Since
 612 version 0.16 PVST+ is supported. Simply specify the VLAN for which you want
 613 to send a BPDU:
 614
 615   # mausezahn eth0 -t bpdu "vlan=123, rid=2000"
 616
 617 See mausezahn -t bpdu help for more details.
 618
 619 * CDP:
 620
 621 mausezahn can send Cisco Discovery Protocol (CDP) messages since this protocol
 622 has security relevance. Of course lots of dirty tricks are possible; for
 623 example arbitrary TLVs can be created (using the hex-payload argument for
 624 example p=00:0e:00:07:01:01:90) and if you want to stress the CDP database of
 625 some device, mausezahn can send each CDP message with another system-id using
 626 the change keyword:
 627
 628   # mausezahn -t cdp change -c 0
 629
 630 Some routers and switches may run into deep problems ;-) See
 631 mausezahn -t cdp help for more details.
 632
 633 * 802.1Q VLAN Tags:
 634
 635 mausezahn allows simple VLAN tagging for IP (and other higher layer) packets.
 636 Simply use the option -Q <[CoS:]VLAN>, such as -Q 10 or -Q 3:921. By
 637 default CoS=0. For example send a TCP packet in VLAN 500 using CoS=7:
 638
 639   # mausezahn eth0 -t tcp -Q 7:500 "dp=80, flags=rst, p=aa:aa:aa"
 640
 641 You can create as many VLAN tags as you want! This is interesting to create
 642 QinQ encapsulations or VLAN hopping: Send a UDP packet with VLAN tags 100
 643 (outer) and 651 (inner):
 644
 645   # mausezahn eth0 -t udp "dp=8888, sp=13442" -P "Mausezahn is great" -Q 100,651
 646
 647 Don't know if this is useful anywhere but at least it is possible:
 648
 649   # mausezahn eth0 -t udp "dp=8888, sp=13442" -P "Mausezahn is great"  \
 650                    -Q 6:5,7:732,5:331,5,6
 651
 652 Mix it with MPLS:
 653
 654   # mausezahn eth0 -t udp "dp=8888, sp=13442" -P "Mausezahn is great" -Q 100,651 -M 314
 655
 656 Only in raw Layer 2 mode you must create the VLAN tag completely by yourself.
 657 For example if you want to send a frame in VLAN 5 using CoS 0 simply specify
 658 81:00 as type field and for the next two bytes the CoS (, CFI) and VLAN values:
 659
 660   # mausezahn eth0 -b bc -a rand "81:00 00:05 08:00 aa-aa-aa-aa-aa-aa-aa-aa-aa"
 661
 662 * MPLS labels:
 663
 664 mausezahn allows you to insert one or more MPLS headers. Simply use the option
 665 -M <label:CoS:TTL:BoS> where only the label is mandatory. If you specify a
 666 second number it is interpreted as the experimental bits (the CoS usually). If
 667 you specify a third number it is interpreted as TTL. Per default the TTL is
 668 set to 255. The Bottom of Stack flag is set automatically (otherwise the frame
 669 would be invalid) but if you want you can also set or unset it using the
 670 S (set) and s (unset) argument. Note that the BoS must be the last argument in
 671 each MPLS header definition. Here are some examples:
 672
 673 Use MPLS label 214:
 674
 675   # mausezahn eth0 -M 214 -t tcp "dp=80" -P "HTTP..." -B myhost.com
 676
 677 Use three labels (the 214 is now the outer):
 678
 679   # mausezahn eth0 -M 9999,51,214 -t tcp "dp=80" -P "HTTP..." -B myhost.com
 680
 681 Use two labels, one with CoS=5 and TTL=1, the other with CoS=7:
 682
 683   # mausezahn eth0 -M 100:5:1,500:7 -t tcp "dp=80" -P "HTTP..." -B myhost.com
 684
 685 Unset the BoS flag (which will result in an invalid frame):
 686
 687   # mausezahn eth0 -M 214:s -t tcp "dp=80" -P "HTTP..." -B myhost.com
 688
 689 Layer 3-7:
 690
 691 IP, UDP, and TCP packets can be padded using the -p option. Currently 0x42 is
 692 used as padding byte ('the answer'). You cannot pad DNS packets (would be
 693 useless anyway).
 694
 695 * IP:
 696
 697 mausezahn allows you to send any (malformed or correct) IP packet. Every field
 698 in the IP header can be manipulated. The IP addresses can be specified via
 699 the -A and -B options, denoting the source and destination address,
 700 respectively. You can also specify an address range or a host name (FQDN).
 701 Additionally, the source address can also be random. By default the source
 702 address is your interface IP address and the destination address is a
 703 broadcast. Here are some examples:
 704
 705 Ascii payload:
 706
 707   # mausezahn eth0 -t ip -A rand -B 192.168.1.0/24  -P "hello world"
 708
 709 Hex payload:
 710
 711   # mausezahn eth0 -t ip -A 10.1.0.1-10.1.255.254 -B 255.255.255.255 p=ca:fe:ba:be
 712
 713 Will use correct source IP address:
 714
 715   # mausezahn eth0 -t ip -B www.xyz.com
 716
 717 The Type of Service (ToS) byte can either be specified directly by two
 718 hexadecimal digits (which means you can also easily set the Explicit
 719 Congestion Notification (ECN) bits (LSB 1 and 2) or you may only want to
 720 specify a common DSCP value (bits 3-8) using a decimal number (0..63):
 721
 722 Packet sent with DSCP = Expedited Forwarding (EF):
 723
 724   # mausezahn eth0 -t ip dscp=46,ttl=1,proto=1,p=08:00:5a:a2:de:ad:be:af
 725
 726 If you leave the checksum zero (or unspecified) the correct checksum will
 727 be automatically computed. Note that you can only use a wrong checksum when
 728 you also specify at least one L2 field manually.
 729
 730 * UDP:
 731
 732 mausezahn support easy UDP datagram generation. Simply specify the
 733 destination address (-B option) and optionally an arbitrary source address
 734 (-A option) and as arguments you may specify the port numbers using the
 735 dp (destination port) and sp (source port) arguments and a payload. You can
 736 also easily specify a whole port range which will result in sending multiple
 737 packets. Here are some examples:
 738
 739 Send test packets to the RTP port range:
 740
 741   # mausezahn eth0 -B 192.168.1.1 -t udp "dp=16384-32767, \
 742                                           p=A1:00:CC:00:00:AB:CD:EE:EE:DD:DD:00"
 743
 744 Send a DNS request as local broadcast (often a local router replies):
 745
 746   # mausezahn eth0 -t udp dp=53,p=c5-2f-01-00-00-01-00-00-00-00-00-00-03-77-77-\
 747                           77-03-78-79-7a-03-63-6f-6d-00-00-01-00-01"
 748
 749 Additionally you may specify the lenght and checksum using the len and sum
 750 arguments (will be set correctly by default). Note: several protocols have same
 751 arguments such as len (length) and sum (checksum). If you specified a udp type
 752 packet (via -t udp) and want to modify the IP length, then use the alternate
 753 keyword iplen and ipsum. Also note that you must specify at least one L2 field
 754 which tells mausezahn to build everything without help of your kernel (the
 755 kernel would not allow to modify the IP checksum and the IP length).
 756
 757 * ICMP:
 758
 759 mausezahn currently only supports the following ICMP methods: PING (echo
 760 request), Redirect (various types), Unreachable (various types). Additional
 761 ICMP types will be supported in future. Currently you would need to tailor them
 762 by your own, e.g. using the IP packet builder (setting proto=1). Use the
 763 mausezahn -t icmp help for help on actually implemented options.
 764
 765 * TCP:
 766
 767 mausezahn allows you to easily tailor any TCP packet. Similar as with UDP you
 768 can specify source and destination port (ranges) using the sp and dp arguments.
 769 Then you can directly specify the desired flags using an "|" as delimiter if
 770 you want to specify multiple flags. For example, a SYN-Flood attack against
 771 host 1.1.1.1 using a random source IP address and periodically using all 1023
 772 well-known ports could be created via:
 773
 774   # mausezahn eth0 -A rand -B 1.1.1.1 -c 0 -t tcp "dp=1-1023, flags=syn"  \
 775                    -P "Good morning! This is a SYN Flood Attack.          \
 776                        We apologize for any inconvenience."
 777
 778 Be careful with such SYN floods and only use them for firewall testing. Check
 779 your legal position! Remember that a host with an open TCP session only accepts
 780 packets with correct socket information (addresses and ports) and a valid TCP
 781 sequence number (SQNR). If you want to try a DoS attack by sending a RST-flood
 782 and you do NOT know the target's initial SQNR (which is normally the case) then
 783 you may want to sweep through a range of sequence numbers:
 784
 785   # mausezahn eth0 -A legal.host.com -B target.host.com \
 786                    -t tcp "sp=80,dp=80,s=1-4294967295"
 787
 788 Fortunately, the SQNR must match the target host's acknowledgement number plus
 789 the announced window size. Since the typical window size is something between
 790 40000 and 65535 you are MUCH quicker when using an increment using the ds
 791 argument:
 792
 793   # mausezahn eth0 -A legal.host.com -B target.host.com \
 794                    -t tcp "sp=80, dp=80, s=1-4294967295, ds=40000"
 795
 796 In the latter case mausezahn will only send 107375 packets instead of
 797 4294967295 (which results in a duration of approximately 1 second compared to
 798 11 hours!). Of course you can tailor any TCP packet you like. As with other L4
 799 protocols mausezahn builds a correct IP header but you can additionally access
 800 every field in the IP packet (also in the Ethernet frame).
 801
 802 * DNS:
 803
 804 mausezahn supports UDP-based DNS requests or responses. Typically you may want
 805 to send a query or an answer. As usual you can modify every flag in the header.
 806 Here is an example of a simple query:
 807
 808   # mausezahn eth0 -B mydns-server.com -t dns "q=www.ibm.com"
 809
 810 You can also create server-type messages:
 811
 812   # mausezahn eth0 -A spoofed.dns-server.com -B target.host.com \
 813                    "q=www.topsecret.com, a=172.16.1.1"
 814
 815 The syntax according to the online help (-t dns help) is:
 816
 817   query|q = <name>[:<type>]  ............. where type is per default "A"
 818                                            (and class is always "IN")
 819   answer|a = [<type>:<ttl>:]<rdata> ...... ttl is per default 0.
 820            = [<type>:<ttl>:]<rdata>/[<type>:<ttl>:]<rdata>/...
 821
 822 Note: If you only use the 'query' option then a query is sent. If you
 823 additionally add an 'answer' then an answer is sent. Examples:
 824
 825   q = www.xyz.com
 826   q = www.xyz.com, a=192.168.1.10
 827   q = www.xyz.com, a=A:3600:192.168.1.10
 828   q = www.xyz.com, a=CNAME:3600:abc.com/A:3600:192.168.1.10
 829
 830 Please try out mausezahn -t dns help to see the many other optional command
 831 line options.
 832
 833 * RTP and VoIP path measurements:
 834
 835 mausezahn can send arbitrary Real Time Protocol (RTP) packets. Per default a
 836 classical G.711 codec (20 ms segment size, 160 bytes) is assumed. You can
 837 measure jitter, packet loss and reordering along a path between two hosts
 838 running mausezahn. The jitter measurement is either done following the variance
 839 low-pass filtered estimation specified in RFC 3550 or using an alternative
 840 "real-time" method which is even more precise (the RFC-method is used by
 841 default). For example on Host1 you start a transmission process:
 842
 843   # mausezahn -t rtp -B 192.168.1.19
 844
 845 And on Host2 (192.168.1.19) a receiving process which performs the measurement:
 846
 847   # mausezahn -T rtp
 848
 849 Note that the option flag with the capital "T" means that it is a server RTP
 850 process, waiting for incoming RTP packets from any mausezahn source. In case
 851 you want to restrict the measurement to a specific source or you want to
 852 perform a bidirectional measurement, you must specify a stream identifier.
 853 Here is an example for bidirectional measurements which logs the running
 854 jitter average in a file:
 855
 856   Host1# mausezahn -t rtp id=11:11:11:11 -B 192.168.2.2 &
 857   Host1# mausezahn -T rtp id=22:22:22:22 "log, path=/tmp/mz/"
 858
 859   Host2# mausezahn -t rtp id=22:22:22:22 -B 192.168.1.1 &
 860   Host2# mausezahn -T rtp id=11:11:11:11 "log, path=/tmp/mz/"
 861
 862 In any case the measurements are printed continuously onto the screen; by
 863 default it looks like this:
 864
 865   0.00                     0.19                      0.38                      0.57
 866   |-------------------------|-------------------------|-------------------------|
 867   #########                                                                      0.07 msec
 868   ####################                                                           0.14 msec
 869   ##                                                                             0.02 msec
 870   ###                                                                            0.02 msec
 871   #########                                                                      0.07 msec
 872   ####                                                                           0.03 msec
 873   #########                                                                      0.07 msec
 874   #############                                                                  0.10 msec
 875   ##                                                                             0.02 msec
 876   ###########################################                                    0.31 msec
 877   #########                                                                      0.07 msec
 878   ##############################################                                 0.33 msec
 879   ###############                                                                0.11 msec
 880   ##########                                                                     0.07 msec
 881   ###############                                                                0.11 msec
 882   ##########################################################                     0.42 msec
 883   #####                                                                          0.04 msec
 884
 885 More information is shown using the txt keyword:
 886
 887   # mausezahn -T rtp txt
 888   Got 100 packets from host 192.168.0.3: 0 lost (0 absolute lost), 1 out of order
 889     Jitter_RFC (low pass filtered) = 30 usec
 890     Samples jitter (min/avg/max)   = 1/186/2527 usec
 891     Delta-RX (min/avg/max)         = 2010/20167/24805 usec
 892   Got 100 packets from host 192.168.0.3: 0 lost (0 absolute lost), 1 out of order
 893     Jitter_RFC (low pass filtered) = 17 usec
 894     Samples jitter (min/avg/max)   = 1/53/192 usec
 895     Delta-RX (min/avg/max)         = 20001/20376/20574 usec
 896   Got 100 packets from host 192.168.0.3: 0 lost (0 absolute lost), 1 out of order
 897     Jitter_RFC (low pass filtered) = 120 usec
 898     Samples jitter (min/avg/max)   = 0/91/1683 usec
 899     Delta-RX (min/avg/max)         = 18673/20378/24822 usec
 900
 901 See mausezahn -t rtp help and mz -T rtp help for more details.
 902
 903 * Syslog:
 904
 905 The traditional Syslog protocol is widely used even in professional networks
 906 and is sometimes vulnerable. For example you might insert forged Syslog
 907 messages by spoofing your source address (e.g. impersonate the address of a
 908 legit network device):
 909
 910   # mausezahn -t syslog sev=3 -P "You have been mausezahned." -A 10.1.1.109 -B 192.168.7.7
 911
 912 See mausezahn -t syslog help for more details.
 913
 914 [1] http://www.perihel.at/