Apcupsd Post Installation Configuration

It may be necessary to change the configuration information in the file /etc/apcupsd/apcupsd.conf to meet your needs and to correspond to your configuration. This file is a plain ASCII file and you can use your favorite editor to change it. However, please take a careful look at the installation chapter in this document, because many of these directives can be correctly set during installation using the ./configure program. This simplifies the task of editing the configuration file, and ensures that other files (CGI) are appropriately modified as well.

Three Major Configuration Possibilities for Apcuspd

There are three major ways of running apcupsd on your system. The first is a standalone configuration where apcupsd controls a single UPS, which powers the computer. This is the most common configuration. The second configuration is a master/slave configuration, where one UPS powers several computers, each of which runs a copy of apcupsd. The computer that controls the UPS is called the master, and the other computers are called slaves. The master copy of apcupsd communicates with and controls the slaves via an ethernet connection. The third configuration (new with version 3.8.3), is where a single computer controls multiple UPSes. In this case, there are several copies of apcupsd on the same computer each controlling a different UPS. One copy of apcupsd will run in standalone mode, and the other copy or copies will normally run in master/slave mode.

These three possibilities can be represented by the following diagrams:

                    Stand Alone Configuration

           ---------------------   serial port    ------ 
          |                     | <============> |      |
          |  Computer running   |                | UPS  |
          |    apcupsd in       |   Power        |      |
          |    stand alone      | <============= |      |
          |       mode          |                 ------  
          |                     |
           ---------------------




                   Typical Master/Slave Configuration

           ---------------------   serial port    ------ 
          |                     | <============> |      |
          |  Computer A running |                | UPS  |
          |    apcupsd in       |   Power        |      |
          |    master mode      | <============= |      |
          |                     |           ||    ------  
          |                     |           ||
           ---------------------            ||
                     |                      ||
     ----------------|  Ethernet            ||
     |               |                      ||
     |     ---------------------            ||
     |    |                     |           ||
     |    |  Computer B running |           ||
     |    |    apcupsd in       |   Power   ||
     |    |    slave mode       | <=========||
     |    |                     |           ||
     |    |                     |           ||
     |     ---------------------            ||
     |                                      ||
     |                                      ||
     -----------------  Ethernet            ||
                     |                      ||
           ---------------------            ||
          |                     |           ||
          |  Computer C running |           ||
          |    apcupsd in       |   Power   ||
          |    slave mode       | <===========
          |                     |           
          |                     |
           ---------------------



                   
               Multi-UPS Configuration (apcupsd 3.8.3 only)

           ---------------------   serial port    ------ 
          |                     | <============> |      |
          |  Computer A running |   Power        | UPS  |
          |   two copies of     | <============= |      |
          |     apcupsd         |                 ------ 
          |                     |   serial port   ------  
          |                     | <============> |      |
           ---------------------                 | UPS  |
                     |                      ==== |      |
                     | Ethernet             ||    ------
                     |                      ||
           ---------------------            ||
          |                     |           ||
          |  Computer B running |           ||
          |    apcupsd in       |   Power   ||
          |    slave mode       | <===========
          |                     |
          |                     |
           ---------------------

If you wish to see some simple examples of possible configuration files, please see the Configuration Examples Chapter of this document.

Configuration Directives

Configuration directives in /etc/apcupsd/apcupsd.conf are:

General Configuration Directives

In general, each of these directives is required (the DEVICE directive is ignored for UPSCABLE ether).

UPSTYPE <type of APC UPS you have>

One of the big problems is understanding what kind of UPS you have and knowing what cable to use with what UPS. If you received a cable with your UPS, the cable number is stamped on the side of the connector (usually in the plastic on both cable ends), and it is most likely the correct cable for your UPS.

In the table below, we attempt to show what cables are known to work with each UPS. This information is a bit sketchy and so should not yet be considered definitive. Any comments or corrections would be appreciated.

The UPSTYPE directive can be defined during installation by using the --with-upstype= option on the ./configure program.

