ZipTie User's Guide

This chapter describes what you need to know to get ZipTie installed and running to manage your network device inventory.

Before installing either of the server or client components for ZipTie, certain prerequisites must be met. While these prerequisites will be discussed here, there is also documentation for them on the ZipTie website, located here: http://ziptie.org/requirements

The following operating systems are officially supported for the ZipTie server and client components:

• Windows XP (x86 only) Service Pack 2 or higher
• Ubuntu Linux
• Mac OS X (x86 and PowerPC)

Any operating system listed here is not supported and ZipTie functionality is purely experimental.

• Other Linux (x86 only)
• Solaris

The following prerequisites are needed for running the ZipTie server:

• Sun Java Development Kit (JDK) version 1.5 (aka version 5) or higher
  • JDK 6 for Windows and Linux can be found here: http://java.sun.com/javase/downloads/index.jsp
  • JDK 5 for Windows and Linux can be found http://java.sun.com/products/archive/j2se/5.0_11/index.html
  • On Mac OS X, the version of Sun Java included should be the correct version if updates with Apple are up to date. Please run Apple's Software Update to ensure this is so.
• Perl version 5.8.8 or higher
  • On Windows, ActiveState's version of Perl is recommended for use. This can be downloaded from here: http://www.activestate.com/store/activeperl/download/
  • On Linux and Mac OS X, the Perl included with the operating system should suffice.
• NMAP version 4 or higher
  • On Windows, NMAP can be downloaded from here: http://download.insecure.org/nmap/dist
  • On Linux, many distributions already have NMAP version 4 installed. If it is not, use your distributions package manager to install it.
  • On Mac OS X, the proper version is already installed.
• Subversion (SVN) Libraries and Java Bindings
  • On Windows, the SVN libraries and java bindings are already provided for use in the ZipTie server.
  • On Linux, the libsvn SVN library package and javahl SVN Java bindings package must both be installed.
    • On Ubuntu, the libsvn SVN library package is named libsvn1; the javahl SVN Java bindings package is named libsvn-javahl. Use Ubuntu's package manager to install these packages.
    • On Mandriva, the libsvn SVN library package is named libsvn; the javahl SVN Java bindings package is named svn-javahl. Use Mandriva's package manager to install these packages.
  • On Mac OS X, the SVN libraries and Java bindings can be found here: http://downloads.open.collab.net/binaries.html.

Besides having version 5.8.8 of higher installed of Perl, there are a number of Perl modules that must be properly installed in order for the ZipTie server to function properly.

There is a Perl script named perlcheck.pl located in the base directory of the ZipTie server install that can be executed to check if all of the Perl dependencies have been met. While the perlcheck.pl script will check for missing modules on all operating systems, it does behave slightly differently depending on if Windows is being used or not:

• On Windows, if it has been determined that any number of Perl modules have been missing, then PPM will automatically be used to download all of the missing modules. The ZipTie server installer for Windows automatically executes the perlcheck.pl Perl script at the end of installation to automate the install of missing modules.
• On Linux and Mac OS X, the perlcheck.pl Perl script will simply print out all of the Perl CPAN commands necessary to retrieve the missing Perl modules. This method was chosen since many distributions of Linux can have their package managers install Perl modules instead of using the CPAN method of install Perl modules. It is up to the user to decide how they want to install the missing Perl modules.

Once the perlcheck.pl Perl script has been executed and all of the Perl module dependencies have been successfully met, you should see a message stating:

All the Perl modules required by ZipTie are already installed! Yatta!

The following prerequisites are needed for running the ZipTie client:

• Sun Java Runtime Environment (JRE) version 1.5 (aka version 5) or higher
• JRE 6 for Windows and Linux can be found here: http://www.java.com/en/download/manual.jsp
• JRE 5 for Windows and Linux can be found here: http://java.sun.com/products/archive/j2se/5.0_11/index.html
• On Mac OS X, the version of Sun Java included should be the correct version if updates with Apple are up to date. Please run Apple's Software Update to ensure this is so.

ZipTie is split up into two components: server and client. Both components need to be download and installed in order to fully utilize what ZipTie offers. All of the installers and binary distributions for ZipTie can be found here: http://www.ziptie.org/stable_build

The following sections outline steps for properly installing the ZipTie server component on various operating systems. Certain operating systems may have various ways of having the ZipTie server installed, so please find the section that corresponds the chosen installation method. Before attempting installation of the ZipTie server, please ensure that all the prerequisites are met; this is outlined in the Prerequisites section of the User Guide.

To install the ZipTie server on Windows, double-click the downloaded file and follow the installation wizard. The installation wizard will perform the following actions:

• Ensure that a valid version of both Perl and and the Sun JDK are installed before continuing. This should not be an issue if all of the prerequisites have been properly met.
• Prompts the user for the desired installation location. The default location is: C:\Program Files\ZipTie Server
• Prompts the user as to whether or not they would like to install the ZipTie server as a service and/or start the server once the installation has finished. For more information regarding running the ZipTie server, particularly as a service, please refer to The Server section.
• Installs all of the ZipTie server files into the specified location.
• Once the installation has finished, the perlcheck.pl script will be ran to resolve any possible missing Perl modules. For more information regarding the perlcheck.pl script, please refer to the Perl Module Dependencies section.

