apcupsd.conf(5)
NAME
apcupsd.conf --- apcupsd(8) configuration file
DESCRIPTION
apcupsd.conf is the configuration file for the apcupsd(8) program. The
file is a plain ASCII text file which comprises a number of configuration
directives which control how the apcupsd program behaves when controlling
most American Power Conversion Corp (APC) UPSes. The configuration file
is also used for the apctest(8) program when bulk programming the EEPROM
in a Smart-UPS model.
It will almost certainly be necessary to customise the information in the
configuration file to suit your particular configuration and operating
requirements.
Note that the apcupsd daemon must be restarted in order for changes to
the configuration file to become active.
The configuration file directives are explained in the subsections below.
GENERAL CONFIGURATION DIRECTIVES
UPSNAME <string>
Specify a name for the UPS for log files, status reports etc.
UPSCABLE [ simple | smart | ether | usb | 940-0119A | 940-0127A |
940-0128A | 940-0020B | 940-0020C | 940-0023A | 940-0024B |
940-0024C | 940-1524C | 940-0024G | 940-0095A | 940-0095B |
940-0095C | 940-0625A | MAM-04-02-2000 ]
The type of cable used to connect the UPS to the computer.
UPSTYPE [ dumb | apcsmart | net | usb | snmp | pcnet | modbus |test ]
The type of APC UPS that you have.
DEVICE <name>
The name of the device used for communication between the UPS
and the computer. For a USB UPS, you should leave the DEVICE
directive blank and apcupsd will figure out where the device is
located.
* apcsmart : /dev/tty** (serial connection)
* usb : leave blank! (USB connection)
* net : hostname:port (NIS connection)
* snmp : hostname:port:vendor:community (SNMP connection)
* dumb : /dev/tty** (serial connection)
* pcnet : ipaddr:username:passphrase (AP9617 SmartSlot card)
* modbus : /dev/tty** (serial connection)
* modbus : leave blank (USB connection)
If you have problems, please see the apcupsd manual for more
detailed information and comprehensive troubleshooting advice.
POLLTIME <seconds>
The rate in seconds that the daemon polls the UPS for status.
This rate is automatically set to 1 second when the UPS goes on
battery and reset to the specified value when the utility power
returns. This setting applies both to directly-attached UPSes
and networked UPSes. A low setting will improve the daemon's
responsiveness to certain events at the cost of higher CPU
utilisation. The default of 60 is appropriate for most
situations.
LOCKFILE <path>
apcupsd creates a lockfile for the serial or USB port in the
specified directory. It must be changed when running more than
one copy of apcupsd on the same computer to control multiple
UPSes.
SCRIPTDIR <path>
Directory in which apccontrol and event scripts are located.
Defaults to /usr/local/etc/apcupsd. It must be changed when
running more than one copy of apcupsd on the same computer to
control multiple UPSes.
PWRFAILDIR <path>
Directory in which apcupsd writes the powerfail flag file
created when apcupsd initiates a system shutdown. The directory
is checked in halt scripts to determine if turning off the UPS
output power is required. Defaults to /var/run. It must be
changed when running more than one copy of apcupsd on the same
computer to control multiple UPSes.
NOLOGINDIR <path>
Directory in which apcupsd writes the nologin file which tells
the OS to disallow new logins. Defaults to /var/run. It must be
changed when running more than one copy of apcupsd on the same
computer to control multiple UPSes.
NIS CONFIGURATION DIRECTIVES
NETSERVER [ on | off ]
Turns the network information server (NIS) on or off. When on,
apcupsd serves status and event information over the network.
This information is also used by the web-based CGI monitoring
programs. The default is set to on.
NISIP <IP address>
Specifies the IP address of the network interface on which
apcupsd will listen for incoming connections. The default value
is 0.0.0.0 which means the NIS will listen for connections on
all network interfaces. If the computer has more than one
interface, you can specify the IP of a single interface to limit
connections to that interface. Specifying the loopback address
(127.0.0.1) will cause the NIS daemon to accept connections only
from the local computer.
NISPORT <port>
Specifies the port to be used by the NIS daemon. The default is
3551 which has been received from IANA as the official apcupsd
networking port. It must be changed when running more than one
copy of apcupsd on the same computer to control multiple UPSes.
EVENTSFILE <filename>
If you want NIS to provide the last 10 events via the network,
you must specify a file where apcupsd will save these events.
The default is: /var/log/apcupsd.events. apcupsd will save at
most the last 50 events to this file. When more than 50 events
are saved and a network request for the events arrives, apcupsd
will truncate the file to the most recent 10 events. It must be
changed when running more than one copy of apcupsd on the same
computer to control multiple UPSes.
LOGGING CONFIGURATION DIRECTIVES
STATTIME <seconds>
Specifies the time interval between writes to the status file.
If set to zero, the status file will not be written. The status
file will disappear in a future apcupsd version as its
functionality has been replaced by the Network Information
Server and the apcaccess(8) program.
STATFILE <file>
Specifies the file to be used when writing the status
information. The default is /etc/apcupsd/apcupsd.status. It
must be changed when running more than one copy of apcupsd on
the same computer to control multiple UPSes.
LOGSTATS [ on | off ]
Activate log file. This generates a lot of output, so if you
turn this on, be sure that the file defined in syslog.conf(5)
for LOG_NOTICE is a named pipe.
DATATIME <seconds>
Specifies the time interval between writes of the APC PowerChute
software-like data information to the log file.
FACILITY <log-facility>
Change the system logging (syslog) 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 syslog.conf(5) for details of other possible
facilities and general system logging configuration.
POWER FAILURE CONFIGURATION DIRECTIVES
ONBATTERYDELAY <seconds>
The number of seconds from when a power failure is detected
until apcupsd reacts with an onbattery event.
BATTERYLEVEL <percentage>
apcupsd will shutdown the system during a power failure when the
remaining battery charge falls below the specified percentage.
The default is 5.
MINUTES <minutes>
apcupsd will shutdown the system during a power failure when the
remaining runtime on batteries as internally calculated by the
UPS falls below the specified minutes. The default is 3.
TIMEOUT <seconds>
After a power failure occurs, apcupsd will shutdown the system
after the specified number of seconds have expired. For a
Smart-UPS, this should normally be set to zero so that the
shutdown time will be determined by the battery level or
remaining runtime (see above). This command is, however, useful
for a Back-UPS or other simple signalling UPS which does not
report battery level or the remaining runtime. It is also useful
for testing apcupsd because you can force a rapid shutdown by
setting a small value (eg 60) and turning off the power to the
UPS.
TIMEOUT, BATTERYLEVEL, and MINUTES can all be set without
problems. apcupsd will initiate a shutdown when the first of
these conditions becomes valid.
ANNOY <seconds>
Specifies the time in seconds between broadcast messages
requesting logged in users to log off from the system. This
timer starts only when the UPS is running on battery. The
default is 300 seconds (5 minutes).
ANNOYDELAY <seconds>
Specifies the delay time in seconds before broadcast messages
requesting logged in users to log off from the system. This
timer starts only after the UPS is running on battery power.
This timer is reset when the power returns. The default is 60
seconds (ie the first request to log off occurs after 60 seconds
on battery power).
NOLOGON [ disable | timeout | percent | minutes | always ]
Specifies when apcupsd should create the nologon file to prevent
users from logging on to the system.
"disable" prevents apcupsd from creating the nologin file.
"timeout" specifies a specific wait time before apcupsd creates
the nologin file.
"percent" specifies the percentage of battery charge remaining
before apcupsd creates the nologin file.
"minutes" specifies the battery runtime remaining before apcupsd
creates the nologin file.
"always" specifies that apcupsd should create the nologin file
immediately after a power failure occurs.
This directive is important for allowing systems with BIG UPSes
to run normally until the system administrator determines the
need for dumping users. It also allows the system administrator
to hold the "ANNOY" factor until the /etc/nologin file is
created.
KILLDELAY <seconds>
Specifies the number of seconds for which apcupsd will continue
running after a shutdown has been requested. After the specified
time, apcupsd will attempt to put the UPS into hibernate mode
and kill the power to the computer. This is for use on operating
systems where apcupsd cannot regain control after a shutdown (eg
FreeBSD) to issue an apcupsd --killpower command. Setting the
delay to 0 disables it.
SHARE-UPS CONFIGURATION DIRECTIVES
UPSCLASS [ standalone | shareslave | sharemaster ]
The default is "standalone" and should be used for all computers
powered by the UPS, with a direct connection to the UPS and
where there are no other computers dependent on power from the
UPS. This is the "normal" case.
Use "shareslave" if you are using a Share-UPS interface expander
and connected to the BASIC port (simple signalling).
Use "sharemaster", if you are using a Share-UPS interface
expander and connected to the ADVANCED port (smart signalling).
UPSMODE [ disable | share ]
Set to "disable" for normal standalone operation to indicate
that you are disabling the Share-UPS interface expander support.
Set to "share" for two to seven additional simple signalling
ports on a Share-UPS interface expander. This code may not be
fully tested in every new release.
APCTEST EEPROM CONFIGURATION DIRECTIVES
These directives have no effect on the operation of apcupsd(8) but are
reserved for use by apctest(8) when bulk programming the values of the
UPS EEPROM configuration variables in a Smart-UPS model.
UPSNAME <string>
Name of UPS. Maximum of 8 characters.
BATTDATE [ mm/dd/yy | dd/mm/yy ]
Last battery replacement date. Maximum of 8 characters.
SENSITIVITY [ H | M | L ]
H : High (most sensitive setting)
M : Medium
L : Low (least sensitive setting)
WAKEUP [ 000 | 060 | 180 | 300 ]
The time delay in seconds that the UPS waits after the return of
utility power before "waking up" and restoring power to the
connected equipment.
SLEEP [ 020 | 180 | 300 | 600 ]
The time delay in seconds for which the UPS waits or "sleeps"
after it receives a request to power off the connected system.
LOTRANSFER <voltage>
Low line voltage causing transfer to battery power or activation
of SmartBoost. Allowable values depend on the last letter of
the firmware or APCMODEL. Typical values are:
D 106 103 100 097
M 177 172 168 182
A 092 090 088 086
I 208 204 200 196
where D = domestic (USA), M = Canada, A = Asia and I =
International.
HITRANSFER <voltage>
High line voltage causing transfer to battery power or
activation of SmartTrim. Allowable values depend on the last
letter of the firmware or APCMODEL. Typical values are:
D 127 130 133 136
M 229 234 239 224
A 108 110 112 114
I 253 257 261 265
where D = domestic (USA), M = Canada, A = Asia and I =
International.
RETURNCHARGE [ 00 | 15 | 50 | 90 ]
Percentage of battery charge needed for the UPS to restore power
to the connected equipment.
BEEPSTATE [ 0 | T | L | N ]
Alarm delay.
0 : Zero delay after power fails.
T : When power fails plus 30 seconds.
L : When low battery occurs.
N : Never.
LOWBATT <minutes>
Low battery warning occurs when the specified number of minutes
remains before the UPS estimates battery power will be
exhausted. There are four user-changeable settings: 2, 5, 7, or
10 minutes
OUTPUTVOLTS <voltage>
UPS nominal output voltage when running on battery. Allowable
values depend on the last letter of the firmware or APCMODEL.
Typical values are:
D 115
M 208
A 100
I 230 240 220 225
where D = domestic (USA), M = Canada, A = Asia and I =
International.
SELFTEST [ 336 | 168 | ON | OFF ]
Self test interval in hours (336 = 2 weeks, 168 = 1 week, ON =
at power on, OFF = never).
EXAMPLES
Note that in the following examples, the device names assume that you are
using Linux. Device names for serial devices in *BSD and other operating
systems will be different.
Minimal USB Configuration for a USB UPS
UPSCABLE usb
UPSTYPE usb
DEVICE
LOCKFILE /var/lock
UPSCLASS standalone
UPSMODE disable
Notice no device name is specified. apcupsd(8) will try all the well
known USB ports. Only specify a specific USB device name if you know what
you are doing. For detailed information on setting up a USB UPS, refer to
the "USB Configuration" section of the apcupsd manual.
Minimal Serial Configuration for a Smart UPS
UPSCABLE smart
UPSTYPE apcsmart
DEVICE /dev/ttyS0
LOCKFILE /var/lock
UPSCLASS standalone
UPSMODE disable
Normally there would be more configuration directives to completely
customise your installation, but this example shows the minimum required.
Minimal Serial Configuration for a Dumb UPS
UPSCABLE <number of the cable used>
UPSTYPE dumb
DEVICE /dev/ttyS0
LOCKFILE /var/lock
UPSCLASS standalone
UPSMODE disable
If your cable does not have low battery detection (eg such cables include
the APC 940-0020B and 940-0023A), you will also need to define the
TIMEOUT <seconds> configuration directive to set the number of seconds on
battery during a power failure after which apcupsd will do a system
shutdown.
Normally there would be more configuration directives to completely
customise your installation, but this example shows the minimum required.
FILES
/etc/apcupsd/apcupsd.conf default configuration file
SEE ALSO
syslog.conf(5), apcupsd(8), apctest(8).
The HTML apcupsd manual installed on your system or available online at
http://www.apcupsd.org/
AUTHORS
Trevor Roydhouse (current)
Andre M. Hedrick
Christopher J. Reimer
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
