NAME

Control::CLI::AvayaData - Interact with CLI of Avaya Networking products over any of Telnet, SSH or Serial port

SYNOPSIS

use Control::CLI::AvayaData;

Connecting with Telnet

# Create the object instance for Telnet
$cli = new Control::CLI::AvayaData('TELNET');
# Connect to host
$cli->connect(	Host		=> 'hostname',
		Username	=> $username,
		Password	=> $password,
	     );

Connecting with SSH - password authentication

# Create the object instance for SSH
$cli = new Control::CLI::AvayaData('SSH');
# Connect to host
$cli->connect(	Host		=> 'hostname',
		Username	=> $username,
		Password	=> $password,
	     );

Connecting with SSH - publickey authentication

# Create the object instance for SSH
$cli = new Control::CLI::AvayaData('SSH');
# Connect to host
$cli->connect(	Host		=> 'hostname',
		Username	=> $username,
		PublicKey	=> '.ssh/id_dsa.pub',
		PrivateKey	=> '.ssh/id_dsa',
		Passphrase	=> $passphrase,
	     );

Connecting via Serial port

# Create the object instance for Serial port e.g. /dev/ttyS0 or COM1
$cli = new Control::CLI::AvayaData('COM1');
# Connect to host
$cli->connect(	BaudRate	=> 9600,
		Parity		=> 'none',
		DataBits	=> 8,
		StopBits	=> 1,
		Handshake	=> 'none',
	     );

Sending commands once connected and disconnecting

$cli->enable;
$cli->return_result(1);
$cli->cmd('config terminal') or die $cli->last_cmd_errmsg;
$cli->cmd('no banner') or die $cli->last_cmd_errmsg;
$cli->cmd('exit') or die $cli->last_cmd_errmsg;
$cli->return_result(0);
$cli->device_more_paging(0);
$config = $cli->cmd('show running-config');
print $config;
$cli->disconnect;

DESCRIPTION

Control::CLI::AvayaData is a sub-class of Control::CLI allowing CLI interaction customized for Avaya (ex Nortel Enterprise) Networking products over any of Telnet, SSH or Serial port. This class supports all of Avaya Virtual Services Platform (VSP), Ethernet Routing Switch (ERS), Secure Router (SR), WLAN Controller (WC) and WLAN Security Switch (WSS) models as well as most of the legacy data products from Nortel Enterprise (Bay Networks) heritage. Currently supported devices:

VSP 4000, 7000, 8000, 9000
ERS/Passport models 1600, 8300, 8600, 8800
ERS models 2500, 3500, 4x00, 5x00
SR models 2330, 4134
WLAN(WC) 81x0
WLAN(WSS) 2350, 236x, 238x
BPS 2000, ES 460, ES 470
Baystack models 325, 425
Accelar/Passport models 1000, 1100, 1200

Avaya has converged the CLI interface of its current range of products into a single unified (Cisco-like) CLI interface (Avaya-CLI or ACLI; previously called NNCLI in the Nortel days). This module supports the current and latest Avaya Networking products as well as the older product families previously offered by Nortel where a number of different CLI variants exist (e.g. Passport/Accelar CLI which is still widely used). Hence the devices supported by this module can have an inconsistent CLI (in terms of syntax, login sequences, terminal width-length-paging, prompts) and in some cases two separate CLI syntaxes are available on the same product (ERS8x00 product families support both the new and old CLI modes). This class is written so that all the above products can be CLI scripted in a consistent way regardless of their underlying CLI variants. Hence a script written to connect and execute some CLI commands can be written in exactly the same way whether the product is an ERS8600 (using old CLI) or an ERS4500 or a SR2330. The CLI commands themselves might still vary across the different products though, even here, for certain common functions (like entering privExec mode or disabling terminal more paging) a generic method is provided by this class.

Control::CLI::AvayaData is a sub-class of Control::CLI (which is required) and therefore the above fuctionality can also be performed in a consistent manner regardless of the underlying connection type which can be any of Telnet, SSH or Serial port connection.

In the syntax layout below, square brackets [] represent optional parameters. All Control::CLI::AvayaData method arguments are case insensitive.

OBJECT CONSTRUCTOR

Used to create an object instance of Control::CLI::AvayaData

new() - create a new Control::CLI::AvayaData object

$obj = new Control::CLI::AvayaData ('TELNET'|'SSH'|'<COM_port_name>');

$obj = new Control::CLI::AvayaData (
	Use			 => 'TELNET'|'SSH'|'<COM_port_name>',
	[Timeout		 => $secs,]
	[Connection_timeout	 => $secs,]
	[Errmode		 => $errmode,]
	[Return_result		 => $flag,]
	[Return_reference	 => $flag,]
	[Prompt			 => $prompt,]
	[Username_prompt	 => $usernamePrompt,]
	[Password_prompt	 => $passwordPrompt,]
	[More_prompt		 => $string,]
	[More_paging		 => $numberOfPages,]
	[Cmd_confirm_prompt	 => $string,]
	[Cmd_initiated_prompt	 => $string,]
	[Cmd_feed_timeout	 => $value,]
	[Input_log		 => $fhOrFilename,]
	[Output_log		 => $fhOrFilename,]
	[Dump_log		 => $fhOrFilename,]
	[Blocking		 => $flag,]
	[Prompt_credentials	 => $flag,]
	[Read_attempts		 => $numberOfReadAttemps,]
	[Read_block_size	 => $bytes,]
	[Wake_console		 => $string,]
	[Output_record_separator => $ors,]
	[Debug			 => $debugFlag,]
	[Debug_file		 => $debugFilename,]
);

This is the constructor for Control::CLI::AvayaData objects. A new object is returned on success. On failure the error mode action defined by "errmode" argument is performed. If the "errmode" argument is not specified the default is to croak. See errmode() for a description of valid settings. The first parameter, or "use" argument, is required and should take value either "TELNET" or "SSH" (case insensitive) or the name of the Serial port such as "COM1" or "/dev/ttyS0". The other arguments are optional and are just shortcuts to methods of the same name.

OBJECT METHODS