To install the ZipTie server on Ubuntu, the preferred method is to use the Ubuntu-specific .deb package. Please note that this .deb package is designed specifically for Ubuntu. This means that it will not work for Debian or any Debian-based Linux distributions. This is because the list of dependencies that the .deb package try to resolve are specific only to Ubuntu. In order to install the ZipTie server on a different Linux distribution, please refer to the Other Linux Distributions and Mac OS X (.tgz Method) section.

The Ubuntu-specific .deb package will perform the following actions:

• Installs all of the ZipTie server files into the /usr/share/ziptie-server directory.
• Creates a ziptie user. This is the user that will be used to run the ZipTie server if being executed through as an init.d service. Please refer to the various ways to run the ZipTie server in the The Server section.
• Changes the ownership of all of the files and directories in the /usr/share/ziptie-server directory to belong to the ziptie user. This is to ensure that the server can only be ran by the authorized ziptie user and to make sure that it can't be executed with an super-user privileges.
• Executes the perlcheck.pl Perl script to determine if there are any missing Perl modules that are required by the ZipTie server. The check is performed because when using the Ubuntu-specific .deb package, nearly all dependencies will be installed; It is possible, however, that not all of Perl module dependencies could automatically be installed. The reasons for this is that some of the required Perl modules can not be installed using Ubuntu's package manager or they do not have package maintainer for Ubuntu. Please use the commands output by the perlcheck.pl Perl script to install these missing modules. For more information regarding the perlcheck.pl script, please refer to the Perl Module Dependencies section.
• Installs the ZipTie server to run as an init.d service and be properly handled at system startup and shutdown. Once the service is installed, the ZipTie server will be started. For detailed regarding setting up and running the ZipTie server using a service, please refer to the The Server section.

The ZipTie RPM file that is provided is created for the Mandriva distribution of Linux. However, the RPM installer can still be used on other RPM-based distributions, provided that prerequisites are installed separately. On a non-Mandriva distribution, use the 'nodeps' option during installation. The prerequisites are Sun JDK 1.5 or 1.6 (server), or Sun JRE 1.5 or 1.6 (client). The version of Java that is in your path must be the Sun version of Java, otherwise ZipTie will not run.

You will notice at the end of installation a list of Perl dependencies that could not be satisfied during installation. These modules (typically two) will need to be installed from the CPAN (www.cpan.org) archive.

To install the ZipTie server on any other distribution of Linux or Mac OS X, simply download the ZipTie Server tarball (.tgz) archive and extract the contents into a desired location. This process will only install the ZipTie server files onto the system and does not perform any other task. In order to to run the server, refer to the The Server section.

The following sections outline steps for properly installing the ZipTie client component on various operating systems. Certain operating systems may have various ways to having the ZipTie client installed, so please find the section that corresponds the chosen installation method. Before attempting installation of the ZipTie client, please ensure that all the prerequisites are met; this is outlined in the Prerequisites section of this User Guide.

To install the ZipTie client, click on Windows, double-click the downloaded file and follow the installation wizard. The installation wizard will perform the following actions:

• Ensure that a valid version of the Sun JRE is installed before continuing. This should not be an issue if all of the prerequisites have been properly met.
• Prompts the user for the desired installation location. The default location is: C:\Program Files\ZipTie Client
• Prompts the user whether or not they would like an application shortcut to the ZipTie client placed our their desktop, quick launch taskbar, and Start menu.
• Installs all of the ZipTie client files into the specified location.

To install the ZipTie client on Ubuntu, the preferred method is to use the Ubuntu-specific .deb package. Please note that this .deb package is designed specifically for Ubuntu. This means that it will not work for Debian or any Debian-based Linux distributions. This is because the list of dependencies that the .deb package try to resolve are specific only to Ubuntu. In order to install the ZipTie client on a different Linux distribution, please refer to the Other Linux Distributions (.tgz Method) section.

The Ubuntu-specific .deb package will perform the following actions:

• Installs all of the ZipTie client files into the /usr/share/ziptie-client directory.
• Changes the permissions on the ziptie binary to be executed for group, user, and others.
• Places an application shortcut to the ZipTie client within the Applications→Internet menu.

To install the ZipTie client on Mac OS X, the preferred method is to use the OS X specific.dmg disk image. The .dmg disk image represents a virtual drive that contains the ZipTie client application. The ZipTie client can either be ran directly from the disk image, or it can be copied into the Applications folder within Mac OS X to be installed.

To install the ZipTie client on any other distribution of Linux, simply download the ZipTie client tarball (.tgz) archive and extract the contents into a desired location. This process will only install the ZipTie client files onto the system and does not perform any other task.

The default installation of the ZipTie server includes an embedded version of the Apache Derby database. However, ZipTie can be configured to use MySQL 5.1+ or PostgreSQL 8.2.5+. Included with the ZipTie server is a utility that can be used to initialize (or re-initialize) the ZipTie database. This utility is a Perl script that resides in the root of the server installation directory and is called dbutil.pl.

Here is an example of running the utility to initialize a MySQL database instance:

./dbutil.pl --db=mysql reset

And here is an example of running the utility to initialize a PostgreSQL database instance:

./dbutil.pl --db=pgsql reset

Both of these example assume defaults for the given database. For MySQL the user 'root' with no password is assumed, and for PostgreSQL the user 'postgres' is assumed. By default, a 'localhost' installation of either database is assumed. These defaults can be overridden by command line parameters supplied to the dbutil.pl utility. Running dbutil.pl with no parameters provides usage information for the utility, like so:

Usage: dbutil [options] <action>

