SIP Scenario Generator version=1.2.7

################################################################################################################

The SIP Scenario Generator Software License, Version 1.1

Copyright (c) 2003 IPC Information Systems Inc.  All rights reserved.

Redistribution and use in source and binary forms, with or without modification, 
are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, 
this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, 
this list of conditions and the following disclaimer in the documentation 
and/or other materials provided with the distribution.

3. The end-user documentation included with the redistribution, 
if any, must include the following acknowledgment:

"This product includes software developed by 
IPC Information Systems Inc (http://www.ipc.com/)."

Alternately, this acknowledgment may appear in the software itself, 
if and wherever such third-party acknowledgments normally appear.

4. The names "SIP Scenario Generator" and "IPC Information Systems Inc" 
must not be used to endorse or promote products derived from this software 
without prior written permission. For written permission, please contact 
the legal department at IPC Information Systems Inc.

5. Products derived from this software may not be called "SIP Scenario Generator", 
nor may "SIP Scenario Generator" appear in their name, without prior written 
permission of IPC Information Systems Inc.

THIS SOFTWARE IS PROVIDED ``AS IS`` AND ANY EXPRESSED OR IMPLIED WARRANTIES, 
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND 
FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL 
IPC INFORMATION SYSTEMS INC OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE 
OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

This software consists of voluntary contributions made by 
Ray Elliott of IPC information System Inc. e-mail:ray.elliott@ipc.com
please see <http://www.ipc.com/>.

################################################################################################################


################################################################################################################

This program makes SIP callflows (scenarios) diagrams from an ethernet trace.
The program reads the libpcap output format created by ethereal, tcpdump, etc) and creates sip scenario (call flows).
There are three basic outputs:
	A printable text file.
		BASENAME.txt 			a printable version of XXXX.html
	A single HTML File version
		BASENAME.html	 		a basic html file with reference to the expanded SIP messages.
	An HTML version using frames. (has 2 files).
		BASENAME_index.html	 	a basic html file that has the frame definitions
		BASENAME_indexhtml.html	 	an html file with with references using frames.

Each ethernet packet that is contained in the libpcap trace file is called a physical Frame. Each packet is given a sequence number
call the Physical Frame number. The Physical Frame Number is used for Documentations as a reference to a fixed location.

Each SIP message that is display is identified by a sequential number call the SIP Frame Number.

All UDP and TCP packets will be will be parsed to check if there are SIP messages or not.
Non-SIP messages will be automatically filtered out of the display.
		
Different SIP calls (Based on CALLID)  will be indicated in different colors.
Links are made from the sip scenario (call fow) to the actual SIP Message (frame data).

detects and displays hold / nomedia for messages with content-type=application/sdp
detects and displays different content types on sip scenario
displays a list a reasons that ethernet packets in trace file were not displayed.

Has various display options.
Has several mechanism to filter Sip Messages or Physical frames.


	Basic Output Document Format is 
	###################################
	Title and Info Section
	###################################
		Scenario Title
		File: trace.dump
		Generated: Sat Mar  1 20:30:10 2003
		Traced on: Fri Feb 28 16:30:30 2003
		Created by:../sip_scenario.pl version=1.0.39
	###################################
	Scenario Trace
	###################################
		Proxy              Turret 1           Phone2
		10.70.200.148      10.70.200.195      10.70.200.218
		|                  |                  |  
		|                  |                  |
		|<--------------------(sdp) INVITE F1<|  
		|>F2 100 Trying --------------------->|  
		|>F3 INVITE (sdp)->|                  |  
		|>F4 INVITE (sdp)-------------------->|  
		|<-(sdp) OK 200 F5<|                  |  
		...
	###################################
	Detail Frame Information
	###################################
		    SIP Frame     1    10.70.200.218:1067(Pingtel) -> 10.70.200.148:5060(Proxy)
		Physical Frame    3    28/Feb/03 16:30:31.5593 TimeFromPreviousSipFrame=0 TimeFromStart=0 
		INVITE sip:2111@10.70.200.148 SIP/2.0
		From: sip:2110@10.70.200.148;tag=2c497
		To: sip:2111@10.70.200.148
		Call-Id: call-1046467828-28@10.70.200.218
		Cseq: 1 INVITE
		...
	###################################
	Miscellaneous Information
	###################################

	###################################
	End Of Document

Note:
This program can generate html pages that are too big for browsers. When this occurs there are several things that can be done.
1) Remove the extended frame data so that the basic SIP scenario can be viewed. use -format:frames:0 command
2) Use the include/exclude Callid commands -include:callid: or -exclude:callid: to reduce the calls
3) Use the -range command to reduce the input.
After the set of calls have been reduced, then add the related extended frame data by removing the command -format:frames:0
################################################################################################################

################################################################################################################
Files Delivered
################################################################################################################
scenario.vx.x.xx.zip
Compressed archive file

readme.txt
This file
a description of the capabilites and syntax of the sip_scenario program. This is a must to read.

sip_scenario.pl: 
This is the perl script source file.

sip_scenario.exe: 
This is an windows executable version of sip_scenario.pl that does not require perl to be preinstalled.

sip_scenario.ini
contains user preferences for the sip_scenario.pl program. This file is automatically included
when sip_scenario.pl is started. If the file is not present then this file is not used.
This file is optional.

ethereal_trace.dump
This is an actual ethernet trace of several Sip phones and a proxy. Ethereal was used to generate this file.

There are there sets of batch files that are delivered to show all the functions of sip_scenario.pl
There are several basic modes of operation for sip_scenario. The goal of these different configurations
is to show all the capabilities of the sip scenario generator tool. I expect that most users will change these
setting. I did. Some options will not be used. The most complex options will be used.
There will be a batch file for each of these modes.

1) Debug 
2) Test Documentation
3) Final Documentation
4) User Defined Scenarios

Batch Files
ethereal_trace_debug.bat
ethereal_trace_test_doc.bat
ethereal_trace_final_doc.bat
user_scenario.bat
test.bat

