Network Configuration Manager Extension Utility

Contents
casp1030
Contents
The Network Configuration Manager Extension Utility lets you extend the basic functionality of Network Configuration Manager. You can create device families and manage additional devices and vendors by using Perl scripts for the operations that Network Configuration Manager executes on a device. You can customize trap settings and use them to correlate configuration change event information.
The following sections describe how to use the Extension Utility to expand Network Configuration Manager support.
Supported Operations
The Network Configuration Manager Extension Utility lets you use Perl scripts to extend Network Configuration Manager to additional devices and vendors. Network Configuration Manager can be extended by providing Perl scripts for any, or all, of the operations Network Configuration Manager performs on a device. The following list summarizes these operations:
  • Capture Startup Configuration
    Capture device startup configuration.
  • Capture Running Configuration
    Capture device running configuration.
  • Upload Running Configuration
    Upload and merge specified content into the device running configuration.
  • Write Startup Configuration
    Write the device current running configuration to its startup configuration.
  • Reload Device
    Reboot a device.
  • Cancel Reload
    Cancel the scheduled reboot of a device.
  • Load Device Firmware
    Initiate a load of the specified firmware image on the device.
Scripts can be configured for each of these operations within device families that are created on demand. Any operation that lacks a script is handled as an unsupported operation for the given Device Family and all devices contained within it.
The Cisco PIX OS out-of-box device family provides an example of how scripts are used to extend Network Configuration Manager support. (Within these example scripts, the Net::Telnet perl module does
not
support IPv6.)
The utility also lets you use Perl scripts to alter Network Configuration Manager interactions with devices that belong to out-of-the-box device families.
OpenSSH Device Family
Starting from this release Spectrum introduces the OpenSSH Device Family to support the Network Configuration Management functionality, which you can use to capture and upload device configurations. This OpenSSH functionality includes the Perl scripts to support OpenSSH.
Follow these steps to add any OpenSSH supported devices to this device family:
  1. Select the device that you want to add to the OpenSSH Device Family
  2. Right click the device, then select
    Add to
    ,
    Device Family
    .
  3. Select the NCM OpenSSH Device Family.
Create a Custom Device Family
Network Configuration Manager supports Cisco, Enterasys, Enterasys/Riverstone SSR, Extreme, Foundry, Juniper, Lancom, Nortel Baystack, and Nortel Passport device families out-of-box. The Network Configuration Manager Extension Utility lets you create custom device families.
Follow these steps:
  1. Expand Configuration Manager in the Explorer tab of the Navigation panel.
  2. Right-click Device Families, and select Create Device Family.
    The Create Device Family dialog opens as shown in the following image:
    SPEC--createdevicefamily
  3. Enter a unique name in the Name field.
  4. (Optional) Enter a description and security string.
  5. (Optional) Click the Landscapes button to select the Landscapes where you want to place the device family.
  6. Click the Search Options button to search for specific devices.
    The Search Options dialog opens. Like a Global Collection, a device family can have both static members that are manually added to the family, and dynamic members that are automatically added using specified search criteria. For more information, see the section.
    A device can belong to only one device family. If multiple device families contain search criteria that apply to the same device, the first device family to execute the search contains the device.
  7. Click OK when you have finished.
    The device family is created and appears under Device Families in the Explorer tab of the Navigation panel. Static members can now be added.
Place a Device in a Device Family
Network Configuration Manager automatically assigns out-of-the-box supported devices to the family. A device that is currently associated with a device family must be manually moved to a user-created device family. Manually-created device families that contain search criteria to define membership do not pull in devices that already belong to a device family. For the search criteria to pull in a new device, the device must not currently be a member of any device family.
You have several options for placing a device in a device family. You can manually make the association.
Follow these steps:
  1. Locate the device.
  2. Right-click the device and select Add To, Device Family.
    The Select Device Family dialog opens.
  3. Select the device family that you want to associate with the selected device.
    If a suitable device family is not displayed, create a custom device family by clicking Create. See Create a Custom Device Family for more information.
    The device is now associated with the selected device family.