Methods which can be run on a previously created Control::CLI::AvayaData instance

Main I/O Object Methods

connect() - connect to host

$ok = $obj->connect($host [$port]);

($ok, $output || $outputRef) = $obj->connect($host [$port]);

$ok = $obj->connect(
	[Host			=> $host,]
	[Port			=> $port,]
	[Username		=> $username,]
	[Password		=> $password,]
	[PublicKey		=> $publicKey,]
	[PrivateKey		=> $privateKey,]
	[Passphrase		=> $passphrase,]
	[Prompt_credentials	=> $flag,]
	[BaudRate		=> $baudRate,]
	[Parity			=> $parity,]
	[DataBits		=> $dataBits,]
	[StopBits		=> $stopBits,]
	[Handshake		=> $handshake,]
	[Timeout		=> $secs,]
	[Connection_timeout	=> $secs,]
	[Read_attempts		=> $numberOfLoginReadAttemps,]
	[Wake_console		=> $string,]
	[Errmode		=> $errmode,]
);

($ok, $output || $outputRef) = $obj->connect(
	[Host			=> $host,]
	[Port			=> $port,]
	[Username		=> $username,]
	[Password		=> $password,]
	[PublicKey		=> $publicKey,]
	[PrivateKey		=> $privateKey,]
	[Passphrase		=> $passphrase,]
	[Prompt_credentials	=> $flag,]
	[BaudRate		=> $baudRate,]
	[Parity			=> $parity,]
	[DataBits		=> $dataBits,]
	[StopBits		=> $stopBits,]
	[Handshake		=> $handshake,]
	[Timeout		=> $secs,]
	[Connection_timeout	=> $secs,]
	[Return_reference	=> $flag,]
	[Read_attempts		=> $numberOfLoginReadAttemps,]
	[Wake_console		=> $string,]
	[Errmode		=> $errmode,]
);

This method connects to the host device. The connection will use either Telnet, SSH or Serial port, depending on how the object was created with the new() constructor. On success a true (1) value is returned. On time-out or other connection failures the error mode action is performed. See errmode(). In the first & third forms only a success/failure value is returned in scalar context, while in the second & fourth forms, in list context, both the success/failure value is returned as well as any output received from the host device during the connect/login sequence; the latter is either the output itself or a reference to that output, depending on the object setting of return_reference or the argument override provided in this method. The read_attempts argument is simply fed to the login method. See login().

The optional "errmode" argument is provided to override the global setting of the object error mode action. The optional "connection_timeout" argument can be used to set a connection timeout for Telnet and SSH TCP connections.

This method overrides Control::CLI::connect() and calls both the Control::CLI::connect() method as well as the login() method from this class. This allows the connect() method to seamlessly handle connection and login for both SSH (which normally handles authentication as part of the connection process) and Telnet and Serial port access (for which authentication needs to be dealt with after connection). Which arguments are used depends on the whether the object was created for Telnet, SSH or Serial port. The "host" argument is required by both Telnet and SSH. The other arguments are optional. If username/password or SSH Passphrase are not provided but are required and prompt_credentials is true, the method will automatically prompt the user for them; otherwise the error mode action is performed. See errmode(). The optional "prompt_credentials" argument is provided to override the global setting of the parameter by the same name which is by default false. See prompt_credentials().

For Telnet, these arguments are used:
```
$ok = $obj->connect($host [$port]);

$ok = $obj->connect(
	Host			=> $host,
	[Port			=> $port,]
	[Username		=> $username,]
	[Password		=> $password,]
	[Prompt_credentials	=> $flag,]
	[Timeout		=> $secs,]
	[Connection_timeout	=> $secs,]
	[Read_attempts		=> $numberOfLoginReadAttemps,]
	[Wake_console		=> $string,]
	[Errmode		=> $errmode,]
);
```
If not specified, the default port number for Telnet is 23. The wake_console argument is only relevant when connecting to a Telnet port other than 23 (i.e. to a Terminal Server device) in which case, the login() method, which is called by connect(), will automatically send the wake_console string sequence to the attached device to alert it of the connection. The default sequence will work across all Avaya Networking products but can be overridden by using the wake_console argument.
For SSH, these arguments are used:
```
$ok = $obj->connect($host [$port]);

$ok = $obj->connect(
	Host			=> $host,
	[Port			=> $port,]
	[Username		=> $username,]
	[Password		=> $password,]
	[PublicKey		=> $publicKey,]
	[PrivateKey		=> $privateKey,]
	[Passphrase		=> $passphrase,]
	[Prompt_credentials	=> $flag,]
	[Timeout		=> $secs,]
	[Connection_timeout	=> $secs,]
	[Read_attempts		=> $numberOfLoginReadAttemps,]
	[Errmode		=> $errmode,]
);
```
If not specified, the default port number for SSH is 22. A username must always be provided for all SSH connections. If not provided and prompt_credentials is true then this method will prompt for it. Once the SSH conection is established, this method will attempt one of two possible authentication types, based on the accepted authentications of the remote host:
- Publickey authentication : If the remote host accepts it and the method was supplied with public/private keys. The public/private keys need to be in OpenSSH format. If the private key is protected by a passphrase then this must also be provided or, if prompt_credentials is true, this method will prompt for the passphrase. If publickey authentication fails for any reason and password authentication is possible, then password authentication is attempted next; otherwise the error mode action is performed. See errmode().
- Password authentication : If the remote host accepts it. A password must be provided or, if prompt_credentials is true, this method will prompt for the password. If password authentication fails for any reason the error mode action is performed. See errmode().
For Serial port, these arguments are used:
```
$ok = $obj->connect(
	[BaudRate		=> $baudRate,]
	[Parity			=> $parity,]
	[DataBits		=> $dataBits,]
	[StopBits		=> $stopBits,]
	[Handshake		=> $handshake,]
	[Username		=> $username,]
	[Password		=> $password,]
	[Prompt_credentials	=> $flag,]
	[Timeout		=> $secs,]
	[Read_attempts		=> $numberOfLoginReadAttemps,]
	[Wake_console		=> $string,]
	[Errmode		=> $errmode,]
);
```
If arguments "baudrate", "parity", "databits", "stopbits" and "handshake" are not specified, the defaults are: Baud Rate = 9600, Data Bits = 8, Parity = none, Stop Bits = 1, Handshake = none. These default values will work on all Avaya Networking products with default settings. Allowed values for these arguments are the same allowed by Control::CLI::connect().

