PowerAlert UPS Monitor
Tripp-Lite PowerAlert is a UPS monitoring and management program designed for use with Tripp-Lite UPS systems, although it can also be used with a variety of other vendors' equipment. Moreover, PowerAlert v12 is designed to be queried by software agents on the network, which it does by exposing information about the local UPS devices via SNMP tables on a private port number. This script template takes advantage of this design by acting as a PowerAlert client, querying the PowerAlert v12 daemons through the private interface, extracting the operational information for each of the connected UPS devices, and then generating multiple graphs from the collected data.
For illustration purposes, the graphs in the figures at right show the "Power Input" graphs for a Windows 2003 server running PowerAlert 12.04 communicating with an MGE Pulsar Evolution 1100 and a Tripp-Lite SMART2200RMXL2U via local USB interfaces, while the additional pair of graphs below show the "Load Capacity" output for the same two devices, and a separate graph shows the battery temperature for the Tripp-Lite UPS. I also use these same tools to monitor the same data on a variety of APC ES 650 and 750 UPS devices that serve the individual desktop systems. However, PowerAlert does not provide all of the data from all of the UPS devices—of the three UPS brands I have in use here, PowerAlert only displays the full set of data for the Tripp-Lite UPS.
Specifically, the PowerAlert software has a few dozen device variables that it tries to track and make available to other PowerAlert nodes on the network, although the amount of data that it can make available depends on how much information it is able to extract from the UPS device itself. The attributes that can be monitored are enumerated in an SNMP table by name, with the associated values being stored in a sister table.
Since the attributes are not keyed to common OIDs, but instead are keyed to the textual attribute name, it is necessary to use a script in order to first determine the data that is available, and then to query for the associated values after that. Furthermore, the use of an application-specific SNMP community string and port number also creates some difficulties, since Cacti does not currently provide a way to store application-specific variables with a device.
Note that the PowerAlert software architecture has recently changed, and depending on your needs, you may want to use either PowerAlert v12.03 or v12.04. PowerAlert v12.03 used a peer-to-peer model whereby every installation was capable of monitoring remote PowerAleter nodes, and was also capable of being monitored by other PowerAlert nodes. Meanwhile, PowerAlert v12.04 introduced a more rigid client-server hierarchy, whereby PowerAlert Local provided server functionality only and was not able to monitor remote devices, while separate shutdown agents were used to monitor the server devices. v12.04 is more appropriate if you limit your UPS devices to a few server devices, but v12.03 is more appropriate if you use a combination of local and remote UPS devices to provide protection at multiple layers. The two versions are interoperable with each other, so it's possible to use v12.03 on some systems and v12.04 on others without much trouble.
To use this script template, perform the following steps:
- Download and install the PowerAlert component software that is most appropriate for your network architecture, and configure it accordingly. Verify that a PowerAlert server agent is running on the target system and responding to SNMP queries by using the snmpwalk command with the community name of "tlremote" or "public" or "tripplite" and the SNMP port number of 3664.
- Download cacti-poweralert.0.6.tar.gz to a temporary directory on the Cacti server machine.
- Expand the archive with the command
tar -xvzf cacti-poweralert.0.6.tar.gz, and change to the cacti-poweralert directory that is created.
- Copy scripts/ss_poweralert_ups_status.php to the <cacti>/scripts/ directory.
- Copy resource/poweralert_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/poweralert_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 one of the PowerAlert v12 server agents, and scroll down to the "Associated Data Queries" table. Select "TrippLite PowerAlert - UPS Statistics" in the "Add Data Query" drop-down box, and click the "Add" button.
- After the Device screen reloads, verify that the "TrippLite PowerAlert - 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 "TrippLite PowerAlert - UPS Statistics" data query, which should be similar to the figure at right. 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 SNMP version in use and the output that is desired.
The first parameter group provides an SNMP protocol "bundle" of the following values, separated by colon characters: In those cases where a value is unneeded (such as SNMP v3 authentication credentials for an SNMP v2 query), or where a default value is adequate (such as the SNMP port number), the value can be omitted.
- hostname: The domain name or IP address of the target device. This value is mandatory.
- version: The version of SNMP to use. The remaining parameter values will be verified against this value, and is mandatory.
- community: The SNMP community string to use. If version 1 or 2 was specified, the community string must be provided. If version 3 was specified, this value will be ignored. Note that PowerAlert typically uses "tlremote" as the default string, and this community string is used in the XML resource definition, but PowerAlert will also often respond to "public" and other strings.
- v3 username: Part of the credentials for SNMP v3 queries. If version 1 or 2 was specified, this value will be ignored.
- v3 password : Part of the credentials for SNMP v3 queries. If version 1 or 2 was specified, this value will be ignored.
- v3 authentication protocol : Part of the credentials for SNMP v3 queries. If version 1 or 2 was specified, this value will be ignored.
- v3 privilege password : Part of the credentials for SNMP v3 queries. If version 1 or 2 was specified, this value will be ignored.
- v3 privilige protocol : Part of the credentials for SNMP v3 queries. If version 1 or 2 was specified, this value will be ignored.
- v3 authentication context : Part of the credentials for SNMP v3 queries. If version 1 or 2 was specified, this value will be ignored.
- port number: The UDP port number for the SNMP daemon on the target device. If a value is not specified, the default value of "3664" will be used.
- timeout: The number of seconds to wait for the SNMP query to be executed. If a value is not specified, the Cacti configuration will be read for a locally-defined default value.
Taken as a whole, a valid SNMP bundle for the localhost device using SNMP v2 with the community string of "tlremote" on the default port number and a default timeout would be "localhost:2:tlremote::::::::".
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:
- upsdevice: The index value for the UPS device(s).
- upsname: The human-friendly name for the UPS device(s).
- inputvoltage: The input voltage for the UPS.
- inputfrequency: The input line frequency for the UPS.
- batteryvoltage: The battery voltage for the UPS.
- batterycharge: The level of the battery charge, as a percentage.
- batterytemperature: The temperature of the battery or sometimes the UPS.
- outputload: The demand on the UPS as a percentage of available output.
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 upsname" 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_poweralert_ups_status.php hostname:2:tlremote:::::::: query upsname 1:SMART2200RMXL2U 2:Evolution 1100 $ php ss_poweralert_ups_status.php hostname:2:tlremote:::::::: get outputload 1 23