rickslab-ups-utils 1.1.1

Ricks-Lab UPS Utilities

rickslab-ups-utils

A set of utilities to monitor and react to the status of a supported UPS

Installation

Debian Package Installation

First, remove any previous PyPI installation and exit that terminal:

pip uninstall rickslab-ups-utils
exit

Next, add the rickslab-ups-utils repository:

wget -q -O - https://debian.rickslab.com/PUBLIC.KEY | sudo apt-key add -

echo 'deb [arch=amd64] https://debian.rickslab.com/ups-utils/ stable main' | sudo tee /etc/apt/sources.list.d/rickslab-ups-utils.list

sudo apt update

Then install the package with apt:

sudo apt install rickslab-ups-utils

After installation, you will need to create a new group, upsutils, and add trusted users to this group. This required for this type of installation in order to secure the snmp shared secret stored in the configuration files:

sudo groupadd upsutils
sudo usermod -a -G upsutils $LOGNAME

After adding the user to a new group, the user must logout and relogin before the change is in effect.

PyPI Installation

Install the latest package from PyPI with the following commands:

pip3 uninstall rickslab-ups-utils
pip3 install rickslab-ups-utils

The uninstall is required to make sure all modules are updated. If you still get an old version, then specify not to use cached files:

pip3 install --no-cache-dir rickslab-ups-utils

Getting Started

Application configuration parameters can be specified in the ups-utils.ini file. A template files is provided: ups-utils.ini.template. You can verify the values of the configuration settings by executing:

ups-daemon --list_params

Also, a UPS list must be specified in the ups-config.json file using ups-config.json.template as a template. This file contains details about each UPS that make snmp communication possible. The utility requires snmp v2c in order to communicate with the network accessible UPSs. As a result, you must configure your target Network attached UPS devices to use SNMPv2 with a known Private Community String.

If you installed from debian package, the template configuration files will be owned by root. When you create your configuration files from the templates, you MUST change group ownership to upsutils and change permissions to 660:

cd /usr/share/rickslab-ups-utils/config/
sudo chgrp upsutils ups-utils.ini ups-config.json
sudo chmod 660 ups-utils.ini ups-config.json

The ups-utils rely on the command snmpget which is part of the snmp package that must be installed:

sudo apt install snmp

ups-daemon

With no options specified, the utility will give the current status of the UPS configured with daemon = true in the ups-config.json file. With the --daemon option, ups-daemon will continuously check the status of the UPS. When it detects that the UPS is sourcing powering from the battery, it will check the amount of time it has been running on battery and run the specified suspend script when the specified threshold is exceeded. It will execute the specified resume script when it detects power has resumed. When the utility detects a Battery Low event from the UPS or that time remaining for battery or the battery charge is below specified thresholds, then the shutdown script will be executed. If ups-deamon detects a return to line power has occurred before the shutdown has completed, it will execute the cancel shutdown script. With the --verbose option set, no event update messages will be output, otherwise, only events are output. With the --list_commands option, the utility will list all available SNMP commands for the configured UPS. With the --list_params option, the daemon configuration parameters will be listed. The --logfile filename option is used to specify a logfile, but is not implemented at this time. The threshold and script definitions must be made in the config.py file using config.py.template as a template.

ups-ls

This utility displays most relevant parameters for installed and compatible UPSs listed in the ups-config.json file. By default, all available parameters are displayed. The --input and --output options can be used to get relevant UPS input and output parameters.

ups-monitor

A utility to give the current state of all compatible UPSs. The default behavior is to continuously update a text based table in the current window until Ctrl-C is pressed. With the --gui option, a table of relevant parameters will be updated in a Gtk window. You can specify the delay between updates with the --sleep N option where N is an integer > 10 that specifies the number of seconds to sleep between updates. The --log option is used to write all monitor data to a psv log file. When writing to a log file, the utility will indicate this in red at the top of the window with a message that includes the log file name. The --status option will output a table of the current status. The --long option will include additional informational parameters. By default, unresponsive UPSs will not be displayed, but the --show_unresponsive can be used to force their display.

New in Development

• Delay sys exit on failure to allow more information to be available for user to troubleshoot.
• Check file permissions for security issues and exit if not secure.
• Determine installation type (Local Git Repository, PyPI, or Debian), and force use of Debian location for configuration files if it is a debian installation.
• The ups-utils.ini file is now only required for ups-daemon. Other utilities will use defaults if missing.
• Added verbose option to ups-daemon to output status message for normal readings.
• Changes in documentation to describe steps necessary to secure snmp shared secret.
• Added check of configuration files readability.

Known Issues

The utility currently supports:

• APC UPS with AP9630 NMC
• EATON UPS with PowerWalker NMC

It monitors the specified UPS using snmp v2c. I have not implemented the ability to listen to snmp traps yet, as I still have some research to do. If you have different UPS and would like to extend the dictionary in this code to support it, feel free to make a pull request.

Reference Material

• apc-ups-snmp
• Partial List of OIDs for APC UPS
• Another Partial List of OIDs for APC UPS
• Another Partial List of OIDs for APC UPS
• APC Reference
• snmp utilities
• MIB Browser
• Eaton PowerWalker NMC

New in Previous Release - v1.0.0

• Initial Release - Full functionality and working debian package!