Options:
  --db   database (one of: derby, mysql, pgsql)
  --user the user to connect to the database as (optional)
  --pass the password to connect to the database with (optional)
  --host the hostname of the database server (optional)
  --port the port number of the database server (optional)
  --dir  the ZipTie installation directory (optional)

Actions:
  reset  reset ZipTie to it's original state

If you are running your database server on a different machine, there are further edits to ZipTie configuration files that must be made in order for the ZipTie server to be able to connect to the database during startup.

For MySQL the file osgi-config/bitronix-jta/btm-config.mysql.properties must be edited and the following lines changed to suit your environment:

resource.ds.driverProperties.url=jdbc:mysql://localhost/ziptie
resource.ds.driverProperties.user=root
resource.ds.driverProperties.password=

Additionally, the file osgi-config/quartz/quartz.mysql.properties must be edited and the following lines changed to suit your environment:

org.quartz.dataSource.ziptie.URL=jdbc:mysql://localhost/ziptie
org.quartz.dataSource.ziptie.user=root
org.quartz.dataSource.ziptie.password=

In the case of PostgreSQL, the two files are osgi-config/bitronix-jta/btm-config.pgsql.properties and osgi-config/quartz/quartz.pqsql.properties and the lines that must be edited are the same.

In the files above, for a remote installation of a server, 'localhost' should be replaced by the hostname or IP address of the server along with the port if it is not the default port (eg. jdbc:mysql:/ /mysqlhost:8029/ziptie). Once these edits are made, the server can be started. You should check the ziptieServer.log file to ensure there were no errors during startup. If you received no errors, your installation is correctly configured.

The following sections outline steps for running the ZipTie server component on various operating systems. Certain operating systems may have various ways of running the ZipTie server installed, so please find the section that corresponds to the desired method of execution.

On Windows, there are two methods for running the ZipTie server: using the system service that was setup when the ZipTie server was installed, or directly starting up using the server.bat batch script.

The ZipTie server is capable of being installed as a Windows Service, which will allow it to begin at system startup and will terminate at system shutdown. The installation of this service is usually achieved by choosing to install it during the ZipTie server installation. Assuming that the ZipTie server install ran successfully with the option to install as a service, then there should be a ZipTie Server service available on your system.

If the ZipTie server was not installed as a Windows Service during the installation process, it can be done manually after the fact following these steps:

1. In a terminal, navigate to the ZipTie server installation directory, such as C:\Program Files\ZipTie Server
2. From the base ZipTie server directory, navigate to the ztwrapper\windows directory
3. Execute the following command:

   ''ztwrapper.exe --install ztwrapper.conf''

   Once the ZipTie server is installed as a Windows service, the following message will be displayed:

   STATUS | wrapper  | 2008/01/15 12:54:21 | ZipTie Server installed.

In order to manually control the ZipTie Server service from the command line, refer to the following commands:

• To start the service:

  net start "ZipTie Server"

• To stop the service:

  net stop "ZipTie Server"

• To see what other functionality can be performed against the service:

  net help

Although the ZipTie Server service may have been properly installed, there may be a time when a user wishes to manually run the ZipTie server. This can be achieved by executing the server.bat batch script that is located within the installation directory of the ZipTie server. Please note that the server can only be invoked this way if the ZipTie Server service is not currently running; otherwise, there will be conflicts.

In order to provide support for automatically starting and stopping the ZipTie server on Ubuntu, an init.d service script by the name of ztserver is included. The ztserver script allows the ZipTie server life cycle to be controlled within the init.d service framework. Here are the actions that the ztserver init.d script supports:

• start
  • Redirects certain low ports for TFTP, FTP, HTTPS and SNMP to higher ports for use by ZipTie Server using the iptables command. This is needed because the TFTP and FTP servers provided by the ZipTie server can not bind to 69/21 due to restricted access. The ZipTie TFTP and FTP servers by default bind to port 11069 and 11021 respectively.
  • Uses the su command to switch to the ziptie user.
  • Invokes the ztwrapper binary as the ziptie user to start the ZipTie server.
• stop
  • Tears down any port redirection that was set up using the iptables command.
  • Uses the su command to switch to the ziptie user.
  • Invokes the ztwrapper binary as the ziptie user to stop the server.
• restart
  • Calls the stop action
  • Calls the start action
• status
  • Checks the pid of the Java Service Process used to run the ZipTie server to determine if it is running or not. A status message along with the pid will be displayed if the server is running; otherwise, a message saying the server is not running will be displayed.

As mentioned in the Server Installation section, this init.d service functionality will be installed automatically when using the Ubuntu .deb package.

In order to manually control the ZipTie server init.d service on Ubuntu, reference the following commands:

• To start the server:

  sudo invoke-rc.d ziptie-server start

• To stop the server:

  sudo invoke-rc.d ziptie-server stop

• To restart the server:

  sudo invoke-rc.d ziptie-server restart

• To check the status of the server:

  sudo invoke-rc.d ziptie-server status

For more information on how to manually set up the init.d service for the ZipTie server, read the following section.

On systems that don't support init.d style services, or if you wish to manually run the server, there is a Bash shell script provided to invoke the ZipTie server called server.sh. The server.sh is a Bash script that invokes the ZipTie server for startup. The server.sh script can be found with in the base ZipTie server directory location.

In contrast to the functionality of the ztserver init.d script, the server.sh script only brings up the ZipTie server. This means that any port redirection that may be necessary for certain low ports for TFTP, FTP, HTTPS and SNMP to higher ports for use by ZipTie Server will need to be manually done by the user. This has to be done because the TFTP and FTP servers provided by the ZipTie server can not bind to 69/21 due to restricted access. The ZipTie TFTP and FTP servers by default bind to port 11069 and 11021 respectively.