For a serial connection, this method - or to be precise the login() method which is called by connect() - will automatically send the wake_console string sequence to the attached device to alert it of the connection. The default sequence will work across all Avaya Networking products but can be overridden by using the wake_console argument.

login() - handle login for Telnet / Serial port; also set the host CLI prompt

$ok = $obj->login(
	[Username		=> $username,]
	[Password		=> $password,]
	[Prompt_credentials	=> $flag,]
	[Timeout		=> $secs,]
	[Read_attempts		=> $numberOfLoginReadAttemps,]
	[Wake_console		=> $string,]
	[Errmode		=> $errmode,]
);

($ok, $output || $outputRef) = $obj->login(
	[Username		=> $username,]
	[Password		=> $password,]
	[Prompt_credentials	=> $flag,]
	[Timeout		=> $secs,]
	[Return_reference	=> $flag,]
	[Read_attempts		=> $numberOfLoginReadAttemps,]
	[Wake_console		=> $string,]
	[Errmode		=> $errmode,]
);

This method handles login authentication for Telnet and Serial port access (also for SSH access in the case of the WLAN2300 WSS controllers, since they use no SSH authentication but instead use an interactive login once the SSH connection is established). For all connection types (including SSH) it also performs all the necessary steps to get to a CLI prompt; for instance on the Baystack / Stackable ERS platforms it will skip the Banner and/or Menu interface. Over a serial port connection or a telnet connection over a port other than default 23 (indicating a Terminal Server connection) it will automatically generate a wake_console sequence to wake up the attached device into producing either a login banner or CLI prompt. This sequence can be overridden by using the wake_console argument; setting this argument to the empty string will disable the wake_console sequence.

On success the method returns a true (1) value. On failure the error mode action is performed. See errmode(). In the first form only a success/failure value is returned in scalar context, while in the second form, in list context, both the success/failure value is returned as well as any output received from the host device during the login sequence; the latter is either the output itself or a reference to that output, depending on the object setting of return_reference or the argument override provided in this method. This method internally uses the readwait() method and by default sets the read_attemps for it to 10 (which is a safe value to ensure proper connection to any Avaya Networking device); the read_attempts argument provided by login() can be used to override that value.

Once a valid Avaya Networking CLI prompt is detected (using pre-configured pattern match strings), this method records the actual CLI prompt of the host device for the remainder of the session by automatically invoking the prompt() method with a new pattern match string based on the actual device CLI prompt. This ensures a more robust behaviour where the chances of triggering on a fake prompt embedded in the device output data is greatly reduced. At the same time this method will also set the --more-- prompt used by the device when paging output as well as a number of attributes depending on what family_type was detected for the host device. See attribute(). Note that this method is automatically invoked by the connect() method and therefore should seldom need to be invoked by itself. A possible reason to invoke this method on its own could be if initially connecting to, say, an ERS8800 device and from there initiating a telnet connection onto a Stackable device (i.e. telnet hopping); since we are connecting to a new device the login() method must be invoked to set the new prompts accordingly as well as re-setting all the device attributes. An example follows:

	# Initial connection could use Telnet or SSH, depending on how object was constructed
	# Connect to 1st device, e.g. via out-of-band mgmt
	$cli->connect(
		Host		=> '<ERS8800 IP address>',
		Username	=> 'rwa',
		Password	=> 'rwa',
	);
	# From there connect to another device, perhaps on inband mgmt
	# NOTE: use print() not cmd() as there is no prompt coming back, but the login screen of the stackable
	$cli->print("telnet <Stackable IP address>");
	# Call login() to authenticate, detect the device, reset appropriate attributes 
	$cli->login(
		Username	=> 'RW',
		Password	=> 'RW',
	);
	# Execute commands on target stackable device
	$output = $cli->cmd("show running-config");
	print $output;
	[...]
	# If you want to return to the first device..
	# NOTE: use print() not cmd() as the next prompt will be from the ERS8800, not the stackable anymore
	$cli->print("logout");
	# Call login() to detect the device and reset appropriate attributes (no authentication needed though)
	$cli->login;
	# Now we are back on the 1st device
	$output = $cli->cmd("show sys info");
	print $output;
	[...]

cmd() - Sends a CLI command to host and returns result or output

$ok || $output || $outputRef = $obj->cmd($cliCommand);

$ok || $output || $outputRef = $obj->cmd(
	[Command		=> $cliCommand,]
	[Prompt			=> $prompt,]
	[Reset_prompt		=> $flag,]
	[More_prompt		=> $morePrompt,]
	[More_pages		=> $numberOfPages,]
	[Cmd_confirm_prompt	=> $ynPrompt,]
	[Timeout		=> $secs,]
	[Return_reference	=> $flag,]
	[Return_result		=> $flag,]
	[Progress_dots		=> $bytesPerDot,]
	[Errmode		=> $errmode,]
);

This method sends a CLI command to the host and returns once a new CLI prompt is received from the host. The output record separator - which is usually a newline "\n"; see output_record_separator() - is automatically appended to the command string. If no command string is provided then this method will simply send the output record separator and expect a new prompt back. Before sending the command to the host, any pending input data from host is read and flushed. The CLI prompt expected by the cmd() method is either the object prompt previously set by any of connect(), login() or prompt(); or it is the override prompt specified by the optional prompt method argument. If the reset_prompt flag is activated then the prompt match pattern is automatically reset using the same initial pattern match used by connect() & login() to match the prompt for the first time; this is useful when executing a CLI command which will cause the CLI prompt to change (such as changing the switch name). If the reset_prompt flag is set any prompt supplied via the argument will be ignored.

