5 Cisco Cartridge Configuration Utility

This chapter describes the Oracle Communications IP Service Activator Cisco IOS cartridge configuration utility and explains how to use it.

About the Cisco Cartridge Configuration Utility

The Cisco cartridge configuration utility is a command line tool that is installed with the Cisco IOS cartridge, and provides the ability to automatically generate options and registry files for your Cisco devices.

You can run the Cisco cartridge configuration utility to generate a CSV (comma-separated values) file containing entries for all the Cisco devices and IOS combinations in your IP Service Activator database. You can then run the Cisco cartridge configuration utility again to generate the options files for your devices. The Cisco cartridge configuration utility reads the options from the master options CSV file and matches them to your device and IOS combinations.

The Cisco cartridge configuration utility will create an options xml file for each device and IOS version. The tool can be run with a different parameter to generate a registry file that will use the newly generated options files. The necessary procedures are provided in this section, and cover the tasks listed in the task checklist.

The cartridgeConfigurationTool.sh script is the executable file used to invoke commands in the Cisco cartridge configuration utility.

Task Checklist

The following list displays the suggested order of tasks for using the Cisco cartridge configuration utility:

Retrieving a List of Device Type and IOS Version Combinations
Generating the Registry File
Generating Multiple Options Files and/or Generating a Single Options File
Generating Capabilities Files

Using the Cisco Cartridge Configuration Utility: General Commands

The Cisco cartridge configuration utility is installed with the IP Service Activator Cisco IOS cartridge. Following is the syntax of a list of device type and IOS version combinations:

Navigate to the IP_SERVICE_ACTIVATOR_HOME /bin directory.

For example:

bin/cartridgeConfigurationTool.sh -help

Table 5-1 displays general usage commands for the Cisco cartridge configuration utility.

Table 5-1 Commands for Cisco Cartridge Configuration Utility

Command	Description
-generateCapabilitiesFiles	Generates an initial set of capabilities files.
-generateOptionsInDir	Generates the complete set of options in the output directory.
-generateOptionsZip	Generates the complete set of options.
-generateRegistry	Generates the MIPSA_registry.xml file.
-generateSingleOptionsFile	Generates a single options file.
-help	Displays help text for the Cisco cartridge configuration utility.
-output	Sets the output filename or directory.
-queryActiveDeviceTypesAndIOS	Queries IP Service Activator for active Cisco device and IOS data.

Retrieving a List of Device Type and IOS Version Combinations

Using the cartridgeConfigurationTool.sh executable file in the Cisco cartridge configuration utility, you can retrieve a list of device type and IOS version combinations from the Policy Server database.

To retrieve a list of device type and IOS version combinations:

Navigate to the IP_SERVICE_ACTIVATOR_HOME directory.

Execute one of the following commands:

bin/cartridgeConfigurationTool.sh -queryActiveDeviceTypesAndIOS db [host_name port sid user_name password] [proxyagent] [-output output_filename]
OR
bin/cartridgeConfigurationTool.sh -queryActiveDeviceTypesAndIOS oim [hostname port username password] [proxyname] [-output output_filename]

Table 5-2 Commands to Retrieve Device TypOe and IOS Version Combinations

Where	Is
db	Used to query data directly from the database.
oim	Used to query data via the IP Service Activator Integration Manager.
hostname	The database (db) or IP Service Activator naming service (oim) host name or IP address.
port	The database (db) or IP Service Activator naming service (oim) port number. (Optional).
sid	The database (db) SID.
username	The database (db) or IP Service Activator (oim) username.
password	The database (db) or IP Service Activator (oim) password.
proxyagent	Used to restrict the device query to devices managed by the specified proxy agent (optional).
output_filename	The device IOS data output file (optional) that will be created in IP_SERVICE_ACTIVATOR_HOME directory

For example:

bin/cartridgeConfigurationTool.sh -queryActiveDeviceTypesAndIOS oim localhost 2809 orchestream orchestream -output device_ios.csv