On most Linux distributions, the iptables command is available to perform this functionality. Please refer to the zt_iptables function within the ztserver script to see one way of redirecting ports using the iptables command.

On Linux systems that support the init.d services framework, a user can leverage the ztserver script to control the ZipTie server life cycle. Here are the actions that the ztserver init.d script supports:

• start
  • Redirects certain low ports for TFTP, FTP, HTTPS and SNMP to higher ports for use by ZipTie Server using the iptables command. This is needed because the TFTP and FTP servers provided by the ZipTie server can not bind to 69/21 due to restricted access. The ZipTie TFTP and FTP servers by default bind to port 11069 and 11021 respectively.
  • Uses the su command to switch to the ziptie user.
  • Invokes the ztwrapper binary as the ziptie user to start the ZipTie server.
• stop
  • Tears down any port redirection that was set up using the iptables command.
  • Uses the su command to switch to the ziptie user.
  • Invokes the ztwrapper binary as the ziptie user to stop the server.
• restart
  • Calls the stop action
  • Calls the start action
• status
  • Checks the pid of the Java Service Process used to run the ZipTie server to determine if it is running or not. A status message along with the pid will be displayed if the server is running; otherwise, a message saying the server is not running will be displayed.

In order to properly use the ztserver script to control the ZipTie server, two pre-requisites must be fulfilled:

1. Create a ziptie user with non-administrative privileges. This is required in order to ensure that the ZipTie server is not run as a user with administrative privileges. Within the ztserver script, it is expected that ziptie is a valid user and will be used via the su command when starting/stopping/restarting the server. If you wish to use a different name than ziptie, be sure to update the RUN_AS_USER variable located within the ztserver script; the RUN_AS_USER variable is what is referenced when changing users using the su command.
2. Change the ownership for the ZipTie server installation directory and its entire contents to belong to the newly created ziptie user. This is to ensure that the ZipTie server can only be executed by the ziptie user or a super-user.

Once the ziptie user has been successfully created and the ownership of the ZipTie server has been successfully changed, the following steps can be enacted to allow the ztserver script to be used to control the ZipTie server as an init.d service:

1. Create a symbolic link to the ztserver script within your distribution's init.d directory:

   ln -s <ziptie_server_dir>/ztserver /etc/init.d/ziptie-server

   A symbolic link must be used rather than copying the ztserver script because there are relative paths contained within the script that assume the script is based out of the ZipTie server directory.

2. Create a symbolic link to the ztserver script within your distribution's desired init.d run-level directories. For most distributions based on System V architecture, the following commands should work:

   ln -s /etc/init.d/ziptie-server /etc/rc3.d/S99ztserver
   ln -s /etc/init.d/ziptie-server /etc/rc3.d/K01ztserver
   ln -s /etc/init.d/ziptie-server /etc/rc5.d/S99ztserver
   ln -s /etc/init.d/ziptie-server /etc/rc5.d/K01ztserver

   These commands will ensure that the ZipTie server is invoked at system startup and terminated at system shutdown.

In order to manually control the ZipTie server init.d service, reference the following commands:

• To start the server:

  sudo /etc/init.d/ziptie-server start

• To stop the server:

  sudo /etc/init.d/ziptie-server stop

• To restart the server:

  sudo /etc/init.d/ziptie-server restart

• To check the status of the server:

  sudo /etc/init.d/ziptie-server status

ZipTie has the ability to mail things like scheduled reports. To do this, ZipTie must know of a good SMTP server to send mail through. By default it tries to send mail to the hostname mail. If that hostname doesn't resolve on your ZipTie server then you must configure it further.

To do so, edit the file ~/ZipTie Server/osgi-config/mail/mail.properties. Set the mail.host property to the hostname of your SMTP server. There are additional commented out fields in the file to allow you to authenticate to your SMTP server if necessary. Below is an example of this file's contents.

 mail.host=mail.company.com
 mail.from=ziptie@ziptie.org
 mail.from.name=ZipTie
 mail.smtp.starttls.enable=true
 # mail.auth.user=someuser
 # mail.auth.password=somepassword
 mail.smtp.auth=false

After editing the file you must restart your ZipTie server for the changes to take effect.

The first time you start the application, ZipTie presents you with the Server Connection dialog. Use this dialog to connect to the ZipTie server. Enter the Administrator username (default 'admin'), password (default 'password'), and hostname or IP address for the ZipTie server. The default hostname and port is localhost:8080.

Click OK to initiate the Startup Wizard.

The first time you start ZipTie you will be prompted with the Startup Wizard. This wizard guides you through the initial connection to a server and setup of your device inventory. ZipTie manages your inventory largely through its flexible search interface.

Next, you are presented with the Credentials Management dialog. In ZipTie, the credentials are managed independently of the devices. This allows for easy management of large sets of devices that all have the same credentials. Read the chapter on credential management for a more thorough explanation. You can always come back and change the credentials later. Once you have configured your initial credentials click the wizard's Next button.

Next, you are presented with the Protocol Management dialog. In ZipTie, the protocols are managed independently of the devices. This allows for easy management of large sets of devices that all have similar protocols. Read the chapter on protocol management for a more thorough explanation. You can always come back and change the protocols later. Once you have configured your initial protocols click the wizard's Next button.

Finally you will need to populate your inventory with devices. ZipTie provides a way for you to automatically discover devices using SNMP. See the Discovery chapter for details on discovering devices via SNMP.