Apcupsd UPSTYPE Keyword	APC Model	UPS Signaling	Cables Supported	Status
backups	BackUPS	Simple	Simple-Custom, 940-0020B, 940-0020C, 940-0119A, 940-0023A	Supported
backups	BackUPS Office	Simple	940-0119A	Supported
backups	BackUPS ES	Simple	940-0119A	Supported (apparently identical to the BackUPS Office)
backups	BackUPS CS (serial mode)	Simple	940-0127A (and possibly 940-0128A)	Supported
sharebasic	ShareUPS Basic Port	Simple	940-0020B, 940-0020C, 940-0023A	Supported
backupspro	BackUPS Pro	SubSmart	940-0095A	Supported (note, see newbackupspro)
smartvsups	SmartUPS VS	SubSmart	940-0095A??	Supported
newbackupspro	Smarter BackUPS Pro	SubSmart	940-0095A	Supported
backupspropnp	Smarter BackUPS Pro	SubSmart	940-0095A	Supported
smartups	SmartUPS	Smart	Smart-Custom, 940-0024C	Supported
matrixups	MatrixUPS	Smart	Smart-Custom, 940-0024C	Supported
sharesmart	ShareUPS Advanced Port	Smart	Smart-Custom, 9400-024C	Unknown status
usb	BackUPS CS USB, BackUPS Pro USB	SubSmart	USB as supplied by APC	Supported in apcupsd version 3.9.4 and later

UPSCABLE <type of cable you are using>>

[ simple | 940-0020B | 940-0023A ]
[ smart | 940-0024B | 940-0024C ]
[ 940-1524C | 940-0024G | 940-0095A | 940-0095B | 940-0095C | 940-00119A]
[ ether ]

If you have a Smart or a SubSmart UPS (see table above), and you build your own cable, build a Smart-Custom cable (see the Cables Chapter of this manual). If you have a Simple UPS, build a Simple-Custom cable.

The --with-upscable= option can be used on the

./configure

program to set this directive during the installation.

DEVICE <name of device>

