Documentation forKiwi CatTools

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

Custom

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

Manufacturer

The manufacturer or supplier of the device. For example, Cisco, Nortel, 3Com, Juniper, Foundry, and so on.

Type

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 Type, as you can reuse your custom script for different models of the same Manufacturer and Type. For example: PIX model 501 and Cisco PIX model 515 can use the script Custom.Cisco.Firewall or Custom.Cisco.PIX.

Different models of similar device types can be specified within the device .ini file in the [item_Model] section. Alternatively you can add the model to the model drop-down list field at runtime.

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 .ini file

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 from list 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"