Metadata-Version: 2.1
Name: rickslab-ups-utils
Version: 1.1.0
Summary: Ricks-Lab UPS Utilities
Home-page: https://github.com/Ricks-Lab/ups-utils
Author: RicksLabs
Author-email: rueikes.homelab@gmail.com
License: GPL-3
Project-URL: Bug Tracker, https://github.com/Ricks-Lab/ups-utils/issues
Project-URL: Documentation, https://github.com/Ricks-Lab/ups-utils/
Project-URL: Source Code, https://github.com/Ricks-Lab/ups-utils
Keywords: ups system monitoring apc eaton linux boinc
Platform: posix
Classifier: Development Status :: 5 - Production/Stable
Classifier: Operating System :: POSIX
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Power (UPS)
Classifier: Topic :: System :: Monitoring
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: pytz (>=2019.3)

![](https://img.shields.io/github/license/Ricks-Lab/ups-utils)
[![PyPI version](https://badge.fury.io/py/rickslab-ups-utils.svg)](https://badge.fury.io/py/rickslab-ups-utils)
[![Downloads](https://pepy.tech/badge/rickslab-ups-utils)](https://pepy.tech/project/rickslab-ups-utils)
![GitHub commit activity](https://img.shields.io/github/commit-activity/y/Ricks-Lab/ups-utils)
![GitHub last commit](https://img.shields.io/github/last-commit/Ricks-Lab/ups-utils)

# 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](https://pypi.org/project/rickslab-ups-utils/) 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](https://github.com/Ricks-Lab/ups-utils/blob/master/UPSmodules/UPSmodule.py) to support it, feel
free to make a pull request.

## Reference Material

* [apc-ups-snmp](https://github.com/phillipsnick/apc-ups-snmp)
* [Partial List of OIDs for APC UPS](https://www.opsview.com/resources/monitoring/blog/monitoring-apc-ups-useful-oids)
* [Another Partial List of OIDs for APC UPS](https://www.itninja.com/blog/view/snmp-oids-for-apc-smart-ups-3000-rm-xl)
* [Another Partial List of OIDs for APC UPS](https://wiki.netxms.org/wiki/UPS_Monitoring_(APC)_via_SNMP)
* [APC Reference](https://www.apc.com/salestools/LFLG-AFACYW/LFLG-AFACYW_R1_EN.pdf)
* [snmp utilities](http://www.net-snmp.org/docs/man/)
* [MIB Browser](http://www.ireasoning.com/)
* [Eaton PowerWalker NMC](https://powerwalker.com/?page=nmc&lang=en)

## New in Previous Release  -  v1.0.0

* Initial Release - Full functionality and working debian package!