Output files
ethereal_trace_debug.html
ethereal_trace_debug_index.html
ethereal_trace_debug.txt
ethereal_trace_test_doc.html
ethereal_trace_test_doc_index.html
ethereal_trace_test_doc.txt
ethereal_trace_final_doc.html
ethereal_trace_final_doc_index.html
ethereal_trace_final_doc.txt
user_scenario.html
user_scenario_index.html
user_scenario.txt
test.html
test.html
test.txt

################################################################################################################
##### General Information
################################################################################################################

The command documentation and syntax is specified in the header section of the file sip_scenario.pl.

Each of the batch files describes that basic commands that are being illustrated.

Each of the four batch files contain illustration on various commands are used.

Print the first section of sip_scenario.pl to get a list of arguments that are possible.

################################################################################################################
##### Windows PC section.
################################################################################################################

sip_scenario.exe was tested on a Windows 2000 Intel PentiumIII PC.

Unzip all files from sip_scenario.zip and place them in a folder.

execute the following command from a command window

sip_scenario.exe ethereal_trace.dump 
This will generate four files
	ethereal_trace.txt 
	ethereal_trace.html 
	ethereal_trace_index.html 
	ethereal_trace_indexhtml.html 

Batch files illustrate other ways this program can be executed.

run one of the batch files that was included. for example use ethereal_trace_debug.bat
Run ethereal_trace_debug.bat 
1) double click on file ethereal_trace_debug.bat 
or
2) execute ethereal_trace.bat from a command window.
open a command window.
cd to the appropiate folder.
execute the following
cmd /c ethereal_trace_debug.bat

This will re-create the file ethereal_trace_debug.html

################################################################################################################
##### Debug 
################################################################################################################

1) Execute the batch file from the command using "cmd /c ethereal_trace_debug.bat"
	A) check for parsing errors if any
	B) check the reasons why packets were filtered out.
2) Insure all the required IP addresses are defined.
3) Is the file sip_scenario.ini defined in the local directory?

################################################################################################################
#####  Solaris Section
################################################################################################################

TBA

################################################################################################################
#####  Linux Section
################################################################################################################
TBA
################################################################################################################

################################################################################################################

The Sip Scenario Generator Program was created and designed by Ray Elliott of IPC Information Systems Inc.
SIP Scenario Generator Version=1.2.7
 
E-mail Contact is Ray.Elliott@ipc.com

If Problems reports are being submitted please include the corresponding ethernet trace file.

################################################################################################################

SIP Scenario Generator version=1.2.7

quick help
sip_scenario  filename eg. sip_scenario ethereal_trace.dump

sip_scenario  help | -help | -syntax | -syntax++ | -description | -v[ersion] | -l[icenseinfo] | -about | Parameters
help | - help			Displays help Message
-syntax 			Displays basic syntax
-syntax++			Displays Extended syntax information
-de[scription]			Displays a description of the program
-v[ersion]			Displays the version of this program
-l[icenseinfo]			Displays licensing information
-about				Displays information by program and where to send problem reports

Parameters 		:=	inputFilename  | -oBaseOutfilename           optionalParameters
optionalParameters 	:=	optionalParameters | [optionalParameter]
optionalParameter 	:= 
IPADDRESS[:PORT}[/ALIAS][:NUMBER]][:singleua] |	# Defines an IP address with alias and column position
-t[itle]:TITLE | 				# Defines Title
-g[ap]:NUMBER | 				# defines the gap between columns
-de[scription]:NUMBER | 			# Enable/Disable Display of long Sip Scenario Descriptions
-ver[ify]:NUMBER | 				# Enable/Disable verify all call partcipants in columns
-i[nclude][:NUMBER]:INCLUDEFILE | 		# Defines Include file and number of lines to skip at the start of the include file

Filter Commands
-ports:udp|tcp:LIST | 				# defines set of udp/tcp used to filter SIP messages
-r[ange]:RANGELIST | 				# Range of Physical Frames to include
-i[nclude]:line:RANGELIST | 			# Range of Physical Frames to include
-e[xclude]:[line:]RANGELIST | 			# defines list of physical frames to exclude.
-i[nclude]:t[ime]:STARTTIME-ENDTIME | 		# Range of Physical Frames to include based on a time range 
-i[nclude]:c[allid]:RANGELIST | 		# defines set of calls to include
-e[xclude]:c[allid]:RANGELIST | 		# defines set of calls to exclude
-i[nclude]:e[xpression]:PERLPATTERN | 		# defines a set of calls to include by matching any header in the call with the PERLPATTERN
-e[xclude]:e[xpression]:PERLPATTERN | 		# defines a set of calls to exclude by matching any header in the call with the PERLPATTERN
-i[nclude]:req[uest]:REQUEST |	 		# defines a set of calls to include by matching any SIP REQUEST in the call with REQUEST
-e[xclude]:req[uest]:REQUEST |	 		# defines a set of calls to exclude by matching any SIP REQUEST in the call with REQUEST
-i[nclude]:m[atch]:STRING | 			# defines a set of calls to include by matching any header in the call with the STRING
-i[nclude]:ip:IPADDRESS | 			# includes any call that has any SIP packet with the IP header containing the specified IPADDRESS
-e[xclude]:ip:IPADDRESS | 			# excludes any call that has any SIP packet with the IP header containing the specified IPADDRESS

Format Commands
-f[ormat]:c[allid]:NUMBER | 			# defines display format for callid 0-2
-f[ormat]:t[ime]:NUMBER | 			# defines display format for time   0-15
-f[ormat]:f[rames]:NUMBER | 			# defines display format for Adding extended frame Data  0-1
-f[ormat]:p[hy]:NUMBER | 			# defines display format for Physical Frame Number  0-1
-f[ormat]:v[ertical]:NUMBER | 			# defines vertical spacing 0-3 0==>most compressed   3==> least compressed
-f[ormat]:s[pacetime]:N/Q | 			# defines extra spacing based on time    N=Seconds Q=#of lines to add
-percent:NUMBER |	 			# defines the percent of vertical space allocated to the bottom frame in the index.html file.

