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

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       | <===========
          |                     |
          |                     |
           --------------------- 

Configuration Directives

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

General Configuration Directives

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

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 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.

Configuration Directives Used by the Network Information Server

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 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.

Configuration Directives Used by the Network Information Server

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 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.

Configuration Directives Used by the Network Information Server

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 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.