##############################################################################
# DIALOGIC CONFIDENTIAL
# 
# Copyright (C) [2007] Dialogic Corporation. All Rights Reserved.
# The source code contained or described herein and all documents related
# to the source code ("Material") are owned by Dialogic Corporation or its
# suppliers or licensors. Title to the Material remains with Dialogic Corporation
# or its suppliers and licensors. The Material contains trade secrets and
# proprietary and confidential information of Dialogic or its suppliers and
# licensors. The Material is protected by worldwide copyright and trade secret
# laws and treaty provisions. No part of the Material may be used, copied,
# reproduced, modified, published, uploaded, posted, transmitted, distributed,
# or disclosed in any way without Dialogic's prior express written permission.
# 
# No license under any patent, copyright, trade secret or other intellectual
# property right is granted to or conferred upon you by disclosure or delivery
# of the Materials, either expressly, by implication, inducement, estoppel or
# otherwise. Any license under such intellectual property rights must be
# express and approved by Dialogic in writing.
##############################################################################

##############################################################################
#        NAME : cte_readme.txt
# DESCRIPTION : General information for using cte.pl
#     HISTORY : 1.0 - BLC - Initial Version
##############################################################################


##############################################################################
#### General Description ####
*   This script is designed to automate issuing commands to the CLI interface.
	The script and the *.cfg files are shipped as demos and can be designed
	to suit any solution.

*   cte.pl is the PERL script that handles the following:
	1.  CLI (Telnet) session
	2.  Command parsing/processing
	3.  Logging

*   The *.cfg files are templates that represent the basic configuration commands
	needed to start the system.  They will need to be changed to fit the 
	environment they are to be used in.  These files are passed to cte.pl 
	via the command line.

*   The configuration files can be any number of commands of any type.  If 
	the command exists in the CLI it can be set into the configuration file.

*   Examples: (Notice config file names can omit extension or be of any type)
	
	1.  Run sanity check on local machine
		'./cte.pl'
	
	2.  Run as a craftsperson user on ipaddress which uses show_all as the config file. 
		'./cte.pl -u craft -c show_all -i 192.168.1.105
	
	3.  Run as account manager on local system
		'./cte.pl -u acctmgr -c build_new_accts

	4.  Run as root user on remote machine running CLI on different port
		'./cte.pl -i 192.168.1.105 -p 2323 -c config_machine.cli


##############################################################################
#### Notes (Limitations / Expectations) ####
*   The default port will need to be changed when the default CLI listening port 
    is changed.

*   This tool has no built in error handling for the CLI responses, meaning the 
    script will not react to any CLI output.

*   The PPM portion for installing the Telnet module is commented out for the 
    demo version of this script.  Check the subroutine CheckForModules().

*   The username will be used for the password.

*   The supplied cfg files are to be used as templates, changes will have to be
    made to suit the environment.

*   All runtime params are supported either on the command line or config file except for '-c', '-d' and '-h'.

*   Runtime parameters 'i', 'p', 'l', 'c', and 'u' are currently case sensitive when used on the command line.

*   Command line has the highest precedence

*   <cfgfile>.log is the script log file.

*   CLI_session.log is the readable form of the CLI transactions.

*   network_dump.log is the complete dump of the network traffic.  Use Debug (-d) flag to generate.

*   'Net-Telnet' package must be installed on Linux systems.  Windows systems will have the module installed if it is not present.

*   Demo version of script must uncomment PPM portion in CheckForModules() for the PPM to work.

*   Setting timeout for event handling is currently not supported.

##############################################################################
#### Runtime Parameters ####
Argument             Default Value           Purpose
-i = IP Address      - 127.0.0.1             CLI IP address
-p = Port            - 23                    CLI Port
-l = Loops           - 1
-c = Config file     - cli_sanity.cfg
-u = Login name      - 'root'                CLI login name
-d = Debug flag      - Off                   Print execution flow to console
-q = Quit flag       - Off                   Quit testcase on first failure
-s = Strict flag     - Off                   Does not remove leading (trailing) whitespace and <CR> from comparisons
-h = Options Menu    - Off                   Show this menu, optional '?'


