Network UPS Tools (NUT) UPS Monitor
Network UPS Tools is an open-source UPS monitoring package that is capable of supporting a large number of UPS devices. Architecturally, NUT consists of several *NIX-based device drivers that communicate with specific UPS devices through private protocols, while a upsd server exposes common operational details in a consistent manner, with local and/or remote clients communicating with upsd for monitoring and management purposes. This script template takes advantage of this model by acting as a NUT client, querying the upsd server for operational information about the connected UPS devices, and then generating multiple graphs from the collected data.
Specifically, this script template uses PHP sockets to open a connection to the NUT upsd daemon on the target host, and then uses the NUT protocol to enumerate and query the UPS devices for operational details. This model allows for more flexibility and speed over alternative approaches, but the downside is that you must have the PHP sockets library installed and operational.
For illustration purposes, the graphs in the figure at right shows the data that is monitored for a Tripp-Lite SMART2200RMXL2U rack-mount UPS attached to a Linux server via USB. I have also successfully tested this script template against an APC ES 750 small-office UPS and a MGE Pulsar Evolution 1100 rack-mount system, although it should be noted that not all of the devices support all of the variables that are used by this script template.
Installation
To use this script template, perform the following steps:
- Obtain a working copy of the NUT server package, and configure it for your UPS devices as instructed. You may be able to download a pre-made binary for your Linux distribution from an online package repository, or you may be able to use one of the prebuilt packages on the NUT web-site, or in worst case scenarios you may need to compile the program from source. Verify that the NUT server is operating correctly with a NUT client package running on the Cacti server. Note that you may need to specify the network interface for NUT to listen on, since the deafult is to use the localhost interface.
- Download cacti-nut.0.5.tar.gz to a temporary directory on the Cacti server machine.
- Expand the archive with the command
tar -xvzf cacti-nut.0.5.tar.gz, and change to the cacti-nut directory that is created. - Copy scripts/ss_nut_ups_status.php to the <cacti>/scripts/ directory.
- Copy resource/nut_ups_status.xml to the <cacti>/resource/script_server/ directory.
- Access the Cacti installation in a web browser, click on the "Import Templates" menu item on the left side of the Console screen, and import the template/nut_ups_status_data_query.xml file. Cacti should automatically create the required graph template, data input method, and data template objects.
- Click on the Devices menu item on the left side of the Console screen, select a host that is running the upsd daemon, and scroll down to the "Associated Data Queries" table. Select "NUT - UPS Statistics" in the "Add Data Query" drop-down box, and click the "Add" button.
- After the Device screen reloads, verify that the "NUT - UPS Statistics" data query is now present, and then click the "Create Graphs for this Host" link at the top of the page.
- Once the screen finishes loading, locate the "NUT - UPS Statistics" data query, which should contain entries for each UPS device that is known to the upsd server on the target host. At the bottom right of the list is a drop-down box containing three available graph types for the data query. Select the graph type that you want to generate, then select the UPS device(s) that you want to monitor, and then click the "create" button at the bottom of the screen to include the required data in the poller process. If you wish to create multiple graphs for multiple devices, you will need to repeat this process for each graph type.
Note: these files are intended to be used with Cacti 0.8.6 and 0.8.7 and PHP 5.2, and may not operate as expected with other versions.
Script Input and Output
In some cases you may want to execute the script file manually for debugging purposes. The parameters to the script use a fixed structure that is optimized for use with the Cacti poller, but also allows for human interaction. In particular, the script uses three parameter groups, with the exact structure depending on the output that is desired.
The first parameter group provides a NUT protocol "bundle" of the following values, separated by colon characters: In those cases where a default value is adequate (such as the NUT port number), the value can be omitted.
- hostname: The domain name or IP address of the target device. This value is mandatory.
- port number: The TCP port number for the NUT upsd daemon on the target device. If a value is not specified, the default value of "3493" will be used.
- timeout: The number of seconds to wait for the NUT session to be established. If a value is not specified, the Cacti configuration will be read for a locally-defined default value.
Taken as a whole, a valid NUT bundle for the localhost device on the default port number and a default timeout would be "localhost::".
The next parameter identifies the type of Cacti data that is being requested. Cacti uses "index" queries to enumerate all of the entries for a data query template, and then uses various kinds of "query" queries to obtain extended information about those entries (such as the full name of each indexed entry). Separately, the Cacti poller uses "get" queries to fetch the readings for each specific entry (again, keyed by index value). Note that he index and query operations are typically only performed when the device entry is being created or modified, and the get operations provide the actual readings to the poller. This script parameter must be one of those query types, with any remaining parameters providing any necessary supplemental data. Specifically the request parameters are one of the following:
- index: This request asks for a list of UPS device identifiers. No additional input data is needed. The response data is provided as a series of index values, with each UPS being enumerated on a separate response line.
- query <fieldname>: This request asks for the specified field data associated with each UPS device. The response data is provided as "index:data" pairs, where the index value is the primary device identifier, and the data value is the requested field data as available.
- get <fieldname> <ups>: This request asks for the specified field data associated with the specified UPS device. The requested data is provided by itself with no other accompanying information.
The field names that can be used in "query" or "get" requests are as follows:
- ups.device: The index value for the UPS device(s).
- ups.description: The human-friendly name for the UPS device(s).
- input.voltage: The input voltage for the UPS.
- input.frequency: The input line frequency for the UPS.
- battery.voltage: The battery voltage for the UPS.
- battery.charge: The level of the battery charge, as a percentage.
- ups.temperature: The temperature of the UPS or sometimes the battery.
- ups.load: The demand on the UPS as a percentage.
You must know the index value that has been assigned to a device before you can ask for details about that specific device. To do this, you can use the "query ups.description" request to get a list of UPS devices and their descriptions, and then use the "get <fieldname> <ups>" request to get information about the desired UPS. The full command lines for these requests, using example data from above, are shown below:
$ php ss_nut_ups_status.php hostname:: query ups.description SMART2200RMXL2U:Tripp-Lite SMART2200RMXL2U $ php ss_nut_ups_status.php hostname:: get ups.load SMART2200RMXL2U 23
Copyright © 2010-2017 Eric A. Hall.