Click Finish and the discovery process will begin. As devices are discovered, they are added to your project in the Devices view. Click Finish and an import job will be spawned.

Once you have your inventory populated, you will want to back up the configurations of all your devices. A device that has never been backed up will be decorated with a question mark on it.

To see the entire inventory, click the Go button in the Query field using a blank query.

To back up a device, right click on it in the Device view and select Backup.

A progress dialog displays. If the backup fails, the device is decorated with a red dot. If the backup is successful, the device has no decoration.

ZipTie provides a way for you to organize your devices by “tagging” them. You can tag devices by right-clicking one or more of them in the inventory and selecting Edit Tag. You can create as many tags as you like. You can tag and untag devices and, you can file devices with the same tag by performing a tag search.

This section aims to familiarize you with the various aspects of the workbench. The workbench window is the main ZipTie window that contains all the views used for performing various tasks against devices. ZipTie is built on the Eclipse rich-client platform (RCP), so it borrows many concepts. To better understand the user interface, click around and see what you can find.

The following definition of views is taken from the Eclipse help:

A view is a visual component within the Workbench. It is typically used to navigate a hierarchy of
information (such as the resources in the Workbench), open an editor, or display properties for
the active editor. Modifications made in a view are saved immediately.  Normally, only one instance
of a particular type of view may exist within a Workbench window.

Views are accessed from the Views menu. The following sections describe some of the more useful ZipTie views.

The Devices view displays all the devices in your inventory. This is the starting point for many tasks in the system.

The left section is the search area. Here you may specify a type of search (eg: IP Address, Hostname, OS Version, etc) and the query input. Under the query is a status message explaining the results of the last search requested.

The right section is the results area. The devices matching your search on the left will be displayed in this table.

IP Address based search allows for a single input where the input can be either an exact IP Address or an IP CIDR mask.

For example: '10.100.22.6' will return just the device with the IP '10.100.22.6' and '10.100.22.0/24' will return all devices that are in the 10.100.22.* subnet.

This search allows you to search for devices based on the Operating System Version devices are running.

To search for a device you must specify an OS Type an operator and the target value.

For example: If you are looking for Cisco devices running IOS 12.2(17) or higher your search input would be 'Cisco IOS', '>=' (Greater or equal to), and '12.2(17)'.

In this case, a devices running 12.2(15) or 11.2 won't match but a devices running 12.2(17a) or 12.3 will.

As different device types use different versioning schemes it is not possible to search for similar version across device types.

This search allows you to find devices based on their model number. For this search you must specify the Vendor and a query for the Model.

The Vendor drop down is populated based on all the available vendors in the system.

The Model query allows for '*' wildcards anywhere in the input.

For example: If you want to see a list of you Cisco 2600 series routers select 'Cisco' as the Vendor and specify the Model query as '26*'. The results will include Cisco devices with model numbers that start with 26.

This search allows you to find devices based on user set tags.

The tag query input consists of a space separated list of tags.

By default the query is an AND search so the input “Austin Corporate” would find only devices which are tagged with both “Austin” and “Corporate.”

You can also perform OR queries by separating each tag with “OR”. So the input “Austin OR Houston” would find devices tagged with either “Austin” or “Houston.”

For details on tagging devices see (INSERT LINK HERE).

The hostname search allows you to find devices based on the hostname.

You may use wildcards in you query input but only at the beginning or end of the input.

The right side of the view contains a table display of the devices. This table gives a brief overview of each device it displays. For more information on any device you may double click on it to open it's details.

The backup status for a device is indicated by the icon in the left most column of the table. There are four states: Not Backed Up, Backup Failed, Invalid Credentials, and Backed Up.

If the state is either Invalid Credentials or Backup Failed you can see the error details by right clicking on the device and selecting Show Error Details.

The configuration search view allows you to search for text in all devices' latest configurations.

ZipTie uses Apache Lucene to search configurations, details on the syntax can be found on the Lucene website: http://lucene.apache.org/java/docs/queryparsersyntax.html

The following Lucene fields are made available to search upon:

• text - The contents of the configuration.
• address - The device IP address.
• name - The configuration path (eg: /running-config)
• timestamp - The time when the configuration was backed up.
• mimetype - The mime-type of the configuration.
• network - The device's managed network.

To find any configuration containing the text “Joe Bob”

"Joe Bob"

To find any configuration containing the text Joe and Bob but not necessarily next to each other

Joe Bob

To find all running-configs containing the text “Loopback2”

text:"Loopback2" AND name:"/running-config"

The Progress view displays all the currently running client side user jobs. You can select Run In Background in most progress dialogs, you can then view the progress for the job in this view.

The Jobs View shows all the server jobs. From this view you can open, rename, move, and delete jobs.

This view will display the history of job executions including jobs currently in progress. Double clicking on an execution will open the results for the execution if applicable.

ZipTie includes an advanced classless IPv4 subnet calculator. To open the calculator go to Window→Show View→Other. Type “Subnet Calculator” in the filter window or go directly to it under Network Tools.

The subnet calculator can answer questions such as:

1. What mask should I use if I need a network with at least 100 hosts?
2. If my ISP gives me a /24, what mask should I used to split that network into 4 broadcast domains?
3. What is the broadcast address of the network that 192.168.2.42/27 is a member of?

This view keeps a log of any client side errors and warnings that may be interesting for developers.

In this chapter you will be introduced to the standard tools supplied with ZipTie. See the Content Developer's guide for information on writing your own tools.

