Monitoring Your UPS With apcupsd

Riccardo delves into the details of apcupsd, a program for monitoring and controlling APC UPSes.
Networked Configuration

When you have a UPS that is powering more than one computer, and you want to protect every computer from power failures, you can configure apcupsd to work as network master/slave service. Listing 3 and 4 describe how to configure apcupsd as master and a slave in order to shut down both in case of a power failure.

Listing 3

Listing 4

The master apcupsd is configured as described above in stand-alone configuration, with the exception that the configuration directive NETACCESS is now true and the master will use port 6666 to communicate with slaves. The apcupsd master will connect to the slave at in order to communicate alerts and power events. The slave apcupsd shares the same configuration except that instead of using the serial port, it will listen to to get all the information needed to operate correctly.

Advanced Configuration

apcupsd configuration is very flexible. But adding to this flexibility, you can also configure your control scripts to execute customized actions, and you can even configure your UPS eeprom to suit your needs.

Customizing apcupsd Actions

When apcupsd detects anomalies from your UPS device, it will make some decisions that usually result in one or more calls to the script located in /etc/apcupsd/apccontrol. The apccontrol file is a shell script that takes the first argument that apcupsd passes to it to do actions. These actions are set up by default to sane behavior for all possible situations apcupsd is likely to detect from the UPS. Nevertheless, you can change the apccontrol behavior for every action. To do so, simply create a file with the same name as the action you want to customize, which is passed as the first argument (argv[1], or $1 for shell scripts). Place your script in the /etc/apcupsd/ directory. The arguments that apccontrol can recognize are shown in Table 3.

Table 3. Arguments apccontrol Recognizes

Listing 5

If, for example, you want to write your own routine for the on-battery action, you can write your own shell script, as shown in Listing 5, called onbattery and put it in the /etc/apcupsd/ directory. Doing so will run the customized script before the default action. In case you don't want the default action to be taken, terminate your customized script with an exit code of 99. If you want to write customized scripts to replace the default behavior, you are encouraged to edit the apccontrol script and at least mimic its behavior in your own script. Please be aware that writing faulty scripts may cause your system to crash during power failures.

Configuring the UPS eeprom

In SmartUPSes there are at least 12 different values stored in the eeprom that determine how the UPS reacts to various conditions such as high line voltage, low line voltage, power down grace periods, etc.

In general, for the moment, it is not recommended to change eeprom values unless absolutely necessary. There have been several reported cases of problems setting the Low Transfer Voltage. Consequently, if at all possible, do not attempt to change this value.

If, despite these warnings, eeprom vales must be changed, we recommend to connect your UPS to a Windows machine running PowerChute and making the changes.

In the absence of alternatives, eeprom values can be changed also with apcupsd. Before doing so, it is recommended that you make a printed copy of UPS parameters as they are before any eeprom changes, so that they can be checked against the changes made. This can be done by printing a copy of the output from apcaccess status and also of the output from apcaccess eprom.

Once this is done, choose which eeprom values you want to change. Choose the new values from the list provided by apcaccess eprom. For the battery date, and the UPS name, you can use any eight characters.

To make the eeprom changes with apcupsd you must first stop the apcupsd dæmon. See “Stopping Apcupsd” in the appropriate section of apcupsd manual. Then edit the appropriate configuration directive in /etc/apcupsd/apcupsd.conf.

It is recommended to change one eeprom value at a time, by defining only one configuration directive at a time. After each change, check that everything is okay before proceeding to the next value you wish to change.

To actually change the eeprom, as root with the apcupsd dæmon stopped, enter:

apcupsd -c

When it has completed the reprogramming of the eeprom, it will print the new STATUS report. Check that you got the expected results before continuing.



Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.

Re: Monitoring Your UPS With apcupsd

Anonymous's picture

Not only is this an excellent review, but its also short, but covers alot of the basic material. Besides from being a review and a tutorial, its a inspiration.

I just bought a APC 1000 and had problems with upsd .. but this made me switch over and are now running apcupsd and made tons of scripts to monitor it .. even mrtg. Wonderfull program :)

Re: Monitoring Your UPS with apcupsd

Anonymous's picture

Nice article.

I will add that we are also successfully monitoring Belkin UPSs with apcupsd.