Monitor your el-cheapo UPS via SNMP

Overview

UPSC-SNMP-Agent

UPSC-SNMP-Agent exposes your el-cheapo locally connected UPS via the SNMP network management protocol. This enables various equipment (servers, NAS) to poll the status of the UPS in a standardized way over the network, and initiate proper shutdown procedures in case mains power has gone and the battery is nearing depletion.

Ingredients:

  • an UPS connected to a local system via whatever means (most commonly serial port or USB), set up to be queried via the tools provided by NUT (upsc);
  • one or more remote computing systems powered by this UPS (remote in the sense that the UPS is not directly connected to them) that are able to monitor an UPS via SNMP, and shut themselves down if they see the UPS battery reported as ‘low’.

If you find yourself in a position stuck with the above ingredients… well, that is a sign that you should have bought a real UPS (with out-of-the-box SNMP capabilities). But fear not, with minimal hacking and UPSC-SNMP-Agent, you might achieve very similar results.

On the other hand:

  • if your UPS natively supports SNMP;
  • if your remote computing systems can query the UPS via non-SNMP over-the-network queries provided by NUT;
  • if you can arrange for your local system to shut down the remote ones via different means (e.g., by some clever SHUTDOWNCMD);

… then you do not need UPSC-SNMP-Agent and should stop reading here!

License and Disclaimer

This program (UPSC-SNMP-Agent) is made available to you under a very permissive license, the MIT license (included in the file LICENSE). You can basically make use of it in whatever way you want, except pretending that you made it.

In exchange, please keep the following in mind: I am not responsible if your UPS goes down and takes down your critical infrastructure without notice (due to incorrect or misinterpreted data from this program). I am also not responsible in case your UPS is fine, but your critical infrastructure believes otherwise (due to the same reason) and goes down. Thoroughly and regularly test your setup for fault scenarios at times when taking down your critical infrastructure does not hurt, and don’t send me complaints (or worse) when it does!

What is this?

UPSC-SNMP-Agent, as its name tries to convey, is an SNMP agent, or at least a part thereof. That is, a component designed to answer SNMP queries on behalf of an UPS that, by itself, is not capable to do so.

To be more concrete: UPSC-SNMP-Agent translates the output of the upsc command (the simple UPS client, part of the NUT client tools) into (a useful subset of) the UPS-MIB, the standard (vendor-independent) MIB for UPS devices. This means that most SNMP-capable general computing devices interested in the status of an UPS will be able to query it.

UPSC-SNMP-Agent is not a full-blown SNMP agent in itself. It is implemented as a so-called “pass script” for Net-SNMP, the de-facto standard SNMP implementation for general-purpose computers. Essentially, UPSC-SNMP-Agent is a script to answer SNMP GET requests within the object tree of the UPS-MIB (everything under .1.3.6.1.2.1.33).

See this document for a tabular extract of the information presented by the UPS-MIB.

How do I use this?

Let’s say that you have your UPS set up, connected to the host theups.mylan. First, make sure that you are able to use the upsc command on this host and see relevant (and correct) output for your UPS. Setting up Network UPS Tools (NUT) to achieve this is a prerequisite, but documenting it is out of scope here.

Then, you need to install and setup snmpd on this system. This is also beyond the scope of this document; consult the Net-SNMP documentation. Make sure to set up the correct access controls for your environment. On the other hand, you do not need to install any MIBs (unless you need them for some other reason), so it is safe to ignore anything related.

Manually install the UPSC-SNMP-Agent script as /usr/bin/upsc-snmp-agent.py (or at any other location you desire). You also need python3 installed to be able to run it. Add a single hook in /etc/snmp/snmpd.conf to pass all queries of the UPS-MIB’s object identifiers to this script:

pass_persist .1.3.6.1.2.1.33 /usr/bin/python3 /usr/bin/upsc-snmp-agent.py

Now you need to make some changes to the upsc-snmp-agent.py script itself, see the next section Configuration.

After you are done with that, restart your snmpd and verify that you are able to query stuff (preferably from the remote machine for which you are doing this setup, or at least a different remote host). You need Net-SNMP or equivalent management/client tooling there. Assuming that you set up SNMP v2 with a read-only community of public, an snmpget test command would look like this:

$ snmpget -v2c -cpublic theups.mylan .1.3.6.1.2.1.33.1.1.4.0
SNMPv2-SMI::mib-2.33.1.1.4.0 = STRING: "UPSC-SNMP-Agent"

The above OID belongs to upsIdentAgentSoftwareVersion, and the returned value is proof that you have successfully queried just this program.

Configuration

Before deploying UPSC-SNMP-Agent for real use, you need to edit the script a little bit to make it fit your setup (under the comment that says CONFIGURATION). Most importantly, you have to set suitable default values for the things listed under upsDefaults. The variables listed here are the ones that UPSC-SNMP-Agent cares about from the set of variables potentially provided by NUT (as reported by upsc).

To tune your config, you will need to study the output of upsc for your specific UPS, preferably under different conditions: connected and charged; on battery; on low battery; just before forced shutdown (FSD).

Concentrate on the variables in upsDefaults that are missing from your upsc output. These need meaningful default values, since they will not be populated by actual data from the UPS. You also have the option of leaving them out of upsDefaults; in that case SNMP requests for them will get the ‘no such object’ response. If your data consumers can deal with it, this might be a conceptually better solution than ‘faking’ a value. For example, your UPS might not report a value for battery.temperature; but chances are good that your consumers do not care about it either.

Of particular importance is the value of battery.charge.warning. This will act as the threshold for battery.charge under which the upsBatteryStatus MIB variable will be reported as low. This will commonly trigger monitoring devices to initiate their shutdown sequences, so make sure to set battery.charge.warning as appropriate to your needs (considering the behaviour of your UPS, as well as the time your connected devices require for a clean shutdown). If your UPS is supported by a NUT driver that supplies you with an actual battery.charge.warning value, then you can relax about this (but you still need to test your setup thoroughly).

Limitations

  • No setting of any values – this agent provides read-only access only.
  • SNMP GETNEXT requests are not supported, only GET.
  • Only one input and one output line is supported (this is for simple and small UPS devices, after all).
  • Missing support for some MIB-defined variables, because they do not have suitable counterparts among the upsc output variables:
    • upsInputLineBads counter is not supported.
    • upsEstimatedMinutesRemaining is not supported.
    • upsConfigLowBattTime is not supported.
  • Hardcoded values are reported for the following queries:
    • alarms: reported as “no alarms present”
    • tests: reported as “no tests initiated”
    • countdown timers for shutdown, reboot, startup: reported as “no countdown in effect”
You might also like...
Discord bot to monitor collection of mods on the Steam Workshop and notify on update to selected discord server via Nextcordbot API.
Discord bot to monitor collection of mods on the Steam Workshop and notify on update to selected discord server via Nextcordbot API.

Steam-Workshop-Monitor Discord bot to monitor collection of mods on the Steam Workshop and notify on update to selected Discord channel via Nextcordbo

Nagios status monitor for your desktop.

Nagstamon Nagstamon is a status monitor for the desktop. It connects to multiple Nagios, Icinga, Opsview, Centreon, Op5 Monitor/Ninja, Checkmk Multisi

A global contest to grow and monitor your own food with Raspberry Pi
A global contest to grow and monitor your own food with Raspberry Pi

growlab A global contest to grow and monitor your own food with Raspberry Pi A capture from phototimer of my seed tray with a wide-angle camera positi

Monitor your Binance portfolio

Binance Report Bot The intent of this bot is to take a snapshot of your binance wallet, e.g. the current balances and store it for further plotting. I

Monitor your ML jobs on mobile devices📱, especially for Google Colab / Kaggle
Monitor your ML jobs on mobile devices📱, especially for Google Colab / Kaggle

TF Watcher TF Watcher is a simple to use Python package and web app which allows you to monitor 👀 your Machine Learning training or testing process o

Watch your Docker registry project size, then monitor it with Grafana.
Watch your Docker registry project size, then monitor it with Grafana.

Watch your Docker registry project size, then monitor it with Grafana.

A monitor than send discord webhook when a specific monitored product has stock in your nearby pickup stores.
A monitor than send discord webhook when a specific monitored product has stock in your nearby pickup stores.

Welcome to Apple In-store Monitor This is a monitor that are not fully scaled, and might still have some bugs.

Monitor creation, deletion and changes to LDAP objects live during your pentest or system administration!
Monitor creation, deletion and changes to LDAP objects live during your pentest or system administration!

LDAP Monitor Monitor creation, deletion and changes to LDAP objects live during your pentest or system administration! With this tool you can quickly

Dashboard to monitor the performance of your Binance Futures account
Dashboard to monitor the performance of your Binance Futures account

futuresboard A python based scraper and dashboard to monitor the performance of your Binance Futures account. Note: A local sqlite3 database config/fu

ShotsGram - For sending captures from your monitor to a telegram chat (robot)

ShotsGram pt-BR Envios de capturas do seu monitor para um chat do telegram. Essa

Ipscanner - A simple threaded IP-Scanner written in python3 that can monitor local IP's in your network

IPScanner 🔬 A simple threaded IP-Scanner written in python3 that can monitor lo