The DNS Lookup tool performs a reverse-DNS lookup using the IP of the selected devices to resolve the names. Note that the name resolution is performed on the ZipTie server, and therefore the DNS servers configured for that machine will be used.

The Interface Brief tool obtains the list of interfaces configured on the selected device and displays Current UP/DOWN status and Administrative UP/DOWN status of each interface.

The IP Routing tool retrieves the routing table, if available, from the selected device.

The OS Fingerprint tool uses nmap program to perform a fingerprinting operation against the selected devices to try to determine what operating system they are running.

The Ping tool performs a simple (ICMP) ping operation against the selected devices and displays the results in a tabular format.

The Portmap tool uses the nmap program to perform a port-scan of the selected devices and displays the results in a table consisting of common protocol ports and an “Other” column used to display non-standard ports that are discovered open.

The SNMP System Information tool uses SNMP to retrieve system information from a standard SNMP Object Identifier against a set of selected devices. The resulting system information is displayed in a table.

The Traceroute tool performs a standard traceroute operation to discover the connection path between the ZipTie server and the selected device. The resulting route is displayed in a table, with one “hop” displayed per row.

To connect to individual device in the network ZipTie must - like all other device users - gain access to the devices. To gain access to a specific device, the device must first ensure that ZipTie is a valid user on that device. Many network environments have different authentication credentials for different types or different functions of their devices. For example, you may have one set of credentials for all of your Cisco devices and another set for all of your Nortel devices. You may have different sets of credentials based on whether the devices are routers or firewalls or because one set of devices is managed by one part of the organization and another set by another part of the organization. In this chapter you will learn how to configure these device credentials for ZipTie to use.

Before ZipTie performs its management operations on individual devices in the network, it must - like all other device users - initiate communication with the devices to perform backups and make changes. For ZipTie to communicate with a specific device, ZipTie must understand the protocol the device uses for communication. Many network environments have different communication protocol for different types or different functions of their devices. For example, you may have one protocol for all of your Cisco devices and another set for all of your Nortel devices. You may have different protocols based on whether the devices are routers or firewalls or because one set of devices is managed by one part of the organization and another set by another part of the organization.

Since there may be multiple different credentials for the devices in your network, ZipTie employs the concept of network groups. A network group is a container into which you add credential sets and address sets. Credential sets are “named sets” of credential types and credential values for a set of devices that require those specific authentication credentials. Address sets are IP addresses that define the network group. You can use wildcards as a way of grouping devices based on your network addressing scheme.

Network groups can have multiple credential sets and multiple address sets. To help manage access to network devices, ZipTie provides a way to prioritize how network groups (and their associated credentials and address sets) are evaluated. By listing network groups in priority order, you are telling ZipTie which address sets to attempt to connect to first, second, and third before failing. When the credentials in a network group are successful at accessing a device, ZipTie remembers the credentials that were successful on that device and uses them each time thereafter when connecting to the device. If, for some reason, the credentials on that device change, then the next time ZipTie attempts to connect to that device, it will fail authentication. On the next connection attempt, ZipTie will reconcile the credentials again, so it will succeed. And then it remembers the new credentials.

You specify the IP addresses of a set of device and then create enough credential sets to authenticate ZipTie on all devices under management.

ZipTie employs the same strategy for protocols as it does for credentials. Protocol sets are sets of protocol types for a set of devices that require those specific communication protocols. Address sets are IP addresses that define the network group.

ZipTie provides a Discovery process as a means to add devices to the inventory. These devices are found by looking at very specific IP addresses on a network and/or by crawling a network. Communication is mostly through SNMP v1 or v2c although devices not running and SNMP agent can also be discovered via the CDP table of another SNMP enabled device.

This chapter will describe the necessary steps to start a Discovery task and explain a few of the underlying algorithms that the process uses to intelligently crawl a network.

Discovery can be run either through the startup wizard, or by clicking on the Discover Devices… task in the Inventory section of your ZipTie client. Either of those two locations will bring you to the Discovery wizard.

First, provide a starting point for the discovery job. Click the Add button to provide Discovery with a single address, a subnet or a range of IP addresses. You can add one or more of each type, combining them at will.

The other option for discovery is “crawling”. By default, the discovery wizard will assume that the discovery job should stay within the confines of the addresses configured. You can optionally tell discovery to crawl the network, using the addresses configured as starting points for a more complete discovery. Do this by checking the box labeled Crawl the network from the addresses defined. It will stop crawling when it cannot communicate with learned devices.

After completing the above pieces, click the Finish button to start the discovery job. Devices will be added to the ZipTie inventory as they are discovered.

All addresses within the initial address definition are tested for reachablility. On Windows this means an ICMP ping, on Linux or MacOS this means a lightweight TCP port check of 22, 23, and 443. Those addresses responding to the initial check will be further probed using SNMP.

The SNMP get community string configured in the credentials management section of ZipTie is used by Discovery. Using SNMP the sysName, sysDescr and sysObjectId are read. This detail is enough to figure out if the device in question is supported by ZipTie. Additionally, if crawling is turned on, the ARP table, OSPF and EIGRP routing neighbors as well as CDP neighbors are read via SNMP. All of those neighbor addresses are fed back into the discovery engine to allow the engine to crawl the network. The discovery engine maintains a cache of addresses discovered for one week to ensure that it doesn't walk it circles.

