HOWTO Script a tool

Ziptie currently supports tools written Perl. Tools written in Perl require the presence of Perl on the user's workstation to execute.

Properties File

Each tool script is accompanied by a properties file. By convention the name of this file is the same as the name of the tool, eg. ping.properties.

The following is an example properties file for a ping tool written in Perl.
01 script.name=snmpwalk.pl {device.ipAddress} {cred.roCommunity}
02 menu.label=SNMP System Info.
03 menu.tooltip=Gather SNMP information from a device
04
05 mode.supported=multi
06
07 column.0=
08 column.1=Device
09 column.2=System Description
10 column.3=System UpTime?
11 column.4=System Contact
12 column.5=System Name
13 column.6=System Location
14
15 column.0.icons=success.gif,warning.gif,error.gif
16 column.0.regex=(OK)|(WARN)|(ERROR)
17
18 column.0.resizable=false
19 column.0.align=center
20 column.0.width=20
21 column.1.width=90
22 column.2.width=300
23 column.3.width=150
24 column.4.width=100
25 column.5.width=200
26 column.6.width=100
27
28 thread.concurrency=8


Line	Explanation
1	The name of the script used to execute the tool. Additionally, you can see that some 'macro-ized' parameters are passed to the script as arguments. We'll discuss these later.
2	The name that will appear on the Tool menu.
3	The text of the tooltip that is associated with the tool.
5	Determines the mode this tool is allowed to run in. The two possible modes are 'single' and 'multi'. If the tool is a 'single' mode tool it is only allowed to run against a single device selection and typically displays multiple lines of output for a given device. If the tool is a 'multi' mode tool it can be run against a multiple device selection and displays one line of output for each device.
7-13	The names of the columns in the output table.
15	Defines icons that can appear in the specified column. This icon works in conjunction with the 'regex' attribute on line 18. Multiple icon images can be specified by separating them with a comma.
16	Defines a regular expression that will be matched against the tool output for the given column to select an icon image to display in the output table. This regular expression should be defined with multiple 'match groups', with the first match group resolving to the first image, the second match group resolving to the second image, etc.
18	Specifies that Column 0 is not resizable.
19	Defines an alignment (horizontal) for the contents of Column 0. The default is 'left', possible values are 'left', 'center', and 'right'.
20-26	Defines default column widths (in pixels). These are optional. If all of these were left off, then all columns would have equal width.
28	Specified that 8 worker threads will be used to run this tool when multiple devices are selected.

Interface

Tool scripts interact with the UI via stdout and command arguments. Command line arguments are passed in, and the tool is expected to output specially formatted data to stdout.

The input to tools comes in the form of command line arguments (ie argv). See below for more details about specifying command line arguments.

Multi-mode

A multi-mode tool is a tool that is meant to run against multiple devices, providing columnar output for the purposes of comparison across devices. These tools must be able to summarize their output in a single line of a table; as one line is given to each device. In the case of running a multi-mode tool, consider ping as an example. In the ZipTie environment, the user would click-select several IP addresses, right-click and go to Tools->Ping. At this point, the perl or python script will NOT get several IP addresses on its command line. The framework will handle that for you. The Framework will start several threads and run the proper script against a single IP, one instance per thread. When your tool script runs, it will only get one IP address.

The format of output from a multi-mode tool is a single line containing comma separated values, followed optionally by multiple lines of detail. Here is an example:

OK,10.10.3.25,64,62,4.303,17.026,38.896,14.212,0%

PING 10.10.3.25 (10.10.3.25): 56 data bytes
64 bytes from 10.10.3.25: icmp_seq=0 ttl=62 time=20.387 ms
64 bytes from 10.10.3.25: icmp_seq=1 ttl=62 time=38.896 ms
64 bytes from 10.10.3.25: icmp_seq=2 ttl=62 time=4.303 ms
64 bytes from 10.10.3.25: icmp_seq=3 ttl=62 time=4.519 ms

