apcupsd(8)apcupsd(8)NAMEapcupsd - daemon for most APC's UPS for Linux
SYNOPSIS
/sbin/apcupsd
/etc/apcupsd/apccontrol
/etc/apcupsd/apcupsd.conf
/sbin/apcaccess
/sbin/apcnetd
DESCRIPTION
This document is considerably out of date. It can be used for a brief
overview of apcupsd, but you should consult the html manual for current
information. Normally this manual will be loaded on your system in the
doc directory, which varies from system to system. Otherwise, you may
find an online version at: http://www.apcupsd.com
This daemon can be used for controlling the most APC UPSes. During a
power failure, "apcupsd" will inform the users about the power failure
and that a shutdown may occur. If power is not restored, a system
shutdown will follow when the battery is exausted, a timeout (seconds)
expires, or runtime expires based on internal UPS calculations deter‐
mined by power consumption rates. If the power is restored before one
of the above shutdown conditions is met, apcupsd will inform users
about this fact.
The shutdown is made by script calls to "/etc/apcupsd/apccontrol",
which is called by "apcupsd". Consequently, no changes to /etc/inittab
are necessary. There is no communication between apcupsd and init(1)
process. Apcupsd modifies the halt script so that at the end of the
shutdown process, apcupsd will be re-executed in order to power off the
UPS. On certain platforms (e.g. FreeBSD) there is no halt script so
apccontrol must be modified to cause apcupsd to power off the UPS after
a delay time.
The apcupsd daemon now supports two networking modes that function
independently, but if desired they can both run at the same time.
Most users will probably enable the first network mode and simplest
(NIS or Network Information Service), which permits apcupsd to serve
status and event information to clients over the network.
The second networking mode is for multiple networked machines that are
powered by the same UPS. In this mode, one machine is configured as a
master with the UPS attached to the serial port. The other machines
(max. 20) powered by the same UPS are configured as slaves. The mas‐
ter has a network connection with the slaves and sends them information
about the UPS status. This mode is significantly more complicated to
setup than the NIS networking mode described above.
For details and configurations on these networking modes please see the
manual.
RedHat and SuSE versions of Linux have direct install support. All
other flavors of Linux may need some fussing with to get the install
correct.
OPTIONS-c --configure
Attempts to configure the UPS EPROM to the values specified in
the configuration file "/etc/apcupsd/apcupsd.conf". This option
is now deprecated (not supported) and should not be used.
Instead use the apctest program, which has an interactive EEPROM
configuration.
-d --debug <level>
Turns on debugging output.
-f --config-file <file>
Specifies the location of the configuration file. The default
is: /etc/apcupsd/apcupsd.conf
-k --killpower
Attempt to turn the UPS off. This option is normally only used
by the daemon itself to shut the UPS off after a system shutdown
has completed.
-V --version
Prints the apcupsd version number and the help.
-? --help
Prints a brief apcupsd help screen.
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.
Configuration commands in /etc/apcupsd/apcupsd.conf are:
GENERAL CONFIGURATION COMMANDS
UPSCABLE -- <type of cable you are using>
[ simple | 940-0020B | 940-0023A (broken) ]
[ smart | 940-0024B | 940-0024C ]
[ 940-0095A | 940-0095C ]
[ ether ]
[ usb ]
UPSTYPE -- <Type of APCC UPS you have>
[ dumb | apcsmart | net | usb | snmp | test ]
DEVICE -- <name of serial port>
Please specify which device is used for UPS communication. The default
is /dev/ttyS[0|1|2|3]. If you have a USB UPS, you should leve the
DEVICE directive blank and apcupsd will figure out where your device is
located. If you have problems, please see the manual as it has more
details.
LOCKFILE -- <path to lockfile>
By supplying this argument, "apcupsd" tries to create a lockfile for
the serial or USB port in the specified directory.
CONFIGURATION COMMANDS USED BY THE NETWORK INFORMATION SERVER
NETSTATUS [on | off]
This configuration command 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 this case, NETSTATUS should be
off.
STATUSPORT <port>
This configuration command specifies the port to be used by the apcupsd
server. The default is 3551.
EVENTFILE <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: /var/log/apcupsd.events. Currently,
apcupsd will save at most the last 50 events. When more than 50 events
are recorded and a network request for the events arrives, the network
server will truncate the file to the most recent 10 events. Conse‐
quently this file will not grow indefinitely as long as the events are
checked from time to time.
CONFIGURATION COMMANDS USED TO CONTROL SYSTEM LOGGING
STATTIME
STATFILE
DATATIME
FACILITY
CONFIGUATION COMMANDS USED DURING POWER FAILURES
ANNOY -- <time in seconds>
Please specify the time in seconds between messages requesting logged
in users to get off the system. This timer starts only when the UPS is
running on batteries. The default is 300 seconds (5 minutes).
ANNOYDELAY -- <time in seconds>
Please specify delay time in seconds before apcupsd begins requesting
logged in users to get off the system. This timer starts only after the
UPS is running on batteries. This timer is reset when the power
returns. The default is 60 seconds. That is the first warning to log
off the system occurs after 60 seconds on batteries.
NOLOGON -- <specifies when apcupsd should create the nologon file>
[ disable | timeout | percent | minutes | always ] are valid types.
Based on Ten (10) percent of a setting. This allows one to define the
point when the /etc/nologin file is added. This is important for
allowing systems with BIG UPSes to run as normally until the system
administrator determines the need for dumping users. The feature also
allows the system administrator to hold the "ANNOY" factor until the
/etc/nologin file is added.
disable prevents apcupsd from creating the nologin file.
timeout specifies a specific wait time before creating the nologin
file.
percent specifies the percent battery charge remaining before creating
the nologin file.
minutes specifies the battery runtime remaining before creating the
nologin file.
always causes the nologin file to be immediately created on a power
failure.
BATTERYLEVEL -- <percent of battery>
If BATTERYLEVEL is specified, during a power failure, apcupsd will
shutdown the system when the remaining battery charge falls below the
specified percentage. The default is 5.
MINUTES -- <battery runtime in minutes>
If MINUTES is specified, during a power failure, apcupsd will shutdown
the system when the remaining remaining runtime on batteries as inter‐
nally calculated by the UPS falls below the time specified. The default
is 3.
TIMEOUT -- <time in seconds>
After a power failure, the system will be shutdown after TIMEOUT sec‐
onds have expired. Normally for SMARTUPSes, this should be zero so
that the shutdown time will be determined by the battery level or
remaining runtime (see above). This command is useful for dumb UPSes
that do not report battery level or the remaining runtime. It is also
useful for testing apcupsd in that you can force a rapid shutdown by
setting a small value (e.g. 60) and pulling the plug to the UPS.
The timeout for the master is always 30 seconds longer than slaves.
TIMEOUT, BATTERYLEVEL, and MINUTES can be set together without prob‐
lems. The daemon 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 (BAT‐
TERYLEVEL) or the remaining battery runtime (MINUTES).
CONFIGURATION COMMANDS FOR SHARING A UPS
UPSCLASS -- <class of operation>
[ standalone | shareslave | sharemaster ] and
[ netslave | netmaster ] are valid types.
[ standalone | netslave | netmaster ] are tested classes.
[ shareslave | sharemaster ] classes are being tested.
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 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.
Use "netslave" if and only if you have no serial port connection to the
UPS, but you derive power from it.
Use "shareslave" if and only if you are using a ShareUPS and connected
to a BASIC Port with Simple Signal.
Use "sharemaster", if and only if you are using a ShareUPS and con‐
nected to the ADVANCED Port Smart Signal control.
UPSMODE -- [ disable | share | net | sharenet ] are valid types.
[ disable | net ] are the only known and tested classes.
[ share | sharenet ] classes are being tested.
BETA [ share ] For two or seven (2/7) additional simple signal ports on
a SmartAccessories(tm) (internal/external box) for SmartUPSes.
NETTIME -- <time in seconds>
The rate in seconds that broadcasts information to Slave machines.
This rate is reset if there is a power state change. This value is now
passed to the slaves to sync. the openning of a socket by the slave for
the master.
NETPORT -- <TCP|UDP port number>
This unix service port number must be set in the /etc/services file as
follows:
tab tab(spacejunk) tab tab
name (stuff)/xxp #
apcupsd NETPORT/tcp #
apcupsd NETPORT/udp #
MASTER -- <name of master> for Slave machine.
The name of the master which is authorized to send commands to this
slave.
SLAVE -- <name of slave(s)> for Master machine.
The name of the slave machine attached to the master. There can be
max. 20 slaves attached to one master.
USERMAGIC -- < user defined password> for the slave machine.
The second level of password security. It must be (17) characters long
without spaces. This is passed to the master machine during initializa‐
tion of sockets. This string should be different for each and every
slave on the network. This is not at all secure as passwords are passed
in the clear. Please protect your network by firewalling or tcpwrap‐
pers.
SMARTUPS
If you start getting the follow message:
Emergency -- Batteries Have Failed!
Change Them NOW!
Act upon it quickly. It means what it says.
Also, not all "SmartUPS" models are eqaully smart. A non-NET or old
class of "SmartUPS" has a subset of the full UPSlink(TM) language, and
can not be polled for its control codes.
SHAREUPS
Special note for ShareUPS users, TIMEOUT, BATTERYLEVEL, and MINUTES are
disabled or set to default values. Currently, there is not a known way
for early signals to be sent to BASIC Ports. MINUTES are set to 0.
FILES
/etc/apcupsd/apcupsd.conf - configuration file.
/var/log/apcupsd.status - STATUS file
/var/log/apcupsd.events - where up to the last 50 events are stored for
the network information server.
EVENTSapcupsd generates events when certain conditions occur such as a power
failure, batteries exhausted, power return,
These events are sent to the system log, optionally sent to the tempo‐
rary events file (/var/log/apcupsd.events), and they also generate a
call to /etc/apcupsd/apccontrol which in turn will call any scripts you
have placed in the /etc/apcupsd directory.
DATA format
If the DATATIME configuration command is set nonzero, apcupsd will log
a data record at the interval defined on the DATATIME command. This
data record is in a format similar to the PowerChute data file format.
STATUS format
The STATUS output is in ASCII format and generally there is a single
piece of information on each line output. The format varies based on
the type of UPS that you are using.
DATE : time and date of last update
CABLE : cable type used
UPSMODEL : ups type or signal method
UPSMODE : tells apcupsd what to check
SHARE : if ShareUPS is used, this determines what
SmartUPS and MatrixUPS Smart Signals
ULINE : Current (observed) Input Line Voltage
MLINE : Max (observed) Input Line Voltage
NLINE : Min (observed) Input Line Voltage
FLINE : Line Freq (cycles)
VOUTP : UPS Output Voltage
LOUTP : Percent Load of UPS Capacity
BOUTP : Current Charge Voltage of Batteries
BCHAR : Batteries Current Charge Percent of Capacity
BFAIL : UNSIGNED INT CODE (ups state)
UTEMP : Current UPS Temp. in Degrees Cel.
DIPSW : Current DIP switch settings for UPS.
Newer BackUPS Pro Smart Signals
ULINE : Current (observed) Input Line Voltage
MLINE : Max (observed) Input Line Voltage
NLINE : Min (observed) Input Line Voltage
FLINE : Line Freq (cycles)
VOUTP : UPS Output Voltage
LOUTP : Percent Load of UPS Capacity
BOUTP : Current Charge Voltage of Batteries
BCHAR : Batteries Current Charge Percent of Capacity
BFAIL : UNSIGNED INT CODE (ups state)
BackUPS Pro and SmartUPS v/s Smart Signals
LINEFAIL : OnlineStatus
BATTSTAT : BatteryStatus
MAINS : LineVoltageState
LASTEVNT : LastEventObserved
BackUPS and NetUPS Simple Signals
LINEFAIL : OnlineStatus
BATTSTAT : BatteryStatus
BackUPS Pro and SmartUPS v/s Smart Signals
OnlineStatus BatteryStatus LineVoltageState LastEventObserved
BackUPS and NetUPS Simple Signals
OnlineStatus BatteryStatus
SEE ALSO
The html manual installed on your system or http://www.apcupsd.com
AUTHOR
Andre M. Hedrick
Retired Co-AUTHOR
Christopher J. Reimer
Current maintainers
Kern Sibbald Adam Kropelin
Contributors
An enormous list of past and former persons who have devoted their time
and energy to this project -- thanks.
APC UPS management under Linux -- November 1999 apcupsd(8)