2 About the CLI Cartridge

This chapter describes the components of the Oracle Communications Network Integrity Command Line Interface (CLI) cartridge.

The CLI cartridge supports a recording mode for recording CLI data. See "About Record and Playback" for more information.

About Actions and Processors

The CLI cartridge contains the following actions:

Discover Abstract Base CLI
Discover Abstract CLI

The Discover Abstract CLI action extends the Discover Abstract Base CLI action and inherits all its processors to establish and manage the CLI connection.

The Discover Abstract Base CLI action contains the following processors run in the following order:

CLI Property Initializer
CLI Connection Manager

Figure 2-1 illustrates the processor workflow of the Discover Abstract Base CLI action.

Figure 2-1 Discover Abstract Base CLI Action Processor Workflow

The Discover Abstract CLI action adds scan parameter groups to the Discover Abstract Base CLI action and passes the property values to the CLIProperties object.

The Discover Abstract CLI action contains the following processors run in the following order:

CLI Property Initializer (inherited)
CLI Property Customizer
CLI Connection Manager (inherited)

Figure 2-2 illustrates the processor workflow of the Discover Abstract CLI action.

Figure 2-2 Discover Abstract CLI Action Processor Workflow

CLI Property Initializer

This processor is part of the Discover Abstract Base CLI action.

This processor initializes all the properties required for connecting to CLI devices and puts all the properties into a CLIProperties object (a Java class).

Table 2-1 lists the values that are initialized by the CLI Property Initializer processor.

Table 2-1 CLI Properties Initialized by the CLI Property Initializer Processor

Parameter	Description
host	The host name or IP address of the CLI device.
port	The port number of the CLI device.
loginName	The user name for logging in to the CLI device. It may be from 1 to 10 characters in length. Input is case-sensitive and can consist of numbers and upper- and lower-case alphabetic letters.
password	The user password or private identifier. It may be up to 10 characters in length.
prompt	The prompt on the CLI device.
telnetLoginPrompt	The Telnet prompt for the login name on the CLI device.
telentPasswordPrompt	The Telnet prompt for the password on the CLI device.
continueResponsePrompt	The continue response prompt for long responses on the CLI device.
knownHostFileLocation	The location where the public keys of the CLI device are stored if SSH is used. Leave blank to accept all public keys. If a directory is provided, the Network Integrity server must have permission to write to it; otherwise, the CLI cartridge defaults to accepting all public keys.
timeout	The timeout in seconds of the underlying socket connection.
retries	The number of retries that are attempted after a timeout. Obtained from the CLI scan parameter groups.
transportProtocol	The connection protocol to use: Telnet or SSH. The default is SSH.
mode	(Optional) The mode of the Record and Playback feature. Valid values are Normal (no record or playback), Record (recording mode enabled), and Playback (playback mode enabled). Specifying this parameter is optional.
recordFileDir	(Optional) The directory where the cartridge writes and retrieves recorded CLI data files. Specifying this parameter is optional.
deviceType	The type of the device.
softwareVersion	The software version of the device.
service	The type of service to be discovered on the device.

CLI Property Customizer

This processor is part of the Discover Abstract CLI action.

This processor populates the CLIProperties object produced by the CLI Property Initializer processor with the parameter values configured in the Network Integrity UI.

Table 2-1 lists all the parameters that are customizable in the Network Integrity UI. The host property is initialized from the scan address.

CLI Connection Manager

This processor is part of the Discover Abstract Base CLI action.

This processor uses the CLIProperties object produced by the CLI Property Initializer processor or the CLI Property Customizer processor to establish a CLI connection. It provides a CLIConnection object to any extending cartridges and subsequent processors.

To establish a CLI connection, this processor performs the following operations:

Creates a connection to the CLI device using the values in the CLIProperties object.
Logs in to the CLI device using the credentials in the CLIProperties object.
If successful, returns the CLIConnection object.
When the scan ends, logs out and disconnects from the device.