When this method is retrieving the output of the command and the output is generated over multiple pages of output, each page paused with a --more-- prompt, the cmd() method will retrieve as many pages as defined globally by more_paging(). If the optional "more_pages" argument is specified then this value will override the global setting of more_paging(). Either way, if a value of 0 is specified, space characters are automatically fed to obtain all output until the next CLI prompt is received. Note that for best script performance it is recommended to disable more paging on the host device using the appropriate CLI command or the device_more_paging() method. The optional 'more_prompt' argument can be used to override the object more_prompt string though this should seldom be necessary as the correct more prompt string is automatically set by connect() & login(). See more_prompt().

If the command produces a Y/N confirmation prompt as certain Avaya Networking device CLI commands do (for example "boot" or "reset") this method will automatically detect the confirmation prompt and feed a 'y' to it as you would expect when scripting the device. If, for some reason, you wanted to feed a 'n' then refer to cmd_prompted() method instead. The optional 'cmd_confirm_prompt' argument can be used to override the object match string defined for this; see also cmd_confirm_prompt().

This method will either return the result of the command or the output. If return_result is set for the object, or it is set via the override "return_result" argument provided in this method, then only the result of the command is returned. In this case a true (1) value is returned if the command was executed without generating any error messages on the host device. While a false (0) value is returned if the command generated some error messages on the host device. The error message can be obtained via the last_cmd_errmsg() method. See last_cmd_errmsg() and last_cmd_success(). This mode of operation is useful when sending configuration commands to the host device.

If instead return_result is not set then this method will return either a hard reference to the output generated by the CLI command or the output itself. This will depend on the setting of return_reference; see return_reference(); the global setting of return_reference can also be overridden using the method argument by the same name. Passing a refence to the output makes for much faster/efficient code, particularly if the output generated is large (for instance output of "show running-config"). The echoed command is automatically stripped from the output as well as the terminating CLI prompt (the last prompt received from the host device can be obtained with the last_prompt() method). This mode of operation is useful when sending show commands which retrieve information from the host device. Note that in this mode (return_result not set), sending a config command will result in either a null string or a reference pointing to a null string being returned, unless that command generated some error message on the host device. In this case the return_result mode should be used instead.

The progress_dots argument is provided as an override of the object method of the same name for the duration of this method; see progress_dots().

On I/O failure to the host device, the error mode action is performed. See errmode(). If, after expiry of the configured timeout - see timeout() -, output is no longer received from host and no valid CLI prompt has been seen, the method will send an additional carriage return character and automatically fall back on the initial generic prompt for a further 10% of the configured timeout. If even that prompt is not seen after this further timeout then the error mode action is performed. See errmode(). So even if the CLI prompt is changed by the issued command (e.g. changing the system-name or quitting the debug shell) this method should be able to recover since it will automatically revert to the initial generic prompt, but this will happen after expiry of the configured timeout. In this case, to avoid waiting expiry of timeout, set the reset_prompt argument. Here is an example showing how to revert to the normal CLI prompt when quitting the shell:

$obj->cmd('priv');
# Before entering the shell we need to set the prompt to match the shell prompt
$obj->prompt('-> $');
# Now enter the shell
$obj->cmd('shell');
$obj->cmd('spyReport');
[...other shell cmds issued here...]
# When done, logout from shell, and revert to standard CLI prompt
$obj->cmd(Command => 'logout', Reset_prompt => 1);

Alternatively, since accessing the shell now requires a priv & shell password, if you only need to execute a few shell commands you can assume that the shell prompt is a prompt belonging to the shell command and use cmd_prompted() instead; the following example does the same thing as the previous example but does not need to change the prompt:

# Enter the shell and execute shell commands all in one go
$obj->cmd_prompted(
		Command			=> 'priv',
		Feed			=> $privPassword,
);
$obj->cmd_prompted(
		Command			=> 'shell',
		Cmd_confirm_prompt	=> '(:|->) $',
		Feed			=> $shellPassword,
		Feed			=> 'spyReport',
		Feed			=> 'logout',
);

If the issued command returns no prompt (e.g. logout), consider using print() instead of cmd() or, if logging out, simply use the disconnect() method.

If the issued command produces a Y/N confirmation prompt but does not return a regular prompt (e.g. reset, boot) there are two possible approaches. On some Avaya Networking devices (e.g. PassportERS family_type) you can append '-y' to the command being sent to suppress the Y/N confirmation prompt, in which case you can simply do:

$cli->print('reset -y');
$cli->disconnect;

However, other Avaya Networking devices do not accept a '-y' appended to the reset/boot commands (e.g. BaystackERS family_type); on these devices use this sequence:

$cli->print('reset');
$cli->waitfor($cli->cmd_confirm_prompt);
$cli->print('y');
$cli->disconnect;

cmd_prompted() - Sends a CLI command to host, feeds additional requested data and returns result or output

$ok || $output || $outputRef = $obj->cmd_prompted($cliCommand, @feedData);

$ok || $output || $outputRef = $obj->cmd_prompted(
	[Command		=> $cliCommand,]
	[Feed			=> $feedData1,
	[Feed			=> $feedData2,
	[Feed			=> $feedData3, ... ]]]
	[Prompt			=> $prompt,]
	[Reset_prompt		=> $flag,]
	[More_prompt		=> $morePrompt,]
	[More_pages		=> $numberOfPages,]
	[Cmd_initiated_prompt	=> $cmdPrompt,]
	[Timeout		=> $secs,]
	[Return_reference	=> $flag,]
	[Return_result		=> $flag,]
	[Progress_dots		=> $bytesPerDot,]
	[Errmode		=> $errmode,]
);

This method is identical to cmd() except that it will not automaticaly feed a 'y' to Y/N confirmation prompts but in a more general manner will detect any prompts generated by the issued CLI command (whether these are Y/N confirmation prompts or simply prompts for additional information the CLI command requires) and will feed whatever data has been provided to the method. In the first form, this data can be provided as an array while in the second form any number of "feed" arguments can be provided. Note that if you want to use the second form, then the "command" argument must be the first argument supplied, otherwise the first form is expected. The prompt used to detect CLI command prompts can be set via the cmd_initiated_prompt() or via the override method argument by te same name.