##############################################################################
#### Issuing commands ####
 Notes:
         * The format for action lines within a test case is:
             'CLI Command' <COMPARISONOPERATOR> |Expected Response
         
	 * Responses can span multiple lines, all that is needed is the '|'
           character to denote the response.  The response will be appended to the
           last parsed command / compare operator
         
         * Supported Comparison Operators:
             '=>' - Response pattern is matched exactly.
             '~>' - Response pattern must contain substring(s).  Substrings are
                    separated by a comma.
             '!>' - Response pattern must NOT contain substring(s).  Substrings
                    are separated by a comma.
         
         * To issue the command and not test the response just put the command
           in single quotes on a line. (Ideal for configuration purposes)
         
         * The response strings are case sensitive.
         
         * While using strict mode leading white space within an exact comparison match 
	   can sometimes cause problems. 

 Examples:
         * Just issue the command, do not test the response
         'show boot'

         * Test for the exact string 
         'show hardware amc 2'                   => |AMC not installed

         'show version'                          => |IPMS ATCA Blade
                                                    |Name:          TVL16
                                                    |Form Factor: ATCA
                                                    |Model:       IPMS-MDL-707
                                                    |Vendor:      Intel Corp,  Serial Number: SN-123456789

         'show whatever'                         => |Usage:show
                                                    |	 arp               ARP table
                                                    |    boot              Boot image setting
                                                    |    controller        Controller status and configuration

         * Test for containing the substrings
         'show interface Ethernett'              ~> |unknown, option, expected, desc, Display
         'show interface eth4'                   ~> |Bay, Status, Vendor, MMC Version
                                                    |Service, Health, LEDs

         * Test for NOT containing the substrings
         'show interface ds1'                    !> |HMP, cPCI, SIP
         'show interface Internet'               !> |http, link up, proxy


##############################################################################
#### Setting User Defined Variables ####
 Notes:
         * The format to set user defined variables from the response is as
           follows:  [ &UserVar <LOCATIONOPERATOR> "Token"
           This will place a substring in &UserVar to be used in a following
           command.
         
	 * Supported location operators:
             '->' - Grab the substring following the token
             '<-' - Grab the substring preceding the token
         
	 * User defined variables cannot be used on the first command in the
           config file.
         
	 * If multiple tokens are found in a response the last token will be used.
         
	 * Once initialized, variables have global scope.
         
	 * Variables will be overwritten if re-defined within the config file, the last
           variable matched will contain the latest value
         
	 * Warnings will be generated if a user variable is not set from the
           token not being found.  Execution will continue with &"UserVarName"
           string literal being inserted into the command string.

 Examples: (Made up commands just to illustrate)
         * This example will grab the first substring to the right of "Hardware address:"
           (and "Ip Address:") and place it in &MACAddr (&IPAddr) to be used in
           subsequent commands

         'show interface ethernet 4'             ~> |Hardware address:, Ip Address:
                                                    [ &MACAddr -> "Hardware address:"
                                                    [ &IPAddr  -> "Ip Address:"


         'conf &IPAddr for &MACaddr'             !> |Fail, invalid, error


##############################################################################
#### Event Handling ####
 Notes:
	* The format to handle events is as follows:
			!EVENT[event1]
	  This will cause command execution to pause until event1 is detected in an event string
	
	* Multiple events can be handled in a single declaration using the syntax:
			!EVENT[event1|event2|event3]
	
	* The first 'event' detected will cause the next command to be issued
	
	* Event substrings are case sensitive and whitespace sensitive
	
	* !EVENT[] declarations will be assigned to the previous command that has been parsed

	* If the event is not detected by the timeout the script will exit.

Examples:
	* This example will look for the 'not ready' event after the stop command has been issued.
	  The start command will not be issued until 'not ready' is detected.

	'conf system ip stop'			~> |updated
						   	   !EVENT[not ready]

	'conf system ip start'			~> |updated
						   	   !EVENT[ready|fault] 
 	 	

##############################################################################
#### Substring Handling ####
 Notes:
	* Similiar to events, substrings can be detected in circumstances where the expected event will not occur. 
	
	* The format to handle substrings is as follows:
			!SUBSTRING[substring1]
	  This will cause all output, up to the next prompt, to be searched for the substring.
	
	* Multiple substrings can be handled in a single declaration using the syntax:
			!SUBSTRING[substring1|substring2|substring3]
	
	* The first 'substring' detected will cause all events, defined for that test case, to be cleared 
	
	* Substrings are case sensitive and whitespace sensitive
	
	* Only substrings contained in the output up until the next prompt will be tested
	
	* !SUBSTRING[] declarations will be assigned to the previous command that has been parsed

	* If the substring is not detected any events that are defined must be detected by the timeout or the script will exit.

	* If no events are defined substring handling has no effect

Examples:
	* This example will look for the 'not ready' event after the stop command has been issued.  However, if the system is in the stopped state the event will not occur, there will be output returned to signal this fact.  The !SUBSTRING[] will guard against the script timing out looking for an event that will never occur.

	'conf system ip stop'			~> |updated
						   	   !EVENT[not ready]
							   !SUBSTRING[stopped]
							   
	* This example will search the output detected up until the cli prompt is returned looking for "stopped", if it is detected the system is in the stopped state so the script will not poll for the event.