You can force a manually created device family to update using its defined search criteria.
Follow these steps:
  1. Right-click the device family in the Navigation panel.
  2. Select Update Device Family.
    The device family searches for and adds all devices that meet the search criteria if they do not currently belong to a device family.
For more information about device family search criteria, see Create a Custom Device Family.
You can also restore a device to one of the out-of-box supported device families.
Follow these steps:
  1. Right-click a device that is not currently associated with a device family.
  2. Select Reconfiguration, Reevaluate NCM Device Family.
    Cisco PIX devices do not support the Reevaluate NCM Device Family function.
    Network Configuration Manager reevaluates the device to determine whether it should belong to an out-of-the-box device family.
    If Network Configuration Manager determines that the placement is appropriate, the device is added to the device family.
The Reevaluate NCM Device Family action on a device that is currently in a manually created device family has no effect.
For more information about out-of-the-box supported device families, see Supported Devices.
Extension Utility Script Configuration
Perform all interactions with Network Configuration Manager scripts using OneClick. Network Configuration Manager handles all script administration within the
CA Spectrum
environment. The available scripting options are discussed in the following sections.
Scripting Considerations
When a script is configured for a Network Configuration Manager operation, the script is used for all devices in the family. For example, if scripts are configured for all of the supported operations in the Cisco IOS SSH Capable device family, the Communication Mode setting at the device family and any overridden Communication Mode settings at local devices will have no effect. In this example, the scripts for all Network Configuration Manager operations on all devices contained in the Cisco IOS SSH Capable Device Family will be used.
In the case where only a subset of the Network Configuration Manager operations have scripts configured, Network Configuration Manager uses the Communication Mode selected at the device family or overridden at the local device for the operations for which no script is configured.
Username, Password and Enable Password are always sent to the scripts as command line parameters. The values specified in the device family are used unless they are overridden at the local device in which case the locally overridden values are used.
Default Script Command Line Parameters
By default Network Configuration Manager provides the following parameters, in the order shown, to every script. If the script does not make use of these parameters, the script must still be written to accept them.
  • Device IP.
  • Absolute filename of file containing content to upload. (Upload operation only).
  • Device Username.
  • Device Password.
  • Device Enable Password.
Additional Script Command Line Parameters
Optionally, unlimited additional command line parameters can be configured for each of the supported operations. The parameters are passed on the command line to the script after the default set of parameters. The parameters are passed in the order they are shown in the Additional Script Parameters list.
Upload Running Configuration and Load Device Firmware operations can have additional command line parameters configured in such a way that the user is prompted for a value at runtime. A label and default value can also be displayed when prompting at runtime.
Error Code Mappings
Network Configuration Manager provides the ability to map non-zero integer values returned by the script to a textual error message which displays in OneClick if the error occurs. This enables script creators to provide detailed information on the failure mode.
Script Error Handling
For Network Configuration Manager to report success of a script-based operation, the script must return a value of zero. Network Configuration Manager assumes the operation failed if a non-zero value is returned by the script.
Additional Error Detail Returned in STDERR Buffer
If a script returns a non-zero value, in addition to the error mapping above, Network Configuration Manager will also look for any output returned by the script in the STDERR buffer. If content is found, it will display in OneClick as additional error information.
Enter a Configuration Script
Network Configuration Manager can use Perl scripts for the following operations:
  • Capture Startup Configuration
    This script must return the device startup configuration in the STDOUT buffer. All content that is returned in the buffer is considered to be the device startup configuration.
  • Capture Running Configuration
    This script must return the device running configuration in the STDOUT buffer. All content that is returned in the buffer is considered to be the device running configuration.
  • Upload Running Configuration
    This script reads the file that is identified by the Absolute Filename parameter (for more information, see Default Script Command Line Parameters). It then uploads and merges the content of the file to the device running configuration.
  • Write Startup Configuration
    This script causes the device running configuration to be written to its startup configuration.
  • Reload Device
    This script reboots a device.
  • Cancel Reload
    This script cancels a pending or scheduled reboot of a device.
  • Load Device Firmware Configuration
    This script uploads a new firmware image onto a device and executes all necessary operations to reload the device using this firmware image.
