Define Kiwi CatTools custom device script using .txt file
Device scripts are defined within CatTools using .txt files and are stored in the \Program Files (x86)\CatTools3\Scripts sub folder within the root CatTools directory.
When an activity is run, CatTools reads the name item value in the [device] section from the device type .ini file to determine which device script .txt file it needs to use. Therefore each .txt file must be given the same file name as the name item in the corresponding .ini file.
SolarWinds recommends that the .ini file and .txt files have the same file name, apart from the file extension.
For all the predefined device types in CatTools, the associated device script .txt files are encrypted. They are encrypted for two reasons:
- To protect our intellectual property.
- To prevent unauthorized modification of files which may cause the scripts to fail at run time.
Custom device script .txt template
CatTools provides a starting point template file, based on a Cisco Router, to help assist in the creation of a new custom device script. The template file is called Custom.Device.Template.txt and can be found in the \Program Files (x86)\CatTools3\Templates sub folder within the root CatTools directory.
If you need to create a new custom device script, make a copy the template file and save it to the \Scripts sub folder giving it a new file name.
This template file is included as part of the predefined device scripts in CatTools, but is unencrypted. It is subject to updates and modifications with each new release of the CatTools product. For this reason, you should never modify the original template file when creating a new custom device script.
Creating your custom device script .txt file
When adding a new custom device script to CatTools, the first step is to copy the template file Custom.Device.Template.txt in the \Templates sub folder and save it to the \Scripts sub folder, giving it a file name the same as the value entered for the name item within the device type .ini file [device] section, and end with a .txt file type suffix. This gives you a new starting point device script file to work with.
For example, to create a new custom device script for a Cisco ASA Firewall device, you may have created an .ini file Custom.Cisco.FirewallASA.ini which contains the name item in the [device] section of Custom.Cisco.FirewallASA. Therefore, the custom script file must be named Custom.Cisco.FirewallASA.txt.
Editing the .txt file
The next step is to open the .txt file and make any necessary changes in order to customize the script to work with your device. The .txt file is well documented, providing instructions and assistance in making your modifications. There are a few important sections at the top of the script file which require further mention.
Visual Basic module name
You may see the following line at the very top of the script: Attribute VB_Name = "Dev_CustomDeviceTemplate".
This is the Visual Basic module name for the device script file when viewing within the Visual Basic, or equivalent, development environment. This line typically does not appear when editing the file in a VB development environment, but may in other environments.
"Dev_CustomDeviceTemplate" is the name given to the custom template file module. If you have a number of custom device files, consider changing this default name to reflect your device script file name. By doing so, you can then open multiple custom device script files in your VB development environment.
If you are using a text based editor to modify your scripts, such as Notepad, changing the module name is optional. To avoid confusion you may prefer to change the name anyway.
Option Explicit
The Option Explicit statement enforces a level of compliance for the scripting code. You must explicitly declare all variables using the Dim statement, or, if re-dimensioning, using ReDim. If you attempt to use an undeclared variable name, an error occurs at compile time.
Device script files use the Visual Basic Scripting language (VB Script). There is no declaration of the variable types.
Constant declarations
The script constants (Const) are declared below the Option Explicit statement.
Private Const SCRIPT_NAME = "Device Template"The
SCRIPT_NAMEconstant is a reference given to the script file. This reference appears within the Info Log pane andInfolog.txtfile whenever the script is called.Private Const DEVICE_The
DEVICE_constants are constants which define device configuration or responses from the device. For example:DEVICE_USERNAMEPROMPT = "Username:"implies that every time there is a prompt from the device to enter a user name, we expect to see a"Username:"prompt.Private Const COMMAND_The
COMMAND_constants are constants which define commands that CatTools sends to the device in order to perform specific tasks or actions when running an activity. For example:COMMAND_ENTERENABLEMODE = "enable"tells CatTools to send theenablecommand, instructing the device to enterenable mode.
Notes
--- SCRIPT NOTES ---
The Script Notes section provides useful information and lists tasks that are required to be carried out during the initial script creation phase. You can edit this section as and when you feel it is appropriate. An example may be deleting the initial setup tasks block of text from the Script Notes section after you have carried out the initial script setup tasks, as it no longer applies.
Any complex routines or script specific behavior which may be of assistance to any person maintaining the device scripts, should be mentioned in the Script Notes section. They should be either fully documented in the Script Notes section, or a reference made to the relevant function where they are fully documented.
--- DEVICE NOTES ---
The Device Notes section is an area where you can enter any device specific behavior or quirks which may be of assistance to any person maintaining the device scripts. An example may be: "The device you are creating the custom script for only supports SSH2".
Required functions
There are a number of functions that must exist within your device script in order for CatTools access the device and run activities.
| Function | Action |
|---|---|
|
|
Authentication to the device |
|
|
Commands to be sent after successful login to device |
|
|
To enter privileged mode |
|
|
Commands to set the environment after successfully entering enable mode |
|
|
To send necessary commands to exit or logout of the device |
The SendPost... functions do not necessarily have to contain any commands, however, the function must exist and return TRUE. Likewise, if your device does not have the concept of an Enable mode, the device script still requires the EnterEnableMode function. However, the function only needs to include a single line of code sending the return value of TRUE.
Unsupported activities
The device template file contains a number of activities functions which have a call to the internal CatTools client function cl.CatToolsNoSupport. You should call cl.CatToolsNoSupport so that a message is written to the Info Log to inform you that the activity is not supported.
Most activities only require the one line of code call to the cl.CatToolsNoSupport function. For example:
Function Activity_UpdatePassword()
Call cl.CatToolsNoSupport
End Function
Some activities also require a second line which supplies a return value to the CatTools main activity script:
Function Activity_TFTPUpload(iActionType, sTFTPServer, sTFTPFile, sResponseFile, bDoSaveToNVRAM)
Call cl.CatToolsNoSupport
Activity_TFTPUpload = "Not supported"
End Function
If you decide to add support in your custom device script for any of these activities, you need to ensure that you replace the call to the cl.CatToolsNoSupport function with your new lines of code and update the return value, if one exists.
Saving the script file
Before CatTools can access the script file you have built, you must save it to the \Scripts folder. Normally, you do not have to stop and restart CatTools in order for script file code changes to be picked up. There may be occasions during testing in which you have to restart CatTools if the changes are not recognized.
Testing your custom device scripts
After you have the scripts set, test the new device with CatTools by setting up activities using the new device.
See Testing your custom device for more information and tips.
Send us your working scripts
If you would like us to consider adding your customized device script file as a predefined device type to ship with the product, please contact us using the Technical Support form on our web site.
There are no guarantees as to when or if the device will be added to the predefined device types in CatTools, as there are a number of factors to consider, such as the number of requests for the device, complexity of the script, and technical resources available. However scripts that are sent in are cataloged for future reference.