This processor logs any errors and fails the scan if it cannot establish a connection with the CLI device.

About Record and Playback

The CLI cartridge can be configured to record all discovered objects. The Record and Playback feature is not recommended for clustered environments because it relies on files being saved and loaded from the file system.

You enable the Record and Playback feature at run time by setting a managed bean (MBean) configured on a property group on the Discover Abstract CLI action.

When recording mode is enabled, the CLIConnection object writes the response data to a CLI data file in Local_Dir/IP_HostName/Filename.rec, where:

Local_Dir is a local directory that you can configure in the MBean at runtime. If you do not set a value in the MBean, Local_Dir is set to Domain_Home/cliData, where Domain_Home is the Network Integrity domain.
IP_HostName is the value of the host property on the CLIProperties object.
Filename the name of a file that contains either the command code passed to the CLI Connection Manager processor or the full command string.

For example: Local_Dir/10/156/66/191/Filename.rec

When playback mode is enabled, CLIConnection reads the CLI data file (created in Record mode and stored on the local hard drive) and sends the data back to the discovery cartridge without polling any network devices. The resource adapter does not require a connection to the network device.

See "About Using Record and Playback" for more information about enabling or disabling the Record and Playback feature.

SSH Login Behavior

The following sequence describes the SSH login behavior:

If the SSH Known Host File Location parameter is not set, the CLI cartridge accepts all public keys from target devices.
If the SSH Known Host File Location parameter is set:
- And Network Integrity cannot write to the specified directory, the behavior is to accept all public keys from target devices.
- And Network Integrity can write to the specified directory, all public keys are stored in the directory for each connection to a device, and all public keys are verified when the cartridge reconnects with a device to ensure that keys match. If the keys do not match, the public key is replaced.

Using the CLI Cartridge

This section describes how to use the CLI cartridge after it is deployed to the server.

Creating a Discovery Scan Action Type for CLI Devices

You can create a discovery scan to discover CLI device information in one or more network systems.

The CLI cartridge has the following scan parameter groups:

CLI Parameters: A group of the parameters that you must configure to connect to devices and retrieve information using CLI commands over Telnet or Secure Shell (SSH) protocol.
CLI Device Discovery Parameters: A group of parameters that you configure for specific device types, specific operating systems on which the device is running, and the services on the device.

To create a CLI discovery scan, follow the instructions explained in the Network Integrity Help and do the following during the creation process:

On the General tab, from the Scan Action list, select Discover Cisco IOS XR VPLS CLI.

The Scan Type field displays Discovery.
Under the Scan Action Parameters area, do the following:
- From the Select Parameter Group list, select CLI Parameters and enter the required information in the following fields:
  - From the Transport Protocol list, select the protocol used by the CLI device. Available options are: SSH and Telnet.
  - If you selected Telnet from the Transport Protocol list, in the Telnet Login Prompt field, enter the Telnet prompt for the login name on the CLI device.
  - If you selected Telnet from the Transport Protocol list, in the Telnet Password Prompt field, enter the Telnet prompt for the password on the CLI device.
  - In the Prompt field, specify the prompt for the CLI device.
  - In the Continue Response Prompt field, enter the CLI prompt to resume response for long responses on the CLI device.
  - If you selected SSH from the Transport Protocol list, in the SSH Known Host File Dir field, enter the directory location where the public keys of the CLI device are stored. Leave blank to accept all public keys. If a directory location is provided, the Network Integrity server must have permission to write to it; otherwise, the CLI cartridge defaults to accepting all public keys.
  - In the Port field, enter the CLI connection port.
  - In the Login Name field, enter the user name for logging in to the CLI device.
  - In the Password field, enter the user password for logging in to the CLI device.
  - In the Retries field, enter the number of retries that the cartridge attempts after a timeout.
  - In the Timeout (Seconds) field, enter the timeout length (in seconds) of the underlying socket connection.
