https://github.com/tomszilagyi/upsc-snmp-agent Skip to content Sign up Sign up * Why GitHub? Features - + Mobile - + Actions - + Codespaces - + Packages - + Security - + Code review - + Project management - + Integrations - + GitHub Sponsors - + Customer stories- * Team * Enterprise * Explore + Explore GitHub - Learn and contribute + Topics - + Collections - + Trending - + Learning Lab - + Open source guides - Connect with others + The ReadME Project - + Events - + Community forum - + GitHub Education - + GitHub Stars program - * Marketplace * Pricing Plans - + Compare plans - + Contact Sales - + Education - [ ] [search-key] * # In this repository All GitHub | Jump to | * No suggested jump to results * # In this repository All GitHub | Jump to | * # In this user All GitHub | Jump to | * # In this repository All GitHub | Jump to | Sign in Sign up Sign up {{ message }} tomszilagyi / upsc-snmp-agent * Notifications * Star 18 * Fork 1 Monitor your el-cheapo UPS via SNMP MIT License 18 stars 1 fork Star Notifications * Code * Issues 0 * Pull requests 0 * Actions * Projects 0 * Security * Insights More * Code * Issues * Pull requests * Actions * Projects * Security * Insights master Switch branches/tags [ ] Branches Tags Nothing to show {{ refName }} default View all branches Nothing to show {{ refName }} default View all tags 1 branch 0 tags Go to file Code Clone HTTPS GitHub CLI [https://github.com/t] Use Git or checkout with SVN using the web URL. [gh repo clone tomszi] Work fast with our official CLI. Learn more. * Open with GitHub Desktop * Download ZIP Launching GitHub Desktop If nothing happens, download GitHub Desktop and try again. Go back Launching GitHub Desktop If nothing happens, download GitHub Desktop and try again. Go back Launching Xcode If nothing happens, download Xcode and try again. Go back Launching Visual Studio If nothing happens, download the GitHub extension for Visual Studio and try again. Go back Latest commit Tom Szilagyi Expose stale data (upsc not functional) instead of serving default va... ... 8f35379 Mar 13, 2021 Expose stale data (upsc not functional) instead of serving default va... ...lues 8f35379 Git stats * 2 commits Files Permalink Failed to load latest commit information. Type Name Latest commit message Commit time doc Initial commit Mar 6, 2021 test Expose stale data (upsc not functional) instead of serving default va... Mar 13, 2021 .gitignore Initial commit Mar 6, 2021 LICENSE Initial commit Mar 6, 2021 README.org Initial commit Mar 6, 2021 upsc-snmp-agent.py Expose stale data (upsc not functional) instead of serving default va... Mar 13, 2021 View code README.org 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" About Monitor your el-cheapo UPS via SNMP Resources Readme License MIT License Releases No releases published Packages 0 No packages published Languages * Python 56.9% * Shell 43.1% * (c) 2021 GitHub, Inc. * Terms * Privacy * Security * Status * Docs * Contact GitHub * Pricing * API * Training * Blog * About You can't perform that action at this time. You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.