Please specify which device is used for UPS communications (normally a serial port or a USB port. The default is platform dependent, and is usually something like /dev/ttyS0. Normally, the ./configure program will set an appropriate default value, otherwise, you may also specify the --with-serial-dev= option on the ./configure program to set this directive during the installation.

LOCKFILE <path to lockfile>

By supplying this argument, "apcupsd" tries to create a lockfile for the serial port in the specified directory. This is important to keep two programs from reading or writing the serial port at the same time. Please note that although the directive name is LOCKFILE, you are actually specifying the lock file path. Apcupsd automatically appends the name of the device when creating the file. On most systems, this directive is automatically set by the ./configure program. You may also explicitly set it during the installation process by using the --with-lock-dir= option on the ./configure program.

Configuration Directives Used by the Network Information Server

None of these directives are required for proper operation of apcupsd.

NETSERVER [on | off]: This configuration directive turns the network information server on or off. If it is on, apcupsd will spawn a child process that serves STATUS and EVENTS information over the network. This information is currently used by the Web based CGI programs. The default is on. In some cases, for added security, you may want to invoke a separate information server daemon from the inetd daemon. In that case, NETSERVER should be off.
SERVERPORT <port>: This configuration directive specifies the port to be used by the apcupsd Network Information Server. The default is platform dependent, but typically 7000. If you change this port, you must manually change the #define SERV_TCP_PORT in cgi/upsfetch.c and rebuild the CGI programs. An alternative is to use the --with-nis-port= option on the ./configure program during installation. In this case, all the appropriate locations will be automatically changed.
EVENTSFILE <filename>: If you want the apcupsd network information server to provide the last 10 events via the network, you must specify a file where apcupsd will save these events. The default is: /etc/apcupsd/apcupsd.events. Currently, apcupsd will save at most the last 50 events. Periodically (once an hour by default), apcupsd will check the size of this file. When more than 50 events are recorded, apcupsd will truncate the file to the most recent 10 events. Consequently this file will not grow indefinitely. Although we do not recommend it, you may change these values by editing apcevents.c and changing the appropriate defines. Be aware that if you set these values to very large numbers, apcupsd may make excessive memory demands on the system during the data access and file truncation operations.
This filename may also be specified at installation time by using the --with-log-dir= option on the ./configure program.

Configuration Directives used during Power Failures

In general, none of these directives are required. However, if you have a simple signaling (dumb) UPS with a cable that does not support the Low Battery signal, you must set the TIMOUT directive to force a shutdown. Please see the Simple Signaling features Supported section of this manual for more details.

ANNOY <time in seconds>: Specify the time in seconds between messages requesting logged in users to get off the system during a power failure. This timer starts only when the UPS is running on batteries. The default is 300 seconds (5 minutes). apcupsd sends the annoy messages by invoking the apccontrol script with the annoyme argument. The default is to send a wall message on Unix systems and a popup in Windows. The value of ANNOYDELAY must be greater than the value of ANNOY in order to receive annoy messages (this doesn't make sense, and means that the default values do not generate annoy messages -- KES).
Note that if NOLOGON is set to disable the annoy messages will also be disabled.
ANNOYDELAY <time in seconds>: Specify delay time in seconds before apcupsd begins requesting logged in users to get off the system during a power failure. This timer starts only after the UPS is running on batteries. This timer is reset when the power returns. The default is 60 seconds. Thus, the first warning to log off the system occurs after 60 seconds on batteries, assuming that NOLOGON is not set to disable.
NOLOGON <specifies when apcupsd should prevent user logins>: [ disable | timeout | percent | minutes | always ] are valid types.; The type specified allows you define the point when apcupsd will create the /etc/nologin file and thus when user logins are prohibited. Once the /etc/nologin file is created, normal users are prevented from logging in. Control of when this file is created is important for allowing systems with BIG UPSes to run as normally until the system administrator determines the need for preventing user logins. The feature also allows the system administrator to hold the "ANNOY" factor until the /etc/nologin file is created. The default is always if no NOLOGON directive is specified.
As far as I can tell, the only useful types are disable and always since the diffence in the time when the logout warning is given and shutdown occurs for the other types is very short (KES).
BATTERYLEVEL <percent of battery>: If BATTERYLEVEL is specified, during a power failure, apcupsd will halt the system when the remaining battery charge falls below the specified percentage. The default is 5 percent. This directive is ignored for simple signaling UPSes. To totally disable this counter, set BATTERYLEVEL -1 in your apcupsd.conf file.
MINUTES <battery runtime in minutes>: If MINUTES is specified, during a power failure, apcupsd will shutdown the system when the remaining runtime on batteries as internally calculated by the UPS falls below the time specified. The default is 3. This directive is ignored for simple signaling UPSes. It should be noted that some UPSes report an incorrect value for remaining runtime when the battery is fully charged. This can be checked by examining the TIMELEFT value as printed in the output of an apcaccess status command. If the value is zero or otherwise unreasonable, your UPS is probably broken. In this case, we recommend that you disable this timer by setting MINUTES -1 in your apcupsd.conf file.
TIMEOUT <time in seconds>: After a power failure, apcupsd will halt the system when TIMEOUT seconds have expired. A value of zero disables this timer. Normally for all Smart UPS models and dumb UPSes with cables that support low battery detection, this should be zero so that the shutdown time will be determined by the battery level and/or remaining runtime (see above) or in the case of a simple signaling UPS, when the battery is exhausted. This command is required for dumb UPSes that do not provide a battery exhausted signal (only testing can determine this point). For more information, see the testing section of this manual. This timer can also be useful if you want some slave machines to shutdown before other machines to conserve battery power. It is also useful for testing apcupsd because you can force a rapid shutdown by setting a small value (e.g. 60) and pulling the plug to the UPS.; When apcupsd is running in master mode (UPSCLASS netmaster), and a shutdown condition is determined, apcupsd will notify each of the slaves to perform a shutdown then apcupsd will sleep for 30 seconds before issuing the shutdown of its own computer. If you need the master to wait additional time before shutting down (to allow for shutdown of slower slaves or of slaves running software that requires more time to shutdown -- e.g. databases), you can do so by adding additional sleep() commands to /etc/apcupsd/apccontrol in each case that causes a shutdown.; TIMEOUT, BATTERYLEVEL, and MINUTES can be set together without problems. apcupsd will react to the first case or test that is valid. Normally SmartUPS users will set TIMEOUT to zero so that the system is shutdown depending on the percentage battery charge remaining (BATTERYLEVEL) or the remaining battery runtime (MINUTES).
KILLDELAY <time in seconds>: If killdelay is set, apcupsd will continue running after a shutdown has been requested, and after the specified time in seconds, apcupsd will attempt to shut off the UPS the power. This directive should normally be disabled by setting the value to zero, but on some systems such as Win32 systems apcupsd cannot regain control after a shutdown to force the UPS to shut off the power. In this case, with proper consideration for the timing, the KILLDELAY directive can be useful. Please be aware, if you cause apcupsd to kill the power to your computer too early, the system and the disks may not have been properly prepared.

Configuration Directives used to Control System Logging

None of these directives are required.

STATTIME <time>: This directive supplies the time interval between writes to the STATUS file. If set to zero, the STATUS file will not be written. Please note that in a future version of apcupsd the STATUS file code will disappear since its functionality has been replaced by the Network Information Server and by apcaccess status, as a consequence, it is normally disabled by setting it to zero.
STATFILE <file>: This directive specifies the file to be used when writing the STATUS information. The default is /etc/apcupsd/apcupsd.status
DATATIME<time>: This directives supplies the time interval between writes of PowerChute&tm; like data information to the log file. See the DATA format specification section of this manual for additional details.
FACILITY <log-facility>: The facility directive can be used to change the system logging class or facility. The default is DAEMON. This parameter can be useful if you wish to direct the apcupsd system logging information to other than your system default files. See the logging section of this manual for additional details.

Configuration Directives for Sharing a UPS

The following directives apply to the master/slave networking mode of apcupsd where multiple machines can be powered by the same UPS. One machine, the master, will have a serial port connection to the UPS, and the other machines, the slaves, will obtain their information via the network from the master.

UPSCLASS <class of operation>

The default is standalone and should be used for all machines powered by the UPS and having a serial port connection to the UPS, but where there are no other computers dependent on power from the same UPS. This is the normal case.

Use netmaster, if and only if you have a serial port connection to the UPS and there are other machines deriving power from the same UPS. This is required in all master configuration files.

Use netslave if and only if you have no serial port connection to the UPS, but you derive power from it. This is required in all slave configuration files, and in this case, you will also have UPSCABLE set to ether.

Use shareslave if and only if you are using a ShareUPS and connected to a BASIC Port with Simple Signal. This code is not fully tested.

Use sharemaster, if and only if you are using a ShareUPS and connected to the ADVANCED Port Smart Signal control. This code is not fully tested.

UPSMODE [ disable | share | net | sharenet ] are valid types.

[ disable | net ] are the only known and tested classes.

[ share | sharenet ] classes are being tested.

For normal standalone operations, you will set UPSMODE to disable to indicate that you are disabling the master/slave networking.

However, if you are using a single UPS to power several computers and you have configured master and slave computers, then set this value to net.

Use share for two or seven (2/7) additional simple signal ports on a SmartAccessories(tm) (internal/external box) for SmartUPSes. The share and sharenet code is not fully tested.

NETTIME <time in seconds>

The interval in seconds that the master uses to send information to slave machines. This rate is automatically set to 1 second if the UPS goes on batteries and reset to your specified value when the mains power returns. A typical value might be 60 seconds.

NETPORT <IP port number>

This port number is used for communications in the master/slave networking code. Note that the master and each slave must have the same port number specified on the NETPORT directive in the configuration file. This port may also be specified during installation by using the --with-net-port= option on the ./configure program.

The NETPORT should not be confused with the port number for the Network Information Server which is specified with the SERVERPORT configuration directive.

MASTER <name of the master> for Slave machines.

Used in slave configuration files, this is the network name of the master which is authorized to send commands to this slave. In all cases (of which I am aware), when you specify a MASTER directive, you will also specify UPSCABLE ether since your information about the UPS will come via the network from a master.

The slave machine will be shutdown whichever occurs first: either at the request of the master when it does a shutdown or when the values you have specified for TIMEOUT, BATTERYLEVEL, or MINUTES expire (these should work but have not been fully tested). Consequently, if you want the slaves to begin shutting down before the master, you can do so by adjusting the values in the configuration file. If you want the slave to remain up until the master shuts down, you should set TIMEOUT, BATTERYLEVEL, and MINUTES all to zero.

For proper functioning of the slave, you must specify the same UPSTYPE in the slave configuration file as is in the master configuration file.

It should be noted that the master and slaves continue to communicate over the network even after the master has issued a shutdown command to the slaves. This is because the master apcupsd continues to run until it receives the shutdown signal from the system. This is important to ensure that all the slaves have been properly notified of the shutdown.

We recommend that the machine names used on the MASTER and SLAVE directives be put in your /etc/hosts file so that apcupsd will be able to resolve the machine name during startup and shutdown even if DNS is not running. Alternatively, you can use IP addresses on the MASTER and SLAVE directives, but this is less flexible.

SLAVE <name of slave(s)> used only in MASTER configuration files.

Used in master configuration files, this is the name of a slave machine that depends on this master. There can be a maximum of 20 slaves attached to one master. Thus you can specify multiple SLAVE directives in a master configuration file. Only one slave name can be specified per SLAVE directive, thus for multiple slaves, specify multiple SLAVE directives.

As noted above the master and slaves continue to communicate over the network even after the master has issued a shutdown command to the slaves. This is because the master apcupsd continues to run until it receives the shutdown signal from the system. This is important to ensure that all the slaves have been properly notified of the shutdown.

USERMAGIC < user defined magic> used only in SLAVE configuration files.

The USERMAGIC directive is a sort of password that gives a second level of identification security in a slave configuration file. It is a character string up to 17 characters in length. It should be unique for each slave. When the slave makes initial contact with the master, this string is passed to the master. Then on each transmission from the master to the slave, the string is passed back to the slave, which checks that it is the correct string before accepting the master's information. This string should be different for each and every slave on the network. This directive is not required.

Configuration Directives Used to Set the UPS EPROM

The values specified with the following directives are only used if the --configure option is specified on the apcupsd command line, and the UPS is capable of internal EPROM programming. In that case, apcupsd attempts to set the values into the UPSes EPROM.

Under normal operations, the values for these parameters specified in the configuration file are not used. Instead, they are read from the UPS EPROM by apcupsd. See the EEPROM programming section of this manual for further details before attempting to reprogram your EEPROM.

SENSITIVITY <sets sensitivity level>: (H)igh, (M)edium, (L)ow; This value determine how sensitive the UPS is to the mains quality and voltage fluctuations. The more sensitive it is, the quicker the UPS will switch to battery power when the mains line quality is bad. Normally, this should be set to H, but if you find your UPS switching to batteries frequently, you might want to try a less sensitive setting, providing that your computer equipment tolerates the poor quality mains. This value is written to the UPS EPROM when the configure option is specified.; Under normal apcupsd operations (no --configure option), apcupsd will read the value stored in the UPS and display it in the STATUS output.
WAKEUP <set wakeup delay>: The UPS power restart delay value in [0,60,180,300] in seconds after the UPS has shut down during a power failure. This is to prevent the power from coming back on too quickly after a power down, and is important for those who have high rpm drives that need to spindown before powering them up again. Some older SCSI models are very sensitive to this problem. Default is zero. This value is written to the UPS EPROM when the --configure option is specified. Under normal apcupsd operations (no --configure option), apcupsd will read the value stored in the UPS and display it in the STATUS output.
SLEEP <set sleep delay>: The UPS delay or grace period in [20,180,300,600] seconds before the UPS cuts the power to your equipment. The default is 20 seconds. This value is written to the UPS EPROM when the --configure option is specified. Under normal apcupsd operations (no --configure option), apcupsd will read the value stored in the UPS and display it in the STATUS output.
LOTRANSFER <lower limit of ups batt. transfer>: This sets the low line voltage point at which to switch over to batteries. Different values are permitted based on the UPS model, classification, and manufacture date. Use apcaccess eeprom to show you which values are permitted. This value is written to the UPS EPROM when the --configure option is specified.; Under normal apcupsd operations (no --configure option), apcupsd will read the value stored in the UPS and display it in the STATUS output.
HITRANSFER <upper limit of ups batt. transfer>: This sets the high line voltage point to switch over to batteries.; Different values are permitted based on the UPS model, classification, and manufacture date. Use apcaccess eeprom to show you which values are permitted. This value is written to the UPS EPROM when the --configure option is specified.; Under normal apcupsd operations (no --configure option), apcupsd will read the value stored in the UPS and display it in the STATUS output.
RETURNCHARGE <min. batt. charge level>: This parameter specifies what battery percentage charge is necessary before the UPS will supply power to your equipment after a power down. Different values are permitted based on the UPS model, classification, and manufacture date. Use apcaccess eeprom to show you which values are permitted. This value is written to the UPS EPROM when the --configure option is specified.; Under normal apcupsd operations (no --configure option), apcupsd will read the value stored in the UPS and display it in the STATUS output.
BEEPSTATE <alarm beep state>: This parameter tells the UPS when it can sound its audio alarm. These settings are based on discrete events related to the remaining capacity of the UPS.
UPSNAME <string>: This is an eight character string.This is the UPS name that will be stored in the UPS EPROM.; This value is written to the UPS EPROM when the --rename-ups option is specified. Under normal apcupsd operations (no --configure option), apcupsd will read the value stored in the UPS and display it in the STATUS output.
BATTDATE <string>: This is an eight character string that is the last date the batteries were changed.; This value is written to the UPS EPROM when the --update-battery-date option is specified. Under normal apcupsd operations (no --configure option), apcupsd will read the value stored in the UPS and display it in the STATUS output.