ZipTie Developer's Guide

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.