You can select a configuration script for these operations.
Follow these steps:
  1. Select a device family from the Explorer tab.
    Information and configurations display in the Information tab of the Contents panel.
  2. Expand the Device Configuration Transfer Settings subview.
    The script operation subviews appear.
    Note:
    For the Cisco IOS and Cisco IOS - SSH Capable device families, the Load Device Firmware Script resides in the Device Firmware Transfer Settings subview.
  3. Expand the appropriate script operation subview.
    The available script configuration fields display.
  4. Click set next to the script name.
    The Select Script dialog opens as shown in the following example:
    SPEC--selectscript
  5. Take one of the following steps:
    • If a script that you want to use is available, select the script, click OK, and go to Step 10.
    • If you have not yet created a script for the selected device family, click Create to upload or create one.
  6. Supply a unique name for the script in the Script Name field. Paste the script into the field under Script Name, or click Import to import a configuration file that is saved locally on your system.
    The script content appears in the field under the Script Name field, as shown in the following example:
    SPEC--createscript
  7. (Optional) Edit script content if necessary. Or enter criteria in the Search field to locate specific lines in the script file.
  8. Click OK when you have finished importing and configuring the script.
    The script name appears in the Select Script dialog.
  9. Select the script, and click OK.
    The script is loaded and is visible in the Script Content field.
  10. Add any additional script parameters.
    For more information, see Additional Script Command Line Parameters.
  11. Click Add under the Additional Script Parameters field.
    The Add dialog opens.
    1. Enter the parameter name and value. If the operation is Upload, or the task is Load Firmware, you can configure the parameter to prompt you at run time for a value.
    2. Click OK.
      The parameter appears in the Additional Script Parameters field, as shown in the following example:
    SPEC--additionalscriptparameter
  12. Add any error code mappings. For more information, see Error Code Mappings.
  13. Click Add under the Error Code Mappings field.
    The Add dialog opens.
  14. Enter the error code in the Error Code field and the corresponding message in the Error Message field, and click OK.
    The error code appears in the Error Code Mappings field, as shown in the following example:
    SPEC--errorcodemapping
    The configuration script is ready to run.
NCM Support for SSH using Jsch libraries
This release of CA Spectrum NCM supports SSH using Jsch libraries to perform NCM Captures and uploads for CISCO and Juniper devices only using SSH configuration.
Follow these steps to enable NCM SSH to use JSCH mode
:
  1. Goto $SPECROOT\NCM\config.xml
  2. Set the 'ssh-library type' value to 'jsch' (the default value is 'mindterm')
    <ssh-library type="java.lang.String">mindterm</ssh-library>
    to
    <ssh-library type="java.lang.String">jsch</ssh-library>
For large configuration devices (>8K lines), Jsch sometimes throws the capture failure/capture file doesn't work error. To fix this, increase the output wait time.
Follow these steps:
  1. Goto $SPECROOT\NCM\config.xml
  2. Change the jsch-read-datawait type value:
    <jsch-read-datawait type="java.lang.Integer">4</jsch-read-datawait>
    to
    <jsch-read-datawait type="java.lang.Integer">7</jsch-read-datawait>
Information!
CA Spectrum by default uses MindTerm SSH libraries for NCM activities. In some cases, MindTerm libraries throw premature EOF error, then the user need to shift to other libraries such as JSCH or OpenSSH.
For Windows platform, user can shift to only JSCH libraries. For Linux platforms user can shift to either JSCH libraries or Perl Script using the OpenSSH.
In this release of CA Spectrum, NCM supports JSCH for CISCO and Juniper device family only. Once the configuration is set to leverage JSCH libraries, all the NCM activities use JSCH SSH API instead of default SSH API (mindterm).
Perl Modules
CA Spectrum
ships all Perl Modules (for the Windows platforms) required to run the Perl scripts that are provided out-of-box. That includes:
  • Net::Telnet