attribute() - Return device attribute value

$value = $obj->attribute($attribute);

$value = $obj->attribute(
	Attribute		=> $attribute,
	[Reload			=> $flag,]
);

When connecting to an Avaya Networking device a certain number of attributes are automatically recorded if the information is readily available and does not require additional CLI commands. The attribute() method allows to retrieve the value of such attributes. If the attribute is already set, then the method simply returns its value. If on the other hand the requested attribute is not yet set, then in this case the method will issue the necessary CLI command to find the relevant information to set the attribute (or multiple attributes since in some cases a CLI command yields information for multiple attributes) and will then return its value. Any subsequent lookup for the same attribute name will no longer need to issue CLI commands. In the second form, if the "reload" flag is true, then even if the attribute was already set the method will verify the setting on the connected device by re-issuing the necessary commands. In case of any IO failures while issuing CLI commands the error mode action is performed.

Once a connection is established (including login) the family_type attribute is always set. As long as it is set to a valid Avaya Networking product type, then all other global attributes are available as well as all the relevant attributes for the family type specified (a full list of available attributes is returned by specifying attribute all). Attributes for other product families different from the current value of family_type will be undefined. If the family_type attribute is not yet set or is set to generic then all other attributes, including the other Global ones, will be undefined.

Valid attributes and their possible values follow.

Global attributes which apply to any product family type:

family_type:
- BaystackERS : Any of Baystack, BPS, ES, Stackable ERS (ERS-2500, ERS-3500, ERS-4x00, ERS-5x00), Stackable VSP (VSP-7000), WLAN8100
- PassportERS : Any of Passport/ERS-1600, Passport/ERS-8x00, VSP-9000, VSP-8000, VSP-4000
- SecureRouter : Any of the Secure Router 2330 & 4134 series
- WLAN2300 : WLAN WSS2300 Controllers
- Accelar : Any of the old Accelar 1000, 1100, 1200
- generic : Not an Avaya Networking product; equivalent functionality to Control::CLI
model: Device model e.g. ERS-8610, ERS-4526-GTX-PWR; The model naming will usually be in the format <VSP|ERS|ES|WC>-<number>-<type>-<subtype>. This attribute will remain undefined if connected to the Standby CPU of a PassportERS device.
sysname: System name of the device. This attribute will remain undefined if connected to the Standby CPU of a PassportERS device.
base_mac: Base MAC address of the device in string format xx-xx-xx-xx-xx-xx. This is the base MAC address from which all other device MACs (VLAN, Port, etc) are derived. This attribute is useful for maintaining a unique reference for the device. This attribute will remain undefined if connected to the Standby CPU of a PassportERS device.
is_acli: Flag; true(1) for Cisco like acli mode which has PrivExec & Config modes; false(0) otherwise. So for family types BaystackERS, SecureRouter, WLAN2300 and PassportERS (the latter in acli mode) this flag is true. Whereas for family types Accelar, generic and PassportERS (the latter in cli mode) this flag is false.
is_nncli: Flag; alias for above is_acli attribute as nncli is historically how this CLI mode was called in Nortel days
sw_version: Run time software version
fw_version: Boot / Boot Monitor / Firmware verson, if applicable, undef otherwise
slots: Returns a list (array reference) of all valid slot numbers (or unit numbers in a stack); returns an empty list if the device ports have no slot number associated (e.g. a BaystackERS switch in standalone mode) and undefined if no slot/port information could be retrieved from the device, e.g. if connected to the Standby CPU of a PassportERS device
ports: If the slots attribute is defined, this attribute returns an array reference where the index is the slot number (valid slot numbers are provided by the slots attribute) and the array elements are a list (array references again) of valid ports for that particular slot. If the slots attribute is defined but empty (i.e. there is no slot number associated to available ports), this attribute returns a list (array reference) of valid port numbers for the device.

Attributes which only apply to PassportERS family type:

is_master_cpu: Flag; true(1) if connected to a Master CPU; false(0) otherwise
is_dual_cpu: Flag; true(1) if 2 CPUs are present in the chassis; false(0) otherwise
cpu_slot: Slot number of the CPU we are connected to
is_ha: Flag; true(1) if HA-mode is enabled; false(0) otherwise; undef if not applicable
stp_mode: Spanning tree operational mode; possible values: stpg, mstp, rstp

Attributes which only apply to BaystackERS family type:

unit_number: Unit number we are connected to (Generaly the base unit, except when connecting via Serial) if a stack; undef otherwise
base_unit: Base unit number, if a stack; undef otherwise
switch_mode:
- Switch : Standalone switch
- Stack : Stack of switches
stp_mode: Spanning tree operational mode; possible values: stpg, mstp, rstp

All available attributes on a given connection

all: Retuns a list (array reference) of all valid attributes for the current connection; this will include all Global attributes as well as all attributes corresponding to the family type specified by family_type. This is useful for iterating through all available attributes in a foreach loop.

change_baudrate() - Change baud rate on current serial connection

$baudrate = $obj->change_baudrate($baudrate);

$baudrate = $obj->change_baudrate(
	BaudRate		=> $baudrate,
	[Timeout		=> $secs,]
	[Local_side_only	=> $flag,]
	[Errmode		=> $errmode,]
);

This method is only applicable to an already established Serial port connection and will return an error if the connection type is Telnet or SSH or if the object type is for Serial but no connection is yet established.

If the 'local_side_only' argument is set this method will simply call the Control::CLI method by the same name which will simply change the baudrate of the current serial connection without trying to also change the baudrate on the device we are connected to.

Without the 'local_side_only' argument set, this method combines the knowledge of the Avaya device type we are connected to by automatically changing the baudrate configuration on the attached device before actually changing the baudrate of the connection. The ability to change the baudrate configuration on the attached device is only available when the attribute family_type is either BaystackERS or PassportERS. If the family_type is 'generic' then this method becomes again identical to Control::CLI::change_baudrate() and will simply change the baudrate of the local connection. For other valid AvayaData values of family_type (SecureRouter & WLAN2300) this method will simply return an undefined value since there is no way to change the baudrate configuration on these devices to a value other than 9600 baud.