- From the Select Parameter Group list, select CLI Device Discovery Parameters and enter the required information in the following fields:
  - From the Device Type list, select the type of the device. For example, Cisco.
  - From the Service list, select the type of service to be discovered on the device. For example, Virtual Private LAN Service.
  - From the Software Version list, select the operating system of the device. For example, Cisco IOS XR.
On the Scope tab, do one of the following:
- Enter an IP address.
- Enter a range of IP addresses (for example, 192.0.2.* or 198.51.100.11-23 or 198.51.100.1/24).
- Enter a host name.
The CLI cartridge supports IPv4 and IPv6 IP address formats. You can enter multiple IP addresses.
On the Schedule tab, define a schedule for the scan.

See the Design Studio Modeling Network Integrity Help for more information about defining a scan schedule.
Make any other required configurations.
Click Save and Close.

About Using Record and Playback

The record feature allows you to record CLI responses from devices for auditing, demonstration, or debugging the cartridge. The playback feature allows you to replay recorded files to simulate interaction with the device.

When record mode is enabled, the raw CLI responses are written to a CLI data file stored on the server.

When playback mode is enabled, the CLI connection reads the CLI data file (created in Record mode and stored on the server) and sends the data back to the discovery cartridge. The resource adapter does not require a connection to the network device.

Note:

Record and Playback is not recommended for clustered environments because it relies on files being saved and loaded from the file system.

A property group on the Discover Abstract CLI action controls the Record and Playback feature. MBeans allow you to adjust the record and playback functionality in the runtime system without the need to restart systems or servers.

The Record and Playback feature mode property has these valid values:

Normal: The recording mode and playback mode are disabled.
Record: The recording mode is enabled.
Playback: The playback mode is enabled.

Viewing and Configuring the Current Record and Playback Mode

You use the MBean Browser in Oracle Enterprise Manager is used to view the mode property of the Record and Playback feature. See Network Integrity System Administrator's Guide for more information.

To view the current Record and Playback feature mode:

In the MBean Browser, navigate to the oracle.communications.integrity.ActionProperty.ActionProperties MBean.
Run the listPropertyGroups operation.

This operation lists the configurable property groups. The Returned Value table displays the current mode.

To configure the Record and Playback feature mode:

In the MBean Browser, navigate to the oracle.communications.integrity.ActionProperty.ActionProperties MBean.
Select the Action_Name:CLI Property Initializer:RecordPlayback property group, where Action_Name is the name of the extending action.
Run the listProperties action, using the full property group name in the argument.
Copy the Action_Name:CLI Property Initializer:RecordPlayback:mode string from the Return Value table.
Open the setProperty operation and paste the string into the Property field.
In the Value field, set the value of the Record and Playback feature to either Normal, Record, or Playback.
Click the Invoke button.

To set the location where the recorded data is saved, open the recordFileDir action property and specify the desired directory. The directory must exist on the server and must be accessible by the Oracle WebLogic Server user.

Design Studio Construction

This section provides information about the composition of the CLI cartridge from the Design Studio perspective.

Actions

The following tables outline the Design Studio construction of the CLI cartridge actions and associated components:

Table 2-2, "CLI Cartridge Actions"
Table 2-3, "CLI Cartridge Scan Parameter Group"
Table 2-4, "CLI Cartridge Device Discovery Scan Parameter Group"
Table 2-5, "CLI Cartridge Processors"

Note:

Parameter values are case-sensitive and must be entered in capital letters when commands are run from a command line interface.

Table 2-2 CLI Cartridge Actions

Action Name	Result Category	Address Handler	Scan Parameter Group	Processors
Discover Abstract Base CLI	Device	IPAddressHandler	N/A	CLI Property Initializer CLI Connection Manager
Discover Abstract CLI	Device	IPAddressHandler	CLI Parameters CLI Device Discovery Parameters	CLI Property Initializer CLI Property Customizer CLI Connection Manager

Action Name

Result Category

Address Handler

Scan Parameter Group

Processors

Discover Abstract Base CLI

Device

IPAddressHandler

N/A

CLI Property Initializer
CLI Connection Manager