--- 10.10.3.25 ping statistics ---
4 packets transmitted, 4 packets received, 0% packet loss
round-trip min/avg/max/stddev = 4.303/17.026/38.896/14.212 ms

Here you can see that the ping tool output a single line of CSV corresponding to the columns defined in the ping.properties file. Next is a mandatory blank line followed with the full detail of the ping execution. This detail is displayed when a user clicks on a summary entry in the output table.

Here is an example of "multi-mode" output from the SNMP System Info tool:

Single-mode

A single-mode tool is a tool that is meant to run against only one device at a time because comparing it's values with those of other devices would be relatively meaningless. These tools should be able to provide multiple rows of identically formatted output data for a single device.

The format of output from a single-mode tool is multiple lines containing comma separated values, followed optionally by multiple lines of detail. Here is an example:

Tool Property Definitions

Tool Properties
Property	Required	Definition
column.N	yes	Defines the display name of the column. For example: column.0=IP Address
column.N.align	no	Defines the horizontal alignment of the header and the data in the cell. Possible values are: left, right, center
column.N.icons	no	Defines a comma separated list of icon images associated with the column that may appear in a cell. This property works in concert with the column.N.regex property, which selected which icon to display. For example: column.1.icons=success.gif,error.gif
column.N.regex	no	Defines a regular expression whose 'match groups' are used to select an icon for this column. The regular expression is applied to the data associated with the cell, and the index of the first match group that matches is used as the index to select the Nth icon from the icons list. For example, column.1.regex=(OK)¦(ERROR), in this case, if the data for the cell contained the text "ERROR" then the 2nd match group of the regex would match, meaning that the 2nd icon in the icons list would be selected.
column.N.resizable	no	Defines the specifed column as resizable. For example, column.4.resizable=false. By default, all columns are resizable.
column.N.width	no	Defines the default width, in pixels, of the column.
menu.label	yes	Defines the name display name of the tool that will appear on the 'Tools' menu. For example, menu.label=Traceroute
menu.tooltop	no	Defines the hover text that may appear with the tool if it resides on a toolbar. For example, menu.tooltip=Perform a traceroute operation to the specified device.
mode.supported	yes
script.enabled	no	Defines whether this tool appears in the tools menu. Useful during development to hide incomplete tools. For example, script.enabled=false
script.name	yes	Defines the name and command-line parameters of the script.
thread.conncurency	no	Defines how many threads will be used to execute the script simultaneously against devices.

Interactive Tools (Milestone 2)

While the ability to write scripts to drive tools is great and provides most of the functionality that our user's need, there are some occasions when a tool needs user input in order to collect parameters with which to run. We call these "Interactive Tools", and we've tried our hardest to allow a tool writer to solicit input without having to resort to code. A very few tools will still be beyond the scope of even this input; those tools will need to be implemented in the native tool framework (Java).

Let's take a look at an example that is in Milestone 2 of Main.ZipTie. Here is a section of the properties file for the Switch Port Mapping tool.

01 script.name=switchport.pl {input.switchIP} {input.switchSnmpCred} {input.routerIP} {input.routerSnmpCred}
02
03 input.0=switchIP
04 input.0.label=Switch IP
05 input.0.type=ipAddress
06 input.0.default={device.ipAddress}
...

Line	Explanation
1	The name of the script to run is "switchport.pl", and we've defined four Interactive inputs to solicit a switch IP, switch SNMP community string, a router IP, and a router SNMP community string.
3	Define the name of the "variable" that will store the user input. This name must match one of the "input.XYZ" fields in the script invocation defined on line 1 above.
4	Define the label of this input to be displayed in the UI when soliciting input.
5	Define the type of field the UI should display. Options currently are: ipAddress, password, text, and boolean.
6	Define a default value to populate in the control.
...	There will be three more input sections like the one above for the other three parameters.

The result of this configuration in the properties file is that when the tool is executed against a device the following UI is presented, all without writing a line of code: