The custom device type file (.ini)

Previous  Top  Next

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=Kiwi CatTools

version=3

author=Kiwi Enterprises

[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

Custom being the text "Custom" to distinguish custom device types from CatTools predefined types. They will also be grouped together in the 'Device type' drop-down list field Manufacturer the manufacturer or supplier of the device (Cisco, Nortel, 3Com, Juniper, Foundry, Enterasys, etc.) Type the type of device (router, switch, firewall, etc.)*

* 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=Kiwi CatTools
version=3
author=Kiwi Enterprises 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_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"