Your own movie streaming service. Easy to install, easy to use. Download, manage and watch your favorite movies conveniently from your browser or phone. Install it on your server, access it anywhere and enjoy.
Your own movie streaming service. Easy to install, easy to use. Download, manage and watch your favorite movies conveniently from your browser or phone. Install it on your server, access it anywhere and enjoy.

Vigilio Your own movie streaming service. Easy to install, easy to use. Download, manage and watch your favorite movies conveniently from your browser

Real-time monitor and web admin for Celery distributed task queue

Flower Flower is a web based tool for monitoring and administrating Celery clusters. Features Real-time monitoring using Celery Events Task progress a

Monitor Memory usage of Python code
Monitor Memory usage of Python code

Memory Profiler This is a python module for monitoring memory consumption of a process as well as line-by-line analysis of memory consumption for pyth

Python library and shell utilities to monitor filesystem events.

Watchdog Python API and shell utilities to monitor file system events. Works on 3.6+. If you want to use Python 2.6, you should stick with watchdog

Safe temperature monitor for baby's room. Made for Raspberry Pi Pico.
Safe temperature monitor for baby's room. Made for Raspberry Pi Pico.

Baby Safe Temperature Monitor This project is meant to build a temperature safety monitor for a baby or small child's room. Studies have shown the ris

Automatically monitor the evolving performance of Flask/Python web services.
Automatically monitor the evolving performance of Flask/Python web services.

Flask Monitoring Dashboard A dashboard for automatic monitoring of Flask web-services. Key Features • How to use • Live Demo • Feedback • Documentatio

Monitor Memory usage of Python code
Monitor Memory usage of Python code

Memory Profiler This is a python module for monitoring memory consumption of a process as well as line-by-line analysis of memory consumption for pyth

Development tool to measure, monitor and analyze the memory behavior of Python objects in a running Python application.

README for pympler Before installing Pympler, try it with your Python version: python setup.py try If any errors are reported, check whether your Pyt

Owner
Tom Szilagyi
Tom Szilagyi
An opensource library to use SNMP get/bulk/set/walk in Python

SNMP-UTILS An opensource library to use SNMP get/bulk/set/walk in Python Features Work with OIDS json list [Find Here](#OIDS List) GET command SET com

Alexandre Gossard 3 Aug 3, 2022
Juniper SNMP Migrations For Python

Juniper SNMP Migrations This example will show how to use the PyEZ plugin for Nornir to build a NETCONF connection to a remote device validate that SN

Calvin Remsburg 1 Jan 7, 2022
Wrapper around the UPS API for creating shipping labels and fetching a package's tracking status.

ClassicUPS: A Useful UPS Library ClassicUPS is an Apache2 Licensed wrapper around the UPS API for creating shipping labels and fetching a package's tr

Jay Goel 55 Dec 12, 2022
A collection of write-ups and solutions for Cyber FastTrack Spring 2021.

IMPORTANT: Please contact us before you use any styling or content shown here! Cyber FastTrack Spring 2021 / National Cyber Scholarship Competition -

Alice 48 Aug 28, 2022
Write-ups for the SwissHackingChallenge2021 CTF.

SwissHackingChallenge 2021 : Write-ups This repository contains a collection of my write-ups for challenges solved during the SwissHackingChallenge (S

Julien Béguin 3 Jun 7, 2021
Integrates a UPS monitored by NUT into OctoPrint

OctoPrint UPS This OctoPrint plugin interfaces with a UPS monitored by NUT (Network UPS Tools). Requirements NUT must be configured by the user. This

Shawn Bruce 11 Jul 5, 2022
CTF challenges and write-ups for MicroCTF 2021.

MicroCTF 2021 Qualifications About This repository contains CTF challenges and official write-ups for MicroCTF 2021 Qualifications. License Distribute

Shellmates 12 Dec 27, 2022
Write-ups for CTF Internacional MetaRed 2021 5th stage

MetaRed2021-5th-Writeups Write-ups for CTF Internacional MetaRed 2021 5th stage Easy (15) No Status Category Name Creator(s) 01 Done osint Cybersecuri

UA Cybersecurity 2 Dec 22, 2021
Trackthis - This library can be used to track USPS and UPS shipments.

Trackthis - This library can be used to track USPS and UPS shipments. It has the option of returning the raw API response, or optionally, it can be used to standardize the USPS and UPS responses so they are easier to work with.

Aaron Guzman 0 Mar 29, 2022
Description NerdQuest is a social site for creating events and/or meet ups based on games.

NerdQuest Description NerdQuest is a social site for creating events and/or meet

David Allen 1 Jul 11, 2022