ICEcap 1.0-beta
===============

Introduction:
============
ICEcap is a tool that captures network behavior over time for simulation 
purposes at a latter time using Candela Technologies LANforge ICE WAN link 
simulator.  By default, ICEcap sends ICMP echo request packets to a target host 
and records the ICMP echo reply statistics in a data capture file.  ICEcap then 
formats them into an XML file according to user specified arguments.  The XML 
file can then be used to reproduce the recorded network conditions in the 
LANforge ICE WAN link simulator

WARNING:

Since ICEcap is based on the GPL tool HPING/HPING2 there are options available 
that can cause undesirable results.  Anytime the [--icecap] option is specified 
use only the options recommended in this document.  Without the [--icecap] 
option normal HPING operation applies and all HPING options are available.


Usage:
=====
- One must be super user to run ICEcap.

- Command line help on ICEcap is available at anytime when the [--icecap] and 
  [-h|--h|-help|--help] options are specified.

e.g.

[root@tyan2460 hping]# ./hping2 10.1.2.1 --icecap -h

 
Example:
=======
The following command will ping the target host 10.1.2.1 with ICMP echo 
requests containing a 64 byte payload (-d 64).  The host will be pinged 50 
times a second (--i_spi 100 divided by --i_interval 2 seconds) for one hour 
(--i_duration 3600 seconds).  Two files, test.dat and test.xml, 
will be generated (--filename test).  Additionally, any existing files named 
test.dat and test.xml from previous captures will be lost (--i_overwrite). 
 

[root@tyan2460 hping]# ./hping2 --icecap --i_filename test --i_duration 3600 
--i_interval 2 --i_spi 100 -d 64 10.1.2.1 --i_overwrite

NOTES:

1.  The --i_overwrite option will pause approximately for five seconds 
    before overwriting the existing files.  If a Ctrl-C is issued during the 
    five seconds the files will not be overwritten.

2.  Issuing a Ctrl-C during an active capture will end the capture and an XML 
    file will be generated up to the time of the Ctrl-C.


ICEcap Options:
==============
--icecap
  Enable ICEcap options.  Will cause suppression of HPING output to STDOUT 
  unless -V --verbose option is specified.
 
--i_filename <filename>
  Path and base file name for <filename>.dat (data capture) and <filename>.xml 
  (XML output) files.
  
--i_overwrite
  Automatically overwrite existing .dat and .xml files.  ICEcap will wait 
  approximately 5 seconds before overwriting existing data unless a Ctrl-C is 
  issued.

--i_duration <time>
  Duration of ICE capture in seconds (default 300 seconds / 5 minutes).  When 
  <time> seconds have elapsed the data capture will cease and the XML file 
  will be generated.        
    
--i_interval <time>
  Time sample interval during capture in seconds (default 1 second).  ICEcap 
  will send option --i_spi pings during <time> period and the XML file will 
  generate statistics based on each <time> interval.  This options provides 
  control over the degree of resolution of the network capture.          
    
--i_spi <n>         
  Samples per interval e.g. number of pings in option --i_interval (default 100 
  pings). ICEcap will send <n> pings during the option --i_interval <time> which 
  affects the resolution and accuracy of the network capture.

Ctrl-C
  Stops ICE capture and generates XML output file at the time of issuance.  Or 
  will stop overwriting of existing data and XML files.
  

Base Options:
============
-h --help
  Show an help screen on standard output, so you can pipe to less.

-v --version
  Show version information and API used to access to data link layer,
  linux sock packet or libpcap.

-c --count <count>
  Stop after sending (and receiving) <count> response packets. After last packet 
  was sent wait 10 seconds target host replies.  Will only apply if receive 
  <count> is met before --i_duration.  Make --i_duration exceed expected time 
  that receiving <count> packets should take.
      
-n --numeric
  Numeric output only, No attempt will be made to lookup symbolic names for host 
  addresses.
  
-q --quiet
  Quiet output. Nothing is displayed except the summary lines at startup time 
  and when finished.
  
-I --interface interface name  By default on linux and BSD systems hping2 uses 
  default routing interface.  In other systems or when there is no default route 
  the first non-loopback   interface is used.  However you are able to force 
  hping2 to use the interface   you need using this option. Note: you don't need 
  to specify the whole name,   for example -I et will match eth0 ethernet0 myet1 
  et cetera. If no   interfaces match hping2 will try to use lo.