When changing the baudrate of the local connection this method calls Control::CLI::change_baudrate() which will restart the object serial connection with the new baudrate (in the background, the serial connection is actually disconnected and then re-connected) without losing the current CLI session. If there is a problem restarting the serial port connection at the new baudrate then the error mode action is performed - see errmode(). If the baudrate was successfully changed the value of the new baudrate (a true value) is returned. The advantage of using this method to increase the baudrate to a higher value than 9600 is that when retrieving commands which generate a large amount of output, this can be read in a lot faster if the baudrate is increased.

Remember to restore the baudrate configuration of the attached device to default 9600 when done or anyone connecting to its serial port thereafter will have to guess the baudrate! To minimize the chance of this happening the disconnect & destroy methods for this class will automatically try to restore whatever baudrate was used when initially connecting to the device.

Supported baudrates for this method are:

BaystackERS: 9600, 19200, 38400 or 'max' (where 'max' = 38400)
PassportERS: 9600, 19200, 38400, 57600, 115200 or 'max' (where 'max' = 115200)

Follows an example:

use Control::CLI;
# Create the object instance for Serial port
$cli = new Control::CLI('COM1');
# Connect to switch
$cli->connect(
		Baudrate 	=> 9600,
		Username	=> $username,
		Password	=> $password,
	);
# Get the config
$output = $cli->cmd(
		Command		=> "show running-config",
		Progress_dots	=> 100,
	);
# Increase the baudrate
$maxBaudrate = $cli->change_baudrate('max');
print "Baudrate increased to $maxBaudrate" if $maxBaudrate;
# Get the config a 2nd time (4 times faster on BaystackERS; 12 times faster PassportERS)
$output = $cli->cmd(
		Command		=> "show running-config",
		Progress_dots	=> 100,
	);
# Restore the baudrate
$cli->change_baudrate(9600);
# Disconnect
$cli->disconnect;

enable() - Enter PrivExec mode

$ok = $obj->enable($enablePassword);

$ok = $obj->enable(
	[Password		=> $enablePassword,]
	[Prompt_credentials	=> $flag,]
	[Timeout		=> $secs,]
	[Errmode		=> $errmode,]
);

This method checks whether the 'is_acli' attribute is set and, if so, whether the last prompt ends with '>'; if both conditions are true, it will flush any unread pending input from the device and will just send an 'enable' command to enter Priviledge Executive mode. If either of the above conditions are not met then this method will simply return a true (1) value. The method can take a password argument which only applies to the WLAN2300 series and in some older software versions of the ERS-8300 in NNCLI mode. If a password is required, but not supplied, this method will try supplying first a blank password, then the same password which was used to connect/login into the WLAN2300 and finally, if prompt_credentials is true for the object, prompt for it. On I/O failure, the error mode action is performed. See errmode(). The optional "prompt_credentials" argument is provided to override the global setting of the parameter by the same name which is by default false. See prompt_credentials().

device_more_paging() - Enable/Disable more paging on host device

$ok = $obj->device_more_paging($flag);

$ok = $obj->device_more_paging(
	Enable			=> $flag,
	[Timeout		=> $secs,]
	[Errmode		=> $errmode,]
);

This method issues the necessary CLI commands to turn on/off --more-- paging on the connected device. It relies on the setting of family_type attribute - see attribute() - to send the appropriate commands. If an error occurs while sending the necessary CLI commands, then the error mode action is performed. See errmode(). Returns a true value (1) on success.

device_peer_cpu() - Connect to peer CPU on ERS8x00 / VSP9000

$ok = $obj->device_peer_cpu(
	[Username		=> $username,]
	[Password		=> $password,]
	[Prompt_credentials	=> $flag,]
	[Timeout		=> $secs,]
	[Errmode		=> $errmode,]
);

This method, only applicable on ERS8x00 and VSP9000, will try to connect to the peer CPU. On success a true (1) value is returned otherwise the error mode action is performed. See errmode(). It should not normally be necessary to provide username/password since the credentials used to connect to the current CPU will automatically be used. If not so, or to override the cached ones, optional "username" & "password" arguments can be provided. Attributes 'cpu_slot' and 'is_master_cpu' are automatically updated once the connection to the peer CPU succeeds. See attribute().

Methods to set/read Object variables

flush_credentials - flush the stored username, password, passphrase and enable password credentials

$obj->flush_credentials;

The connect(), login() and enable() methods, if successful in authenticating, will automatically store the username/password/enable-password or SSH passphrase supplied to them. These can be retrieved via the username, password, passphrase and enable_password methods. If you do not want these to persist in memory once the authentication has completed, use this method to flush them. This method always returns 1.

prompt() - set the CLI prompt match pattern for this object

$string = $obj->prompt;

$prev = $obj->prompt($string);

This method sets the CLI prompt match patterns for this object. In the first form the current pattern match string is returned. In the second form a new pattern match string is set and the previous setting returned. If no prompt has yet been set (connection not yet established) undef is returned. The object CLI prompt pattern is automatically set by the connect(), login() and cmd(reset_prompt => 1) methods and normally does not need to be set manually unless the CLI prompt is expected to change. Once set, the object CLI prompt match pattern is only used by the cmd() and cmd_prompted() methods.

more_prompt() - set the CLI --More-- prompt match pattern for this object

$string = $obj->more_prompt;

$prev = $obj->more_prompt($string);

This method sets the CLI --More-- prompt match patterns for this object. In the first form the current pattern match string is returned. In the second form a new pattern match string is set and the previous setting returned. If no prompt has yet been set (connection not yet established) undef is returned. The object CLI --More-- prompt pattern is automatically set by the connect() and login() methods based upon the device type detected during login. Normally this should not need not be changed manually. Once set, the object CLI --More-- prompt match patterns is only used by the cmd() and cmd_prompted() methods.

more_paging() - sets the number of pages to read when device output is paged by --more-- prompts

$numberOfPages = $obj->more_paging;

$prev = $obj->more_paging($numberOfPages);

