next up previous contents index
Next: apcupsd Status Logging Up: Apcupsd User's Guide Previous: Technical Reference   Contents   Index

Subsections


Configuration Directive Reference

Configuration directives in /etc/apcupsd/apcupsd.conf control the behavior of the apcupsd daemon. For most installations it is only necessary to set a handful of general directives. The rest can be left at their defaults unless you have an exotic configuration.


General Configuration Directives

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

UPSTYPE <type of APC UPS you have>
The name of a driver. Should be one of dumb, apcsmart, net, usb, snmp, or test. This describes your interface type.

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

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-0119A]
                [ ether | usb ]

The --with-upscable= option of ./configure can be used to set a default for this directive during the your build.

DEVICE <name of device>
Specify which device is used for UPS communications. For serial ports, it is usually something like /dev/ttyS0. For USB ports, you may leave the name of the device blank (no specification) and apcupsd will automatically search the standard locations for the UPS.

Normally, the ./configure program will set an appropriate default value. You may also specify the --with-serial-dev= option of the ./configure program to set this directive at build time.

If you have specified UPSTYPE net, then the device name to be specified consists of hostname:port where the hostname is the fully qualified name or IP address of the host (NIS server) and the port (optional) is the port to use to contact the server.

If you specified UPSTYPE snmp, then the device name becomes hostname:vendor:community. Please see the SNMP chapter (see Support for SNMP UPSes) in this manual for more details.

POLLTIME <time in seconds>
The interval, in seconds, at which apcupsd polls the UPS for status. 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. This setting applies both to directly-attached UPSes (UPSTYPE apcsmart, usb, dumb) and networked UPSes (UPSTYPE net, snmp). Lowering this setting will improve apcupsd's responsiveness to certain events at the cost of higher CPU utilization. The default of 60 is appropriate for most situations. This directive was formerly known as NETTIME.

LOCKFILE <path to lockfile>
This option tells apcupsd where to create a lockfile for the USB or serial port in the specified directory. This is important to keep two programs from reading or writing the 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 build process by using the --with-lock-dir= option of 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.

NISIP <IP-address>
This directive specifies the IP address of the network interface on which the NIS server will listen for incoming connections. Default value is 0.0.0.0 which means the NIS will listen for connections on all network interfaces. If your machine has more than one interface, you can specify the IP of a single interface to limit connections to only that interface. Furthermore, you can specify the loopback address (127.0.0.1) to accept connections only from the local machine. You may also use the --with-nisip= option of the ./configure program to set this directive during the build.

This directive does not work on Win32 machines because inet_ipton() is not implemented there.

NISPORT <port>
This configuration directive specifies the port to be used by the apcupsd Network Information Server. The default is platform dependent, but typically 3551, which we have received from IANA as the official apcupsd networking port. 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 of the ./configure program during the build. 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 build time by using the --with-log-dir= option of the ./configure program.


Configuration Directives used during Power Failures

In general, none of these directives are required. However, if you have a voltage-signalling (dumb) UPS with a cable that does not support the Low Battery signal, you must set the TIMEOUT directive to force a shutdown. Please see the Cables (see Cables) section of this manual for more details.

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 dumb (voltage-signalling) 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 dumb (voltage-signalling) 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 voltage-signalling 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 (see

Testing Apcupsd) 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.

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

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 message 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 'nologin' file and thus when user logins are prohibited. Once the '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 'nologin' file is created. The default is always disable if no NOLOGON directive is specified.

The 'nologin' file will be created in the directory specified by the NOLOGINDIR directive desribed below.

As far as I can tell, the only useful types are disable and always since the difference in the time when the logout warning is given and shutdown occurs for the other types is very short (KES).

disable
prevents apcupsd from creating the nologin file. Consequently, any user can login during a power failure condition. Also, the ANNOY feature is disabled so users will not be warned to logoff the system.

timeout
specifies that apcupsd should prohibit logins after the UPS is on batteries for 90% of the time specified on the TIMEOUT configuration directive. Note! Normally you don't want to specify a TIMEOUT value, so this option is probably not too useful (KES).

percent
specifies that apcupsd should prohibit logins when the remaining battery charge percentage reaches 110% or less than the value specified on the BATTERYLEVEL configuration directive. Thus if the BATTERYLEVEL is specified as 15, apcupsd will prohibit logins when the battery charge drops below 16% (15% X 110% = 16%).

minutes
specifies that apcupsd should prohibit logins when the remaining runtime in minutes reaches 110% or less than the value specified on the MINUTES configuration directive. Thus if MINUTES is set to 3, apcupsd will prohibit logins when the remaining runtime is less than 3 minutes (3 X 110% = 3).

always
causes apcupsd to immediately prohibit logins when a power failure occurs. This will also enable the ANNOY feature.

NOLOGINDIR <path to nologin dir>
This directive configures the directory into which apcupsd will write the nologin file, as described above for the NOLOGON directive.

Normally, the ./configure program will set an appropriate default value for your platform, often /etc. You may also specify the --with-nologdir= option of the ./configure program to change the default at compile time.

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. In addition, apcupsd must continue running after the shutdown is requested, and on Unix systems, this is not normally the case as the system will terminate all processes during the shutdown.

SCRIPTDIR <path to apccontrol dir>
This option configures the directory in which apccontrol and other event scripts are located.

Normally, the ./configure program will set an appropriate default value for your platform, often /etc/apcupsd.

PWRFAILDIR <path to powerfail dir>
When apcupsd shuts down your system, it creates a temporary "flag file" which is used by the operating system halt scripts to know if this shutdown is due to a power failure. This directive configures which directory the flag file will be written into. The chosen directory must be writable by the user apcupsd is running as (normally root) and must not be cleared or unmounted early in the shutdown sequence.

Normally, the ./configure program will set an appropriate default value for your platform, often /etc/apcupsd. You may also specify the --with-pwrfaildir= option of the ./configure program to change the default at compile time.


Configuration Directives used to Control System Logging

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 (see DATA Logging) 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 sharing an UPS using a ShareUPS hardware module. Most users will not use this mode.

UPSCLASS <class of operation>
[ standalone | shareslave | sharemaster ] are valid types.

The default is standalone and should be used for all machines powered by the UPS and having a serial port or other direct connection to the UPS. This is the normal case.

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 <mode of operation>
[disable | share ] are valid modes.

For normal standalone operations, you will set UPSMODE to disable to indicate that you are disabling the ShareUPS support.

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.


Configuration Directives Used to Set the UPS EPROM

NOTE. THESE ARE DEPRECIATED AND NO LONGER WORK IN APCUPSD PLEASE USE APCTEST

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 Configuration Directives Used to Set the UPS EPROM 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 spin down 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 apcupsdoperations (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 apcupsdoperations (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 apcupsdoperations (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 apcupsdoperations (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.

0
immediately upon power failure

T
power failure + 30 seconds

L
low battery power

N
never

UPSNAME <string> This is an eight character string. This is the UPS name that will be stored in the UPS EPROM.

BATTDATE <string> This is an eight character string that is the last date the batteries were changed.


next up previous contents index
Next: apcupsd Status Logging Up: Apcupsd User's Guide Previous: Technical Reference   Contents   Index
2009-11-06