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: apcupsd Status Logging
Up: Apcupsd User's Guide
Previous: Technical Reference
Contents
Index
2009-03-11