APCACCESS(8)

📦
version 3.14.14 · 2 versions
, in alpine 3.22, alpine 3.23, alpine 3.24, arch rolling, epel 10, epel 9, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, opensuse-leap 16.0

🌸 APCACCESS(8) 🌸

okay bestie, gather round — this is apcaccess, from the System Manager's Manual, and it's genuinely one of those little tools that just slays at one job. let's get into it 💅

✨ NAME ✨

apcaccess — retrieve status information from apcupsd(8) 🫶

🎀 SYNOPSIS 🎀

apcaccess [-f <config-file>] [-h <host>[:<port>]] [-p <parameter-name>]
          [-u] [<command>] [<host>[:<port>]]

💖 DESCRIPTION 💖

So like. apcaccess is a program that prints out the complete status of most American Power Conversion Corp. (APC) UPSes — but here's the catch, bestie: you gotta have the apcupsd(8) daemon installed, properly configured, and running. All three. No skipping steps 🙈

Once that's sorted, it can pull status info from any APC UPS attached to the localhost, or attached to any computer on the network that's running apcuspd in NIS mode. network UPS? we love to see it 🌈

The command line options are:

  • -f — the configuration file of apcupsd (default is usually /etc/apcupsd/apcupsd.conf)
  • -h — hostname and port of apcupsd to communicate with. The default hostname and port are obtained from the configuration file.
  • -p — report only the value of the named parameter instead of all parameters and values. like, just the one thing. main character energy 👑
  • -u — remove the units field, for easier parsing by scripts. lowkey a lifesaver when you're scripting 🧚
  • <command> — an optional command, unless a hostname is also being specified. The only implemented command is status — shorthand for status localhost:3551. This produces a full printout of the available status information for the associated UPS. 💀 (yes, that's the only one. it's iconic, it doesn't need friends.)
  • <host> — an optional hostname, which may be a bare machine name, fully qualified domain name, or IP address.
  • :<port> — an optional port number, used where a hostname argument has been specified. The default is 3551, the official port number assigned by IANA for the apcupsd NIS server. The default hostname and port are obtained from the configuration file.

so apcaccess uses apcupsd's inbuilt Network Information Server (NIS) — and no relation to Sun's NIS/YP service, fr fr, don't get it twisted — to obtain the current status information from the UPS on the local or remote computer. 🌸

Which means: it is therefore necessary to have the following configuration directives:

NETSERVER on
NISPORT 3551

in the /etc/apcupsd/apcupsd.conf configuration file so that the Network Information Server will be accessible. And bestie — firewall rules for appropriate network access may also be needed. don't forget the firewall, i'm begging 😭

⭐ STATUS REPORT FORMAT ⭐

The status report output format is simple ASCII. Generally there is a single piece of information on each line of output. The content varies based on the model of UPS being used and, in some cases, the firmware version. so like — different UPS, different vibe check. that's just how it is 💜

✨ EXAMPLES ✨

Okay bestie, here's the good part — a whole buffet of sample status output that apcaccess might spit out for the different UPS models. Let's break it down by vibe (aka by hardware) 💅

All models

Every UPS gets these, no matter what:

  • APC — the version, the number of records, and the number of bytes following it
  • DATE — date and time of the last update from the UPS
  • HOSTNAME — hostname of the computer running apcupsd
  • VERSION — the apcupsd version number, plus the date and operating system
  • UPSNAME — the UPS name, pulled from the configuration file (dumb) or from EEPROM (smart)
  • CABLE — cable type, as specified in the configuration file
  • MODEL — the UPS model, derived from the UPS information
  • UPSMODE — the mode the UPS is operating in
  • STARTTIME — date and time apcupsd was started
  • STATUS — the UPS status. One or more of the following, space-separated:
CAL TRIM BOOST ONLINE ONBATT OVERLOAD LOWBATT
REPLACEBATT NOBATT SLAVE SLAVEDOWN

or:

COMMLOST

or:

SHUTTING DOWN
  • MASTERUPD — last time the master sent an update to the slave
  • ENDAPC — date and time the status information was written

Smart-UPS and Matrix-UPS (Smart Signalling)

The full-course meal, honestly 🔥

  • LINEV — current input line voltage
  • LOADPCT — percentage of UPS load capacity used, as estimated by the UPS
  • BCHARGE — current battery capacity charge percentage
  • TIMELEFT — remaining runtime left on battery, as estimated by the UPS
  • MBATTCHG — min battery charge % (BCHARGE) required for system shutdown
  • MINTIMEL — min battery runtime (MINUTES) required for system shutdown
  • MAXTIME — max battery runtime (TIMEOUT) after which the system is shut down
  • MAXLINEV — maximum input line voltage since apcupsd started
  • MINLINEV — min (observed) input line voltage since apcupsd started
  • OUTPUTV — current UPS output voltage
  • SENSE — current UPS sensitivity setting for voltage fluctuations
  • DWAKE — time the UPS waits after power off when the power is restored
  • DSHUTD — delay before the UPS powers down after a command is received
  • DLOWBATT — low battery signal, sent when this much runtime remains
  • LOTRANS — input line voltage below which the UPS will switch to battery
  • HITRANS — input line voltage above which the UPS will switch to battery
  • RETPCT — battery charge % required after power off to restore power
  • ITEMP — UPS internal temperature in degrees Celcius
  • ALARMDEL — delay period before the UPS starts sounding the alarm
  • BATTV — current battery voltage
  • LINEFREQ — current line frequency in Hertz
  • LASTXFER — reason for the last transfer to battery since apcupsd startup
  • NUMXFERS — number of transfers to battery since apcupsd startup
  • XONBATT — date, time of the last transfer to battery since apcupsd startup
  • TONBATT — seconds currently on battery
  • CUMONBATT — cumulative seconds on battery since apcupsd startup
  • XOFFBAT — date, time of the last transfer off battery since apcupsd startup
  • SELFTEST — date and time of the last self test since apcupsd startup
  • STESTI — self-test interval
  • STATFLAG — UPS status flag in hex
  • DIPSW — current UPS DIP switch settings
  • REG1 — fault register 1 in hex
  • REG2 — fault register 2 in hex
  • REG3 — fault register 3 in hex
  • MANDATE — UPS date of manufacture
  • SERIALNO — UPS serial number
  • BATTDATE — date the battery was last replaced (if set)
  • NOMOUTV — nominal output voltage to supply when on battery power
  • NOMBATTV — nominal battery voltage
  • EXTBATTS — number of external batteries (for XL models)
  • BADBATTS — number of bad external battery packs (for XL models)
  • FIRMWARE — UPS firmware version
  • APCMODEL — APC model information

Newer Back-UPS Pro (Smart Signalling)

A lighter little lineup, still cute:

  • LINEV — current input line voltage
  • LOADPCT — percentage of UPS load capacity used
  • MBATTCHG — min battery charge % (BCHARGE) required for system shutdown
  • MINTIMEL — min battery runtime (MINUTES) required for system shutdown
  • MAXTIME — max battery runtime (TIMEOUT) after which the system is shut down
  • MAXLINEV — maximum input line voltage since apcupsd startup
  • MINLINEV — minimum input line voltage since apcupsd startup
  • OUTPUTV — current UPS output voltage
  • BATTV — current battery charge voltage
  • STATFLAG — UPS status flag in hex

Back-UPS RS 1500 (USB)

Look at all those lil stars, it's giving constellation ⭐ (the * means the field is presence dependant on the USB firmware version — more on that at the bottom of this section!)

  • LINEV — current input line voltage
  • LOADPCT — percentage of UPS load capacity used
  • BCHARGE — current battery capacity charge percentage
  • TIMELEFT — remaining runtime left on battery, as estimated by the UPS
  • MBATTCHG — min battery charge % (BCHARGE) required for system shutdown
  • MINTIMEL — min battery runtime (MINUTES) required for system shutdown
  • MAXTIME — max battery runtime (TIMEOUT) after which the system is shut down
  • *OUTPUTV — current UPS output voltage
  • *DWAKE — time the UPS waits after power off when the power is restored
  • *DSHUTD — delay before the UPS powers down after a command is received
  • LOTRANS — input line voltage below which the UPS will switch to battery
  • HITRANS — input line voltage above which the UPS will switch to battery
  • *RETPCT — battery charge % required after power off to restore power
  • *ITEMP — UPS internal temperature in degrees Celcius
  • ALARMDEL — delay period before the UPS starts sounding the alarm
  • BATTV — current battery voltage
  • *LINEFREQ — current line frequency in Hertz
  • *LASTXFER — reason for the last transfer to battery since apcupsd startup
  • NUMXFERS — number of transfers to battery since apcupsd startup
  • XONBATT — date, time of the last transfer to battery since apcupsd startup
  • TONBATT — seconds currently on battery
  • CUMONBATT — cumulative seconds on battery since apcupsd startup
  • XOFFBAT — date, time of the last transfer off battery since apcupsd startup
  • SELFTEST — date and time of the last self test since apcupsd startup
  • STATFLAG — UPS status flag in hex
  • MANDATE — UPS date of manufacture
  • SERIALNO — UPS serial number
  • BATTDATE — date the battery was last replaced (if set)
  • NOMBATTV — nominal battery voltage
  • FIRMWARE — UPS firmware version
  • APCMODEL — APC model information
* presence dependant on USB firmware version. (Yes, that's straight from the page — the stars are conditional, bestie 🫶)

Web/SNMP (AP9716) or PowerNet SNMP (AP9605) SmartSlot Card

Network card energy, honestly iconic 🌈

  • LINEV — current input line voltage
  • LOADPCT — percentage of UPS load capacity used, as estimated by the UPS
  • BCHARGE — current battery capacity charge percentage
  • TIMELEFT — remaining runtime left on battery, as estimated by the UPS
  • MBATTCHG — min battery charge % (BCHARGE) required for system shutdown
  • MINTIMEL — min battery runtime (MINUTES) required for system shutdown
  • MAXTIME — max battery runtime (TIMEOUT) after which the system is shut down
  • MAXLINEV — maximum input line voltage since apcupsd startup
  • MINLINEV — minimum input line voltage since apcupsd startup
  • OUTPUTV — UPS output voltage
  • SENSE — current UPS sensitivity setting for voltage fluctuations
  • DWAKE — time the UPS waits after power off when the power is restored
  • DSHUTD — delay before the UPS powers down after a command is received
  • DLOWBATT — low battery signal, sent when this much runtime remains
  • LOTRANS — input line voltage below which the UPS will switch to battery
  • HITRANS — input line voltage above which the UPS will switch to battery
  • RETPCT — battery charge % required after power off to restore power
  • ITEMP — UPS internal temperature in degrees Celcius
  • ALARMDEL — delay period before the UPS starts sounding the alarm
  • LINEFREQ — current line frequency in Hertz
  • NUMXFERS — number of transfers to battery since apcupsd startup
  • TONBATT — seconds currently on battery
  • CUMONBATT — cumulative seconds on battery since apcupsd startup
  • XOFFBATT — date, time of the last transfer off battery since apcupsd startup
  • STESTI — self-test interval
  • STATFLAG — UPS status flag in hex
  • DIPSW — current UPS DIP switch settings
  • MANDATE — UPS date of manufacture
  • SERIALNO — UPS serial number
  • BATTDATE — date the battery was last replaced (if set)
  • NOMOUTV — nominal output voltage to supply when on battery power
  • NOMPOWER — nominal power output in watts
  • EXTBATTS — number of external batteries (for XL models)
  • BADBATTS — number of bad external battery packs (for XL models)
  • FIRMWARE — UPS firmware version
  • APCMODEL — APC model information

Share-UPS (AP9270) (Basic port)

Basic port, basic babe — short and sweet 🍓

  • MBATTCHG — min battery charge % (BCHARGE) required for system shutdown
  • MINTIMEL — min battery runtime (MINUTES) required for system shutdown
  • MAXTIME — max battery runtime (TIMEOUT) after which the system is shut down
  • NUMXFERS — number of transfers to battery since apcupsd startup
  • TONBATT — seconds currently on battery
  • CUMONBATT — cumulative seconds on battery since apcupsd startup
  • XOFFBATT — date, time of the last transfer off battery since apcupsd startup
  • STATFLAG — UPS status flag in hex

UPS Environmental Monitoring SmartSlot Card (AP9612TH)

Two fields. Yes, two. It's a whole vibe:

  • HUMIDITY — ambient humidity
  • AMBTEMP — ambient temperature

Back-UPS Pro and Smart-UPS v/s (Smart Signalling)

  • LINEFAIL — input line voltage status.
  • BATTSTAT — battery status.
  • LASTXFER — last (observed) transfer to battery.

Back-UPS and Net-UPS (Simple Signalling)

  • LINEFAIL — input line voltage status.
  • BATTSTAT — battery status.
  • STATFLAG — UPS status flag in hex.

📁 FILES 📁

  • /etc/apcupsd/apcupsd.conf

That's the one, bestie — the config file lives here 💖

👀 SEE ALSO 👀

And the HTML apcupsd manual — it's installed on your system, or you can find it online at http://www.apcupsd.org/ ✨

💖 AUTHORS 💖

This page

  • Trevor Roydhouse

Software

  • Adam Kropelin (current Project Manager and Code Maintainer)
  • Kern Sibbald (former Project Manager and Code Maintainer)
  • Riccardo Facchetti (former Project Manager and Code Maintainer)
  • Andre M. Hedrick (Project Founder and former Code Maintainer)

Contributors

An enormous number of users who have devoted their time and energy to this project -- thanks. 🫶 (Fr fr, that's the whole section. Respect the contributors, they ate.)

✨ and that's the whole page, bestie ✨

Signing off from apcaccess v3.14.6, dated March 28, 2014 — go check your UPS status, mwah 💅🎀

📦 where this page comes from