Automatically adding and editing devices in Zenoss Core 4 using the API

Today I figured out how to automatically add new devices (in my case those are mostly virtual machines) to the Zenoss monitoring system. This used to be done by hand, but no more 🙂

To add a new device (for example a Linux server called server001), simply call:

curl -u apiUser:apiPass \
'http://zenoss-server:8080/zport/dmd/DeviceLoader? \
deviceName=server001&devicePath=/Server/Linux&\
loadDevice:method=1'

It’s wise to create a dedicated Zenoss user just for these API calls, but you may use any account that has sufficient permissions to perform the action you’re calling.

As an alternative you can also use the ‘zenbatchload‘ command. Although you can only add new devices, not edit existing ones.The RESTful API does have the possibility to edit an existing device.

Let’s set some properties to the server we’ve just added:

curl -u apiUser:apiPass \
'http://zenoss-server:8080/zport/dmd/Devices/Server/\
Linux/devices/server001/manage_editDevice?serialNumber=1234&\
tag=tagname&productionState=1000&\
groupPaths=Group1&groupPaths=Group2&priority=3&\
comments=Api%20Test%20Comment&systemPaths=/System\
&rackSlot=Virtual'

It took me some time to figure out all available attributes, although once I found some of them I was able to Google the full list with an explaination.

Attributes:

• deviceName – the name or IP of the device. If its a name it must resolve in DNS
• devicePath – the device class where the first “/” starts at “/Devices” like “/Server/Linux” the default is “/Discovered”
• tag – the tag of the device@
• serialNumber – the serial number of the device
• zSnmpCommunity – snmp community to use during auto-discovery if none is given the list zSnmpCommunities will be used
• zSnmpPort – snmp port to use default is 161
• zSnmpVer – snmp version to use default v1 other valid values are v2
• rackSlot – the rack slot of the device.
• productionState – production state of the device default is 1000 (Production)
• comments – any comments about the device
• hwManufacturer – hardware manufacturer this must exist in the database before the device is added
• hwProductName – hardware product this must exist in the manufacturer object specified
• osManufacturer – OS manufacturer this must exist in the database before the device is added
• osProductName – OS product this must exist in the manufacturer object specified
• locationPath – path to the location of this device like “/Building/Floor” must exist before device is added
• groupPaths – list of groups for this device multiple groups can be specified by repeating the attribute in the url
• systemPaths – list of systems for this device multiple groups can be specified by repeating the attribute in the url
• statusMonitors – list of status monitors (zenping) for this device default is “localhost”
• performanceMonitor – performance monitor to use default is “localhost”
• discoverProto – discovery protocol default is “snmp” other possible value is “none”

Finally, in case you wish to delete a device, that can be done as well:

curl -u apiUser:apiPass \
'http://zenoss-server:8080/zport/dmd/Devices/Server/Linux/\
devices/server001/deleteDevice'

Personally I prefer not to delete devices. I rather set the ‘productionState’ to ‘-1’ (Decommissioned) to keep the history in Zenoss.

These simple API calls make it possible to automatically add a new server to the monitoring, or sync information from another source. But you can use the API for gathering all sorts of data as well. For example the load-average:

curl -u apiUser:apiPass \
'http://zenoss-server:8080/zport/dmd/Devices/Server/Linux/\
devices/server001/getRRDValue?dsname=laLoadInt5_laLoadInt5'

Result:

2.0

If you want to start playing with it, have a look at the Zenoss API documentation.