Discover Abstract CLI

Device

IPAddressHandler

CLI Parameters

CLI Device Discovery Parameters

CLI Property Initializer
CLI Property Customizer
CLI Connection Manager

Table 2-3 CLI Cartridge Scan Parameter Group

Parameter Name	Parameter Type	Description	UI Label
loginName	Text box	The user name for logging in to the CLI device.	Login Name
password	Secret text	The user password or private identifier.	Password
telnetLoginPrompt	Text box	The Telnet prompt for the login name on the CLI device.	Telnet Login Prompt
telnetPasswordPrompt	Text box	The Telnet prompt for the password on the CLI device.	Telnet Password Prompt
prompt	Text box	The prompt on the CLI device.	Prompt
continueResponsePrompt	Text box	The continue response prompt for long responses on the CLI device.	Continue Response Prompt
port	Text box	The port number of the CLI device. The default is 22.	Port
timeout	Text box	The timeout in seconds of the underlying socket connection. The default is 60.	Timeout
retries	Text box	The number of retries that are attempted after a timeout. The default is 2.	Retries
knownHostFileDir	Text box	The location where the public keys of the CLI device are stored if SSH is used.	SSH Known Host File Dir
transportProtocol	Drop Down	The connection protocol to use: Telnet or SSH. The default is SSH.	Transport Protocol

Table 2-4 CLI Cartridge Device Discovery Scan Parameter Group

Parameter Name	Parameter Type	Description	UI Label
deviceType	Drop Down	The device vendor type.	Device Type
softwareVersion	Drop Down	Software version of the device.	Software Version
service	Drop Down	Type of service to be discovered on the device.	Service

Table 2-5 CLI Cartridge Processors

Processor Name	Variable
CLI Property Initializer	Input: N/A Output: cliProperties
CLI Property Customizer	Input: N/A Output: cliProperties
CLI Connection Manager	Input: cliProperties Output: cliConnection

Processor Name

Variable

CLI Property Initializer

Input: N/A

Output: cliProperties

CLI Property Customizer

Input: N/A

Output: cliProperties

CLI Connection Manager

Input: cliProperties

Output: cliConnection

Design Studio Extension

This section contains examples and explanations of how to extend certain aspects of the CLI cartridge by using Oracle Communications Design Studio. See Network Integrity Developer's Guide for more information.

Extending the Discover Abstract CLI Action

This example explains how to extend the Discover Abstract CLI action to collect device-specific information using CLI commands and model the collected information into the Oracle Communications Information Model.

Open Design Studio in the Design perspective.
Create a Network Integrity cartridge project; for example, CLIDeviceExtension.
Make the CLIDeviceExtension cartridge project dependent on the CLI cartridge project.
Create a new discovery action; for example, CLI Extension.
Add the Discover Abstract CLI action as a processor in the CLI Extension action.
Add any new scan parameter groups in the CLI Extension action.
Create a new discovery processor; for example, Custom CLI Device Collector, and specify cliConnection and cliProperties as input parameters to this processor.
In the Custom CLI Device Collector processor implementation, add code to run any new CLI commands using the connection object, as shown in the following example:
```
CLIConnection connection = request.getCliConnection();
String resp = connection.runCommand("dir");
```
Create a new discovery processor to model the scan results (for example, Custom CLI Device Modeler) and then do the following:
1. Specify the output from the Custom CLI Device Collector processor as input to the Custom CLI Device Modeler processor.
2. In the Custom CLI Device Modeler processor implementation, add code to model the data into the required scan result entities.
Create a new discovery processor to persist the scan results (for example, Custom CLI Device Persister) and then do the following:
1. Specify the output from the Custom CLI Device Modeler processor as input to the Custom CLI Device Persister processor.
2. In the Custom CLI Device Persister processor implementation, add code to persist the entities into the database.
Build, deploy, and test your cartridge.

The new custom processors are run in the order shown in Figure 2-3.

Figure 2-3 New Custom Processors Workflow