Additionally, Discovery features an algorithm to determine the preferred IP address for a given device. Software loopback addresses outside of the 127.0.0.0/8 network are chosen first. If none are available it will move on the interface with the lowest ifIndex value that has a reachable IP address.

The discovery engine is highly configurable. For example, if you are concerned about the discovery engine using device ARP cache tables to crawl your network, you can turn this off in the ~/osgi-config/network/nil.properties configuration file on your server's file system. The discovery options are outlined below.

                  # A regular expression that matches completely, the enterprise IDs of device
                  # that support the CDP MIB.  The discovery engine will only poll CDP neighbors
                  # from devices that have this matching SNMP enterprise ID.  The defaults are 9 (Cisco)
                  # and 11 (Hewlett Packard).
                  nil.discovery.cdpEnabledDevices=9|11
                  
                  # Tells the server which protocol to use for pinging a host to test its availability.
                  # When left at 'default' the discovery engine will use the ICMP 'ping.exe' program on Windows
                  # machines while doing a TCP port scan on other operating systems.
                  #
                  # Change this value if you'd rather use a TCP scan on Windows or an ICMP ping on other
                  # operating systems.
                  #
                  # Valid settings are 'ICMP', 'TCP' or 'default'
                  nil.discovery.ping.protocol=default
                  
                  # While iterating over a subnet or range of IP addresses, we don't want to simply
                  # put all addresses in memory in the discovery queue.  This would take up too much
                  # RAM if one were to discover a /8 network.
                  #
                  # This count will tell us how many pings to let in memory.  This has nothing
                  # to do with the concurrent ping count, it is simply for memory management.
                  nil.discovery.ping.semaphores=66000
                  
                  # Discovery can be set up for a TCP 'ping'.  This means it will check the availability
                  # of one or more TCP ports.  This value is a comma separated list of ports to check.
                  # The default will be 22,23,80 and 443.
                  #
                  # This value has no effect if the ping protocol is ICMP
                  nil.discovery.ping.tcpPorts=22,23,443
                  
                  # If discovery is set to use TCP as the ping protocol this number dictates
                  # how many open TCP sockets the engine will try to open at a time.  The 
                  # default number is 400.
                  nil.discovery.ping.tcpConnections=500
                  
                  # if a sysObjectId matches the regular expression below, the MAC table
                  # gathering techique described in this link will be used:
                  # http://www.cisco.com/warp/public/477/SNMP/cam_snmp.html
                  #
                  # if it doesn't match we will grab the MAC table without concern for VLANs.
                  # Note that we are specifically trying to exclude 1900 and 2800 catalyst
                  # switches as they don't gracefully support community string indexing.
                  nil.discovery.ciscoMacCollection=1\.3\.6\.1\.4\.1\.9\.(?!5\.(18|20)$).*
                  
                  # If set, no discovery process will go outside of these bounds.
                  # This can be a comma separated list of networks, IP addresses, ranges
                  # or wildcards.  For example 10.0.0.0/8,192.168.0.0/16
                  nil.discovery.boundaries=
                  
                  # If set, the discovery engine will exclude any address, ranges, wildcards
                  # or subnet definitions.  The exclusions can be a comma separated list
                  # of network addresses.  For example 10.*.*.1,172.0.0.0/8,94.20.20.1-94.20.20.200
                  nil.discovery.exclusions=127.0.0.0/8
                  
                  # This will dictate if the engine should crawl the network by default
                  nil.discovery.discoverNeighbors=true
                  
                  # The discovery engine uses ARP cache to traverse a network
                  nil.discovery.pollARP=true
                  
                  # The discovery engine can poll MAC tables.  Set this to true
                  # if you are registering a handler that could use this information
                  nil.discovery.pollMac=false
                  
                  # The discovery engine uses CDP neighbor data to traverse a network
                  nil.discovery.pollCDP=true
                  
                  # The discovery engine uses EIGRP and OSPF neighbors to traverse a network
                  nil.discovery.pollRoutingNeighbors=true
                  
                  # The number of minutes that the discovery engine should keep its cache
                  # of addresses already touched.  The cache keeps the engine from running
                  # in circles.
                  nil.discovery.clearCacheDelayMinutes=10080
                  
                  # The discovery engine will form subnet definitions from interface
                  # IP Address and Subnet Mask details.  If that subnet is smaller than
                  # or equal to the bit mask defined here, the engine will do a ping sweep
                  # of that network.  This is designed to find point-to-point connected
                  # routers that may be addressed with a /30.
                  nil.discovery.maxMaskPingSweep=28
                  
                  # the byte size of ICMP pings
                  nil.discovery.pingSize=16
                  
                  # The number of retries when in ICMP ping mode
                  nil.discovery.pingCount=2
                  
                  # The number of milliseconds to wait before considering a TCP or ICMP
                  # ping dead.
                  nil.discovery.pingTimeout=1000
                  
                  # By default the discovery engine starts with 10 threads.  You can up
                  # that value here.
                  nil.discovery.masterThreads=10
              

The recommended usage is to configure small starting points for discovery and let the crawling feature do its work. If crawling is not an option it should be noted that discovery over large subnets or IP ranges is considerably slower on Windows machines compared to Linux or MacOS. The ICMP ping used on Windows system is a less efficient means to test device reachability than the TCP check used on other operating systems.

The Linux based discovery will open TCP sockets to determine if an IP address is interesting or not. By default it will open up to 800 sockets simultaneously. If the system running ZipTie does not allow for that many simultaneous open files there will be an error similar to this in the server log.