When issuing CLI commands, using cmd() or cmd_prompted(), which generate large amount of output, the host device will automatically page the output with --more-- prompts where the user can either view the next page, by sending a Space character, or terminate the CLI command, by sending a q character. This method sets the number of pages of output that both cmd() and cmd_prompted() will retrieve before sending a q character and thus terminating the CLI command. Hence if more_paging is set to 1, only one page of output will be collected and a q character will be sent to the first --more-- prompt received. if more_paging is set to 2, two pages of output will be collected and a q character will be sent to the second --more-- prompt received. By default more_paging is set to 0, which means that the entire output of any issued command will be retrieved, by always feeding Space characters to every --more-- prompt encountered. Note however that for best performance, if the entire output of a command is required, it is best to disable --more-- paging direcly on the host device rather than letting cmd() or cmd_prompted() feed a Space to every --more-- prompt encountered; see device_more_paging(). This setting can also be overridden directly in cmd() or cmd_prompted() using the 'more_pages' argument. In the first form the current setting of more_paging is returned; in the second form a more_paging setting is configured and the previous setting returned.

progress_dots() - configure activity dots for cmd() and cmd_prompted() methods

$prevBytesPerDot = $obj->progress_dots($bytesPerDot);

With this method it is possible to enable cmd() - and cmd_prompted() - to print activity dots (....) as input data is read from the host device. This is useful if the command sent to the host device returns large amount of data (e.g. "show tech") and/or it takes a long time for the host device to complete the command and return a CLI prompt. To enable the functionality set $bytesPerDot to a non zero value; this value will represent every how many bytes of input data read an activity dot will be printed. For example set a value of 1000. To disable the functionality simply configure it with a zero value. By default this functionality is disabled.

return_result() - set whether cmd methods should return output or the success/failure of the command

$flag = $obj->return_result;

$prev = $obj->return_result($flag);

This method gets or sets the setting for return_result for the object. This applies to the cmd() and cmd_prompted() methods and determines whether these methods should return the success or failure of the issued command (i.e. a true/false value) or instead the output generated by the command. By default return_result is false (0) and the output of the command is returned.

last_cmd_success() - Returns the result of the last command sent via a cmd method

$result = $obj->last_cmd_success;

$prev = $obj->last_cmd_success($result);

This method returns the outcome (true or false) of the last command sent to the host via any of the cmd() or cmd_prompted() methods. If the command generated no error messages on the host, then the command was successful and the result is true (1). If instead an error message was generated by the host, then the command is deemed unsuccesful and the result is false (0). The second form allows the outcome to be manually set. Note that the same information can be directly obtained from the above mentioned cmd methods by simply enabling the 'return_result' object parameter, or method modifier. Note also that this functionality is only available if the host is detected as an Avaya Networking product, i.e. the family_type attribute is set to a value other than generic - see attribute(). If the family_type attribute is set to generic then this method will always return undef.

last_cmd_errmsg() - returns the last command error message received from connected host

$msg = $obj->last_cmd_errmsg;

$prev = $obj->last_cmd_errmsg($msg);

The first calling sequence returns the cmd error message associated with the object. Undef is returned if no error has been encountered yet. The second calling sequence sets the cmd error message for the object. If the attached device is detected as an Avaya Networking product, i.e. the family_type attribute is set to a value other than generic, and a command is issued to the host via cmd() or cmd_prompted(), and this command generates an error on the host, then the last_cmd_success will be set to false and the actual error message will be available via this method. The string returned will include the device prompt + command echoed back by the device (on the first line) and the error message and pointer on subsequent lines. The error message will be held until a new command generates a new error message. In general, only call this method after checking that the last_cmd_success() method returns a false value.

cmd_confirm_prompt() - set the Y/N confirm prompt expected from certain device CLI commands

$string = $obj->cmd_confirm_prompt;

$prev = $obj->cmd_confirm_prompt($string);

This method sets the Y/N confirm prompt used by the object instance to match confirmation prompts that Avaya Networking devices will generate on certain CLI commands. The cmd() method will use this patterm match to detect these Y/N confirmation prompts and automatically feed a 'Y' to them so that the command is executed as you would expect when scripting the device - see cmd(). In the event you want to feed a 'N' instead, refer to cmd_prompted(). The default prompt match pattern used is:

'[\(\[] *(?:[yY] *[\\\/] *[nN]|[nN] *[\\\/] *[yY]) *[\)\]] *[?:] *$'

The first form of this method allows reading the current setting; the latter will set the new Y/N prompt and return the previous setting.

cmd_initiated_prompt() - Set the prompt that certain device CLI commands will generate to request additional info

$string = $obj->cmd_initiated_prompt;

$prev = $obj->cmd_initiated_prompt($string);

This method sets the prompt used by the object instance to match the prompt that certain Avaya Networking device CLI commands will generate to request additional info. This is used exclusively by the cmd_prompted() method which is capable to detect these prompts and feed the required information to them. See cmd_prompted(). The default prompt match pattern used is:

'[?:=][ \t]*$'

This method can also be used if you wish to feed a 'N' to Y/N prompts, unlike what is automaticaly done by the cmd() method. The first form of this method allows reading the current setting; the latter will set the new prompt and return the previous setting.

cmd_feed_timeout() - Set the number of times we skip command prompts before giving up

$value = $obj->cmd_feed_timeout;

$prev = $obj->cmd_feed_timeout($value);

If a CLI command is found to generate a prompt for additional data - i.e. a match was found for string defined by cmd_initiated_prompt() - and no data was provided to feed to the command (either because of insufficient feed data in cmp_promted() or if using cmd() which cannot supply any feed data) the cmd methods will automatically feed a carriage return to such prompts in the hope of getting to the next CLI prompt and return. If however these command prompts for additional data were indefinite, the cmd methods would never return. This method sets a limit to the number of times that an empty carriage return is fed to these prompts for more data for which we have no data to feed. When that happens the cmd method will timeout and the error mode action is performed. The same value will also set an upper limit to how many times a 'y' is fed to Y/N confirm prompts for the same command in the cmd() method. The default value is set to 10.