In addition,
CA Spectrum
also comes with certain perl modules that may be useful in developing scripts for the Extension Utility. These include:
  • Net::OpenSSH
  • Net::SSH
  • Net::SSH::Expect
  • Expect
  • Net::TFTP
  • Net::SCP
  • Net::FTP
Perl modules that ship with
CA Spectrum
can be viewed at:
/opt/SPECTRUM/lib/perl5
Perl modules not compiled and installed correctly may result in failure or other undesirable behavior.
NCM OpenSSH is not supported in the Windows platform.
Using SSH-based Perl Scripts for Network Configuration Manager Operations
CA Spectrum
's out-of-the-box scripts-based support for Network Configuration Manager operations is based on the Net::Telnet module. If you want to use SSH-based scripts for Network Configuration Manager operations:
  • Windows
    --
    CA Spectrum
    includes a complete perl install and the Net::SSH::Expect module.
  • Linux
    -- You must install perl to a separate location on your system and configure
    CA Spectrum
    to use that perl.
This Perl installation and configuration on
CA Spectrum
will have to be done on a per landscape basis in a DSS. You will have to set up perl for each landscape on which you have devices modeled to use SSH-based scripts.
If you want to continue to use
CA Spectrum
's out-of-box scripts once you have configured
CA Spectrum
to use your custom Perl install, then your custom Perl area must have the Net::Telnet perl module installed. You can download and install this module from www.cpan.org. Otherwise,
CA Spectrum
's out-of-box scripts will fail.
In order to set up SSH-based scripts, follow the instructions specific to your platform.
On Windows
  1. Install Perl.
    CA Spectrum
    ships with Cygwin’s complete version of Perl, so you are not required to install anything more if you want to use scripts based on the Net::SSH::Expect module.
    If you want to use scripts based on some other module, complete one of the following depending on the module you are using:
    • If the perl module is compatible with a version of Perl other than Cygwin, then we recommend that you install that specific Perl onto your SpectroSERVER machine, then install your specific perl module, and then configure
      CA Spectrum
      to use your particular Perl install. (See Configuring CA Spectrum to Use a Custom Perl Install.)
    • If the perl module that you want to install is only compatible with Cygwin’s perl, and is a change module (i.e., it does not require compilation of C libraries), then you can add it to the
      CA Spectrum
      Perl install. Just place the <Module_Name>.pm file in $SPECROOT/NT-Tools/SRE/lib/perl5/site_perl/5.8
    • If the perl module that you want to install is only compatible with Cygwin’s perl and also requires C libraries to be compiled, then this module will have to be compiled and shipped with
      CA Spectrum
      . Contact
      CA Spectrum
      support for this enhancement request.
  2. Install SSH-based perl modules and SSH program.
    CA Spectrum
    ships with the Net::SSH::Expect (and its required) modules and the ssh program (that is required by Net::SSH::Expect). For instructions on how to develop scripts using this module, check the documentation for Net::SSH::Expect on www.cpan.org.
  3. Configure
    CA Spectrum
    to use the custom Perl install.
    Since
    CA Spectrum
    ’s perl is set up for this purpose, you don’t have to configure
    CA Spectrum
    to use a custom perl install.
