Setting Up Third-Party Device Support


Use ExtremeCloud IQ Site Engine to add device management support for third-party devices by executing scripts on the devices using Telnet or SSH. With this support, ExtremeCloud IQ Site Engine 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 ExtremeCloud IQ Site Engine functions.

The following ExtremeCloud IQ Site Engine 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 Restart
  • Device Timed Restart

Scripts are created and stored in Device Family Definition Files. These definition files can include multiple scripts (one for each 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 ExtremeCloud IQ Site Engine scripting functionality.

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.

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 operations on your third-party device.

Instructions on:

Device Family Definition Files

Scripts for each 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. ExtremeCloud IQ Site Engineprovides 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 you can use as a template when creating new files. Any new files you create are stored in the devicefiles directory, and these files display on the list of files available for selection when configuring your devices.

  NOTE: The path to the data storage directory is specified in Administration > Options Inventory Manager.

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" shows 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
name="Brand X Networks" 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.
desc="scripts for Brand X" 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 restart delay. The default is "HH:mm".
Where:
   H = hours
   m = minutes
   s = seconds
   S = milliseconds
-----BEGIN PRE-SCRIPT "function name"----- 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.
-----END PRE-SCRIPT----- Separator line that denotes the end of the pre-script.
-----BEGIN SCRIPT "function name"----- Separator line that denotes the start of a script.
-----END SCRIPT----- Separator line that denotes the end of a script.
-----BEGIN SUCCESS "function name"----- 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").
-----END SUCCESS----- Separator line that denotes the end of the regular expressions to test for success.
-----BEGIN POST-SCRIPT "function name"----- 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"
  • "Restart"
  • "Timed Restart"

Using Script Variables

The script 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, %TFTPIP%.

System-Defined Variables

There are five system-defined variables you can use in a script (however, not in a pre-script or a post-script). These variables are resolved by ExtremeCloud IQ Site Engine:

     %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 ExtremeCloud IQ Site Engine 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 ExtremeCloud IQ Site Engine 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
%TIMED_RESET_DELAY_SECONDS% The amount of time to delay before the restart occurs. The format of the time is HH:mm:ss:SS.
Where:
   H = hours
   m = minutes
   s = seconds
   S = milliseconds
%TARGET_FILE_NAME% The name of the file 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).
%RELATIVE_TARGET_FILE_PATH% 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/.
%PATH_SEPARATOR% 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 are 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 is 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 ExtremeCloud IQ Site Engine performs an archive (configuration upload) operation using a script file.

  1. Create an empty file before file transfer. The more secure TFTP/FTP/SCP servers does not allow a file to be written that does not already exist. For this reason, ExtremeCloud IQ Site Engine 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 Administration > Options > Inventory Manager > File Transfer settings.) Note that some devices won't transfer the file to the path that ExtremeCloud IQ Site Engine 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.
  2. 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 ExtremeCloud IQ Site Engine 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.
  3. Copy the file transferred to a permanent archive location. When the device reports back success, ExtremeCloud IQ Site Engine copies the file to the data storage directory. If the file is zero length, it is deleted. Note that some devices transfer the file to a location other than the path ExtremeCloud IQ Site Engine 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 ExtremeCloud IQ Site Engine 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 Backup/Restore tab (Administration > Backup/Restore). Use the Back Up and Restore buttons to begin the processes. 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.

  1. 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 Administration > Profiles tab 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.
  2. The device must have SNMP read access configured in the Device Access Profile. Use the Profiles tab to configure your profiles.
  3. You must have a TFTP, FTP, or SCP server configured and running to perform an upload or download operation.
  4. Make sure that the File Transfer Method has been set for the target devices. For information see Inventory Settings window.
  5. 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.

  1. Right-click the desired device, device group, or device type in the left-panel on the Network > Devices tab or select the devices from the right-panel Devices list.
  2. Select Archives > Inventory Settings.

    The Inventory Settings window opens. Configure the following fields in the MIB and Script Override Method section of the window.
  3. In the Firmware Download MIB field, select Script from the drop-down list.
  4. In the Configuration Download MIB field, select Script from the drop-down list.
  5. In the Device Family Definition Filename field, select the file that contains the scripts you want to use.

When you have finished configuring your devices to use scripts, you are able to perform inventory 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 ExtremeCloud IQ Site Engine Server Diagnostics tab 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 by selecting the Administration > Diagnostics tab. To access the server diagnostics, select Diagnostic from the Level drop-down list. 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 ExtremeCloud IQ Site Engine 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

This log output displays the 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.

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 CLI Credentials tab at the bottom of the Administration > Profiles tab.
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 restart 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 Restarting device.
This error is produced during a Timed Restart 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 restart - System up time did not restart.
This error is produced during a manual restart. The sysUpTime did not change as expected, so it is determined that the device restart 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.

For information on related help topics: