Connection Path for Adapter Operations

For the majority of ZipTie^? adapter operations, there is the notion that the operation must be able to connect to and authenticate with a desired network device. The information needed to perform these steps can typically be encapsulated into a hostname or IP address, the various protocols that are to be used to connect to the device, and any credentials that may be used by these protocols to authenticate with the device. There is also the need to expose information regarding various file servers, such as a TFTP or FTP server, which the device in question might need to communicate with.

While it may be easy to encapsulate all of this information within the Java API for ZipTie^?, there needs to be an XML structure that can be used to pass this crucial information between the Java-side of ZipTie^? to the Perl-based device adapters that perform the actual adapter operations themselves. By leveraging the power of XML schema and generating SOAP-compatible Java objects from it, this information can be used by web services to provide an easy and portable representation of this vital data.

What Is A Connection Path

A Connection Path is a way of defining all of the information required for connecting to a device; it is called a Connection Path because a path of nodes are used to make a connection to a desired device. Each node on the Connection Path represents a connection and authentication with a device before continuing on. A single node on a Connection Path can hold the following information:

• A hostname or IP address for a device.
• A set of device credentials for the device.
• A set of network protocols to use to connect to the device and that may be used by that device to connect to other devices.
• A set of metadata containers to provide information about external file servers, such as TFTP or FTP server.
• Any number of other Connection path nodes that should be traveled to after this Connection Path node.

Sometimes when connecting to a device, there may be multiple nodes to navigate before connecting with the desired device. These nodes are other network devices that usually require their own connection and authentication data. This ultimately means that a Connection Path represents all of the data for each node in a path to get the the desired device. In practice, most connection paths will only have to deal with one device, so there is no need for this multiple node concept. However, a Connection Path can contain one or more Connection Paths itself. This means that for each node in the Connection Path, you can have any number of other possible Connection Path nodes to travel to, depending on which nodes on the Connection Path need to be connected and authenticated with before continuing on. This is most likely to be the case when dealing with Jumphost technology.

types.xsd XML Schema for Defining Connection Path and Associated Types

The types.xsd (which lives in the org.ziptie.adapters bundle) XML schema file defines various types that can be used within XML documents to store particular types of information. This allows for a central location to modify and maintain any XML types that are used by XML documents. The majority of the types specified with in the types.xsd file are related to encapsulating data to be used within a Connection Path.

connectionPath Type

The connectionPath type is a simple container for the core aspects of the Connection Path. It includes the following:

• A host attribute that can represent either a hostname or IP address for a device.
• A credentials element that maps to the credentials type that is just a simple set of multiple credential type elements.
• A protocols element that maps to the protocols type that is just a simple set of multiple protocol type elements.
• A fileServers element that maps to the fileServers type that is just a simple set of multiple fileServer type elements.
• Any number of additional connectionPath elements that represent other nodes in this Connection Path.

protocol Type

The protocol type represents data regarding a network protocol. It stores the following information:

• The name of the network protocol. For example: "Telnet". This is represented by the name attribute that is of the xsd:string type.
• The port value for the network protocol. For example: "23". This is represented by the port attribute that is of the xsd:int type.
• Any number of properties that are associated with this protocol. This is represented by a properties element that maps to the properties type that is just a simple set of multiple property type elements.

property Type

The property type represents a simple name/value pair. This type is primarily used by the protocol type, but is abstract enough to be used anywhere else one might need a simple type that maps an arbitrary key to a value.

credentials Type

The credentials type represents all of the credential information to use for this particular node of the Connection Path. It contains a number of credential type elements that represent a simple name to value pair. This is leverages to map the name of a credential, such as "username", to some value that represents that actual credential.

fileServer Type

The fileServer type represents data needed to connect to and handle information with an external file server, such as a TFTP or FTP server. It stores the following information

• The name of the protocol that the file server use. For example: "TFTP". This is represented by the protocol attribute that is of the xsd:string type.
• The IP address of the the networked device that is running the file server. This is represented by the ip attribute that is of the xsd:string type.
• The value of the port that the file server is bound to. For example: "69". This is represented by the port attribute that is of the xsd:int type.
• The absolute file path to the root directory of the file server. This root directory is typically where files are placed when sent to the file server. This is represented by the rootDir attribute that is of the xsd:string type. The only caveat regarding this absolute file path is that it must be accessible from the machine that is executing the adapter that is currently interacting with this Connection Path. In most cases this is the same location of the ZipTie^? server. If the file server is located on the same machine as the ZipTie^? server, an absolute file path to a local directory can be used. However, if the file server exists on a different machine, the absolute path must represent a directory that is mapped to the root directory of the file server that is running on another machine.

Java Classes Associated with Connection Path

SOAP-Compatible Java Classes Generated From types.xsd

During the build process for building the ZipTie^? server, Java classes are generated for the various types that are used within specific WSDL files. For example, the backup.wsdl file (which lives in the org.ziptie.adapters bundle) defines the backup operation for any adapter. It specifies the input and return value for this operation. The only argument for the backup adapter operation is an object of the connectionPath type. This refers to the connectionPath type that was defined in the types.xsd XML schema document. Since the connectionPath type is being used, a Java class will be generated according to the definition laid out in the types.xsd XML schema document. Also, because a connectionPath type contains other types, as outlined above, Java classes for all of these types will be created.

The Java classes that are generated are very simple, bean-like, and SOAP-compatible. Any attributes defined in the type as specified in the types.xsd XML schema document will be private members and have getters and setters for all of them. Also, if a type contained other types as subtypes, there will be setters to set all of the objects of that type.

The classes that are currently generated are as follows. They all reside within the org.ziptie.client.adapters.types package:

• org.ziptie.client.adapters.types.ConnectionPath
• org.ziptie.client.adapters.types.Protocol
• org.ziptie.client.adapters.types.Property
• org.ziptie.client.adapters.types.Credential
• org.ziptie.client.adapters.types.FileServer

Helper ELF (Easy Little Functions) Classes

Despite the fact that Java classes are generated for all of the types associated with a Connection Path, there is still the task of converting ZipTie^? Java objects into these SOAP-compatible objects. To aid with this task, several ELF (Easy Little Functions) classes have been created to help.

ConnectionPathElf^?

This ELF contains a single method to generate a single org.ziptie.client.adapters.types.ConnectionPath object from the following arguments:

• A String object, representing either a host name or IP address of a device to connect to.
• A org.ziptie.protocols.ProtocolSet object that represents a set of all the network protocols to use to connect to the device and that will be utilized by the device.
• A org.ziptie.credentials.CredentialSet object that represents a set of all the credentials that will be used to authenticate with the device.

This method also makes sure to populate any file server information if a file transfer protocol has been specified within the set of protocols and a server using that protocol is being run by ZipTie^?. Currently, the only two possibilities are a TFTP and/or FTP server.

ProtocolElf^?

This ELF contains methods that can convert either a single org.ziptie.protocols.Protocol object or a org.ziptie.protocols.ProtocolSet object into either a single object or an array SOAP-compatible org.ziptie.client.adapters.types.Protocol objects.

CredentialElf^?

This ELF contains methods that can convert either a single org.ziptie.credentials.Credential object or a org.ziptie.credentials.CredentialSet object into either a single object or an array SOAP-compatible org.ziptie.client.adapters.types.Credential objects.

Generated Connection Path XML Structure

By using the SOAP-compatible Java classes that are generated from the types.xsd XML schema file, the web services layer of ZipTie^? can generate an XML document that contains and defines the Connection Path object. Here is an example of such an XML document:

<operation>
     <connectionPath host="10.100.1.1">
          <protocols>
               <protocol name="Telnet" port="23"/>
               <protocol name="SNMP" port="161">
                    <property name="version" value="2c"/>
               </protocol>
               <protocol name="TFTP" port="69"/>
          </protocols>

          <credentials>
               <credential name="username" value="myUsername"/>
               <credential name="password" value="myPassword"/>
               <credential name="enableUsername" value="myEnableUsername"/>
               <credential name="enablePassword" value="myEnablePassword"/>
               <credential name="roCommunityString" value="public"/>
               <credential name="rwCommunityString" value="private"/>
          </credentials>

          <fileServers>
               <fileServer protocol="TFTP" ip="10.100.10.10" port="11069" rootDir="/home/someuser/sometftpserver"/>
               <fileServer protocol="FTP" ip="10.100.10.10" port="11021" rootDir="/home/someuser/someftpserver"/>
          </fileServers>
     </connectionPath>
</operation>

Perl Modules for Handling Connection Path

Once the XML representing the operation and Connection Path data is generated from the SOAP-compatible Java classes, it will be used as one of the arguments into the main invoker script that is the main entry point into Perl so that an adapter operation can be executed. Once the invoker script receives the XML, it will invoke the specified adapter operation, passing the contents of the XML as a parameter. Each adapter operation is in-charge of parsing this operation XML according to the purposes of the operation.

In the case of a backup adapter operation, the adapter should parse the XML for the connectionPath element. This is the XML document that was generated from the SOAP-compatible classes. In order to easily parse the connectionPath XML element, the ZipTie::Typer Perl module along with its translate_document subroutine should be used. To use the translate_document subroutine, a string representing the XML to parse is specified, and then a list of 1 or more type names can be specified. All of these types will have their corresponding elements parsed from the specified XML. The return values of the translate_document subroutine are equal to the number of types specified.

The following is an example call of ZipTie::Typer::translate_document subroutine:

     my $connection_path_obj = ZipTie::Typer::translate_document( $backup_doc, 'connectionPath' );

There is a corresponding Perl module to each SOAP-compatible Java classes generated form the types.xsd XML schema document file. They are listed below in their fully-qualified format:

• ZipTie^?::ConnectionPath
• ZipTie^?::ConnectionPath::Protocol
• ZipTie^?::ConnectionPath::FileServer
• ZipTie^?::Credentials

Possible Use for Jumphost Functionality

-- DylanWhite - 03 Aug 2007