# rickslab-ups-utils
A set of utilities to monitor and react to the status of a set of supported UPSs.
## Installation
There are currently 3 possible ways of installing *rickslab-ups-utils* as summarized here:
* [Repository](https://github.com/Ricks-Lab/ups-utils/blob/master/docs/USER_GUIDE.md#repository-installation) -
You can always clone the repository and run that version. This is useful if you want to contribute to the project.
* [PyPI](https://github.com/Ricks-Lab/ups-utils/blob/master/docs/USER_GUIDE.md#pypi-installation) -
Meant for users wanting to run the very latest version. All **PATCH** level versions are released
here first. This installation method is also meant for users not on a Debian distribution.
[](https://badge.fury.io/py/rickslab-ups-utils)
[](https://pepy.tech/project/rickslab-ups-utils)
* [Rickslab.com Debian](https://github.com/Ricks-Lab/ups-utils/blob/master/docs/USER_GUIDE.md#rickslabcom-debian-installation) -
Lags the PyPI release in order to assure robustness. May not include every **PATCH** version.
## User Guide
For a detailed introduction, a community sourced
[User Guide](https://github.com/Ricks-Lab/ups-utils/blob/master/docs/USER_GUIDE.md)
is available. All tools are demonstrated and use cases are presented. Additions
to the guide are welcome. Please submit a pull request with your suggested additions!
## Commands
### 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. 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 *--list_decoders* option will display list of all MiB decoders available
for the UPS defined as daemon target. The *--verbose* will cause informational
messages to be displayed and *--no_markup* option will result in plain text
output instead of color coded text. The logger is enabled with the *--debug*
option.
### 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-daemon* 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,
event update messages will be output, otherwise, only events are output.
The *--no_markup* option will cause the output to be in plain text, with
no color markup codes. 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 *ups-utils.ini* file using
*ups-utils.ini.template* as a template. The logger is enabled with the
*--debug* option. The *--ltz* option will result in the use of the local
time zone in the monitor window and logs. This will be the local time of
where the app is running, not the location of the UPS. The default is UTC.
### ups-mon
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 threshold for
color coding definitions read from the *ups-utils.ini* file. This can be
created from a template *ups-utils.ini.template*, that is part of the
installation package. *ups-utils.ini.template* as a template. 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. By default, unresponsive
UPSs will not be displayed, but the *--show_unresponsive* can be used to
force their display. The logger is enabled with the *--debug* option. The
*--ltz* option will result in the use of the local time zone in the
monitor window and logs. This will be the local time of where the app is
running, not the location of the UPS. The default is UTC.
## New in Current Release - v1.3.0
* Implemented Enum objects as keys.
* Defaults to text ups-mon window when Gtk is not available.
* Code clean up.
## Known Issues
The utility currently supports:
* APC UPS with AP9630 and AP9641 NMC
* EATON UPS with PowerWalker NMC. I had an issue with voltage interpretation, and
found that PowerWalker does not support the use of their NMC with Eaton UPS. But it
mostly works anyway. I no longer have any Eaton UPSs for testing.
It monitors the specified UPSs 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)
## History
### New in Previous Release - v1.2.11
* Fix GObject.timeout_add deprecation.
* Update repository installation guide and add requirements file.
* Many minor changes.
### New in Previous Release - v1.2.10
* Optimize `ups-ls --about` output.
* Improved messaging to aid new users in configuring new setup.
* Detect specification of multiple daemon UPS. Must only be one target daemon UPS.
### New in Previous Release - v1.2.9
* Fixed error handling for config file reading.
* Exit ups-daemon if no daemon ups is defined.
* Added details on adding *upsutils* group and other configuration details.
### New in Previous Release - v1.2.8
* Improved *ups-mon --gui* eventual stack overflow. Still hangs after long
runs. I need some help on this one.
* Add time of last read to *ups-mon* header.
* Implemented option to display/log in local time. Local time is the time
where the application is running; not the location of the UPS.
### New in Previous Release - v1.2.7
* Updates to the User Guide.
* Cleaned up implementation of GuiComp object.
* Fixed an error in the calculation of time on battery and battery remaining
for APC. Now just store time in minutes in data structure and drop the string version.
* Include time on battery in color coding logic.
* More code optimizations.
* Improved LOGGER.debug messages.
### New in Previous Release - v1.2.5
* Improved message for skipped parameters.
* Rewrite daemon configuration reader to make more robust.
* Catch errors for json and config readers and handle with feedback to user.
* User guide updates.
### New in Previous Release - v1.2.4
* More robust reading of config file. Missing items will generate a warning
message and defaults will be used.
* The PyPI installation still seems to include *ups-monitor*, so I will print
message and inform user to use *ups-mon* instead.
### New in Previous Release - v1.2.3
* Fixed issue in installation instructions that indicated gpu instead of ups.
* More error checking. Make APC NMC names backward compatible and more flexible.
### New in Previous Release - v1.2.2
* Fixed crash when config files are missing and improved feedback to help
user resolve. Update documents to make more clear to user on how to setup.
* Modified the *--about* of *ups-ls* to aid user in configuring the utility.
### New in Previous Release - v1.2.1
* Fixed issue in referencing PyPI install resource paths.
### New in Previous Release - v1.2.0
* 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.
* Implement code improvements from gpu-utils project.
* Move listing like functions from *ups-daemon* to *ups-ls*.
* Complete rewrite.
* USR1 signal will cause *ups-mon* and *ups-daemon* to reread daemon ini file.
* Moved logic of daemon parameter color coding to the daemon class.
### New in Previous Release - v1.0.0
* Initial Release - Full functionality and working debian package!
Raw data
{
"_id": null,
"home_page": "https://github.com/Ricks-Lab/ups-utils",
"name": "rickslab-ups-utils",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "ups system monitoring apc eaton linux boinc",
"author": "RicksLabs",
"author_email": "rueikes.homelab@gmail.com",
"download_url": "",
"platform": "posix",
"description": "\n\n\n\n\n# rickslab-ups-utils\n\nA set of utilities to monitor and react to the status of a set of supported UPSs.\n\n## Installation\n\nThere are currently 3 possible ways of installing *rickslab-ups-utils* as summarized here:\n\n* [Repository](https://github.com/Ricks-Lab/ups-utils/blob/master/docs/USER_GUIDE.md#repository-installation) -\nYou can always clone the repository and run that version. This is useful if you want to contribute to the project.\n\n \n* [PyPI](https://github.com/Ricks-Lab/ups-utils/blob/master/docs/USER_GUIDE.md#pypi-installation) -\nMeant for users wanting to run the very latest version. All **PATCH** level versions are released\nhere first. This installation method is also meant for users not on a Debian distribution.\n\n [](https://badge.fury.io/py/rickslab-ups-utils)\n [](https://pepy.tech/project/rickslab-ups-utils)\n* [Rickslab.com Debian](https://github.com/Ricks-Lab/ups-utils/blob/master/docs/USER_GUIDE.md#rickslabcom-debian-installation) -\n Lags the PyPI release in order to assure robustness. May not include every **PATCH** version.\n\n \n \n\n## User Guide\n\nFor a detailed introduction, a community sourced\n[User Guide](https://github.com/Ricks-Lab/ups-utils/blob/master/docs/USER_GUIDE.md)\nis available. All tools are demonstrated and use cases are presented. Additions\nto the guide are welcome. Please submit a pull request with your suggested additions!\n\n## Commands\n\n### ups-ls\n\nThis utility displays most relevant parameters for installed and compatible\nUPSs listed in the *ups-config.json* file. By default, all available parameters\nare displayed. The *--input* and *--output* options can be used to get relevant\nUPS input and output parameters. With the *--list_commands* option, the\nutility will list all available SNMP commands for the configured UPS. With\nthe *--list_params* option, the daemon configuration parameters will be listed.\nThe *--list_decoders* option will display list of all MiB decoders available\nfor the UPS defined as daemon target. The *--verbose* will cause informational\nmessages to be displayed and *--no_markup* option will result in plain text\noutput instead of color coded text. The logger is enabled with the *--debug*\noption.\n\n### ups-daemon\n\nWith no options specified, the utility will give the current status of the\nUPS configured with *daemon = true* in the ups-config.json file. With the\n*--daemon* option, *ups-daemon* will continuously check the status of the\nUPS. When it detects that the UPS is sourcing powering from the battery,\nit will check the amount of time it has been running on battery and run\nthe specified suspend script when the specified threshold is exceeded. It\nwill execute the specified resume script when it detects power has resumed.\nWhen the utility detects a Battery Low event from the UPS or that time\nremaining for battery or the battery charge is below specified thresholds,\nthen the shutdown script will be executed. If *ups-daemon* detects a return\nto line power has occurred before the shutdown has completed, it will\nexecute the cancel shutdown script. With the *--verbose* option set,\nevent update messages will be output, otherwise, only events are output.\nThe *--no_markup* option will cause the output to be in plain text, with\nno color markup codes. The *--logfile filename* option is used to specify\na logfile, but is not implemented at this time. The threshold and script\ndefinitions must be made in the *ups-utils.ini* file using\n*ups-utils.ini.template* as a template. The logger is enabled with the\n*--debug* option. The *--ltz* option will result in the use of the local\ntime zone in the monitor window and logs. This will be the local time of\nwhere the app is running, not the location of the UPS. The default is UTC.\n\n### ups-mon\n\nA utility to give the current state of all compatible UPSs. The default\nbehavior is to continuously update a text based table in the current window\nuntil Ctrl-C is pressed. With the *--gui* option, a table of relevant\nparameters will be updated in a Gtk window. You can specify the delay\nbetween updates with the *--sleep N* option where N is an integer > 10 that\nspecifies the number of seconds to sleep between updates. The threshold for\ncolor coding definitions read from the *ups-utils.ini* file. This can be\ncreated from a template *ups-utils.ini.template*, that is part of the\ninstallation package. *ups-utils.ini.template* as a template. The *--log*\noption is used to write all monitor data to a psv log file. When writing\nto a log file, the utility will indicate this in red at the top of the\nwindow with a message that includes the log file name. The *--status*\noption will output a table of the current status. By default, unresponsive\nUPSs will not be displayed, but the *--show_unresponsive* can be used to\nforce their display. The logger is enabled with the *--debug* option. The\n*--ltz* option will result in the use of the local time zone in the\nmonitor window and logs. This will be the local time of where the app is\nrunning, not the location of the UPS. The default is UTC.\n\n## New in Current Release - v1.3.0\n\n* Implemented Enum objects as keys.\n* Defaults to text ups-mon window when Gtk is not available.\n* Code clean up.\n\n## Known Issues\n\nThe utility currently supports:\n\n* APC UPS with AP9630 and AP9641 NMC\n* EATON UPS with PowerWalker NMC. I had an issue with voltage interpretation, and\nfound that PowerWalker does not support the use of their NMC with Eaton UPS. But it \nmostly works anyway. I no longer have any Eaton UPSs for testing.\n\nIt monitors the specified UPSs using snmp v2c. I have not implemented the\nability to listen to snmp traps yet, as I still have some research to do.\nIf you have different UPS and would like to extend the dictionary in this\n[code](https://github.com/Ricks-Lab/ups-utils/blob/master/UPSmodules/UPSmodule.py)\nto support it, feel free to make a pull request.\n\n## Reference Material\n\n* [apc-ups-snmp](https://github.com/phillipsnick/apc-ups-snmp)\n* [Partial List of OIDs for APC UPS](https://www.opsview.com/resources/monitoring/blog/monitoring-apc-ups-useful-oids)\n* [Another Partial List of OIDs for APC UPS](https://www.itninja.com/blog/view/snmp-oids-for-apc-smart-ups-3000-rm-xl)\n* [Another Partial List of OIDs for APC UPS](https://wiki.netxms.org/wiki/UPS_Monitoring_(APC)_via_SNMP)\n* [APC Reference](https://www.apc.com/salestools/LFLG-AFACYW/LFLG-AFACYW_R1_EN.pdf)\n* [snmp utilities](http://www.net-snmp.org/docs/man/)\n* [MIB Browser](http://www.ireasoning.com/)\n* [Eaton PowerWalker NMC](https://powerwalker.com/?page=nmc&lang=en)\n\n## History\n\n### New in Previous Release - v1.2.11\n\n* Fix GObject.timeout_add deprecation.\n* Update repository installation guide and add requirements file.\n* Many minor changes.\n\n### New in Previous Release - v1.2.10\n\n* Optimize `ups-ls --about` output.\n* Improved messaging to aid new users in configuring new setup.\n* Detect specification of multiple daemon UPS. Must only be one target daemon UPS.\n\n### New in Previous Release - v1.2.9\n\n* Fixed error handling for config file reading.\n* Exit ups-daemon if no daemon ups is defined.\n* Added details on adding *upsutils* group and other configuration details.\n\n### New in Previous Release - v1.2.8\n\n* Improved *ups-mon --gui* eventual stack overflow. Still hangs after long\n runs. I need some help on this one.\n* Add time of last read to *ups-mon* header.\n* Implemented option to display/log in local time. Local time is the time\n where the application is running; not the location of the UPS.\n\n### New in Previous Release - v1.2.7\n\n* Updates to the User Guide.\n* Cleaned up implementation of GuiComp object.\n* Fixed an error in the calculation of time on battery and battery remaining\n for APC. Now just store time in minutes in data structure and drop the string version.\n* Include time on battery in color coding logic.\n* More code optimizations.\n* Improved LOGGER.debug messages.\n\n### New in Previous Release - v1.2.5\n\n* Improved message for skipped parameters.\n* Rewrite daemon configuration reader to make more robust.\n* Catch errors for json and config readers and handle with feedback to user.\n* User guide updates.\n\n### New in Previous Release - v1.2.4\n\n* More robust reading of config file. Missing items will generate a warning\n message and defaults will be used.\n* The PyPI installation still seems to include *ups-monitor*, so I will print\n message and inform user to use *ups-mon* instead.\n\n### New in Previous Release - v1.2.3\n\n* Fixed issue in installation instructions that indicated gpu instead of ups.\n* More error checking. Make APC NMC names backward compatible and more flexible.\n\n### New in Previous Release - v1.2.2\n\n* Fixed crash when config files are missing and improved feedback to help\n user resolve. Update documents to make more clear to user on how to setup.\n* Modified the *--about* of *ups-ls* to aid user in configuring the utility.\n\n### New in Previous Release - v1.2.1\n\n* Fixed issue in referencing PyPI install resource paths.\n\n### New in Previous Release - v1.2.0\n\n* Delay sys exit on failure to allow more information to be available for user to troubleshoot.\n* Check file permissions for security issues and exit if not secure.\n* Determine installation type (Local Git Repository, PyPI, or Debian), and force use\n of Debian location for configuration files if it is a debian installation.\n* The ups-utils.ini file is now only required for ups-daemon. Other utilities will\n use defaults if missing.\n* Added verbose option to ups-daemon to output status message for normal readings.\n* Changes in documentation to describe steps necessary to secure snmp shared secret.\n* Added check of configuration files readability.\n* Implement code improvements from gpu-utils project.\n* Move listing like functions from *ups-daemon* to *ups-ls*.\n* Complete rewrite.\n* USR1 signal will cause *ups-mon* and *ups-daemon* to reread daemon ini file.\n* Moved logic of daemon parameter color coding to the daemon class.\n\n### New in Previous Release - v1.0.0\n\n* Initial Release - Full functionality and working debian package!\n\n\n",
"bugtrack_url": null,
"license": "GPL-3",
"summary": "Ricks-Lab UPS Utilities",
"version": "1.3.0",
"project_urls": {
"Bug Tracker": "https://github.com/Ricks-Lab/ups-utils/issues",
"Documentation": "https://github.com/Ricks-Lab/ups-utils/",
"Homepage": "https://github.com/Ricks-Lab/ups-utils",
"Source Code": "https://github.com/Ricks-Lab/ups-utils"
},
"split_keywords": [
"ups",
"system",
"monitoring",
"apc",
"eaton",
"linux",
"boinc"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e267d77a49702cabcaa7f6bfdac4fe1953bbea568925088adfc0bb609f9581ce",
"md5": "d35620317e3d26f547113eaa3d622977",
"sha256": "1107a9fe453b2b8d0e14c0ead9bd0e8239fb1ded235439c7e73aac3c20cde3b0"
},
"downloads": -1,
"filename": "rickslab_ups_utils-1.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d35620317e3d26f547113eaa3d622977",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 99435,
"upload_time": "2023-10-07T05:51:30",
"upload_time_iso_8601": "2023-10-07T05:51:30.182296Z",
"url": "https://files.pythonhosted.org/packages/e2/67/d77a49702cabcaa7f6bfdac4fe1953bbea568925088adfc0bb609f9581ce/rickslab_ups_utils-1.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-07 05:51:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Ricks-Lab",
"github_project": "ups-utils",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "rickslab-ups-utils"
}
JSON
