{"id":4293,"date":"2024-03-08T02:15:00","date_gmt":"2024-03-08T07:15:00","guid":{"rendered":"https:\/\/www.both.org\/?p=4293"},"modified":"2024-03-02T12:26:45","modified_gmt":"2024-03-02T17:26:45","slug":"manage-your-apc-battery-backup-system-with-this-linux-command","status":"publish","type":"post","link":"https:\/\/www.both.org\/?p=4293","title":{"rendered":"Manage your APC battery backup system with this Linux command"},"content":{"rendered":"
\r\n
\r\n \r\n <\/i>\r\n <\/a>\r\n <\/span>\r\n<\/div><\/div>\n

Image by: Internet Archive Book Images. Modified by Opensource.com. CC BY-SA 4.0<\/p>\n\n\n\n

Protect yourself from power incidents by running a simple utility: apcupsd.<\/h2>\n\n\n\n

Back in the early days of personal computers, I wrote the IBM training course for the original IBM PC. To complete the course in time for the IBM, ComputerLand, and Sears training, IBM gave me a PC to take home so I could work over evenings and weekends\u2014arguably the first instance of anyone having an IBM PC in their home.<\/p>\n\n\n\n

I did this work in Boca Raton, Florida, where the small, local power company was commonly known as “Florida Flicker and Flash,” with good reason. The short but frequent power outages caused me to lose my work more than once. Unfortunately, there were no personal Uninterruptible Power Supply (UPS) systems to keep my desktop PC up and running through these annoying and sometimes destructive incidents.<\/p>\n\n\n\n

A UPS keeps a computer running long enough to last through minor power events, such as outages and surges of a few seconds up to as much as 20 or 30 minutes. In the case of these longer outages, the function of the modern UPS is to notify the computer to power down before the UPS runs out of battery power. Otherwise, the sudden loss of power can lead to loss of data\u2014although with modern hardware systems this is much less likely.<\/p>\n\n\n\n

The computer and UPS communicate through a serial or USB cable. A system service manages the communications and sends appropriate commands to both the UPS and the computer. Windows computers generally use a free version of the software provided by the UPS vendor. However, the open source apcupsd<\/code> utility supports Linux, Windows, BSD, Solaris, and macOS, providing consistency across operating systems.<\/p>\n\n\n\n

This set of tools supports APC UPS systems and provides varying degrees of support for UPS systems produced by Tripp-Lite, CyberPower, and others. I currently have UPS systems from all three of these manufacturers running on networks that I manage. I have not found a list of supported UPS systems, nor is the apcupsd documentation<\/a> helpful on this, and I have seen nothing definitive in any web searches.<\/p>\n\n\n\n

Be aware that the “APC” portion of the names of these tools indicates that they were designed for APC UPS systems. Their efficacy on other UPS vendors’ systems depends on how closely they follow the APC management interface. I’ve discovered that apcupsd is also quite compatible with CyberPower UPS systems. <\/p>\n\n\n\n

Install apcupsd on Linux<\/h2>\n\n\n\n

Because it is available from the Fedora repository, installation of apcupsd<\/code> is simple. Issue this command as root to install apcupsd<\/code>:<\/p>\n\n\n\n

# dnf -y install apcupsd<\/strong><\/code><\/code><\/pre>\n\n\n\n
To start and enable apcupsd<\/code> so that it will restart after every reboot of your system, run the following command. This command must also be entered as root:<\/p>\n\n\n\n
# systemctl enable --now apcupsd<\/strong><\/code><\/code><\/pre>\n\n\n\n
Other distributions also have apcupsd<\/code> in their repositories.<\/p>\n\n\n\n
Basic usage<\/h2>\n\n\n\n
At this point, the apcupsd<\/code> daemon has been started, so you can interact with it using the apcaccess<\/code> command as a non-root user. Without any options, this command generates a status report describing the current state of the UPS:<\/p>\n\n\n\n
[root@test ~]$ apcaccess<\/strong>\nAPC      : 001,033,0831\nDATE     : 2021-11-30 21:08:10 -0500  \nHOSTNAME : test.both.org\nVERSION  : 3.14.14 (31 May 2016) redhat\nUPSNAME  : test.both.org\nCABLE    : USB Cable\nDRIVER   : USB UPS Driver\nUPSMODE  : Stand Alone\nSTARTTIME: 2021-11-27 13:08:58 -0500  \nMODEL    : CP1500PFCLCDa\nSTATUS   : ONLINE\nLINEV    : 120.0 Volts\nLOADPCT  : 32.0 Percent\nBCHARGE  : 100.0 Percent\nTIMELEFT : 22.5 Minutes\nMBATTCHG : 5 Percent\nMINTIMEL : 3 Minutes\nMAXTIME  : 0 Seconds\nOUTPUTV  : 120.0 Volts\nDWAKE    : -1 Seconds\nLOTRANS  : 100.0 Volts\nHITRANS  : 139.0 Volts\nALARMDEL : 30 Seconds\nNUMXFERS : 2\nXONBATT  : 2021-11-30 13:46:03 -0500  \nTONBATT  : 0 Seconds\nCUMONBATT: 5 Seconds\nXOFFBATT : 2021-11-30 13:46:06 -0500  \nSELFTEST : NO\nSTATFLAG : 0x05000008\nSERIALNO : CXXLT2001977\nNOMINV   : 120 Volts\nNOMPOWER : 1000 Watts\nEND APC  : 2021-11-30 21:08:17 -0500  \n[root@test ~]#<\/code><\/pre>\n\n\n\n
In the output above, there are three fields of particular interest for managing battery backup. The load percentage (LOADPCT<\/code>) indicates how much load is being placed on the UPS. When the unit is plugged in and power is applied, the battery charge (BCHARGE<\/code>) should be 100%, but it will be lower when external power is removed. The TIMELEFT<\/code> is the field of most concern. In this example, if power fails, the UPS can run at the current load for 22.5 minutes.<\/p>\n\n\n\n
Other items to look at include the CUMONBATT<\/code> line, which is the cumulative time the UPS has been running on battery. This field accumulates all of the power outage times over multiple events. The TONBATT<\/code> line is the time for a current ongoing power loss event.<\/p>\n\n\n\n
The man page for apcaccess<\/code> describes the rest of the data items in this output. The displayed data can differ according to the UPS model.<\/p>\n\n\n\n
Managing the UPS<\/h2>\n\n\n\n
In the output from the apcaccess<\/code> command above, the SELFTEST<\/code> line says NO<\/code>. This response means that a self-test has not been performed on this UPS since acpupsd<\/code> was last started. Usually, that would be the time of the last system boot. Self-tests are performed once every seven days on most UPS systems, but you can initiate one using the apctest<\/code> command.<\/p>\n\n\n\n
Unfortunately, the apctest<\/code> command conflicts with the apcupsd<\/code> daemon, so you need to stop apcupsd<\/code> temporarily. Then you can launch apctest<\/code>, which uses a menu-based interface. These commands should be used as root:<\/p>\n\n\n\n
[root@myserver ~]# systemctl stop apcupsd<\/strong> \n[root@myserver ~]# apctest<\/strong> \n\n\n2021-12-01 06:36:47 apctest 3.14.14 (31 May 2016) redhat \nChecking configuration ... \nsharenet.type = Network & ShareUPS Disabled \ncable.type = USB Cable \nmode.type = USB UPS Driver \nSetting up the port ... \nDoing prep_device() ... \n\nYou are using a USB cable type, so I'm entering USB test mode. \nHello, this is the apcupsd Cable Test program. \nThis part of apctest is for testing USB UPSes. \n\nGetting UPS capabilities...SUCCESS \n\nPlease select the function you want to perform. \n\n1)  Test kill UPS power \n2)  Perform self-test \n3)  Read last self-test result \n4)  View\/Change battery date \n5)  View manufacturing date \n6)  View\/Change alarm behavior \n7)  View\/Change sensitivity \n8)  View\/Change low transfer voltage \n9)  View\/Change high transfer voltage \n10) Perform battery calibration \n11) Test alarm \n12) View\/Change self-test interval \nQ) Quit \n\nSelect function number: <\/code><\/pre>\n\n\n\n
Warning:<\/strong><\/em> Be careful not to accidentally choose item 1 because that will turn off the UPS and, therefore, the computer.<\/p>\n\n\n\n
Enter 2<\/code> and press Enter to run a UPS self-test. Note that the menu is displayed again before the self-test has had enough time to complete, so the result is IN PROGRESS<\/code>. This result is from the CyberPower UPS. The program waited for the self-test to complete on an APC UPS before returning to the menu.<\/p>\n\n\n\n
<snip>\nSelect function number: 2\n\n\nThis test instructs the UPS to perform a self-test\noperation and reports the result when the test completes.\n\nClearing previous self test result...CLEARED\nInitiating self test...INITIATED\nWaiting for test to complete...COMPLETED\nResult of last self test: IN PROGRESS\n\n1)  Test kill UPS power\n2)  Perform self-test\n3)  Read last self-test result\n4)  View\/Change battery date\n5)  View manufacturing date\n6)  View\/Change alarm behavior\n7)  View\/Change sensitivity\n8)  View\/Change low transfer voltage\n9)  View\/Change high transfer voltage\n10) Perform battery calibration\n11) Test alarm\n12) View\/Change self-test interval\n Q) Quit<\/code><\/pre>\n\n\n\n
The UPS beeps to indicate that the self-test has finished. The specific beep pattern may differ depending upon the UPS vendor and model. My CyberPower CP1500PFCLCDa gives two short beeps. The alarm will not sound if it has been manually silenced.<\/p>\n\n\n\n
After the self-test has completed, use menu item 3 to read the result. In this case, my UPS has passed the self-test.<\/p>\n\n\n\n
Select function number: 3\n\nResult of last self test: PASSED\n\n1)  Test kill UPS power\n2)  Perform self-test\n3)  Read last self-test result\n4)  View\/Change battery date\n5)  View manufacturing date\n6)  View\/Change alarm behavior\n7)  View\/Change sensitivity\n8)  View\/Change low transfer voltage\n9)  View\/Change high transfer voltage\n10) Perform battery calibration\n11) Test alarm\n12) View\/Change self-test interval\n Q) Quit\n\nSelect function number:<\/code><\/pre>\n\n\n\n
Most of these other menu options do not work on my CyberPower devices, but they do work on APC UPS devices, as expected.<\/p>\n\n\n\n
Battery calibration can be used on supported UPS systems if the UPS’s estimate of the remaining run time is incorrect. This option disconnects the UPS from main power and runs the computer on battery until it drains to about 10% of its maximum charge. This method enables a more accurate estimate of on-battery run time.<\/p>\n\n\n\n
Be sure to restart apcupsd<\/code> after exiting from the apctest<\/code> menu.<\/p>\n\n\n\n
Final thoughts<\/h2>\n\n\n\n
The apcupsd suite of programs provides easy tools to monitor and manage APC UPS systems, and it works with other vendors’ UPS systems to varying degrees. It provides intelligent power incident protection and a managed shutdown if an outage lasts to the edge of the battery charge.<\/p>\n\n\n\n
The apcupsd<\/code> background daemon works with most modern UPS systems and can initiate a power-off sequence on the computer when the UPS battery gets too low. I have found this to be the case for all three vendors for which I have UPS systems. Other functions, those accessible using the apctest<\/code> program, are problematic. Some of those functions may work, and some may not. It depends upon the make and model of your UPS system.<\/p>\n\n\n\n
The most important consideration for me is that the apcupsd<\/code> software can communicate with the UPS enough to initiate a power-off command to the computer when the UPS battery gets low. The second thing I care about is the information available from the apcaccess<\/code> command. The rest is simply nice to have.<\/p>\n\n\n\n
For those who prefer a GUI interface, both CGI web and GUI interfaces are also available in the Fedora repository.<\/p>\n\n\n\n
The apcupsd<\/code> software is mature and stable, so development is limited to fixing bugs. Support is available on the project’s SourceForge page<\/a> via the mailing lists.<\/p>\n","protected":false},"excerpt":{"rendered":"
Protect yourself from power incidents by running a simple utility: apcupsd.<\/p>\n","protected":false},"author":2,"featured_media":4295,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_lmt_disableupdate":"","_lmt_disable":"","footnotes":""},"categories":[5,14,89],"tags":[301],"class_list":["post-4293","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-linux","category-open-source-software","category-system-administration","tag-apcupsd"],"modified_by":"David Both","_links":{"self":[{"href":"https:\/\/www.both.org\/index.php?rest_route=\/wp\/v2\/posts\/4293","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.both.org\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.both.org\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.both.org\/index.php?rest_route=\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/www.both.org\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=4293"}],"version-history":[{"count":15,"href":"https:\/\/www.both.org\/index.php?rest_route=\/wp\/v2\/posts\/4293\/revisions"}],"predecessor-version":[{"id":4310,"href":"https:\/\/www.both.org\/index.php?rest_route=\/wp\/v2\/posts\/4293\/revisions\/4310"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.both.org\/index.php?rest_route=\/wp\/v2\/media\/4295"}],"wp:attachment":[{"href":"https:\/\/www.both.org\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=4293"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.both.org\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=4293"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.both.org\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=4293"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}