wake_console() - Set the character sequence to send to wake up device when connecting to console port

$string = $obj->wake_console;

$prev = $obj->wake_console($string);

When connecting to the serial console port of a device it is necessary to send some characters to trigger the device at the other end to respond. These characters can be defined using this method. By default the wake string is "\n" which attempts to ensure that we can recover a CLI prompt or login prompt from the device regardless of whether it was left at the login banner, or in the Menu based CLI, or in the midst of a --more-- prompt paging previous output. The wake string is sent when connecting via Serial port as well as when connecting via Telnet but with a TCP port other than 23 (i.e. via a Terminal Server device). Setting the wake sequence to the empty string, will disable it.

debug() - set debugging

$debugLevel = $obj->debug;

$prev = $obj->debug($debugLevel);

Enables debugging for the object methods and on underlying modules. In the first form the current debug level is returned; in the second form a debug level is configured and the previous setting returned. By default debugging is disabled. To disable debugging set the debug level to 0. The following debug levels are defined:

0 : No debugging
1 : Basic debugging
2 : Extended debugging of login() and cmd() methods
3 : Turn on debug level 1 on parent Control::CLI
4 : Turn on debug level 2 on parent Control::CLI

debug_file() - set debug output file

$fileName = $obj->debug_file;

$prev = $obj->debug_file($fileName);

Opens a file to print debug messages to. An empty string will close the file.

Methods to access Object read-only variables

config_context - read configuration context of last prompt

$configContext = $obj->config_context;

Returns the configuration context included in the last prompt received from the host device. For example if the last prompt received from the device was 'switch(config-if)#' this method will return 'config-if'. While if the last prompt was in the form 'switch/config/ip#' this method will return '/config/ip'. If the device was not in config mode at the last prompt, this method returns undef.

enable_password - read enable password provided

$enablePassword = $obj->enable_password;

Returns the last enable password which was successfully used in the enable() method, or undef otherwise. Of the supported family types only the WLAN2300 requires a password to access privExec mode.

Methods overridden from Control::CLI

connect() - connect to host
login() - handle login for Telnet / Serial port
cmd() - Sends a CLI command to host and returns output data
change_baudrate() - Change baud rate on current serial connection
prompt() - set the CLI prompt match pattern for this object
disconnect - disconnect from host
debug() - set debugging

Methods inherited from Control::CLI

read() - read block of data from object
readwait() - read in data initially in blocking mode, then perform subsequent non-blocking reads for more
waitfor() - wait for pattern in the input stream
put() - write data to object
print() - write data to object with trailing output_record_separator
printlist() - write multiple lines to object each with trailing output_record_separator
input_log() - log all input sent to host
output_log() - log all output received from host
dump_log() - log hex and ascii for both input and output stream
eof - end-of-file indicator
break - send the break signal
close - disconnect from host

Error Handling Methods inherited from Control::CLI

errmode() - define action to be performed on error/timeout
errmsg() - last generated error message for the object
error() - perform the error mode action

Methods to set/read Object variables inherited from Control::CLI

timeout() - set I/O time-out interval
connection_timeout() - set Telnet and SSH connection time-out interval
read_block_size() - set read_block_size for either SSH or Serial port
blocking() - set blocking mode for read methods
read_attempts() - set number of read attempts used in readwait() method
return_reference() - set whether read methods should return a hard reference or not
output_record_separator() - set the Output Record Separator automatically appended by print & cmd methods
prompt_credentials() - set whether connect() and login() methods should be able to prompt for credentials
username_prompt() - set the login() username prompt match pattern for this object
password_prompt() - set the login() password prompt match pattern for this object

Methods to access Object read-only variables inherited from Control::CLI

parent - return parent object
ssh_channel - return ssh channel object
connection_type - return connection type for object
port - return the TCP port / COM port for the connection
last_prompt - returns the last CLI prompt received from host
username - read username provided
password - read password provided
passphrase - read passphrase provided
handshake - read handshake used by current serial connection
baudrate - read baudrate used by current serial connection
parity - read parity used by current serial connection
databits - read databits used by current serial connection
stopbits - read stopbits used by current serial connection

CLASS METHODS inherited from Control::CLI

Class Methods which are not tied to an object instance. The Control::CLI::AvayaData class expressly imports all of Control::CLI's class methods into itself. However by default Control::CLI::AvayaData class does not import anything when it is use-ed. The following list is a sub-set of those Control::CLI class methods. These should be called using their fully qualified package name or else they can be expressly imported when loading this module:

# Import useTelnet, useSsh, useSerial & useIPv6
use Control::CLI::AvayaData qw(:use);

# Import all of Control::CLI class methods
use Control::CLI::AvayaData qw(:all);

useTelnet - can Telnet be used ?
useSsh - can SSH be used ?
useSerial - can Serial port be used ?
useIPv6 - can IPv6 be used with Telnet or SSH ?
promptClear() - prompt for username in clear text
promptHide() - prompt for password in hidden text
passphraseRequired() - check if private key requires passphrase
parseMethodArgs() - parse arguments passed to a method against list of valid arguments
suppressMethodArgs() - parse arguments passed to a method and suppress selected arguments
parse_errmode() - parse a new value for the error mode and return it if valid or undef otherwise

AUTHOR

Ludovico Stevens <lstevens@cpan.org>

BUGS

Please report any bugs or feature requests to bug-control-cli-avayadata at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Control-CLI-AvayaData. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

DISCLAIMER

Note that this module is in no way supported or endorsed by Avaya Inc.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Control::CLI::AvayaData

You can also look for information at:

RT: CPAN's request tracker

http://rt.cpan.org/NoAuth/Bugs.html?Dist=Control-CLI-AvayaData
AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/Control-CLI-AvayaData
CPAN Ratings

http://cpanratings.perl.org/d/Control-CLI-AvayaData
Search CPAN

http://search.cpan.org/dist/Control-CLI-AvayaData/

LICENSE AND COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

To install Control::CLI::AvayaData, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Control::CLI::AvayaData

CPAN shell

perl -MCPAN -e shell
install Control::CLI::AvayaData

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)