Multi-valued List Options

The cartridge configuration tool can generate options for multivalued lists. An entry in the CSV provided as the base (cisco_options.csv) includes values for the option cartridge.cisco.qos.frameRelay.servicePolicyDirectReference.hardwareList. The multiple values for this option will be separated by "\" (single back slash) so that running the script (cartridgeConfigurationTool.sh on UNIX or Solaris and cartridgeConfigurationTool.bat on Windows) generates options XML with the multiple values provided.

The following is an example of the format of the CSV entry:

cartridge.cisco.qos.frameRelay.servicePolicyDirectReference.hardwareList,Cisco 7600,12.*\(.*\)SXE,12.2(18)SXE,,7600-SIP-200\7600-SIP-400\7600-SIP-600,Cisco service policy direct reference on frame-relay - Hardware list

For this example, the output generated in the generated XML will be as follows:

<cartridge.cisco.qos.frameRelay.servicePolicyDirectReference.hardwareList>

<base:item>7600-SIP-200</base:item>

<base:item>7600-SIP-400</base:item>

<base:item>7600-SIP-600</base:item>

</cartridge.cisco.qos.frameRelay.servicePolicyDirectReference.hardwareList>

Generating the Registry File

Using the cartridgeConfigurationTool.sh executable file in the Cisco cartridge configuration utility, you can generate the MIPSA_registry.xml file with your set of device type and IOS version combinations.

For more information on cartridge capabilities management and the registry, see IP Service Activator System Administrator's Guide.

To generate the registry file:

Navigate to the IP_SERVICE_ACTIVATOR_HOME directory.

Execute the following command:

bin/cartridgeConfigurationTool.sh -generateRegistry device_ios_data package default|series|device|deviceios [-output output_filename]

Table 5-3 Commands to Generate the Registry File

Where	Is
device_ios_data	The csv file of the device type and IOS version pairs that were generated in the procedure. For more information, see "Retrieving a List of Device Type and IOS Version Combinations".
package	The package prefix for the generated options and capabilities files. This translates to an output directory. You can specify a multi-level destination sub-directory hierarchy by providing multiple sub-directory names separated by "." characters. The target directory will be created below the output directory for the registry file.
default	Used to generate all capabilities references to cisco_default.xml.
series	Used to generate capabilities references for each device series - for example: cisco_3600.xml.
device	Used to generate capabilities references for each device type - for example: cisco_3640.xml.
deviceios	Used to generate capabilities references for each device IOS combination - for example: cisco_3640-12.2(13)T.xml.
output_filename	The name of the output registry file.

For example:

bin/cartridgeConfigurationTool.sh -generateRegistry device_ios.csv com.oracle.ipsa series -output MIPSA_registry.xml

The MIPSA_registry.xml file is saved in the IP_SERVICE_ACTIVATOR_HOME directory.

Update the MIPSA registry file to include the new IOS/device combinations. For information on how to include the new IOS/device combinations, see the discussion about creating or editing a cartridge registry file in IP Service Activator System Administrator's Guide.
Copy the generated registry file to the following directory: IP_SERVICE_ACTIVATOR_HOME/Config/networkProcessor

Note:

If you need to re-generate the MIPSA_registry.xml file by running this procedure again at a later time, you must re-start the Network Processor or reload the registry after completion. When you reload the registry, the Network Processor reloads its configuration files. The path for the reload registry script is IP_SERVICE_ACTIVATOR_HOME/bin. To reload the registry, execute the following command:

npAdmin.sh reload_registry

Understanding Registry File Behavior

An entry in the MIPSA_registry.xml file matches a device if all of the following conditions are met:

driverType is equal to the Device Driver value from the Device Type entry on the Topology tab in the IP Service Activator GUI.
deviceType matches the Model, s/w Vn value from the Device Type entry on the Topology tab in the IP Service Activator GUI if useRegex is turned off.
osVersion appears as a substring in the Description field on the Device property page in the IP Service Activator GUI if useRegex is turned off.

