The 2.4 release of Zenoss supports improved modeling and monitoring of devices using SSH connections.  You can run arbitrary commands on the managed host, and write custom parsers in Python that run on the Zenoss server.  Zenoss Core ships with a limited set of operating systems for SSH monitoring, but this document exists to help you, the ZenPack author, add to the list of supported systems.  The LinuxMonitor Core ZenPack serves as an example.

Step 1. Understand Modeling vs. Monitoring

In Zenoss, modeling and monitoring are distinct operations.  They have different collection cycles.  Modeling is typically performed once per day, whereas monitoring runs every five minutes.  They use different persistent storage.  Modeling stores the information it discovers about the managed host in the Zope object database.  Monitoring stores performance data in RRDTool files.  For SSH, modeling is done by the zenmodeler command.  Monitoring is done by the zencommand command.  You can run either of these commands for a single device with debug logging enabled.

zenmodeler run -v10 -d <device name>
zencommand run -v10 -d <device name>

Both of these commands require for zenhub to be up and running.  During the time that you are debugging the parsing scripts in your SSH ZenPack if it seems like one of the above commands is completely silent (no error, but nothing showing the new capability), be sure to checkout the zenhub log.

Step 2. Create a new device class and export to ZenPack

The easiest way to create an SSH ZenPack is to create a new blank ZenPack in the UI.  Create a new device class.  Add the device class to the ZenPack and export the ZenPack.  This will create an objects.xml file.

You should then copy the ZenPack from $ZENHOME/ZenPacks into a directory that is a working copy for the Zenoss community ZenPack subversion instance.  Remove the ZenPack using the UI.  Restart Zenoss.  Link the ZenPack from the working copy with the following command

zenpack --link --install <path to ZenPack in working copy>

Each time you add or change the Templates or zProperties, you should export the ZenPack.  This regenerates the objects.xml in place in your working copy.  Beware that the web UI (ZenPack detail view) will not be updated immediately.  You will need to restart Zenoss to see the new Templates and Data Sources that belong to the device class and the ZenPack.

Step 3. Add a modeling plugin

Consider writing the tests first (How To Add a Test to an SSH Monitoring Zenpack).

A modeling plugin is a Python script that is associated with a command that is run on the managed host.  It parses the output of that command from within the zenmodeler process.  zenmodeler then sends the results to zenhub.  The persistent objects (e.g. Device) are not used by zenmodeler directly.  Instead modeler plugins return data maps as defined in DataMaps.py. A modeler plugin can return an ObjectMap, a RelationshipMap (which contains multiple ObjectMaps sharing the same component and relationship), or a list containing a mix of ObjectMaps and RelationshipMaps.

The skeleton ZenPack that was created for you when you clicked Create ZenPack in the UI, has a directory named modeler. Inside this directory create the following directory structure: modeler/plugins/zenoss/cmd/<os name>.  Where <os name> describes the operating system of the target host.  Place a blank file named __init__.py at every level of the hierarchy.  Create a file in the last directory named <parser name>.py.  Inside that file create a class that extends CommandPlugin from the CollectorPlugin module.

Set the following class attributes (zendmd is very helpful for determining the correct values, see DeviceModel for more info):

 
    command = "/bin/cat /proc/cpuinfo"
    compname = "hw"
    relname = "cpus"
    modname = "Products.ZenModel.CPU"

Override the process method.  It has the following signature:

def process(self, device, results, log):

The results parameter is a string containing the output of the command.  Create ObjectMaps and/or RelationshipMaps using the super class methods objMap and relMap.  Parse the results string and set values on the ObjectMap(s).  Return the data map(s). Code Snippet Example?

In the web UI bind the new plugin to the device class that is associated with your ZenPack.  Export your ZenPack and check-in the new plugin and the updated objects.xml to svn.  Test the plugin by running zenmodeler from the command line against a device in the device class.  Remember to check zenhub.log if zenmodeler fails silently.

Step 4. Add a zencommand Parser

Consider writing the tests first (How To Add a Test to an SSH Monitoring Zenpack).

Create a directory named parsers in the base directory of the ZenPack (the same directory that the modeler directory is in). Add an empty __init__.py file and create a subdirectory using a name that describes the operating system that you are targeting.  Place an empty __init__.py file in that subdirectory.  This directory is where you place the zencommand parsers that you create.