apcupsd

Managing APC Brand Uninterruptible Power Supplies With apcupsd

Summary

apcupsd is a software package that provides the user with the ability to manage their APC brand uninterruptible power supply. Drivers exist for reading battery capacity without installing apcupsd; this much is made apparent by the battery meter present in the system tray area of certain desktop environments like Gnome shell. What apcupsd does is provide the user with the tools necessary to interact with and gather additional information from their UPS. You can gather detailed information such as incoming line voltage, current load, etc. It also allows you to configure scheduled events based on the status of the UPS. For example, if the power goes out, you can configure it to automatically trigger a scripted, graceful shutdown of the system when the battery reaches a certain point. apcupsd and its included utilities apcaccess and apctest are command line utilities, so they can be installed in a headless or terminal only server environment without having to install a graphical desktop environment.

Disclaimer

Information contained in this document pertains to apcupsd version 3.14.14-2 , as available in the official Ubuntu repositories for Ubuntu 18.10. The exact behavior and configuration of the software may differ depending on the version of apcupsd you are using, as well as what Linux distribution and version you are using.

Points of Note

  • apcupsd is the background daemon, and also includes a command line utility, "apcupsd", that allows you to send some commands to the UPS.
  • apcaccess is an additional utility that comes bundled with apcupsd, and is used to display current status information about the UPS.
  • apctest is an additional utility that comes bundled with apcupsd, and is used to modify the on-board EEPROM settings for the UPS itself.
  • The configuration file is /etc/apcupsd/apcupsd.conf

Installation and Configuration

apcupsd is, as of this writing, available in the official repositories of Ubuntu 18.04 and 18.10, and probably older versions as well since I have also used the software in a regular Debian (stable) environment. Therefore, installing it is as easy as running:

sudo apt install apcupsd

You can also click the following link: apt://apcupsd (link may not work in all browsers)

Configuring apcupsd is fairly straight forward, simply edit the config file /etc/apcupsd/apcupsd.conf . The arguments are fairly easy to understand, especially considering the config file is full of detailed comments telling you exactly what each option does. Below are some of the more important ones that you may want to take a look at.

Option

Valid Values

Description

UPSCABLE

usb, simple, smart, ether, or a specific cable model number (i.e. 940-119A, 940-0127A, etc.)

Defines the type of cable connecting the UPS to your computer. Most modern APC UPS units come with a USB to RJ-45 management cable. If this is the type of cable you are using, "usb" is the proper value of this option.

UPSTYPE

apcsmart, usb, net, snmp, netsnmp, dumb, pcnet, modbus

Most newer UPSes are USB, so you probably want the value to be usb . However, if you are managing a particular UPS over the network, or using a different type of management interface, there are various options provided here.

DEVICE

Depends on the value of UPSTYPE, for apcsmart DEVICE should be /dev/tty**, for net it should be hostname:port, etc. For USB UPSes, I suggest leaving the value of DEVICE blank as this will cause it to auto-detect the UPS.

Designates the device type. A default installation may have an arbitrary /dev/tty value set, even though the UPSTYPE value is USB, so you need only delete that value and leave DEVICE blank if you're connected directly to a modern UPS with a standard issue USB to RJ-45 management cable. More details for specific hardware can be found inside the config file itself.

BATTERYLEVEL

A whole number

If during a power failure, the remaining battery percentage (as reported by the UPS) is below or equal to BATTERYLEVEL, apcupsd will initiate a system shutdown.

MINUTES

A whole number

If during a power failure, the remaining runtime in minutes (as calculated internally by the UPS) is below or equal to MINUTES, apcupsd will initiate a shutdown

TIMEOUT

A whole number

If during a power failure, the UPS has run on batteries for TIMEOUT many seconds or longer, apcupsd will initiate a system shutdown. A value of 0 disables this timer. If you are using a smart UPS that can calculate its remaining battery life, you probably want to disable this timer to avoid an unwanted shutdown, that way the UPS will continue to run until the values of either BATTERYLEVEL or MINUTES are reached.

Note:You may want to restart the apcupsd service after making your configuration changes with:

sudo systemctl restart apcupsd

Additional Configuration, Testing and EEPROM Modification

Included with the installation of apcupsd is an aditional utility called apctest. You may also notice that, toward the bottom of the apcupsd config file, there is a section with the header "Configuration statements used in updating the UPS EEPROM". In the past it would appear (based on the verbiage in the config file) these values were set in this configuration file and then apctest would be used to read these values. However, as of this writing, with this version of apcupsd, apctest seems to no longer read these values from the file, rather it has prompts specific to these capabilities where it asks the user directly to enter their desired setting for a particular function. Therefore, it is not necessary for you to modify any of the EEPROM settings in the apcupsd.conf file.

To modify the EEPROM settings on your UPS, first you must stop the apcupsd service with:

sudo systemctl stop apcupsd

Then launch apctest with:

sudo apctest

You will be presented with a menu where you may perform various self tests, modify the voltage sensitivity of the unit, calibrate the batteries, etc. Keep in mind that if you perform a test like "Test kill UPS power", and the system you are using is running off one of the battery backup ports on that UPS, your system will lose power. The options made available by apctest, as of this writing, are:

  1. Test kill UPS power
  2. Perform self-test (does not kill power to connected devices)
  3. Read last self-test result
  4. View/Change battery date (use this when replacing the batteries)
  5. View manufacturing date
  6. View/Change alarm behavior
  7. View/Change sensitivity
  8. View/Change low transfer voltage
  9. View/Change high transfer voltage
  10. Perform battery calibration
  11. Test alarm
  12. View/Change self-test interval

After making your desired changes within apctest, remember to restart the apcupsd background service with: sudo systemctl start apcupsd

Viewing Status and Information About Your UPS

Included when you install apcupsd is another command line utility, "apcaccess". apcaccess can be ran without root privileges. Simply run the command "apcaccess" and you will be given a list of important information about your UPS. Here is some sample output from the one connected to my system at the moment.

APC : 001,036,0859

DATE : 2019-04-10 19:26:31 -0400

HOSTNAME : marcus-pc

VERSION : 3.14.14 (31 May 2016) debian

UPSNAME : marcus-pc

CABLE : USB Cable

DRIVER : USB UPS Driver

UPSMODE : Stand Alone

STARTTIME: 2019-04-10 12:47:08 -0400

MODEL : Back-UPS RS 1500G

STATUS : ONLINE

LINEV : 123.0 Volts

LOADPCT : 14.0 Percent

BCHARGE : 100.0 Percent

TIMELEFT : 42.8 Minutes

MBATTCHG : 5 Percent

MINTIMEL : 3 Minutes

MAXTIME : 0 Seconds

SENSE : High

LOTRANS : 88.0 Volts

HITRANS : 147.0 Volts

ALARMDEL : 30 Seconds

BATTV : 27.2 Volts

LASTXFER : Low line voltage

NUMXFERS : 0

TONBATT : 0 Seconds

CUMONBATT: 0 Seconds

XOFFBATT : N/A

SELFTEST : NO

STATFLAG : 0x05000008

SERIALNO : 3B1618X16833

BATTDATE : 2016-05-07

NOMINV : 120 Volts

NOMBATTV : 24.0 Volts

NOMPOWER : 865 Watts

FIRMWARE : 865.L6 .D USB FW:L6

END APC : 2019-04-10 19:26:32 -0400

Missing or Broken Features

One feature that is missing when compared to APC's official Powerchute software is the ability to leverage the "Controlled by Master" function. This feature is something that is normally written to the UPS EEPROM itself, and allows your UPS to cut or restore power to all of the ports labeled "Controlled by Master" when the power draw of the port labeled "Master" goes above or below a specified threshold. Once this feature is enabled and configured, it will operate regardless of whether a system is connected to the management port on the UPS. Since apcupsd cannot modify this setting, be aware that if you've configured your "Controlled by Master" ports to behave a certain way using the Powerchute software, and then change to system using apcupsd, you will be unable to change that setting.


CategoryHardware

apcupsd (last edited 2019-04-11 02:11:22 by gerowen)