Miscellaneous Commands
-re[order]:RANGELIST:FRAME |			# reorders a set of sip messages.
-c[ommentprefix]:XSTRING: | 			# defines characters that are preappend to each comment line.
-c[omment]:NUMBER:COMMENT | 			# defines a comment line
-fake:SRCIP:DSTIP:CALL#:PFRAME:STRING | 	# defines user defines SIP message.
-colors:COLORLIST | 				# defines set of colors to use
-stat:NUMBER |					# Turn on/off displaying statistics
-copy |						# special copy function
-merge:FILENAME2 |				# Merge capture file2 with 1st capture file, 
						  automatic time synchronization and removes duplicate pkts
-debug:NUMBER |					# debug. Add extra information for debugging.
-ker[beros][:NUMBER] |				# enable/disable kerberos
-summary[:FILENAME] |				# displays a summary of ip adrress used and calls.
-keep:NUMBER					# the set of files to keep
-singleua					# disable symmeteric UDP port detection for all IPADDRESSES.

-NoPauseOnError				        # disables pause on error feature (enabled by default)
-PauseOnError				        # Enables pause on error feature (enabled by default)

STRING 			:= is a non-empty string of ascii characters (0x20-0x7f)
XSTRING			:= is a non-empty string of ascii characters (0x20-0x7f) excluding ":"
ALIAS			:= XSTRING
TITLE			:= STRING
SRCIP,DSTIP		:= IPADDRESS | XSTRING
CALL#			:= NUMBER | XSTRING
PFRAME			:= NUMBER [. NUMBER]
NUMBER			:= a decimal number >= 0
IPADDRESS		:= NUMBER.NUMBER.NUMBER.NUMBER
RANGELIST		:= NUMBER | NUMBER-NUMBER | [,RANGELIST] | <nothing>
LIST			:= NUMBER | [,LIST]
COLORLIST		:= Black|Green|Silver|Lime|Gray|Olive|White|Yellow|Maroon|Navy|Red|Blue|Purple|Teal|Fuchsia|Aqua | #RRGGBB | [,COLORLIST]
RR,GG,BB		:= TWO HEX DIGITS representing the (Red,Green,Blue) color component
PERLPATTERN 		:= STRING
TIME			:= [[[YEAR/]MM/]DD/]HH:MM
FILENAME		:= STRING must be a valid file name.

################################################################################################################


