ZipTie Content Development Guide

ZipTie utilizes a collection of technology known as adapters to interact with a variety of network devices. Adapters define the open network model (ONM) schema (data) and the management interface (behavior) of the device. An adapter must be created for each type of network device supported by ZipTie. Leveraging technologies such as Perl, XML, the Web Services Description Language (WSDL), and SOAP, the ZipTie Adapter Framework facilitates the definition, implementation, and execution of an adapter and operations for a particular set of network devices.

In this chapter you will learn what an adapter is and its anatomy, the technologies used by the ZipTie Adapter Framework, what an adapter operation is, and how an operation can be invoked and executed.

In later chapters you will learn how to leverage the Adapter Tool to build all of the components of an adapter.

An adapter is a collection of scripts (currently Perl), a metadata.xml document, a WSDL XML file, possible XSD files providing open network model extensions. All of these files together form “an adapter”. Adapters are specific to an operating system family that supports a similar set of protocols and has a similar format of responses to commands. The main job of the adapter is to drive the network protocol clients to connect to a device, issue commands, parse the responses and populate an XML document representing the complete configuration of the device.

An operation is a set of scripted device interactions. The most common operation is the backup operation where the adapter connects to the device in order to retrieve configuration information for storage on the ZipTie server.

The metadata XML file should be edited using the ZipTie Development Environment's Adapter Editor. The Metadata XML file describes the adapter metadata including the following elements:

The metadata XML file is located in the root directory for the device vendor's adapters. Device vendor may have more than one adapter, one for each operating system family. Adapters are located in the org.ziptie.adapters.perl bundle under the scripts/ZipTie/Adapters directory. The file name has the format <OS family>.metadata.xml.

The adapter ID is the name of the Perl module that contains the the operation functions defined in the operation WSDL.

The operation WSDL describes the operations supported by the adapter, for example “backup”.

An adapter is made up of at least one Perl module. That Perl module is the one designated as the adapter ID in the metadata.xml. Most likely the main adapter module will use other modules. Some of these will be part of the ZipTie project and others will be from third parties. The modules from third parties must be present in the Perl installation on a host in order for it to run the operations included in the adapter. The ZipTie modules can be devided up into two groups: OS family specific and general. The OS family specific modules are placed into a subdirectory with the same name as the OS family. General adapter modules are located in the org.ziptie.adapters bundle in the scripts/ZipTie/Adapters directory.

The ZED is an XML document describing a device configuration. The definition of the ZED is in a series of XSD documents. The complete documentation of the ZED elements can be found here.

Adapter writers should strive to write an adapter that passes the common XSD document. In some cases, a vendor may have a proprietary technology that does not fit into the standard ZED definition. In this case the schema should be extended only for that vendor. See the ZipTie Developer's Guide for more information on extending the ZED schema.

To help ease and speed up the development and implementation of adapters and adapter operation, ZipTie utilizes a collection of Perl modules that collectively make up the ZipTie Perl Adapter SDK. The Perl modules that are part of the ZipTie Perl Adapter SDK provide functionality for a variety of tasks, such as: a common interface for CLI (command-line interface) protocols to interact with network devices over, recording device interactions, parsing the input XML for adapter operations into relevant Perl objects, and much more. In this section, you will learn what the ZipTie Perl Adapter SDK is, the benefits of using it over writing home-grown solutions, what Perl modules are included with it and the functionality those modules provide.

The SDK lives in the org.ziptie.adapters bundle, which is also included with the Adapter Tool. The full documentation of the SDK modules can be found at http://dev.ziptie.org/docs/perldoc/index.htm

In the previous chapter you learned the specifics of the ZipTie adapter technology. In this chapter, you will learn how to create all of the adapter components using the Adapter Tool.

The ZipTie Adapter Tool is command line interface that enables the development of ZipTie adapters. The Adapter Tool comes complete with the adapter SDK bundle detailed in the previous chapter. This bundle includes all of the standard ZipTie adapter modules as well as the ZipTie element document (ZED) XML schema documents.

