Define Kiwi CatTools custom device type using .ini file
Devices types are defined within CatTools using text (.ini
) files. They are stored in the \Program Files (x86)\CatTools3\Devices
sub folder within the root CatTools directory. Each .ini
file represents a separate item in the Device type
drop-down list field in the Device information setup form.
When CatTools starts, it searches for all the .ini
files in the \Program Files (x86)\CatTools3\Devices
sub folder and reads their contents. All the device types found are then available for selection in the Device type drop-down list when defining devices.
To add a new custom device type, you need to create a new .ini
file defining the device and its characteristics.
.ini file sections overview
The contents of an .ini
file are divided up within [...]
sections. The main sections inside an .ini
file are as follows:
Section | Description | Example |
---|---|---|
[info] section | This is required and identifies the .ini file as a CatTools file. |
[info] cookie=CatTools version=3 author=SolarWinds |
[device] section |
This is required and defines the name used within the CatTools user interface (i.e. the Device type drop-down list field) and within scripting. It also defines the unique key (id) of the device type in the CatTools database. Although the file name of the .ini file may be similar (or the same) to the [device] section name item, it is the name item that defines the device name within the user interface and not the .ini file name. CatTools reserves id's from 0 to 3999 for predefined device types. You can use the number range from 4000 to 4999 for the custom device types you create, however you must ensure the number is unique. |
[device] name=Custom.Cisco.Router id=4000 |
[item] sections |
Each item section defines the input fields used within the CatTools user interface for the Device setup screens. Each input field in the CatTools user interface has a separate [item_xxx] type section. The name item sets the text (or label) to be displayed next to the input or selection field. The default item sets the default value to be used when adding a new device to the database. The required item tells the user interface if the field must contain valid data or not (for example: must be an item from within a predefined list or whether the user can enter their own values). 0=not required, 1=required. The info item is the description associated with this field. This text is displayed in the status bar of the user interface when a field has focus. The above [item_group] section is an example of a standard text box input field within the user interface. When the input field is to be a list box, you need to define the list box contents using a list item within the item section (see below). |
[item_group] name=Group default=Default required=1 info="The logical group that this device belongs to." |
[item_model] |
The list item contains a comma delimited string of items to populate the list box with. The default field specifies which item from the list to show as the default when adding a new device. Check box input fields can only accept values of 0 or 1. Any value other than a 1 is considered a 0. A check box example is below. The check box is defaulted to 1 (checked). |
name=Model default=Other required=0 info="The device model number." list=501,515,Other |
[item_require_vty_login] | The size (length of the data that can be entered) of each field is determined by the design of the CatTools database. Any data entered via the CatTools user interface that is too long for the field is truncated accordingly. |
name=Initial login requires password default=1 required=0 info="This device requires an initial password for access" |
Custom device type .ini template
CatTools provides a starting point template file to help assist in the creation of a new custom device type. The template file is called Custom.Device.Template.ini
and can be found in the \Program Files (x86)\CatTools3\Templates
sub folder. This template file is included as part of the predefined device types in CatTools.
As for all of the CatTools predefined device types, it may be subject to updates and modifications with each new release of the CatTools product. For this reason, you should never modify the template file itself in order to create a new custom device type.
If you need to create a new custom device type, make a copy the template file and save it to the \Devices
sub folder, giving it a new file name.
Creating your custom device type .ini file
When adding a new custom device type to CatTools, the first step is to make a copy of the template file Custom.Device.Template.ini
in the \Templates
sub folder and save it to the \Devices
sub folder with a new file name. This gives you a new starting point device type file to work with. When naming the file, use the naming convention: Custom.Manufacturer.Type
|
Use the text "Custom" to distinguish between custom device types and CatTools predefined types. Custom devices are also grouped together in the Device type drop-down list field |
|
The manufacturer or supplier of the device. For example, Cisco, Nortel, 3Com, Juniper, Foundry, and so on. |
|
The type of device added, such as a router, switch, or firewall. SolarWinds does not recommend using the exact model number for the device as Different models of similar device types can be specified within the device |
The Model field values in the CatTools predefined device types have no impact on the way the associated device script file (.txt) behaves.
Although SolarWinds recommends you follow this naming standard, the idea of the custom device script file is to give the user as much flexibility as possible while remaining within the limits of the application. If you need to have model specific behavior within your custom device script, you need to code the device script file accordingly.
Editing the .ini file
Open the custom device .ini file to make the required changes to the values within each section.
The custom .ini file contains a number of items values highlighted for emphasis. SolarWinds recommends that any values that are not highlighted be left at its original setting.
Highlight Color | Meaning |
---|---|
Red | The most important item values which must be changed are highlighted in red. These values must be unique otherwise your device type may not appear in the CatTools Device type drop-down list field. |
Green | Items values which may be changed if desired are highlighted in green. |
Blue |
Additional comments are highlighted in blue. Do not include any additional comments in your |
You can customize some of the items within a section, such as the name and info items, to make them more relevant to your device.
- Name item: the field label that is displayed within the form.
- Info item: the text that is displayed in the status bar when you select the field in the form.
After you have made your amendments to the .ini
file, save it back to the \Devices
sub folder. Restart CatTools for your new custom device type to be available in the Device type drop-down list field.
Default values
[info]
- cookie=
CatTools
- version=
3
- author=
SolarWinds
Enter your name or leave as the default value.
[device]
- name=
Custom.Manufacturer.Type
Change to a unique name. For example:
Custom.Cisco.Router
Do not use spaces. Use a period (.) instead.
- id=
4000
Select a number within the range of 4000 to 4999. The number used must be unique.
Device information
[item_Group]
name=Group
default=Default
Enter a default Group for the device or leave as the default.
required=1
info="The logical group that this device belongs to."
[item_Name]
name=Name
default=Unique device name
Enter a unique device name.
required=1
info="A unique name for this device. e.g. sales-router or head-office-3500."
[item_HostAddress]
name=Host Address
default=127.0.0.1
required=1
info="IP address or host name of the device."
[item_Filename]
name=File Name
default=
required=1
info="The base file name to use for this device (unique)."
[item_Model]
name=Model
default=Custom
Enter a default
Model
to use from the list below or leave as the default.required=0
info="The device model number."
list=Custom
Additional
Model
numbers must be separated by commas. For example:Custom,501,515
[item_ConnectVia]
name=Connect via
default=Direct connect
required=1
info="The name of another device to connect to first."
[item_Telnet]
name=Method
default=Telnet
Enter a default
Method
to use fromlist
below. If your device only uses SSH, change the default accordingly.required=1
list=Telnet,SSH1,SSH2,SSH2-nopty,SSH1-DES,SSH1-3DES,SSH1-Blowfish,Cisco SSH
Amend
list
accordingly for the device's available connection methods.info="Connection method to use."
[item_TelnetPort]
name=Port
default=23
Enter a default port from the list below. Port field value automatically changes when Method field is changed in the user interface.
required=1
list=23,22
info="Port number to use."
Device passwords
[item_VTYPass]
name=VTY Password
default=
required=0
info="VTY password."
[item_EnablePass]
name=Enable Password
default=
required=0
info="Enable or privilege password."
[item_PrivilegeLevel]
name=Privilege Level
default=
required=0
info="Sets the enable mode privilege level. (Not required in most cases)"
[item_ConsolePass]
name=Console Password
default=
required=0
info="The console (com port connection) password."
[item_AAAUsername]
name=Username
default=
required=0
info="AAA/TACACS/RADIUS/Local username."
[item_AAAPassword]
name=Password
default=
required=0
info="AAA/TACACS/RADIUS/Local password."
[item_SSHPassword]
name=SSH Password
default=
required=0
info="SSH password."
[item_SSHUsername]
name=SSH Username
default=
required=0
info="SSH username."
[item_SNMPRead]
name=SNMP Read
default=
required=0
info="SNMP Read community name."
[item_SNMPWrite]
name=SNMP Write
default=
required=0
info="SNMP Write community name."
[item_RequireVTYLogin]
name=Initial login requires password
default=1
required=0
info="This device requires an initial password for access"
[item_LoginUsesAAA]
name=Initial login requires username/password
default=0
required=0
info="The initial access requires a username and password"
[item_EnableUsesAAA]
name=Enable mode requires username/password
default=0
required=0
info="Enable mode access requires a username and password"
Device Prompts
[item_VTYPrompt]
name=VTY Prompt
info="Expected VTY prompt from the device. (Only required if non standard prompt is used)"
[item_EnablePrompt]
name=Enable Prompt
info="Expected enable mode prompt from the device. (Only required if non standard prompt is used)"
[item_ConsolePrompt]
name=Console Prompt
info="Expected console prompt from the device. (Only required if non standard prompt is used)"
[item_AAAUserPrompt]
name=Username prompt
info="Expected Username prompt from the device or AAA server. (Only required if non standard prompt is used)"
[item_AAAPassPrompt]
name=Password prompt
info="Expected AAA Password prompt from the device or AAA server. (Only required if non standard prompt is used)"
Device contact information
[item_Address1]
name=Address1
default=
required=0
info="Location of the device"
[item_Address2]
name=Address2
default=
required=0
info="Location of the device"
[item_Address3]
name=Address3
default=
required=0
info="Location of the device"
[item_ContactName]
name=Contact Name
default=
required=0
info="The name of the person responsible for this device."
[item_ContactPhone]
name=Contact Phone
default=
required=0
info="How to contact the person responsible for this device"
[item_ContactEmail]
name=Contact E-mail
default=
required=0
info="How to contact the person responsible for this device"
[item_ContactOther]
name=Contact Other
default=
required=0
info="Any additional contact info"
[item_AlertEmail]
name=Alert e-mail
default=
required=0
info="Who to notify by e-mail of any alarms or alerts for this device"
[item_SerialNumber]
name=Serial number
default=
required=0
info="The serial number of this device"
[item_AssetTag]
name=Asset Tag
default=
required=0
info="Asset tag information"
[item_Identification]
name=Identification
default=
required=0
info="Identification info for this device"
[item_SerialOther]
name=Other info
default=
required=0
info="Any other serial number information"
[item_ActivitySpecific1]
name=Activity Specific1
default=
required=0
info="Information specific to a particular activity"
[item_ActivitySpecific2]
name=Activity Specific2
default=
required=0
info="Information specific to a particular activity"