Inventory Manager provides device management support for third-party devices by executing scripts on the devices using Telnet or SSH. With this support, Inventory Manager Wizards can perform their operations on third-party devices even though the devices do not support the required SNMP MIBs. The devices are set up to use scripts in place of the MIBs when performing the Inventory Manager functions.
The following Inventory Manager functions can be performed on third-party devices through the use of scripts:
- Configuration Upload (Archive Save)
- Configuration Download (Restore Archive)
- Firmware Download (Firmware Upgrade)
- Device Reset
- Device Timed Reset
Scripts are created and stored in Device Family Definition Files. These definition files can include multiple scripts (one for each Inventory Manager function), written for a specific device family. The files can also include regular expressions to determine if the scripts were executed successfully.
The script itself contains the CLI commands used to perform the function on the device, and is executed by the NetSight Command Script Tool. For more information, see the How to Use the Command Script Tool Help topic located in the Suite-Wide Tools section of the online help or user guide (PDF).
Configuration files and firmware image files for script transfers should be stored in the same directories as files for transfers using MIBs. Files can be transferred through the use of a TFTP, FTP, or SCP server. For information on server setup, see the TFTP Server Setup, FTP Server Setup, and SCP Server Setup Help topics in the Inventory Manager online help or user guide (PDF).
This Help topic contains information for creating Device Family Definition Files, and the steps for configuring your third-party devices to use the scripts stored in definition files. When you have completed the device configuration, you will be able to perform Inventory Manager Wizard operations on your third-party device.
Instructions on:
Device Family Definition Files
Scripts for each Inventory Manager function for a specific device family are stored together in a Device Family Definition File. These files are available for selection when configuring your devices to use scripts. Inventory Manager provides definition files for several device families: Extreme, Enterasys, Cisco, and Hewlett Packard. These files are stored as resource files and cannot be modified. You can also create your own user-defined Device Family Definition Files to provide additional scripts for your third-party devices.
Creating Device Family Definition Files
You can create your own Device Family Definition Files to contain the scripts to use for your third-party devices. When you create a definition file, you must follow a specific format. There is a file stored in the <data storage directory>\properties\devicefiles called DeviceFamilyDefTemplate.txt that can be used as a template when creating new files. Any new files you create are stored in the devicefiles directory, and these files will be displayed on the list of files available for selection when configuring your devices.
| NOTE: | The path to the data storage directory is specified in the Inventory Manager options. |
|---|
Following is an example of a file called "Cisco Systems - TFTP" that contains a script to perform archive saves (configuration uploads) on Cisco devices. The name "Cisco Systems - TFTP" will show up in the selection list when configuring devices to use scripts.
--- Use these scripts to manage Cisco devices
name="Cisco Systems - TFTP"
desc="Cisco Systems SSH/TFTP Scripts"
separator=Windows_File_Separator
timed_reset_delay_format="HH:mm:ss:SS"
-----BEGIN SCRIPT "Configuration Upload"-----
enable
%ENABLEPSWD%
copy running-config tftp:
%TFTP_IP%
%RELATIVE_TARGET_FILE_PATH%
@receive 20
exit
-----END SCRIPT-----
-----BEGIN SUCCESS "Configuration Upload"-----
bytes copied
-----END SUCCESS-----
The following table describes the items included in a definition file:
| Item | Description |
|---|---|
|
|
This is the name that appears in the Device Family Definition File drop-down list when selecting a script to use. The name is required and must be unique. |
|
|
A description of the intended use of the scripts. |
| separator=Windows_File_Separator | The type of separator to be used when building a
directory path. Possible values are UNIX_File_Separator,
Windows_File_Separator, or a user-specified string. Where: UNIX_File_Separator= "/" Windows_File_Separator = "\" |
| timed_reset_delay_format="HH:mm:ss:SS" | The format to be used when specifying the time for
the timed reset delay. The default is "HH:mm". Where: H = hours m = minutes s = seconds S = milliseconds |
|
|
Separator line that denotes the start of a pre-script. If the device won’t transfer the file to the path Inventory Manager expects, a pre-script can be used to create an empty file in advance of the file transfer. This would be the case when a device only transfers a file to an absolute path, not a relative one. |
|
|
Separator line that denotes the end of the pre-script. |
|
|
Separator line that denotes the start of a script. |
|
|
Separator line that denotes the end of a script. |
|
|
Separator line that denotes the start of the regular expressions to test for success. If you include multiple expressions, each expression must be successful for the overall script execution to be considered successful. For firmware download and configuration download operations, the script must contain regular expressions to determine the actual success of the script. Note that if the script exits abnormally, then the test for success will not be performed and the Active Status Summary View and Details View in Inventory Manager will show a status of "failure" for the operation. If the script exits normally, then the status will reflect the results of the test ("success" or "failure"). |
|
|
Separator line that denotes the end of the regular expressions to test for success. |
|
|
Separator line that denotes the start of a post-script. If the device transfers the file to a location other than the path Inventory Manager expects, a post-script can be used to copy the transferred file from one location to another. For example, if the device used an absolute path to do the transfer, the file would be created at the <root>/device_ip.cfg path. You can use a post-script to copy the file from the top-level root path to <root>\configs\tmp\device_ip.cfg path so that Inventory Manager can find the file on script completion and copy it to the permanent storage area. |
|
|
Comment. Anything on the line after these characters is ignored. A comment can only exist outside of a script. |
The function name must be one of the following:
- "Configuration Upload"
- "Configuration Download"
- "Firmware Download"
- "Reset"
- "Timed Reset"
Using Script Variables
The Command Script tool that executes the script portion of
the file supports
the use of system-defined and user-defined variables within the scripts. The variable must appear in the script bracketed by percentage signs, for example,
System-Defined Variables
There are five NetSight system-defined variables that can be used in a script (however, not in a pre-script or a post-script). These variables are resolved by the NetSight Command Script service:
%DEVICEIP% - The IP address of the currently selected device.
%LOGINUSER% - The login username configured in the Profile of the selected
device.
%LOGINPSWD% - The login password configured in the Profile of the selected
device.
%ENABLEPSWD% -The enable password configured in the Profile of the selected
device.
%CONFIGPSWD% - The config password configured in the Profile for the selected
device.
The following script variables are defined and resolved by Inventory Manager when a script is executed:
| Variables | Description |
|---|---|
| %TFTP_IP% | The TFTP Server IP address set in the TFTP Transfer Settings in the Inventory Manager Options. The File Transfer Method must be set to TFTP for the target device. |
| %TFTP_URL% | The URL used to copy a file using the TFTP server. It is set to: tftp://TFTP_IP/RELATIVE_TARGET_FILE_PATH |
| %SERVER_IP% | The IP address of the NetSight Server. |
| %FTP_IP% | The FTP Server IP address set in the FTP Transfer Settings in the Inventory Manager Options. The File Transfer Method must be set to FTP for the target device. |
| %FTP_PORT% | The FTP Server Port number set in the FTP Transfer Settings in the Inventory Manager Options. The File Transfer Method must be set to FTP for the target device. |
| %FTP_USER% | The Login Username set in the FTP Transfer Settings in the Inventory Manager Options. The File Transfer Method must be set to FTP for the target device. |
| %FTP_PSWD% | The Login Password set in the FTP Transfer Settings in the Inventory Manager Options. The File Transfer Method must be set to FTP for the target device. |
| %FTP_URL% | The URL used to copy a file using the FTP server. It is set to: fpt://FTP_IP/RELATIVE_TARGET_FILE_PATH |
| %SCP_IP% | The SCP Server IP address set in the SCP Transfer Settings in the Inventory Manager Options. The File Transfer Method must be set to SCP for the target device. |
| %SCP_PORT% | The SCP Server Port number set in the SCP Transfer Settings in the Inventory Manager Options. The File Transfer Method must be set to SCP for the target device. |
| %SCP_USER% | The Login Username set in the SCP Transfer Settings in the Inventory Manager Options. The File Transfer Method must be set to SCP for the target device. |
| %SCP_PSWD% | The Login Password set in the SCP Transfer Settings in the Inventory Manager Options. The File Transfer Method must be set to SCP for the target device. |
| %SCP_URL% | The URL used to copy a file using the SCP server. It is set to: scp://SCP_IP/RELATIVE_TARGET_FILE_PATH |
|
|
The amount of time to delay before the reset should occur. The
format of the time is HH:mm:ss:SS. Where: H = hours m = minutes s = seconds S = milliseconds |
|
|
The name of the file that will be uploaded or downloaded, depending on which function is selected. For example, for a configuration file: xx_xx_xx_xx.cfg (where xx_xx_xx_xx is the device IP address). |
|
|
The file path to the TARGET_FILE_NAME relative to the root directory of the server (TFTP, FTP, or SCP). This variable is required for configuration upload or download operations (archive save and archive restore) and firmware download operations. For configuration operations, the path is configs/tmp/xx_xx_xx_xx.cfg (where xx_xx_xx_xx is the device IP address). For firmware download operations, the path is firmware/../../Resources/Images/invhelp/imageFileName (where imageFileName is the name of the firmware file being downloaded). |
| %RELATIVE_SERVER_DIR_PATH% | The directory path of the TARGET_FILE_NAME relative to the root directory of the server (TFTP, FTP, or SCP). This variable is required for configuration upload or download operations (archive save and archive restore) and firmware download operations. For configuration operations, the path is configs/tmp/. For firmware download operations, the path is firmware/images/. |
| %ABSOLUTE_TARGET_DIR_PATH% | The absolute file path to the TARGET_FILE_NAME of the server (TFTP, FTP, or SCP). This variable is required for configuration upload or download operations (archive save and archive restore) and firmware download operations. For configuration operations, the path is serverRootDir/configs/tmp/xx_xx_xx_xx.cfg (where xx_xx_xx_xx is the device IP address). For firmware download operations, the path is serverRootDir/firmware/images/imageFileName (where imageFileName is the name of the firmware file being downloaded). |
| %ABSOLUTE_SERVER_DIR_PATH% | The absolute directory path of the TARGET_FILE_NAME from the root directory of the server (TFTP, FTP, or SCP). This variable is required for configuration upload or download operations (archive save and archive restore) and firmware download operations. For configuration operations, the path is serverRootDir/configs/tmp/. For firmware download operations, the path is serverRootDir/firmware/images/. |
|
|
Value defined by the "separator=" value, if specified. |
User-Defined Variables
User-defined variables let you create custom variables based on device IP address that will be substituted in a script command when it is executed on the specific device.
For example, let's say you want to perform an archive save (configuration upload) on multiple devices using a script command that specifies interface names. You can create a set of variables that define the interface name values for each device, and add the variables to your script.
The variables are defined in their own script section using the following separators. The section can be placed at any location in the script.
-----BEGIN USER-DEFINED VARIABLES -----
-----END USER-DEFINED VARIABLES -----
User-defined variables have the following format:
userDefinedVariableName.Default=myvalue
where:
userDefinedVariableName is replaced with a unique variable name
Default can be left as Default or replaced with the IP address of a device the script will be used on
myvalue is the value that the variable will be replaced with
The variable must appear in the script bracketed by percentage signs, for example %InterfaceName%. When a script running on a device encounters a variable, it looks in the user-defined variable section for the variable name and the device IP address. If it finds a match, it substitutes the defined value. If the IP address is not found, the script looks for the default. If it finds a default, it substitutes the defined default value. If no default is found, an empty string value is used.
User-defined variable names are not case sensitive and must be unique. They can only contain alphanumeric characters and underscores.
Here are some examples of user-defined variables:
-----BEGIN USER-DEFINED VARIABLES -----
INTERFACE_NAME.default = ge.1.0
INTERFACE_NAME.10.20.77.33=ge.1.1
INTERFACE_NAME.10.20.80.138=ge.1.2
--
firmwareVersion.Default=7.07.12
firmwareVersion.10.20.77.33=06.00.01
firmwareVersion.10.20.80.138=06.00.02
--
SOME_PATH.Default=c:\Temp\newFile.txt
SOME_PATH.10.20.77.33=d:\Temp\10_20_77_33.txt
SOME_PATH.10.20.80.138=d:\Temp\10_20_80_138.txt
--
filename.default=slot4/jcn3p.cfg
fileName.10.20.80.138=someotherfile.txt
--
finalfile.10.20.77.22=d:/Temp/10207733.cfg
-----END USER-DEFINED VARIABLES -----
Sample Script Execution
This is a description of how Inventory Manager performs an archive (configuration upload) operation using a script file.
- Create an empty file before file transfer. The more secure TFTP/FTP/SCP servers will not allow a file to be written that does not already exist. For this reason, Inventory Manager always creates a zero length file in the Protocol's root\configs\tmp\device_ip.cfg path. This provides a placeholder for the device to write to during the file transfer operation. (The root directory is configured in the Tools > Options > File Transfer Setting windows.) Note that some devices won't transfer the file to the path that Inventory Manager expects (for example, the device only transfers a file to an absolute path, not a relative one). In this case, an empty file can be created using a pre-script in the Device Family Definition file.
- Initiate upload to transfer the configuration file from the device to the file transfer server. To do this, the script portion of the Device Family Definition file is executed by the NetSight Command Script Tool. A telnet or SSH session is initiated on the device and the script is sent to the device for execution. The file is expected to be transferred to the path relative to the root of the transfer server at configs/tmp/device_ip.cfg.
- Copy the file transferred to a permanent archive location. Once the device reports back success, Inventory Manager copies the file to the data storage directory. If the file is zero length, it is deleted. Note that some devices will transfer the file to a location other than the path Inventory Manager expects. In this case, the file can be copied to the expected location using a post-script in the Device Family Definition file.
Following is a sample script that uses the pre-script and post-script sections. The pre-script section creates an empty file at the TFTP server's top-level root directory called C:/tftpboot/xx_xx_xx_xx.cfg, where xx_xx_xx_xx is the IP address of the device and the TFTP root directory is C:/tftpboot/. The script section causes the device to transfer the file to the path where the empty file was created. And the post-script section copies the transferred file to the path where Inventory Manager expects to find the file.
-- This script shows how the pre-script and post-script
sections of the DeviceFamilyDefinition file can be used.
-- This is only an example and not intended for use beyond that.
--
name="Enterasys Networks"
desc="Enterasys Networks SSH/TFTP Scripts"
separator=WINDOWS_FILE_SEPARATOR
--
-----BEGIN PRE-SCRIPT "Configuration Upload"-----
create c:%PATH_SEPARATOR%tftpboot%PATH_SEPARATOR%%TARGET_FILE_NAME%
-----END PRE-SCRIPT-----
-----BEGIN SCRIPT "Configuration Upload"-----
delete slot4/switch.cfg
show config outfile slot4/switch.cfg
@receive 20
copy slot4/switch.cfg tftp://%tftp_IP%/%TARGET_FILE_NAME%
exit
-----END SCRIPT-----
-----BEGIN POST-SCRIPT "Configuration Upload"-----
copy c:%PATH_SEPARATOR%tftpboot%PATH_SEPARATOR%%TARGET_FILE_NAME% %ABSOLUTE_TARGET_FILE_PATH%
-----END POST-SCRIPT-----
File Backup and Restore
All user-defined Device Family Definition Files are backed up and restored during a Database Backup and Restore operation. To perform a backup or restore operation, open the Server Information window (Tools > Server Information) and select the Database tab. Use the Backup and Restore buttons in the NetSight Data Set Operations section. The Backup operation places all the files under the <data storage directory>\properties\devicefiles directory in a zip file. The Restore operation unzips them and places them back under the devicefiles directory.
| NOTE: | The path to the data storage directory is specified in the Inventory Manager options. |
|---|
Configuring Devices
This section provides information on setting up your third-party devices to use the scripts stored in Device Family Definition Files. There are several preliminary steps to perform in order to be able to execute a script on a device.
-
The device must have CLI credentials set so that the Command Script Tool can set
up a Telnet or SSH session with the device.
Use the NetSight Authorization/Device Access tool (accessed from Inventory
Manager's
Tools menu) to configure the profiles and credentials that provide
access to your network devices.
Each device is assigned a profile and that profile designates the CLI credentials
to use for that device. CLI credentials include the following information:
- User name
- Login Password
- Enable Password
- Configuration Password
- Connection Type - SSH or Telnet
The Command Script tool uses the connection type (SSH or Telnet), user name, and login password specified in the CLI credentials when establishing a connection to the device. If these are not set up correctly, the connection cannot be created. - The device must have SNMP read access configured in the Device Access Profile. Use the NetSight Authorization/Device Access tool to configure your profiles.
- You must have a TFTP, FTP, or SCP server configured and running to perform an upload or download operation.
- Make sure that the File Transfer Method has been set for the target devices. For information see File Transfer Method Window.
- The files to be transferred should be stored in the same directories as files for transfers using a MIB.
You must also specify the script that will be used by the third-party devices. You can specify a script for a single third-party device, for multiple devices in a device group, or for multiple devices of a specific device type (Extreme or Enterasys devices only) as outlined in the steps below.
To select a script to be executed for a single third-party device:
- In the left-panel Network Elements tab, select the desired device. Select the Image Information tab in the right panel.
- In the Firmware Download MIB field, select Script from the drop-down list.
- In the Configuration Download MIB field, select Script from the drop-down list.
- In the Device Family Definition File Name field, select the file that contains
the scripts you want to use. Once the file is selected, the "Features Supported By This Device"
section is completed with the types of scripts found in the file.
To set a script to be executed for all devices in a device group:
- In the left-panel Network Elements tab, select the desired device group. Right-click and select MIB Override Method. The MIB and Script Override window opens.
- In the Firmware Download MIB field, select Script from the drop-down list.
- In the Configuration Download MIB field, select Script from the drop-down list.
- In the Device Family Definition File Name field, select the file that contains the scripts you want to use.
- Click OK.
To set a script to be executed for all devices of a specific device type (Extreme or Enterasys devices only):
- In the left-panel Firmware Management tab, select a device type firmware image folder. Select the General tab in the right panel.
- In the Firmware Download MIB field, select Script from the drop-down list.
- In the Configuration Download MIB field, select Script from the drop-down list.
- In the Device Family Definition File Name field, select the file that contains
the scripts you want to use.
When you have finished configuring your devices to use scripts, will be able to perform Inventory Manager Wizard operations on those devices.
Logging and Error Reporting
This section provides information about how to enable debug logging and perform troubleshooting using log output and error messages, when using the third-party script functionality.
Logging
You can use the NetSight Server Diagnostics web page to enable debug logging that allows you to see the content of the script before it is sent to the device and the content of the SSH session after the script has been executed.
Access this web page from the NetSight Launch page by clicking the Administration tab. To access the server diagnostics, you will need to log in with your username and password. (If the NetSight Server is a Windows platform system, in the Username field you must enter a domain name and a username using the following format: <domain name>\<username>). Enable the "Inventory Manager" and "Telnet/SSH Command Shell" debug groups by setting the Diagnostic Level to "Verbose." You can view the log output in the Server Information window (Tools > Server Information) on the Server Log tab. You can also access the log output in <install area>\NetSight\appdata\logs\server.log on the NetSight Server.
Log Output
The following debug log error message appears when more than a second has passed without activity over the
SSH session.
If a script uses the meta command @RECEIVE n, there will be n number of these messages in the log.
It does not necessarily indicate an error.DEBUG [SSHShellConnection] 10.20.80.80:20 socket closed or timed out
For information on using meta commands, see
How to Use
the Command Script Tool under Suite-Wide Tools.
This log output displays the Inventory Manager script variable values just before the script is executed. In this example, the File Transfer Method for the device is set to TFTP, so only the TFTPURL is valid. The TIMEDRESET will be set only for a timed reset from the Reset Device Wizard.
DEBUG [ScriptMib] TFTP_IP = 10.20.30.40
DEBUG [ScriptMib] FTP_URL = ftp://null:null@10.20.90.30:69/configs/tmp/10_20_80_80.cfg
DEBUG [ScriptMib] SERVER_IP = 10.20.30.40
DEBUG [ScriptMib] TARGET_FILE_NAME = 10_20_80_80.cfg
DEBUG [ScriptMib] TIMED_RESET_DELAY_SECONDS = -1
DEBUG [ScriptMib] SCP_URL = scp://null:null@10.20.90.30:69/configs/tmp/10_20_80_80.cfg
DEBUG [ScriptMib] TFTP_URL = tftp://10.20.30.40/configs/tmp/10_20_80_80.cfg
DEBUG [ScriptMib] SCP_IP = 10.20.30.40
DEBUG [ScriptMib] FTP_IP = 10.20.30.40
DEBUG [ScriptMib] RELATIVE_TARGET_FILE_PATH = configs/tmp/10_20_80_80.cfg
Error Troubleshooting
Here is a list of some of the possible errors that could be generated from a script and displayed in the Server Log.
- authentication failure: The login credentials are invalid.
- Check the CLI credentials of the target device using the Authorization/Device Access window available from the Inventory Manager Tools menu.
- connection refused: SSH access is not enabled on the device, and is required for the script to execute.
- Verify that SSH is enabled on the target device.
- SSH channel is closed. (The connection is being shutdown): Lost connection to the device.
- This error is produced when the SSH session ends unexpectedly. This can happen during a reset if there are any commands in the script after the "reboot" command. This case is expected and handled in the server.
- Config file is empty.
- This error is produced during a Configuration Upload (Archive Save)
operation, and can be caused by a number of reasons.
Turn on debug logging and check the script output. Here are a few possible
reasons:
- The script has an error and did not perform the function properly.
- The TFTP/FTP/SCP server was not running or could not be reached from the target device.
- The session ended before the file was completely transferred.
- Error Restoring Config File.
- This error is produced during a Configuration Download (Archive Restore)
operation, and can be caused by a number of reasons. Turn on debug logging and check the script output.
Here are a few possible reasons:
- The script has an error and did not perform the function properly.
- The TFTP/FTP/SCP server was not running or could not be reached from the target device.
- The session ended before the file was completely transferred.
- Error Restoring Firmware.
- This error is produced during a Firmware Download operation, and can
be caused by a number of reasons. Turn on debug logging and check the script
output. Here are a few possible reasons:
- The script has an error and did not perform the function properly.
- The TFTP/FTP/SCP server was not running or could not be reached from the target device.
- The session ended before the file was completely transferred.
- Error Resetting device.
- This error is produced during a Timed Reset operation. Turn on debug logging and check the script output. It is possible that the script has an error and did not perform the function properly.
- Device did not reset - System up time did not reset.
- This error is produced during a manual reset. The sysUpTime did not change as expected, so it is determined that the device reset failed. Turn on debug logging and check the script output.
- No matches found for Success type regEx from script.
- This error is produced by the output being parsed for the regular expressions given in the Device Family Definition File. Check the file and script output for the cause.
- Unknown Ticket Type
- The function selected is not supported.
- TFTP Server Setup
- FTP Server Setup
- SCP Server Setup
- File Transfer Method Window
- How to Use the Command Script Tool