This document frequently refers to modules in the Adapter SDK. Refer to the PerlDoc documentation of these modules for complete details. The PerlDoc can be found here.

The Adapter Tool requires a Perl installation. It has been tested with Perl 5.8.8 and later, but may work with previous versions. If you do not already have a Perl distribution, the following is a list of recommended Perl distributions:

• ActiveState Perl
• CPAN Binary Distributions

There are also several required Perl modules that are outside of the standard Perl distribution. Use your respective Perl module installation manager to install the modules listed in the latest revision of the perlcheck.pl file found here. For example, ActiveState Perl users can use:

  ppm install XML-Simple 

While CPAN distributions can use the command:

  cpan install XML::Simple

Start by downloading the Adapter Tool archive from here.

Unzip the archive into a directory. Within the directory there is a script called adapterTool.bat (adapterTool on Linux and Mac OS X). For a brief usage description you can execute this with the –help switch:

  C:\AdapterTool> adapterTool --help

AdapterTool includes a TFTP server and FTP server just as ZipTie itself does. The servers will attach to high ports (11069 and 11021) rather than the well known ports. On Linux, you can use iptables to redirect inbound udp/69 and tcp/21 to the high ports. See the zserver script for an example of how the ZipTie server does this port redirection.

On Windows or if you are running as root on Linux you can simply bind to the well known ports. To do so edit the tftp.properties and ftpd.properties files found in your AdapterTool/conf directory.

In this example you will create an adapter for a Nortel Passport switch that will communicate with devices only via Telnet. Upon completion, our adapter will have a backup operation that produces a ZipTie Element Document (ZED) that can be consumed by the ZipTie application.

The Adapter Tool has a wizard that creates all of the pieces necessary for a full adapter. To create the new adapter execute the adapterTool script with the –script switch. This will start a wizard that will walk you through the process of creating a new adapter.

  C:\AdapterTool> adapterTool.bat --create

If you have never run the Adapter Tool before you will be promted to specify a directory that contains your ZipTie adapters. If you have the ZipTie server installed this would be the directory core/ in the install. If you have the ZipTie source checked out, this directory would be your workspace root. In this example we will assume that the ZipTie server is installed to C:\Program Files\ZipTie Server so the adapters directory would be C:\Program Files\ZipTie Server\core

This appears to be the first time the adapter tool has been run. Specify the adapters directory: C:\Program Files\ZipTie Server\core

You will then be prompted for the following basic metadata about the device.

Here is output from our sample adapter creation:

  Adapter ID: ZipTie::Adapters::Nortel::Passport
  Adapter bundle [ziptie.adapters.nortel.passport]:
  Short name: Nortel Passport
  Description: Nortel Passport Switches

The following files are created upon completion of the wizard. In the subsequent steps, you will be filling out the contents of these files for our specific device.

• Passport.metadata.xml - see the Adapter Technology Section
• Passport.wsdl - see the Adapter Technology Section
• Passport.pm - The main package Perl module. This contains the “backup” method that the application expects.
• Passport/AutoLogin.pm - The command line login sequence is handled in this module. Other modules from the tools framework are free to use this sequence of commands.
• Passport/Parsers.pm - All parsing from the devices command line into the ZED XML should be handled in this module.
• Passport/GetConfig.pm - this module is optional but almost required in all adapters. It downloads configuration file(s) from the device.

Now that you have created the shell of the adapter you can use Adapter Tool to debug it. Simply run the adapterTool program and follow the prompts to choose a device and adapter to test against. Upon completion, the product of your adapter, which is the ZiptieElementDocument (ZED), will be validated against the ZipTie schema documents.

ZipTie adapters produce an XML document upon completion of their backup operation. This XML document is the ZiptieElementDocument (ZED). This document is also often referred to as the “model”.

This chapter describes the process by which to extend the ZED when the provided definitions are not enough.