On Linux
  1. Install Perl.
    The OS already has Perl installed (check /usr/bin/). This pre-installed Perl can be used for Network Configuration Manager scripts.
  2. Install SSH-based perl modules and the SSH program.
    You will need to download and install the Net::SSH::Expect module, its dependent modules and the ssh utility.
    The dependency tree for Net::SSH::Expect looks like:
    Net::SSH::Expect -> Expect -> IO::Pty
    where the ‘->’ represents a “requires” relationship.
    You can download all of these modules from www.cpan.org
    Be sure to install these modules to the custom Perl area you installed above.
    This can be done by specifying the full-path of the perl binary when you are installing the modules such as:
    <PERL_FULL_PATH>/perl Makefile.pl
    Some Perl modules are dependent on C/C++ code libraries. In order to install such modules, you have to install the gcc compiler so that you can link against the libraries. You can install the gcc compiler by using rpm to add the latest gcc package.
  3. Install SSH-based perl modules and the SSH program.
    You will need to download and install the Net::OpenSSH module, its dependent modules and the ssh utility.
    The dependency tree for Net::OpenSSH looks like:
    Net::OpenSSH -> IO::Pty -> File::Path
    where the ‘->’ represents a “requires” relationship.
    You can download all of these modules from www.cpan.org
    Be sure to install these modules to the custom Perl area you installed above.
    This can be done by specifying the full-path of the perl binary when you are installing the modules such as:
    <PERL_FULL_PATH>/perl Makefile.pl
    Some Perl modules are dependent on C/C++ code libraries. In order to install such modules, you have to install the gcc compiler so that you can link against the libraries. You can install the gcc compiler by using rpm to add the latest gcc package.
  4. Configure
    CA Spectrum
    to use the custom Perl install.
    See Configuring CA Spectrum to Use a Custom Perl Install and point
    CA Spectrum
    to the perl install area from Step 1 above.
Configuring
CA Spectrum
to Use a Custom Perl Install
CA Spectrum
is configured by default to use the Perl that is shipped with it. If you want to use additional perl modules that are not shipped with
CA Spectrum
, and have installed them to a perl area, you can configure
CA Spectrum
to use your custom perl install. To set this up, click the Configuration Manager model in the Explorer tab in OneClick. In its Information view, expand the Perl Configuration subview. You will find a table that contains the Perl directory configuration per landscape.
Note that the Use Custom Perl option has to be set to Enabled to be able to specify a custom perl directory. Otherwise, the default Perl that comes with
CA Spectrum
is used. You can point
CA Spectrum
to a custom Perl location that you have installed on a particular
SpectroSERVER
system.
Follow these steps:
  1. On a given landscape, set the Use Custom Perl to Enabled.
  2. Once you have enabled the use of a custom Perl area, specify the Custom Perl Directory.
    The Custom Perl directory must contain the full pathname of the directory that contains the perl.exe (Windows) or the perl program (Linux).
For example, if the perl program is located in /usr/local/bin/, specify Custom Perl Directory as /usr/local/bin.
You can continue to use the
CA Spectrum
default scripts once you have configured
CA Spectrum
to use your custom Perl install. But your custom Perl area must have the Net::Telnet perl module installed. You can download and install this module from www.cpan.org. Otherwise, the
CA Spectrum
default scripts fail.
You can also disable the use of your custom Perl area and use the default
CA Spectrum
Perl.
Set the Use Custom Perl to Disabled (use
CA Spectrum
default). Note that when you disable the use of a custom Perl area, the Custom Perl Directory cannot be seen or edited. But when you enable Use Custom Perl again, your previously specified Custom Perl Directory will be restored.
Using Additional Perl Modules
If you want to use scripts based on your preferred perl module, you must install the perl module to the area that will be used.
On Windows
Depending on the module that you want to use you have three options:
  • If the perl module is compatible with a version of Perl other than Cygwin, then we recommend that you install that specific Perl onto your SpectroSERVER machine, then install your specific perl module and then configure
    CA Spectrum
    to use your particular Perl install. (See Configuring CA Spectrum to Use a Custom Perl Install).
  • If the perl module that you want to install is only compatible with Cygwin’s perl, and is a text-based module (i.e., it does not require compilation of C libraries), then you can add it to the
    CA Spectrum
    Perl install. Just place the <
    Module_Name
    >.pm file in
    $SPECROOT/NT-Tools/SRE/lib/perl5/site_perl/5.8
  • If the perl module that you want to install is only compatible with Cygwin’s perl and also requires C libraries to be compiled, then this module will have to be compiled and shipped with
    CA Spectrum
    . Contact
    CA Spectrum
    support for this enhancement request.