-V --verbose
  Enable verbose output.  Needed to view HPING options that output to STDOUT  
  when the --icecap option is specified
  
-D --debug
  Enable debug mode, it's useful when you experience some problem with hping2. 
  When debug mode is enabled you will get more information about interface 
  detection, data link layer access, interface settings, options  parsing, 
  fragmentation, HCMP protocol and other stuff.


IP Related Options:
==================
-t --ttl time to live  Using this option you can set TTL (time to live) of  
  outgoing packets.
  
-N --id
  Set ip->id field. Default id is random but if fragmentation is turned on and 
  id isn't specified it will be getpid() & 0xFF.
  
-W --winid
  Windows* id has different byte ordering, if this option is enabled hping2 will 
  properly display windows reply ids. (Use with -V --verbose option)
    
-r --rel
  Display id increments instead of id. Increments aren't computed as 
  id[N]-id[N-1] but using packet loss compensation. (Use with -V --verbose 
  option)  
  
-f --frag
  Split packets in more fragments, this may be useful in order to test IP stacks 
  fragmentation performance and to test if some packet filter is so weak that 
  can be passed using tiny fragments(anachronistic). Default 'virtual   mtu' is 
  16 bytes. see also --mtu option.
  
-x --morefrag
  Set more fragments IP flag, use this option if you want that target host send 
  an ICMP time-exceeded during reassembly.

-y --dontfrag
  Set don't fragment IP flag, this can be used to perform MTU path discovery.

-g --fragoff <fragment offset value>
  Set the fragment offset

-m --mtu <mtu value>
  Set different 'virtual mtu' than 16 when fragmentation is enabled. If packets 
  size is greater that 'virtual mtu' fragmentation is automatically turned on.

-o --tos <hex_tos>
  Set Type Of Service (TOS), for more information try --tos help

-G --rroute
  Record route. Includes the RECORD_ROUTE option in each packet sent and 
  displays the route buffer of returned packets. Note that the IP headeris only 
  large enough for nine such routes.  Many hosts ignore or discard this option. 
  Also note that using hping you are able to use record route even if target 
  host filter ICMP.  Record route is an IP option, not an ICMP option. (Use with 
  -V --verbose option)
  
ICMP Related Options:
====================
-C --icmptype <type>
  Set icmp type, default is ICMP echo request (implies --icmp)

-K --icmpcode <code>
  Set icmp code, default is 0. (implies --icmp)

--icmp-ipver <version>
  Set IP version of IP header contained into ICMP data, default is 4.

--icmp-iphlen <length>
  Set IP header length of IP header contained into ICMP data, default is 5 (5 
  word of 32 bits).
  
--icmp-iplen <length>
  Set IP packet length of IP header contained into ICMP data, default is the 
  real length.
  
--icmp-ipid <id>
  Set IP id of IP header contained into ICMP data, default is random.

--icmp-ipproto <protocol>
  Set IP protocol of IP header contained into ICMP data, default is TCP.

--icmp-cksum <checksum>
  Set ICMP checksum, for default is the valid checksum.

--icmp-ts
  Alias for --icmptype 13 (to send ICMP timestamp requests)

--icmp-addr
  Alias for --icmptype 17 (to send ICMP address mask requests)  
 

Common Options:
==============
-d --data <data size>
  Set packet body size. Warning, using --data 40 hping2 will not generate
  0 byte packets but protocol_header+40 bytes. hping2 will display packet size 
  information as first line output, like this (Use with -V --verbose option):
  
  HPING www.yahoo.com (ppp0 204.71.200.67): NO FLAGS are set, 40 headers + 40 
  data bytes.
  
-j --dump
  Dump received packets in hex.

-J --print
  Dump received packets's printable characters.


ICMP Output Format:
==================
An example of ICMP output is (Use with -V --verbose option):

ICMP Port Unreachable from ip=192.168.1.1 name=nano.marmoc.net

It is very simple to understand. It starts with the string "ICMP" followed by 
the description of the ICMP error, Port Unreachablein the example. The ip field 
is the IP source address of the IPdatagram containing the ICMP error, the name 
field is just thenumerical address resolved to a name (a dns PTR request) or 
UNKNOWN if theresolution failed.

The ICMP Time exceeded during transit or reassembly format is a bit different:

TTL 0 during transit from ip=192.168.1.1 name=nano.marmoc.net

TTL 0 during reassembly from ip=192.70.106.25 name=UNKNOWN   

The only difference is the description of the error, it starts with TTL 0.