The custom device type file (.ini)

Device types in CatTools

Devices types are defined within CatTools using text files (.ini files) and are stored in the \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 \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.

The .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:

[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.

[device]

name=Custom.Cisco.Router

id=4000

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.

[item] sections

Each item section defines the input fields used within the CatTools user interface for the Device setup screens.

Example:

[item_group]

name=Group

default=Default

required=1

info="The logical group that this device belongs to."

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_model]

name=Model

default=Other

required=0

info="The device model number."

list=501,515,Other

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).

[item_require_vty_login]

name=Initial login requires password

default=1

required=0

info="This device requires an initial password for access"

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 will be truncated accordingly.

The 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 \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 (as and when required) 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, take 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

If adding a new custom device type to CatTools, the first step will therefore be to take a copy of the template file Custom.Device.Template.ini in the \Templates sub folder and save it to the \Devices sub folder giving it a new file name.

This will give you a new starting point device type file to work with.  When naming the file, try to use the naming convention:

Custom.Manufacturer.Type

* It is not recommended you specify the exact Model number for the device as the Type, as you may be able to reuse your script for different models of the same Manufacturer and Type.   For example:  PIX model 501 and Cisco PIX model 515 can use a script 'Custom.Cisco.Firewall'

or  'Custom.Cisco.PIX' or even 'Custom.Cisco.FirewallPIX'.  The different Models of similar device types can be specified within the device .ini file in the [item_Model] section, or alternatively you can add the Model to the Model drop-down list field at runtime.

Note:  The Model field values in the CatTools predefined device types have no impact on the way the associated device script file (.txt) behaves.  

Although it is recommended 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.  Therefore if you need to have model specific behaviour within your custom device script, then you will need to code the device script file accordingly.

Editing the .ini file

The next step is to open the custom device .ini file and make the required changes to the values within each section.

Below is an example of an .ini file with a number of items values highlighted.

The most important item values which MUST be changed are highlighted in Red. These items must be unique otherwise your device type may not appear in the CatTools 'Device type' drop-down list field.

Items values which may be changed if desired are highlighted in Green.

Additional comments are highlighted in Blue (Note: do not include any comments in your .ini file)

It is recommended that anything else that is not highlighted be left at its original setting.

You can however, customise some of the items within a section, such as the name and info items, to make them more relevant to your device.

The text value within the name item is the field Label that is displayed within the form.

The text value within the info item is the text that is displayed in the Status bar when you select the field in the form (i.e. gets focus).

Once you have made your amendments to the .ini file, remember to save it back to the \Devices sub folder.

You will then need to restart CatTools in order for your new custom device type to be read into the 'Device type' drop-down list field.

[info]

cookie=CatTools

version=3

author=SolarWinds   enter your name or leave as the default

[device]

name=Custom.Manufacturer.Type   change to a unique name.  example: Custom.Cisco.Router   Note: do not use spaces. Use a 'period' mark (.)

id=4000   select a number within the range of 4000 to 4999.  The number used here must be unique.

# Device info

[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   add additional Model numbers 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 from the list below (if your device only uses SSH, you may want to change the default accordingly)

required=1

list=Telnet,SSH1,SSH2,SSH2-nopty,SSH1-DES,SSH1-3DES,SSH1-Blowfish,Cisco SSH   amend the list accordingly

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."

# 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"

# 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)"

# Contact info

[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"