2007-06-07 08:41:37,382 ERROR:  Discovery ping error for 10.100.19.204. Too many open files

In the above case the number of TCP connections allowed to the Discovery process needs to be reduced. To do so, edit the nil.properties configuration file and tune down the following setting appropriately.

nil.discovery.ping.tcpConnections=800

There are a few schedulable jobs in ZipTie including Device Backup and the Command Runner and scheduling works the same for all of them.

Most jobs can be created either from the Jobs View or by right clicking on a device and selecting the job to create under the New Job submenu.

You can open existing jobs from the Jobs View or from the History View.

All jobs' editors have a page called the Schedule page. This is the page where the Triggers for the job are managed.

Here is an example of the Schedule page for a Command Runner job. This page is essentially the same for all job types. It is from this page that you will manage the schedule for the job.

A Trigger defines when a job should run. A job's Schedule normally refers to the set of all Triggers for the job.

To create a trigger all you need is a trigger Name, a Start time, and a Recurrence.

The Name needs to be unique for the specific job but does not need to be anything specify.

The Start time is the time when the trigger will be activated. This is not necessarily the time the job will be run.

The Recurrence is the definition of when the job will run. The available types of recurrence are Once, Daily, Weekly, Monthly, or Cron.

If once is specified as the recurrence frequency the job will run at the time specified by the Start time and then the trigger will be discarded.

A daily trigger will be executed at the time of day as specified by the Start Time every X number of days.

A weekly trigger will be executed at the time of day as specified by the Start Time every checked day of the week.

A monthly trigger will be executed every X months on a certain day of the month at the time of day as specified by the Start Time.

A cron trigger allows you to specify a more complicated schedule similar to unix crontabs.

More information about this syntax can be found on the Quartz website. http://www.opensymphony.com/quartz/api/org/quartz/CronTrigger.html

If an End Date is specified the trigger will be discarded on that day.

A Filter defines a period of time when triggers will not fire. Each trigger can have one filter associated with it.

Filters are defined in the Scheduler Filter preference page.

ZipTie uses Quartz internally for job schedule management. For more information about quartz please visit their website at http://www.opensymphony.com/quartz/.

In this chapter you will be introduced to the configuration command runner. A Command Runner is a schedulable job that allows you to run a set of commands against a set of devices.

You can quickly run a set of CLI commands against a set of devices in ZipTie. To do so, in the Devices View select the set of devices you want to perform commands against.

Right-click on the devices and select Run Commands… This will open the command runner dialog. In this dialog you may specify the commands to run.

Click Run to execute the commands. The results will open.

This command execution will also appear in the Job History for later review.

1. In the Devices view select the devices you want the to run commands against. This list doesn't have to be perfect, you can add and remove devices at later.
2. Right-click on the devices and select New Command Runner… from the menu. This will open the New Command Runner Dialog.
3. Specify a Job name and Group for that the job will reside in and click Finish. The Command Runner editor for your job will be opened.
4. In the Commands area of the editor you can specify the commands to run.

Note: Command Runners can only run against devices that have been successfully backed up.

One way to run the commands is to have the job run immediately. To run the job immediately select Run Now. This will execute the job immediately and the Results viewer for the execution will open. The devices will be added to the results viewer list as the commands complete for each. Also the execution will appear in the Job History view.

To schedule the job

The Command Runner editor is used to modify a Command Runner job.

The devices page allows you to specify the devices that the job will run against.

The schedule page allows you to manage the triggers for the job.

NetworkAuthority Inventory provides a role-based security system. In a role-based security system, Roles are comprised of a set of Permissions. Users in the system can be assigned a Role. This section will document how to manage user's and roles with the NetworkAuthority Inventory administration utility.

The NetworkAuthority Inventory Administration Shell is a command line utility that can be used to administer users and roles. The utility is named admin.pl and can be found in the NetworkAuthority Inventory Server installation directory. In Linux and Mac OS X, the utility is invoked as follows:

./admin.pl

And in Windows, the utlity is invoked as follows:

admin.pl

If you don't have Perl associations installed, you can invoke the utility as follows on all platforms:

perl admin.pl

Once the utility has been invoked, you will receive a login prompt for the Administrative ('admin') password. Once the password has been entered, and the server has been successfully connected to, you will receive an Administration utility prompt like so:

NetworkAuthority Inventory Administrative Shell - 2008.10.0
Administrator password: ********

[localhost:8080]$ 

–more to come–

NetworkAuthority Inventory can be configured to send SNMP v2c traps to an external listener. Currently the following events in NetworkAuthority Inventory can generate a trap.

• A new device is added to the inventory
• A device configuration has changed
• A device is deleted from the inventory
• An operation, such as a backup, fails

To setup the ZipTie server to send these traps, edit the file ~/osgi-conifg/network/nil.properties found on your NetworkAuthority Inventory server. In this file, add your trap receiver to the nil.snmp.trap.receivers property. The NetworkAuthority Inventory server must be restarted to pick up your new trap receivers.

Trap receiver definitions are in the form:

 <community>@<host>/<port>

For example:

 public@10.100.32.53/162

You can configure multiple trap receivers by comma separating their definitions.

 public@192.168.1.20/162,public@10.23.30.2/162

NetworkAuthority Inventory ships with a ZIPTIE-MIB.txt MIB which you can compile on your external trap listener to make the integration even easier. The MIB can be found in your ~/osgi-config/network/ folder on your server or you can download the MIB from http://fisheye.ziptie.org/browse/ZipTie/conf/network/ZIPTIE-MIB.txt.