AlterPoint leverages a large body of work in the area of resource modeling and representational systems by adopting a Standard Metalanguage (SML) based approach. SML defines a general resource model as a representation of the people, equipment, or material needed to perform a project or a task, and defines their relationships. By leveraging this definition, the ZipTie framework defines an open network model (ONM) as a set of data elements that are required to perform network configuration. Any internal data, protocol data, and/or monitoring data that are not used in performing network configuration lie outside the scope of AlterPoint’s definition. This boundary, however, may blur in some cases because some operational data specifies configuration. This SML vocabulary is specific to configuring networks. AlterPoint leverages existing vocabularies for general data types in order to maximize interoperability.

ZipTie provides an extensive version of the ZED inside of the ziptie-common.xsd schema, with the root element being the common:ZiptieElementDocument. But say a vendor invents a feature and a user needs to backup the configuration details of this newly invented feature. Then what should be done? The answer is that a vendor-specific ZED extension should be made that substitutes or extends attributes as needed.

The following sections provide a tutorial for creating your own extensions to the open network model.

Initech Inc. is a corporation that produces manageable switches. Initech wants to provide ZipTie to its customers, but first needs to write an adapter for their switches. The common ZED hits 95% of Initech's use cases. The only thing missing is that Initech sells environment monitoring cards for their switches and customers would like to know the following configuration items.

• Maximum temperature
• Maximum humidity level

To accomplish backing up these hardware configuration attributes the Initech adapter writer will extend the ZED. They will first add a new section to the Card element that will indicate whether a card is an environment monitor card. They will then add a top level section to the ZED for the configruation items above.

First, the adapter writer creates a new XSD in the same location as the ziptie-common.xsd schema document called initech.xsd. The opening section of this document is shown below. Notice the new initech namespace defined and the other namespaces imported.

        <schema xmlns="http://www.w3.org/2001/XMLSchema"
              targetNamespace="http://www.ziptie.org/model/initech/1.0"
              xmlns:initech="http://www.ziptie.org/model/initech/1.0"
              xmlns:dt="http://www.ziptie.org/model/netconftypes/1.0"
              xmlns:common="http://www.ziptie.org/model/common/1.0"
              xmlns:core="http://www.ziptie.org/model/core/1.0" elementFormDefault="qualified">
        
              <import namespace="http://www.ziptie.org/model/netconftypes/1.0" schemaLocation="netconftypes.xsd"/>
              <import namespace="http://www.ziptie.org/model/core/1.0" schemaLocation="ziptie-core.xsd"/>
              <import namespace="http://www.ziptie.org/model/common/1.0" schemaLocation="ziptie-common.xsd"/>

The first thing to do is add a boolean attribute to the Card element to indicate whether a card is capable of monitoring enviromental conditions. Do this by extending the common:Card complexType found in the ziptie-common.xsd.

        <complexType name="InitechCard">
           <complexContent>
            <extension base="common:Card">
              <sequence>
                <element name="envMonitor" type="boolean" minOccurs="0" maxOccurs="1"/>
              </sequence>
            </extension>
           </complexContent>
        </complexType>

Extension of the card is not enough. You must provide the new Initech card definition as a substitute for the common:card element in the common model.

        <element name="card" type="initech:InitechCard" substitutionGroup="common:card"/>

That takes care of the extra card element. Now you need to add the temperature and humidity configuration items to the ZED. First, create the new complexType

        <complexType name="Environmental">
          <all>
            <element name="maxHumidity" type="int" minOccurs="1" maxOccurs="1"/>
            <element name="maxTemp" type="int" minOccurs="1" maxOccurs="1"/>
          </all>
        </complexType>

Next, extend the common:ZiptieElementDocument by adding the new element.

        <complexType name="InitechZED">
          <complexContent>
            <extension base="common:ZiptieElementDocument">
              <sequence>
                <element name="environmental" type="initech:Environmental" minOccurs="0" maxOccurs="1"/>
              </sequence>
            </extension>
          </complexContent>
        </complexType> 

Lastly, substitue the new ZED for the common one, since you added a new element directly under the root.

        <element name="ZiptieElementDocument" type="initech:InitechZED" substitutionGroup="common:ZiptieElementDocument"/>

The XSD is complete.