On Linux
It is required that you install Perl to a separate area on your SpectroSERVER, then install the required perl modules using that Perl and configure
CA Spectrum
to use the Perl install area. Once you have installed Perl, refer to the installation instructions of the specific perl module that you want to install. Then refer to Configuring CA Spectrum to Use a Custom Perl Install. You may refer to the Using SSH-based Perl Scripts for Network Configuration Manager Operations for details about how to use scripts based on the Net::SSH::Expect module but you may use the procedure as a guideline for integrating any perl module.
Import and Export Scripts
Network Configuration Manager lets you import and export scripts in bulk. The scripts are exported to or imported from the file system of the host server that is running the OneClick client.
Follow these steps to export scripts:
  1. Select Configuration Manager in the Navigation panel.
  2. Select the Information tab in the Contents panel.
    Information and configurations display.
  3. Expand the Configuration Script Import/Export subview.
    The Import Scripts and Export Scripts buttons display.
SPEC--configurationscript
  1. Click Export Scripts.
    The Select Scripts To Export dialog opens.
  2. Select the script to be exported. Or select multiple scripts.
    The Save as dialog opens.
  3. Select the location to save, and supply a name for the XML specification file that is automatically generated during export. The export process generates a file for each selected Perl script using its designated name and the .pl extension. The export process also generates the XML specification file that contains the list of scripts that were exported and the error mapping information for each. The XML specification file can then be used to import the scripts on the same or different
    CA Spectrum
    environment.
    The selected Perl scripts are exported to the location that you specified.
Follow these steps to import scripts:
  1. Select Configuration Manager in the Navigation panel.
  2. Click the Information tab in the Contents panel.
    Information and configurations display.
  3. Expand the Configuration Script Import/Export subview.
    The Import Scripts and Export Scripts buttons display.
  4. Click Import Scripts.
    The open dialog opens.
  5. Select the XML specification file that describes the Perl scripts to be imported into Network Configuration Manager. If you are importing scripts that were previously exported from
    CA Spectrum
    , you can use the XML specification file that was generated during that export.
    The XML specification file may also be generated manually by following the format shown in the following example.
    <scripts> <script> <file-name>ABC_Vendor_Capture_Running_Configuration.pl</file-name> <display-name>ABC Vendor Capture Running Configuration</display-name> <error-message errorCode="255">Usage</error-message> <error-message errorCode="99">Invalid Enable Password</error-message> <error-message errorCode="98">Unexpected Response</error-message> <error-message errorCode="97">Illegal Telnet Timeout Value</error-message> </script> <script> <file-name>XYZ_Vendor_Capture_Running_Configuration.pl</file-name> <display-name>XYZ Vendor Capture Running Configuration</display-name> <error-message errorCode="255">Usage</error-message> <error-message errorCode="99">Response Timed out</error-message> <error-message errorCode="50">Connection Error</error-message> </script> <script> <file-name>XYZ_Vendor_Capture_Startup_Configuration.pl</file-name> <display-name>XYZ Vendor Capture Startup Configuration</display-name> </script> </scripts>
    • file-name
      The name of the Perl file to be imported. This file must exist in the same directory as the XML specification file at the time of import.
    • display-name
      The name that is used in OneClick to identify this script.
    • error-message
      (Optional) Describes a mapping of an error code that is returned by the script to a textual error message that is displayed in OneClick if the error occurs. Multiple error-message elements can be specified for each script.
    The Perl script XML is imported. The scripts will be available when configuring Network Configuration Manager operations on device families.
    The import process does not associate the scripts with a device family.
Maintaining a Script Backup and History
Scripts are stored as models in the
CA Spectrum
database and therefore are backed up each time
CA Spectrum
performs a backup. The script export feature provides an additional backup and means of tracking the history of Network Configuration Manager scripts that is easily accessed and imported back into
CA Spectrum
if desired.
Customized Traps
You can extend the functionality of Network Configuration Manager by configuring customized trap settings for your installation. These settings are used to correlate configuration change event information so that events are combined for a particular device. These settings are configured at the device family level. For more information, see Configure Notification Trap Settings.