If multiple entries in the MIPSA_registry.xml file match a given device, the first entry (the one listed first in the file) is used.

Regular expression matching is not supported for the driverType field. However, it can be enabled for the deviceType and osVersion fields by including the useRegex attribute as follows:

<deviceType useRegex="true" >Cisco 26[0-9][0-9]</deviceType>
<osVersion useRegex="true" >12.2(1[45])T</osVersion>

See the sample MIPSA_registry.xml file below for examples of the values mentioned above.

Sample Registry File Entry

The following is a sample MIPSA registry file entry:

<!-- Cisco 2611 --> 
<cartridgeUnit> 
<name>com.oracle.ipsa.cu1.2611.12.2(15)T16</name> 
<driverType>cisco</driverType> 
<deviceType>Cisco 2611</deviceType> 
<osVersion>12.2(15)T16</osVersion> 
<smToDmQuery>com/metasolv/serviceactivator/cartridges/cisco/units/cu1/sm2dm.xq</smToDmQuery> <dmValidation>com/metasolv/serviceactivator/cartridges/cisco/units/cu1/dmValidation.xq</dmValidation>     <dmMigration>com/metasolv/serviceactivator/cartridges/cisco/xquerylib/dmMigration.xq</dmMigration>     <dmToCliQuery>com/metasolv/serviceactivator/cartridges/cisco/units/cu1/annotatedDm2Cli.xq</
dmToCliQuery> 
<capabilities>com/oracle/ipsa/capabilities/cisco_2600.xml</capabilities> <options>com/oracle/ipsa/options/Cisco_2611-12.2(15)T16.xml</options> <errorMessages>com/metasolv/serviceactivator/cartridges/cisco/messages/errorMessages.xml</
errorMessages>     <warningMessages>com/metasolv/serviceactivator/cartridges/cisco/messages/warningMessages.xml</warningMessages>     <successMessages>com/metasolv/serviceactivator/cartridges/cisco/messages/successMessages.xml</successMessages> 
</cartridgeUnit>

Generating Multiple Options Files

Using the cartridgeConfigurationTool.sh executable file in the Cisco cartridge configuration utility, you can generate a complete set of options configuration files for your Cisco device types and IOS versions.

For more information on cartridge capabilities management and option files, see IP Service Activator System Administrator's Guide.

To generate multiple options files:

Navigate to the IP_SERVICE_ACTIVATOR_HOME/lib/java-lib/cartridges/cisco directory.

Execute the following command:

bin/cartridgeConfigurationTool.sh -generateOptionsZip options_filename device_ios_data package -output output_zipfile

Table 5-4 Commands to Generate Multiple Options Files

Where	Is
options_filename	The path to the master options configuration data (cisco_options.csv).
device_ios_data	The csv file of the device type and IOS version pairs that was generated in the procedure. For more information, see "Retrieving a List of Device Type and IOS Version Combinations".
package	The package prefix for options files. This translates to an output directory. You can specify a multi-level destination sub-directory hierarchy by providing multiple sub-directory names separated by "." characters. The target directory will be created below the output directory for the registry file.
output_zipfile	The file name of the output zip file.

For example:

bin/cartridgeConfigurationTool.sh -generateOptionsZip Config/cisco_options.csv device_ios.csv com.oracle -output cisco_options.zip

The cisco_options.zip file is saved in IP_SERVICE_ACTIVATOR_HOME.

Load the updated options by doing one of the following:
- Extract the cisco_options.zip file to the IP_SERVICE_ACTIVATOR_HOME/Config/networkProcessor directory. The new options will be dynamically picked up from the classpath if you use the reload_registry command.
- Shut down and restart the Network Processor. The updated options will be reloaded from the options.zip file.

Note:

If you need to re-generate options by running this procedure again at a later time, you must re-start the Network Processor after completing this procedure.