Below is the end instance document for the ZED that you will end up producing.

        
      <initech:ZiptieElementDocument
              xmlns="http://www.ziptie.org/model/common/1.0"
              xmlns:initech="http://www.ziptie.org/model/initech/1.0"
              xmlns:core="http://www.ziptie.org/model/core/1.0"
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              xsi:schemaLocation="http://www.ziptie.org/model/initech/1.0 initech.xsd
                        http://www.ziptie.org/model/core/1.0 ziptie-core.xsd
                        http://www.ziptie.org/model/common/1.0 ziptie-common.xsd>
      
      .....
      
      <chassis>
      
      .....
      
        <initech:card>
          <core:asset>
            <core:assetType>Card</core:assetType>
            <core:description>ENV Card 123</core:description>
            <core:factoryinfo>
              <core:hardwareVersion>1.8</core:hardwareVersion>
              <core:partNumber>P12345</core:partNumber>
              <core:serialNumber>SN0008234</core:serialNumber>
            </core:factoryinfo>
          </core:asset>
          <slotNumber>0</slotNumber>
          <initech:envMonitor>true</initech:envMonitor>
        </initech:card>
        
      .....
      
      </chassis>
      
      .....
      
      <initech:environmental>
         <initech:maxHumidity>80</initech:maxHumidity>
         <initech:maxTemp>38</initech:maxTemp>
      </initech:environmental>
      
      .....
      
      </initech:ZiptieElementDocument>

The following sections describe some guidelines to consider when creating a model extension.

'Redefine' is explicitly forbidden by SML and other XSD applications that simultaneously process multiple documents. 'Redefine' the meaning of a type, and the redefined type is in the same namespace as the original. Now imagine trying to process documents A and B that are interrelated somehow; A uses type X, B uses type X which is a redefined X. The processor cannot tell X from X, because they are in the same namespace.

In complex type declarations, move subelements that you expect people to want to extend into global element declarations, and reference them from inside the type. This allows substitution of just that element, instead of the entire containing type. Thus, types that use <element ref=“XXX”/> in their definitions are more open, because they are easier to extend.

If you look at how restriction works in XSD, you basically have to redeclare the base type, but you must retain compatible, though more restricted, element declarations. The end result will be a wordy and more fragile type system, where any change to the base type has to be propagated to restricting types for them to remain compatible.

When you extend or restrict a type and declare a substitionGroup element for it in a NEP namespace, use the same element name as is declared in core or common. For example, if you make a Cisco-specific interfaceEthernet substitution, name it “interfaceEthernet”, not ciscoEtherNet or something else. The namespace will differ but the “local” part of the name should be the same.

If you expect to contribute an adapter and a schema, be sure to put documentation elements inside each new definition.

        <annotation>
          <documentation>Explain this element here.</documentation>
        </annotation>

ZipTie contains a number of built-in tools that are based on the ZipTie Script Tools Framework (STF). The STF is itself based on the ZipTie Java Tools Framework (JTF). The purpose of the STF is to simplify the creation of tools for use within ZipTie by providing configuration by convention and the use of a common high-level scripting language (Perl) that network engineers and developers alike are familiar with. In this chapter, you will learn about the anatomy of a scripted tool, the various kinds of supported results display, and how to create more powerful tools through interactive input.

Tools based on the STF are first-class tools, peers of native tools written in the Java Tools Framework, and therefore appear in the primary tools menu within the ZipTie user interface.

A scripted tool contains two principal components: a perl script and a properties file. The properties file describes metadata about the tool itself including: invocation format, display name and description, output table definition, interactive inputs (if any), and threading behavior. By convention the name of the script and the name of the properties file are the same, for example ping.properties and ping.pl, but this is only convention and tool writers can choose to make them different as the properties file references the script file by name.

