banshee/hardware-collection/hardware/ups/apc/snmp/
status
The battery to replace, defective battery packs, operating state, runtime, load and self-test of an APC UPS by SNMP.
par banshee0 installation1 version
v1Dernière
Publiée le 28 octobre 2026. First version.
APC UPS, by SNMP (PowerNet-MIB)
Returns, for an APC UPS with a network management card, what UPS-MIB does not say: whether the UPS asks for its battery to be replaced, how many of its external battery packs it finds defective, and its operating state in APC's own words (smart boost or trim, the kinds of bypass, sleeping, off). With them, the runtime and the charge left, the internal temperature, the load and the last self-test: one probe is enough on a card where UPS-MIB is turned off. Eight watches are offered, each one set on the probe.
Versions
Generic: written for PowerNet-MIB, the MIB of APC's network management cards, whose objects read here have kept their number since they appeared; the newer operating states (13 to 28) come with newer firmware, and a UPS that does not have them never reports them. Hence the common level.
How it works
The collector walks four small branches under 1.3.6.1.4.1.318.1.1.1:
| Object | OID | Read as |
|---|---|---|
upsBasicOutputStatus | .4.1.1.0 | status: on-line (2), on-battery (3), smart-boost (4), timed-sleeping (5), software-bypass (6), off (7), rebooting (8), switched-bypass (9), hardware-failure-bypass (10), sleeping-until-power-return (11), smart-trim (12), eco-mode (13), hot-standby (14), on-battery-test (15), emergency-static-bypass (16), static-bypass-standby (17), power-saving-mode (18), spot-mode (19), e-conversion (20), and the others of the MIB to 28; unknown (1) |
upsAdvBatteryReplaceIndicator | .2.2.4.0 | replace-battery: no (1), yes (2) |
upsAdvBatteryNumOfBadBattPacks | .2.2.6.0 | bad-battery-packs |
upsAdvBatteryRunTimeRemaining | .2.2.3.0 | runtime, in minutes (the agent counts hundredths of a second); not returned at 4294967295, which says the UPS does not know |
upsAdvBatteryCapacity | .2.2.1.0 | charge, in % |
upsAdvBatteryTemperature | .2.2.2.0 | temperature, the UPS's internal temperature in °C; not returned at 255, which says it does not know |
upsAdvOutputLoad | .4.2.3.0 | load, in % of the UPS's capacity |
upsAdvTestDiagnosticsResults | .7.2.3.0 | self-test: ok (1), failed (2), invalid-test (3), in-progress (4) |
- A state the MIB does not name is returned as
state <number>. - A value the UPS does not serve is not returned. An agent that serves no
upsBasicOutputStatusstops the collectormisconfigured. - The collector only reads: SNMP sends nothing but reads. No self-test is started.
Prerequisites
- The SNMP agent of the network management card enabled, reachable from the poller (UDP 161), its access restricted to the poller.
- Read-only access, SNMPv2c or SNMPv3, set on the host or one of its folders (
protocol:snmp:*variables).
Outputs
| Name | Label | Unit | Per instance |
|---|---|---|---|
status | Operating state | — | no |
replace-battery | Battery to replace | — | no |
bad-battery-packs | Defective battery packs | — | no |
runtime | Runtime left | min | no |
charge | Battery charge | % | no |
temperature | Internal temperature | °C | no |
load | Load | % | no |
self-test | Last self-test | — | no |
Watches
| Name | Title | Kind | Defaults | Checked by default |
|---|---|---|---|---|
on-battery | On battery, bypass or off | state to avoid, on status | warning on on-battery, software-bypass, switched-bypass, static-bypass-standby; critical on off, hardware-failure-bypass, emergency-static-bypass, timed-sleeping, sleeping-until-power-return | yes |
replace-battery | Battery to replace | state to avoid, on replace-battery | warning on yes | yes |
bad-battery-packs | Defective battery packs | above a threshold, on bad-battery-packs | warning above 0 | yes |
runtime | Little runtime left | below a threshold, on runtime | warning below 15 min, critical below 5 min | yes |
charge | Battery not charged | below a threshold, on charge | warning below 50 %, critical below 20 %, for 2 runs | yes |
temperature | UPS too hot | above a threshold, on temperature | warning above 40 °C, critical above 50 °C, for 3 runs | yes |
load | Overloaded | above a threshold, on load | warning above 80 %, critical above 95 %, for 3 runs | yes |
self-test | Self-test failed | state to avoid, on self-test | critical on failed | yes |
- Smart boost and smart trim are the UPS correcting a low or a high mains voltage on its own: they raise nothing. A self-test (
on-battery-test) raises nothing either. - On a card that also serves UPS-MIB,
ups/snmp/statusadds the time on battery and the alarms; the watches this collector shares with it are then unchecked on one of the two probes.
Limits
- The runtime and the charge are the UPS's estimates.
- Not checked against an APC UPS: the OIDs and values are those of PowerNet-MIB as its public copies give it (LibreNMS, Observium, Netdisco, gathered by oidref.com).