Generating a Single Options File

Using the cartridgeConfigurationTool.sh executable file in the Cisco cartridge configuration utility, you can generate a single options file for a specific Cisco device type and IOS version.

For more information on cartridge capabilities management and option files, see IP Service Activator System Administrator's Guide.

To generate a single options files:

Navigate to the IP_SERVICE_ACTIVATOR_HOME directory.

Execute the following command:

bin/cartridgeConfigurationTool.sh -generateSingleOptionsFile options_filename "device_type" "ios_version" [-output "output_filename"]

Table 5-5 Commands to Generate a Single Options File

Where	Is
options_filename	The path to the master options configuration data file (cisco_options.csv).
device_type	The Cisco device type entered between quotation marks.
ios_version	The Cisco IOS version entered between quotation marks.
output_filename	The name of the output XML file entered between quotation marks.

For example:

bin/cartridgeConfigurationTool.sh -generateSingleOptionsFile Config/cisco_options.csv "Cisco 3640" "12.2(13)T4" -output "cisco_options_3640_12.2(13)T4.xml"

The generated file is saved in the IP_SERVICE_ACTIVATOR_HOME directory.

Copy the output xml file to the following directory:

IP_SERVICE_ACTIVATOR_HOME/Config/networkProcessor/com/oracle/ipsa/ options
Note:
If you need to re-generate options by running this procedure again at a later time, you must re-start the Network Processor or reload the registry after completing this procedure. When you reload the registry from IP_SERVICE_ACTIVATOR_HOME/bin, the Network Processor reloads its configuration files. To reload the registry, execute the following command:
```
npAdmin.sh reload_registry
```

Generating Capabilities Files

Using the cartridgeConfigurationTool.sh executable file in the Cisco cartridge configuration utility, you can generate an initial set of capabilities files based on the default cartridge capabilities.

Note that only new (missing) capabilities files are generated - existing files are not modified.

For more information on cartridge capabilities management, see IP Service Activator System Administrator's Guide.

To generate capabilities files:

Navigate to the IP_SERVICE_ACTIVATOR_HOME directory.

Execute the following command:

bin/cartridgeConfigurationTool.sh -generateCapabilitiesFiles device_ios_data package default|series|device|deviceios [-output output_dir]

Table 5-6 Commands to Generate Capabilities Files

Where	Is
device_ios_data	The csv file of the device type and IOS version pairs that was generated in the procedure. For more information, see "Retrieving a List of Device Type and IOS Version Combinations".
package	The package prefix for capabilities files. This translates to an output directory. You can specify a multi-level destination sub-directory hierarchy by providing multiple sub-directory names separated by "." characters. The target directory will be created below the output directory for the registry file.
default	Used to generate the capabilities file cisco_default.xml.
series	Used to generate the capabilities files for each device series - for example: cisco_3600.xml.
device	Used to generate the capabilities files for each device type - for example: cisco_3640.xml.
deviceios	Used to generate the capabilities files for each device IOS combination - for example: cisco_3640-12.2(13)T.xml.
output_directory	The directory where the capabilities package and files are to be created (optional) - if you do not specify a directory, IP Service Activator will use the current directory.

For example:

bin/cartridgeConfigurationTool.sh -generateCapabilitiesFiles device_ios.csv com.oracle series -output ./Config/networkProcessor

The Cisco cartridge configuration utility creates the capabilities file and places it in a package directory structure in the following directory:

IP_SERVICE_ACTIVATOR_HOME/Config/networkProcessor/com/oracle/ipsa/ capabilities

Note:

If you need to re-generate the capabilities files by running this procedure again at a later time, you must re-start the Network Processor or reload the registry after completing this procedure. When you reload the registry from IP_SERVICE_ACTIVATOR_HOME/bin, the Network Processor reloads its configuration files. To reload the registry, execute the following command:

npAdmin.sh reload_registry