Scripted tools reside in the scripts folder within the org.ziptie.core.scripttools plugin. The full relative path from the ZipTie installation is ziptie/plugins/org.ziptie.core.scripttools/scripts. It is in this directory that both the Perl scripts and their associated properties files reside. A properly formatted properties file and tool script dropped into this directory will automatically appear on the tools menu within ZipTie. For a new tool, the server and client must be restarted before the tool will appear. Changes made to scripts or in this directory are also picked up immediately by ZipTie making the task of developing, debugging, and testing a tool much easier.

The simplest way to introduce a properties file is to look at an concrete example. The properties file presented below is the actual snmp.properties file for the SNMP System Info tool as it exists at the time of this writing. All of the properties will be explained in greater detail in the coming sections in this chapter.

  script.name=snmpwalk.pl {device.ipAddress} {cred.roCommunity}
  menu.label=SNMP System Info.
  menu.tooltip=Gather SNMP Information from a device
  
  mode.supported=multi
  
  column.0=                                                      
  column.1=Device
  column.2=System Description
  column.3=System Uptime
  column.4=System Contact
  column.5=System Name
  column.6=System Location
  
  column.0.icons=success.gif,warning.gif,error.gif                
  column.0.regex=(OK)|(WARN)|(ERROR)                              
  
  column.0.resizable=false                                        
  column.0.align=center
  column.0.width=20
  column.1.width=90
  column.2.width=300
  column.3.width=150
  column.4.width=100
  column.5.width=200
  column.6.width=100
  
  thread.concurrency=8                                            

This is an explanation of the properties file listing above.

Script tools interact with ZipTie via command arguments (input) and stdout (output). Command arguments are passed in as per their definition in the script.name property, and the script is expected to output specially formatted data to stdout. The form of the output varies depending upon the 'mode' that the tool is defined to support via the mode.supported property. The two currently supported modes are 'multi' and 'single' and are described in the following two sections.

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 row of a table; as one row is given to each device. In the case of running a multi-mode tool, consider the SNMP System Info tool as an example. In the ZipTie environment, the user would select several IP addresses, right-click and pick SNMP System Info from the Tools sub-menu. The perl script will not get several IP addresses as command-line parameters, but instead STF will invoke the script once per device. The script will be invoked with the input arguments just as declared in the properties file, which in the case of SNMP System Info is simply the IP address of a device. STF will actually start several threads and run the script against a single IP, one instance per thread. The script doesn't need care whether the tool was selected to run against one device or one hundred devices, its input and output will be the same.

The format of output from a multi-mode tool is a single line of comma separated values (CSV), followed by a blank line, followed by multiple lines of detail. Looking at just the column definitions from the snmpwalk.properties file these are the columns that are defined:

column.0=
column.1=Device
column.2=System Description
column.3=System Uptime
column.4=System Contact
column.5=System Name
column.6=System Location

Therefore, the tool must output a single line of CSV where each column is accounted for, followed by detailed output that is associated with that information. Often that is just the raw output of some command that was parsed to generate the CSV. Here is some example output from the SNMP System Info tool:

OK,10.100.22.6,"Cisco Systems WS-C292","45 days, 3:33:12.84","XXX","cisco2621.ziptie.org","ziptie"
    
SNMPv2-MIB::sysDescr.0 = STRING: Cisco Systems WS-C292 
IOS (tm) C2600 Software (C2600-I-M), Version 12.2(12e), RELEASE SOFTWARE (fc2)
Copyright (c) 1986-2003 by cisco Systems, Inc.
Compiled Mon 12-May-03 14:42 by pwade
SNMPv2-MIB::sysObjectID.0 = OID: SNMPv2-SMI::enterprises.9.1.209
SNMPv2-MIB::sysUpTime.0 = Timeticks: (390079284) 45 days, 3:33:12.84
SNMPv2-MIB::sysContact.0 = STRING: XXX
SNMPv2-MIB::sysName.0 = STRING: cisco2621.ziptie.org
SNMPv2-MIB::sysLocation.0 = STRING: ziptie
SNMPv2-MIB::sysServices.0 = INTEGER: 78
SNMPv2-MIB::sysORLastChange.0 = Timeticks: (0) 0:00:00.00