################################################################################################################


   inputFilename is a libpcap formatted ethernet trace file.
   	The inputfile name is an optional parameter since fake sip messages can be generated.

   -oBaseOutfilename defines the path and filename (not including the extension) for the output.
   	The extension added is based on the output mode selected.
	the default BaseOutfilename is derived from the inputFile name. It is the filename without extensions or directory information.
	If not specified the output path name is the current directory.
	if a directory name is specified, without the filename (ending with a "/" or "\" or ":") 
	then output will but placed in the specified directory

   IPADDRESS[:PORT}[/Alias}[:newpos][:singleua]
   	IPADDRESS defines the IP address for a column.
   	PORT defines a specific port for an ip address for a column.
	Alias can be assigned to the ipaddress. This alias is used for display purposes as column headings
   		they can also be used to generate SIP messages (see -fake command)
		Alias must be unique. Two different ip address can not have the same alias.
  	newpos is the column number to assign the IP address / alias.
  		newpos=0 ==>	IP address will be remove a defined IP address
		IP addresses can be defined as a parameter or automatically if encountered in the the trace file.
		Only IP addresses that are found in the trace file will be columns in the in the scenario output.
	singleua specifies that the is only one SIP ua at IPADDRESS. disables symmetric udp port detection for that IPADDRESS
  	there is no limitation to the number of IP addresses that can be defined
  	examples
  	10.70.200.218
  	10.70.200.195/Chris			## Add alias of Chris
  	10.70.200.196/Leo:2			## Add alias of Leo and inserts in the second position in front of the exist position 2
  						## if there is no position 2 then it is placed at the end of the list
  	10.70.200.218:0				## deletes ip address from the list. 
  	10.70.200.196:5060/Leo:2		## Add alias of Leo and inserts in the second position in front of the exist position 2
  						
  	Note:10.70.200.218:N	Allows for a common list of ip addresses and aliases. Each specific SIP scenario trace can
  		modify the order of the ip address assigned to the columns.

   -singleua					# disable symmeteric UDP port detection for all IPADDRESSES.
   
   -title:TITLE Sets the title of the sip scenario.
   	default is :Sip Scenario Trace
   	note: the TITLE must contain non-numeric characters

   -g[ap]:NUMBER set the number of spaces between columns
   	e.g.  -g18
		10.63.200.218      10.63.200.148      10.63.200.195    
		|                  |  (sdp) INVITE F1 |
   	e.g.  -g28
		10.63.200.218                10.63.200.148                10.63.200.195    
		|                            |            (sdp) INVITE F1 |

   -de[scription]:N Sip Message descriptions that do not fit between the arrowhead start and the arrow feathers will be truncated
   	An extra line with the full description will be inserted. 
   	where N=
   	0==> no extra line
		|                  |                  |
		|>F20 481 Transact>|                  |                  |  Call#:1
   	1==> extra line  (default)
		|                  |                  |
		| F20 481 Transaction Does Not Exist  |                  |
		|>F20 481 Transact>|                  |                  |  Call#:1

   -ver[ify]:N When verify is enabled, insures that all partcipants of a scenario are included in a SIP scenario. Enabled by default.
	If Ip addresses have been removed (All SIP Ip addresses are included by default) 
		and verify is off then SIP messages for that IP address will not be included.
	The only purpose for verify to be turned off is special documentation purposes. It should not be used
	when debugging traces.
   	The following example IP address 10.63.200.200 has been remove, but is a part of a scenario.
	The vertical column bars and arrow heads removed and extra infomration is added at the end of the trace.
   	This is to make sure SIP messages are not ignored. This is especially important for debugging.
   		Sometimes removing these message is required for documentation purposes.

   	0==> no inclusion. no verification. only include a trace if both IP addresses are defined in a column.
		|<--------------------(sdp) INVITE F1<|  Call#:1
		|>F2 100 Trying --------------------->|  Call#:1
		|>F3 INVITE (sdp)->|                  |  Call#:1
		|<-(sdp) OK 200 F4<|                  |  Call#:1

   	1==> Include SIP Messages with same Callid even though IP address has been removed for a column (default)
		|<--------------------(sdp) INVITE F1<|  Call#:1
		|>F2 100 Trying --------------------->|  Call#:1
		|>F3 INVITE (sdp)->|                  |  Call#:1
		|                  |                  |
		  F4 INVITE (sdp)                        Call#:1 [10.63.200.148:5060==>10.63.200.220:5060] IP_ADDR 10.63.200.220 excluded from columns
		|<-(sdp) OK 200 F5<|                  |  Call#:1

   -i[nclude][:N:]INCLUDEFILE allows file includeFile to be read as a set of commands
   	N is the number of lines to skip from the beginning of the include file.
   	The following this the logic for parsing each line of an include file.
   	*) The Comment delimiter is the "#". Characters starting with the "#" (and including the #) will be considered white space.
   	*) white space will be removed from the begining and end of each line
   	*) Lines ending with white space backslash  or "\" will be joined with the next line. 
   		The back slash will be removed and white space removed from the end of line
   	*) Lines that start with "perl" ,"exit" , "rem" or "sip_scenario" will also be ignored. 
   		This allows a batch file on a pc to trigger the script file and
   	*) A line that starts with end-of-file will cause the rest of the file to be ignored.
   	e.g. -i:includeFIle
   	e.g. -i:2:includeFIle		ignores the first 2 lines from file includeFile
   	
   		and to have that batch file be a sip_scenario.pl include file.
   		e.g.
   		===================================== Start of File sip_scenario.ini =======================
		# this file defines user preferences
		10.70.200.215/Leo
		10.70.200.218/Sam 
		10.70.200.196/George
		10.70.200.148/Proxy 
		10.70.200.195/Xian
		10.70.200.211/Corey
		10.70.200.220/Jeff
		10.70.200.79/Ray`s Laptop 
		10.73.200.150/Gateway
		10.70.200.227/Chris
   		===================================== End of File ==================================
   		or
   		===================================== Start of File doit.bat =======================
   		perl  sip_scenario.pl -I:2:doit.bat
		exit
		dump/trace_forking.dump		 	# input file
		-oipc_call_setup.html 			# output file
		-tRegistrations				# title
		-g30 					# gapwidth
		-phy:1  					# display physical frame numbers
   		===================================== End of File ==================================
		or
   		===================================== Start of File doit.bat =======================
		perl  sip_scenario.pl -i:ipc_call_setup.bat
		exit
		
		## start of include file here
		dump/trace_forking.dump 		# input file
		-oipc_call_setup.html 			# output file
		-tTurret Callflow using IPC Proxy	# set title
		-gap:30					# set gapwidth between lines
		-f:p:1 					# enable physical Frames
		-f:s:2/4				# turn on insertions of extra spaces over 2 seconds add 4 blank lines
		-colors:Black,Blue,Red,Green		# define colors if required
		-exclude:3,4-32,35-39,42-53		# exclude the specified physical frames
		10.70.200.148/IPC PROXY			# redefine alias.
		
		-fake:10.70.200.148:10.70.200.195:0:2:SIP/2.0 402 Some Response\n\
			User-Agent:Turret 9.01.01.x\n\
			ContentType=application/IPC\n\
			\n\
			lac=1024\n
		
		-fake:10.70.200.148:10.70.200.196:0:2:SIP/2.0 402 Some Response\n\
			User-Agent:Turret 9.01.01.x\n\
			ContentType=application/IPC\n\
			\n\
			lac=1024\n
		
		end-of-file
		
   		===================================== End of File ==================================
	Basic Operation: Tailored for windows PC.
		File sip_scenario.ini: this file is an optional file and should contains user preferences
		File ip_address_def_n.include: One or more files that contain ip Address and alias information.
			The order of ip Address determines the order of ip addresses in the scenario trace.
			So multiple multiple may be required for multiple traces.
		user specific setting can also be added to this file to tailer the defaults for a user.
		File trace.bat:a batch file that invokes sip_scenario and customizes the output for that specific trace
			includes:
			A. the input and output file names
			B. title of the document
			C. Physical Frames to exclude.
			D. Reorder physical Frames
			E. Fake (user defined) Frames
			F. Other document specific item.

   		to execute this file from a window command execute
   		cmd /c doit.bat	
   		which creates a new command window executes the batch file doit.bat,
   		doit.bat executes the command perl ... which includes the file doit.bat
   			The sip_scenario.pl script file read doit.bat and will ignore the
   			first two lines.
   		doit.bat then exits and close the window create the command \"cmd\".
   	Note: if file \"sip_scenario.ini\" is present then it will be included before any other parameters are parsed - even from the command line.

   -ports:protocol:LIST Change the list of ports to listen on. the default value is 5060.
   	LIST is a comma separate list of port numbers. 
	e.g. -ports:udp:5060,5061		set ports to trace for udp = 5060 and 5061
	e.g. -ports:tcp:5060,5061		set ports to trace for tcp = 5060 and 5061

   -range:RANGELIST specifies the set of physical frames that will be read.
   	This is designed for very large trace files that can not be otherwise handled by this
   	implementation. Can also be used for filtering.
	packets excluded will not be parsed.
	same as -include:line:RANGELIST
   	RANGELIST is a comma separate list of ranges or individual physical frame numbers ,,1-5,2,3,4,10-12   is a valid LIST
   	e.g.    -range:1-2,10-20,4-5

    -i[nclude]:line:RANGELIST specifies the set of physical frames that will be read.
   	This is designed for very large trace files that can not be otherwise handled by this
   	implementation. Can also be used for filtering.
	same as -range:RANGELIST
   	RANGELIST is a comma separate list of ranges or individual physical frame numbers ,,1-5,2,3,4,10-12   is a valid LIST
   	e.g.    -include:line:3,10-20,4-5

    -e[xclude]:[line:]RANGELIST specifies the set of physical frames that will not be used to generate
    	SIP Scenarios. The -range command will filter frames before this command.
   	RANGELIST is a comma separate list of ranges or individual physical frame numbers ,,1-5,2,3,4,10-12   is a valid LIST
   	-excludes the defined set of physical sip messages from being placed in the scenario.
   	e.g.    -exclude:1,3,10-20,4-5

    -i[nclude]:t[ime]:STARTTIME-ENDTIME | 		Range of Physical Frames to include based on a time range
    	packets outside this time range are immediately discarded and will not be parsed.
        TIME			:= [[[YEAR/]MM/]DD/]HH:MM[:SS]
	Year is the actual year. e.g. 2003		Year is optional
	Month has a range 1-12				Month is optional
	Day has a range 1-31				Day is optional
	Hour has a range 0-23
	Minutes have a range of 0-59
	Seconds have a range of 0-59
	STARTTIME: default values for YEAR,MM (Month), and DD (day) will the the Year,month, and day of the first traced packet.
	ENDTIME: default values for YEAR,MM (Month), and DD (day) will the the Year,month, and day of the STARTTIME
	use the -debug option to debug problems.
    	
    -i[nclude]:c[allid]:RANGELIST specifies the set of Calls that will be included.
    	This is an easy and save way to filter out SIP packets. It is easy to filter of registrations just by excluding a single callid.
    	Call Id are numbered sequentially based on the SIP CALLID field. CallIDs are unique just like a SIP CALLID.
	In large traces in is necessary to limit the display to a certain set of calls. 
	The "-include:callid" and the "-exclude:callid" provide that ability.
	Initially all calls are included.
	If the first include/exclude command is an include then the set is changed to the set described by that include command.
	From then on exclude commands will remove calls from the list and include commands will add calls to the list.
	There is no restriction as to order of includes or excludes.
	There is no restriction of order in the RANGELIST, with the exception that the start of a range must not be greater than the end.
	-include:callid:1,50,20-30

   -e[xclude]:c[allid]:RANGELIST specifies the set of Calls that will be excluded.
    	see -include:callid for details.
	-exclude:callid:1,50,20-30

    -i[nclude]:req[uest]:REQUEST  		defines a set of calls to include by matching any SIP REQUEST in the call with REQUEST

    -e[xclude]:req[uest]:REQUEST 	 	defines a set of calls to include by matching any SIP REQUEST in the call with REQUEST

    -i[nclude]:m[atch]:STRING		  	defines a set of calls to include by matching any header in the call with the STRING
    						same as -include:expression

    -i[nclude]:e[xpression]:PERLPATTERN  	defines a set of calls to include by matching any header in the call with the PERLPATTERN
	Any Header that matches the PERLPATTERN will cause all SIP messages in that call to be included.
	Multiple arguments of -include:expression works as follows: the last one process will be executed.  Only one instance is supported. 
        PERLPATTERN is a "Perl" Language pattern to match. See Perl documentation for details of matching and perl regular expressions
	http://www.perldoc.com/perl5.6/pod/perlre.html 

	Here are some defintions of perl metacharacter characters. 
	^	Matches start of line
	$	Matches end of line
	|	Logical Or
	\w  	Match a "word" character (alphanumeric plus "_")
    	\W  	Match a non-word character
    	\s 	Match a whitespace character
    	\S  	Match a non-whitespace character
    	\d  	Match a digit character
    	\D  	Match a non-digit character
	\X	escapes next character. same as X    		e.g. \ evaluates to \
	\b	Matches a word boundary
	.	Matches any character.
	+	Preceding character or expression must occur one or more times
	*	Preceding character or expression must occur zero or more times
	?	Preceding character or expression must occur zero or one times
	{N,M}	Preceding character or expression must occur at Least N times but not more than M times
	()	Grouping
	(?i)	Add to start of String if case-insenative matching is desired.
	\s*	Matches any white space string. Empty allowed.
	\w+	Matches a word
    	Examples:
	-include:expression:(?i)^(from|to).*George\@			## include calls with george@ contained in From or To headers
	-include:expression:(?i)^(from|to).*george\@ipc\.com		## include calls with george@ipc.com contained in From or To headers
	-include:expression:(?i)^to.*george\@				## include calls with george@ contained in To headers
	-include:expression:presence					## include calls that have the characters presence in some header
	-include:expression:(?i)\bpresence\b				## include calls that have the word presence in some header
	-include:expression:(?i)^Allow-Events\s*:\s*presence\s*$	## include calls that have the header "allow-events : presence" 
	-i:e:^REFER\s+							## include calls with a REFER request

   -e[xclude]:e[xpression]:PERLPATTERN  	Similar to -include:expression except that calls are excluded. 

   -i[nclude]:ip:IPADDRESS 
   	includes any call that has any SIP packet with the IP header containing the specified IPADDRESS
	-include:ip:10.1.2.206						## include calls that have ip address = 10.1.2.206
	-i:ip:10.1.2.206						## include calls that have ip address = 10.1.2.206

   -e[xclude]:ip:IPADDRESS 
   	excludes any call that has any SIP packet with the IP header containing the specified IPADDRESS
	-exclude:ip:10.1.2.206						## exclude calls that have ip address = 10.1.2.206
	-e:ip:10.1.2.206						## exclude calls that have ip address = 10.1.2.206

   -f[ormat]:c[allid]:NUMBER          controls the inclusion of CallId of the scenario Trace
   	default n=1;
   	where N=
   	0==> No call Id
		|>F22 ACK --------------------------->|  
		|<---------------------- REGISTER F23<| 
		|>F24 200 OK ------------------------>| 
   	1==> call Id with no Descriptor (default)
		|>F22 ACK --------------------------->|  1
		|<---------------------- REGISTER F23<|  2
		|>F24 200 OK ------------------------>|  2
   	2==> call Id with Descriptor
		|>F22 ACK --------------------------->|  Call#:1
		|<---------------------- REGISTER F23<|  Call#:2
		|>F24 200 OK ------------------------>|  Call#:2

   -f[ormat]:t[ime]:NUMBER           controls the inclusion of time display on the scenario trace.
       Time is based on the absolute time contained in the libpcap trace input file.
       Delta time can be negative when Physical frames are reordered for display purposes.
       The time display is controled by bits. Add the bits together to get the desired time display.
       1==> Delta Time	(default) (from previous displayed packet)
		10.63.200.218      10.63.200.148      10.63.200.195      10.63.200.196
		|                  |                  |                  |  <DeltaTime>
		|>F1 INVITE (sdp)->|                  |                  |  0     
		|<-- Trying 100 F2<|                  |                  |  0.0013
		|                  |>F3 INVITE (sdp)->|                  |  0.0014
		|                  |>F4 INVITE (sdp)-------------------->|  0.0004
       2==> Relative Time (from first packet)
		10.63.200.218      10.63.200.148      10.63.200.195      10.63.200.196
		|                  |                  |                  |  <RelTime>
		|>F1 INVITE (sdp)->|                  |                  |  0     
		|<-- Trying 100 F2<|                  |                  |  0.0013
		|                  |>F3 INVITE (sdp)->|                  |  0.0027
		|                  |>F4 INVITE (sdp)-------------------->|  0.0040
       4==> Time of Day  (absolute time)
		10.63.200.218      10.63.200.148      10.63.200.195      10.63.200.196
		|                  |                  |                  |  <Time>
		|>F1 INVITE (sdp)->|                  |                  |  16:30:31.5593
		|<-- Trying 100 F2<|                  |                  |  16:30:31.5606
		|                  |>F3 INVITE (sdp)->|                  |  16:30:31.5621
		|                  |>F4 INVITE (sdp)-------------------->|  16:30:31.5633
       8==> Date 
		10.63.200.218      10.63.200.148      10.63.200.195      10.63.200.196
		|                  |                  |                  |  <Date>
		|>F1 INVITE (sdp)->|                  |                  |  28/Feb/03
		|<-- Trying 100 F2<|                  |                  |  28/Feb/03
		|                  |>F3 INVITE (sdp)->|                  |  28/Feb/03
		|                  |>F4 INVITE (sdp)-------------------->|  28/Feb/03
   	where N=
       0==> No time
       1==> Delta Time	(default) (from previous displayed packet)
       2==> Relative Time (from first packet)
       3==> Delta Time	 and Relative Time
       4==> Time of Day  (absolute time)
       5==> Both Delta time  and Time of Day 
       6==> Relative Time and Time of Day  
       7==> Delta time, Relative time, and Time of Day 
       ...
       12==> date and time
		10.63.200.218      10.63.200.148      10.63.200.195      10.63.200.196
		|                  |                  |                  |  <Date><Time>
		|                  |                  |                  |
		|>F1 INVITE (sdp)->|                  |                  |  28/Feb/03 16:30:31.5593
		|<-- Trying 100 F2<|                  |                  |  28/Feb/03 16:30:31.5606
		|                  |>F3 INVITE (sdp)->|                  |  28/Feb/03 16:30:31.5621
		|                  |>F4 INVITE (sdp)-------------------->|  28/Feb/03 16:30:31.5633
       15==> Delta, Relative, and date and time
		10.63.200.218      10.63.200.148      10.63.200.195      10.63.200.196
		|                  |                  |                  |  <DeltaTime><RelTime><Date><Time>
		|                  |                  |                  |
		|>F1 INVITE (sdp)->|                  |                  |  0      0      28/Feb/03 16:30:31.5593
		|<-- Trying 100 F2<|                  |                  |  0.0013 0.0013 28/Feb/03 16:30:31.5606
		|                  |>F3 INVITE (sdp)->|                  |  0.0014 0.0027 28/Feb/03 16:30:31.5621
		|                  |>F4 INVITE (sdp)-------------------->|  0.0004 0.0040 28/Feb/03 16:30:31.5633

   -f[ormat]:p[hy]:NUMBER 
       Adds physical frames numbers to scenario diagram. The physical Frame number is the location of the packet in the ethernet trace file.
   		0==> disable display of physical frame numbers
			|>F1 INVITE (sdp)->|                  |                  | 
			|<-- Trying 100 F2<|                  |                  | 
   		1==> enable display of physical frame numbers
			|>F1 INVITE (sdp)->|                  |                  | PF3  
			|<-- Trying 100 F2<|                  |                  | PF4  

   -f[ormat]:f[rames]:NUMBER       controls the inclusion of the extended frame data or not. 
   	Extended Data is the set of displayed SIP messages including their content
   	where N=
   	0==> No Extended Frame data included.
		When no extended frame data is included then the index.html and indexhtml.html are not created.
   	1==> Extended Frame Data included.   (default)

   -f[ormat]:v[ertical]:NUMBER 
	set the vertical compression mode to value N, where N is 0,1, 2 or 3
   	where N=
   	0==> description and arrow on the same line
		|<--------------------(sdp) INVITE F1<|  
		|>F2 100 Trying --------------------->|  
   	1==> description and arrow on the same line with extra blank line  (default)
		|                  |                  |
		|<--------------------(sdp) INVITE F1<|  
		|                  |                  |
		|>F2 100 Trying --------------------->|  
   	2==> no blank lines	
		|                  |  (sdp) INVITE F1 |
		|<-----------------------------------<|  
		| F2 100 Trying    |                  |
		|>----------------------------------->| 
   	3==> extra blank line   
		|                  |                  |
		|                  |  (sdp) INVITE F1 |
		|<-----------------------------------<|  
		|                  |                  |
		| F2 100 Trying    |                  |
		|>----------------------------------->|  

   -f[ormat]:s[pacetime]:N/Q 
     set the number of seconds between traced messages so that Q extra blank lines can be added between messages.
   	N is a non-negative integer unit seconds
   	Q is a non-negative integer range unit number of blank lines to add.
   	This allows long periods of time to be indicated in the trace.
   	The default value is 2 seconds.
   	The value of zero disables this feature.
   	default: turned off
   	e.g. 
   	-f:s:0/0	## turn off feature
   	-f:s:5/8	## after 5 seconds difference in time betwwen two SIP messages insert 8 blank lines.

   -percent:NUMBER 
   	defines the percent of vertical space allocated to the bottom frame in the index.html file.
	-percent:50	## allocates 50% of the vertical space to frame data.
	Default value is 33 percent.

   -re[order]:LIST:FRAME 
   	LIST is a comma separate list of ranges or individual physical frame numbers ,,1-5,2,3,4,10-12   is a valid LIST
   	FRAME is the physical frame where the defined set of physical frames should be placed after.
   	-reorder reorder the order in which sip messages are displayed.  SIP frame numbers (F10) are resequenced automatically
   		Physical frame numbers are not changed and can be display with the -phy command
   	e.g.    -reorder1,2,3,7,10-20:4
   	e.g.    -reorder,1,2,3,7,10-20:4
   	e.g.    \"-reorder 1 , 2 ,3,7,10-20:4\"

   -c[omment]:FRAME:COMMENT Adds COMMENT after indicate physical Frame.		note: \n works
		e.g. -comment:0:User dials number 2111.

   -c[ommentprefix]:STRING: Adds STRING before all comment lines.  Note the extra : at the end of the STRING.
		e.g. -commentprefix:                            :

   -fake:SRCIP:DSTIP:CALL#:FRAME:MESSAGE	Add Fake Sip messages to the scenario. Increments the SIP Frame number
   	SRCIP==> Source Ip address | IpAddressAlias
   	DSTIP==> Destination Ip Address | IpAddressAlias
   	CALL#==>  CALL#
   		N==> Use CALLID for Call Number N. where is a number. 
   		W==> (alphanumeric string) Use Unique Callid W (Create it one first occurance)
   	FRAME==>  Physical Frame Number. Adds Message after the indicated Frame.
	MESSAGE==> Sip Message to Display    
		Multiple lines may be created and are separated by the delimiter \n.    note: this is much easier from an include file
		line1\nline2\nline3\n\nsdpline1\nsdpline2 ,....
	e.g.
	-fake:10.70.200.148:10.70.200.195:0:2:SIP/2.0 402 Some Response
	or
	-fake:10.70.200.148:10.70.200.196:0:2:SIP/2.0 402 Some Response\nUser-Agent:Turret 9.01.01.x\n
		
   -colors:COLORLIST Change the set of colors that are used to display scenarios.
   	LIST is a comma separate list of colors. 
   	a color is an valid html colors. The set of html colors is from the following list
   		Black,Green,Silver,Lime,Gray,Olive,White,Yellow,Maroon,Navy,Red,Blue,Purple,Teal,Fuchsia,Aqua 
   		or a color can be a user defined color in the form #RRGGBB
		where RR,GG,BB are each two hex digits e.g. #FF0080
	e.g. -colors:Black,Red,#808080

   -stat:NUMBER	This commands turns on/off the display of statistics in the output files.
   		if NUMBER is zero then statistics are disabled.
		if NUMBER is one then statistics are enabled. (default)

   -copy	This commands copies the input file to an output file with filtering.
   		Only TCP and UDP packets are copied.
		the -range command will limit the number of packets that are copied.
		the -x command will translate IP address in the IP headers (host formatted) 
			and in the TCP/UDP data (ascii dot notation).
		-x:IPADDRESS=IPADDRESS

   -merge:FILENAME2  This command Mergeis capture file2 with 1st capture file, 
		automatic time synchronization and removes duplicate pkts

   -debug:NUMBER turns on debug mode. This adds extra information to the output files.

   -ker[beros][:NUMBER] enable/disable adding kerberos protocol to trace
   		if NUMBER is not specified then kerberos tracing is enabled.
		NUMBER=0 disable kerberos tracing
		NUMBER!=0 ensable kerberos tracing


   -summary[:FILENAME] displays a summary of ip adrress used and calls.
   		If the FILENAME is not specified then the output is to STDOUT.
		IPADDRESS[:PORT]	ALIAS
		...
		IPADDRESS[:PORT]	ALIAS
		CALL 1 TIME FROM_USER TO_USER IPADDRESS[:PORT] ... IPADDRESS[:PORT]
		...
		CALL N TIME FROM_USER TO_USER IPADDRESS[:PORT] ... IPADDRESS[:PORT]

   -keep:NUMBER					# the set of files to keep
		bit defined 
		bit	value	Description
		0	1	Triple Frame (dual file) output	
				basefilename_index.html
				basefilename_indexhtml.html
		1	2	Single html file
				basefilename.html
		2	4	plain txt file.
				basefilename.txt
		Default value is 7 which keeps all files.
		
    -NoPauseOnError				# disables pause on error feature that forces a user
    						# to hit a key to see error message
						# NoPause on error should be first argument passed.
    -PauseOnError				# Enables pause on error feature that forces a user
    						# to hit a key to see error message

################################################################################################
# Applications
################################################################################################
*	Run Sip Scenario Generator while actually tracing ethernet data.
	tcpdump can directly capture ethernet data and copy it directly into a file. 
	Each time a packet is traced it is appended to the end of a file. The last packet in the
	file may not be completely written.

	On bsd 4.1 (intel)
	tcpdump -s 1514 -i fxp1 -w /tmp/sip.dump "port 5060" &

	On linux 7.3 I use:
	tcpdump -s 0 -i eth0 "port 5060" -w /var/log/sip1.dump &

	while the tcpdump is writing to the file sip_scenario.pl can be executed.
	The following command will find all calls that have any Sip header containing ray@ipc.com
	perl sip_scenerio.pl /var/log/sip1.dump  -include:match:ray@ipc.com
################################################################################################
# Changes History / Release information
################################################################################################
Date             Author            	Description
 8 Apr 2003      D. Ray Elliott     	Release 1.1.0
10 Apr 2003      D. Ray Elliott     	Added pattern Matching filters 
					-include:expression
					-include:match
11 Apr 2003      D. Ray Elliott     	Fixed libpcap format issues. Now have struct definitions 
					Created Bug list Item.
11 Apr 2003      D. Ray Elliott     	Release 1.1.1
11 Apr 2003      D. Ray Elliott     	Added filtering by Time
					-include:time:
					Allows packets to be included based on time
12 Apr 2003      D. Ray Elliott     	Release 1.1.2
18 Apr 2003      D. Ray Elliott     	Added handling of Compact forms of header names for
					Call-id, Content-type, and Content-Length headers.
18 Apr 2003      D. Ray Elliott     	Copied Time::Local into sip_scenario.pl file.
18 Apr 2003      D. Ray Elliott     	Release 1.1.4
22 Apr 2003      D. Ray Elliott     	Added filtering by ip address
22 Apr 2003      D. Ray Elliott     	Release 1.1.5
16 May 2003      D. Ray Elliott     	Handling Fragmented IP packets
17 May 2003      D. Ray Elliott     	allowed the -o options to be a directory name. 
25 Apr 2003      D. Ray Elliott     	Release 1.1.7
 4 Aug 2003      D. Ray Elliott     	-o options to be a directory name. caused problem with
 					html file that has three frames. _index.html file.
					Release 1.1.8
 5 Aug 2003      D. Ray Elliott     	Add support for 802.1p/q ethernet format.
					Release 1.1.9
25 Aug 2003      D. Ray Elliott     	Add basic support for kerberos tracing
26 Aug 2003      D. Ray Elliott     	Release 1.1.10
10 Sep 2003      D. Ray Elliott     	Did not work on linux/solaris perl 5.8.
13 Sep 2003      D. Ray Elliott     	Release 1.1.11
17 Nov 2003      D. Ray Elliott     	Added -summary command
17 Nov 2003      D. Ray Elliott     	Release 1.1.12
19 Nov 2003      D. Ray Elliott     	Add check for short capture lengths. and display 
					Correct error message
					Changed summary output from IPADDRESS ALIAS to IPADDRESS/ALIAS
22 Nov 2003      D. Ray Elliott     	Release 1.1.14
24 Nov 2003      D. Ray Elliott     	Added symmetric udp ports handling.
					Changed IPADDRESS[/ALIAS][:NUMBER] to
						IPADDRESS[:PORT}[/ALIAS][:NUMBER]
26 Nov 2003      D. Ray Elliott     	Fixed program to determine the version of libpcap format
					requires the use of seek
					Also improved error messages for file format errors.
26 Nov 2003      D. Ray Elliott     	Release 1.1.15
27 Nov 2003      D. Ray Elliott     	Automatcially change width between column 
					if not set by command.
29 Nov 2003      D. Ray Elliott     	added -keep option Delete generated files that are undesired.
29 Nov 2003      D. Ray Elliott     	Release 1.1.16
 3 Dec 2003      D. Ray Elliott     	Fixed  bug in symmetric udp port detection
 4 Dec 2003      D. Ray Elliott     	Added Merge capture file capability.
 					automatic time syncronization.
					automatic discarding of duplicate usp SIP messages.
 5 Dec 2003      D. Ray Elliott     	Added singleua option for symmetric udp port detection
 					by globally or by IPADDRESS
 6 Dec 2003      D. Ray Elliott     	Fixed output so that it can be a directory name without "/" afterwards.
 6 Dec 2003      D. Ray Elliott     	Fixed infinite loop bug in merge capture file 
 					when there are identical pkts in the first file.
 7 Dec 2003      D. Ray Elliott     	Added filter -exclude:expression
 8 Dec 2003      D. Ray Elliott     	Release 1.1.17
 9 Dec 2003      D. Ray Elliott     	Added Multiple expression filters -include/exclude:request
 					Change include/exclude rules. undef,include,exclude.
					Undef to include to exclude or undef to exclude.
					undef == exclude if any include else undef=include
 9 Dec 2003      D. Ray Elliott     	Added filters -include/exclude:request
 9 Dec 2003      D. Ray Elliott     	Release 1.2.0
 1 Mar 2004      D. Ray Elliott     	Added support for PPP over Ethernet
 1 Mar 2004      D. Ray Elliott     	Release 1.2.1
 5 Apr 2004      D. Ray Elliott     	Release 1.2.2 Added Errors message for merge option.
 3 May 2004      D. Ray Elliott     	Release 1.2.3 merge option - fixed duplicate packet check
 					check only for IP Src,IP Desc, IP Protocol, and Data. 
					Not time to live, etc.
23 Jun 2004      D. Ray Elliott     	Release 1.2.4 If the content contains unprintable character
					not ( \r \n \0x20 - \0x7f) then the display of the frame does
					not work properly on windows machines.
18 Jul 2004      D. Ray Elliott     	Release 1.2.5 Fixed various command syntax processing problems.
19 Jul 2004      D. Ray Elliott     	Release 1.2.6 Fixed various command syntax processing problems.
					Added disabling of pauseOnError feature.
25 Jul 2004      D. Ray Elliott     	Release 1.2.7 
					* default end time based on start time rather than time of trace.
					* Addec optional seconds to start & end time
					* changed "forced column excluding" display mechanisms.
					* Fixed various warnings.

################################################################################################
#  Restrictions: (Future Improvements)
################################################################################################
*	only handles ethernet packets.
*	does not have a gui front end,
*	does not trace non-sip packets.	Let ethereal do that or other sniffers do that.
################################################################################################
# Bug List
################################################################################################
*	Does not detected sendonly/recvonly in SDP body. (does detected hold as all port#s=0);
*	Exclude IP address requires an alias 10.10.10.10:0 does not. but 10.10.10.10/x:0 will.
################################################################################################
#  Future Improvements
################################################################################################
*	Change arrows to a graphical interface. for html page
*	-fake add feature for coping from,to headers from a previous message
*	improved help mode from command line. 
################################################################################################