You can see that the Ping tool output a single line of CSV corresponding to the columns defined in the snmpwalk.properties file. Column 0 had a value of 'OK', column 1 had a value of '10.100.22.6', column 2 had a value of 'Cisco Internetwork Operating System Software ', etc. Following the line of CSV is a mandatory blank line, and then the full detail of the raw SNMP data from which the CSV output was generated. This detail is displayed when a user clicks on a summary entry (generated by the CSV) in the output table as seen in this example:

A single-mode tool is a tool that is meant to run against a single selected device. Exactly one invocation of the tool script is made to gather the output for display. These tools can produce multiple lines of output for the selected device. In the case of running a single-mode tool, consider the Traceroute tool as an example. In the ZipTie environment, the user would select a single device, right-click and pick Traceroute from the Tools sub-menu. The tool script will be invoked with the input substitution parameters specified in the properties file. As in the case of the SNMP System Info tool, the Traceroute tool (and any single-mode tool) produces CSV output matching the columns defined in the properties file. However, unlike a multi-mode tool, a single-mode tool may produce one or more lines of CSV output for the selected device. And like a multi-mode tool, this CSV output can then be followed by a blank line and then detailed output. However, unlike the multi-mode tool this detailed output applies to the entire output of the tool and not to a specific row that is selected in the output table.

The following output is an example of output from the Perl script that implements the Traceroute tool:

OK,1,core.ziptie.org,10.10.1.1,2.407,0.720,0.730
OK,2,labcore.ziptie.org,10.10.30.2,0.502,0.508,0.478
OK,3,cisco3640.ziptie.org,10.100.22.15,2.130,*,2.185,

traceroute to 10.100.22.15 (10.100.22.15), 16 hops max, 40 byte packets
1  corp-core.inside.eclyptic.com (10.10.1.1)  2.407 ms  0.720 ms  0.730 ms
2  labcore.inside.eclyptic.com (10.10.30.2)  0.502 ms  0.508 ms  0.478 ms
3  cisco3640.inside.eclyptic.com (10.100.22.15)  2.130 ms *  2.185 ms

You can see in this example output that the Traceroute tool produces three lines of CSV which correspond to the three hops the in the detailed output, whose content follows the CSV after the required blank line.

A combined-mode tool is a tool that is run against one or more devices, but that only has a single invocation of the script. This is in contrast to the single-mode and multi-mode tools in which the tool script is run once per each selected device. Combined-mode is not of much utility without having information about the selected list of devices as input parameters and to this end the framework provides a flexible way of getting this information. The STF provides for a property named devices.selected that can contain the same input substitution parameters as used in the script.name property. The devices.selected property can then be referred to in the script.name entry and its value is expanded for each selected device before before being supplied as an input parameter. Perhaps looking at an example will provide clarification:

script.name=vlan_membership.pl {input.vlan} {devices.selected} 
devices.selected={device.ipAddress} {device.osType} {cred.username} {cred.password} {cred.enablePassword}
menu.label=VLAN Member Ports
menu.tooltip=Shows Cisco VLAN member ports.

input.0=vlan
input.0.label=VLAN ID
input.0.type=string
input.0.default=1

column.0=Device
column.0.width=200
column.1=Port

mode.supported=combined

This example is from the VLAN Member Ports tool. Without getting to far ahead in discussing interactive tool inputs (see the next section on “Interactive Tools”), you can see that the script.name property defines two inputs: an interactive input ({input.vlan}) and the aforementioned devices.selected property. The devices.selected property is defined to expand the IP address, OS type, username, password, and “enable” password for a device. The devices.selected definition will be expanded for every selected device, and then the concatenation of that expansion supplied as input to the vlan_membership.pl script. If the user selected 2 devices then the vlan_membership.pl script would be passed 1) the interactive input.vlan parameter, and 2) the IP address, OS type, username, etc. for the first selected device followed by the IP address, OS type, username, etc. of the second device. If hundreds of devices were selected, there would be thousands of input parameters to the script which should be designed to process each set of input parameters supplied.

ZipTie STF supports the concept of an interactive tool. An interactive tool is one which defines one or more input parameters which should be provided interactively by the user when running the tool. Outside of the scope of this chapter but worth mentioning is that the types of input can be expanded through the use of the JTF from the ones that ZipTie inherently provides. Let's look at an example of an interactive tool and the types of inputs available to you. This example is from the Switch port/IP mapping tool.

script.name=switchport.pl {input.switchIP} {input.switchSnmpCred} {input.routerIP} {input.routerSnmpCred}
menu.label=Switch port/IP mapping
menu.tooltip=Perform a mapping of IP Address to switch port

input.0=switchIP
input.0.label=Switch IP
input.0.type=ipAddress
input.0.default={device.ipAddress}

input.1=switchSnmpCred
input.1.label=Switch SNMP Community
input.1.type=password
input.1.default={cred.roCommunityString}

input.2=routerIP
input.2.label=Router IP
input.2.type=ipAddress
input.2.default={device.ipAddress}

input.3=routerSnmpCred
input.3.label=Router SNMP Community
input.3.type=password
input.3.default={cred.roCommunityString}

You can see above that four inputs are defined, input.0, input.1, input.2, and input.3. The numbers appended to the input. property must begin at zero (0) and increase by one for each subsequent input defined. Examining an individual input definition we see the following:

input.0=switchIP                               
input.0.label=Switch IP                        
input.0.type=ipAddress                         
input.0.default={device.ipAddress}             

Here is a line-by-line explanation of this definition:

When this tool is executed by the user, ZipTie examines the properties of the tool and based on any inputs defined therein constructs a dialog dynamically with the appropriate controls. The Switch port/IP mapping tool therefore presents the following dialog:

An interactive tool might require the location of a file to be one of its inputs. Rather than forcing a user of the tool to manually type in the location of this file, the toolStoreBrowser input parameter can be used to define a file browser dialog that can browse the entire directory structure of the tool store on the ZipTie Server.

The tool store refers to a directory that exists on the ZipTie Server that is used to house files and directories to be used by script tools. By default, the tool store directory is configured to be the tool-file-store directory located in the base directory of the ZipTie Server installation. This directory will be created upon server startup if it does not exist. The tool store can reference a different directory by setting the tool.file.store environment variable/system property to refer to some other directory. It is assumed that this directory is relative to the base directory of the ZipTie Server installation and will be created on server startup if it does not exist.

It is simple to incorporate a file browser dialog of the tool store location into an interactive script tool; the following is code snippet of how this can be done:

input.0=specifiedFile
input.0.label=Select a file to use with the tool ...
input.0.type=toolStoreBrowser

Here is a line-by-line explanation of what these properties do:

Here is an example of what the initial tool store file browser looks like in the ZipTie Client (note that in the first image, the value of the input.0.label property is used):

Here is an example of the actual tool store file browser:

The ZipTie STF work allows for powerful tools to be written, but it may be the case where a tool is written for a specific type of device and is not meant to be used generically by any other type of device. Fortunately, the ZipTie STF provides a simple yet powerful property that can be specified within the properties file of a script tool called enable.filter.

The enable.filter property lets the author of a tool to specify certain requirements for a tool to be enabled based on an LDAP-type filter string (refer to RFC 2254 for information on LDAP filter strings). Using an LDAP-type filter string allows for logical operators to be performed on one or many macro-ized script tool parameters to ensure that the tool should be enabled for use.

Let's take a look at the enable.filter property for the IOS Password Change tool:

enable.filter=(device.osType=ZipTie::Adapters::Cisco::IOS)

In this example, the tool is specifying that it only wants to be enabled if the device adapter associated with the device is ZipTie::Adapters::Cisco::IOS. This is made possible by combining the power of an LDAP filter with the macro-ized parameters supported by the ZipTie STF. Essentially, a macro-ized parameter is a parameter that will be evaluated by the STF and replaced with its actual value. Here is a list of all the macro-ized parameters that the ZipTie STF supports:

Please note that if the enable.filter string is not specified or is empty that the script tool will be available for all devices to use.