"APCC UPS management under Linux Docs."
DESCRIPTION
The daemon, "apcupsd", can be used for controlling the all APC UPS models.
When the power failure or varies, apcupsd will inform all users about
the current power status at a user defined rate in seconds.
When the power is restored before user defined parameters test TRUE,
apcupsd will inform users about this fact. If power is not restored, the
system shutdown will follow when the battery is exausted or a timeout
expires. The whole shutdown is now made by script calls to the
/sbin/powersc file called by "apcupsd" so no changes in the inittab
are necessary. There is now no communication between "apcupsd" and
init(1) process.
It now supports the networking mode. In this mode, one machine is
configured as a master, with UPS attached to the serial port. Other machines
(max. 10) are configured as a slaves. Master has a network connection with
slaves and send them informations about timeouts, power restore etc. The
master machine is also logging the UPS status informations to the text file.
The final version of "apcupsd" will come out after all the "network"
support is complete. I am asking for any and all help with "socket" code.
I am currently working from "powerd-2.0" and "apcd-0.5". I will take any
and all help.
The "apcupsd" must be setuid root !!
Slackware, RedHat, S.u.S.E., Debian, and UNIFIX "FLAVORS" of Linux have direct
install support. All other "FLAVORS" of Linux will need some fussing with
to get the install correct. Please send me all new install methods that
are not listed above or corrections to these for future versions before
the final release.
CONFIGURATION
It is necessary to write configuration info to the file /etc/apcupsd.conf.
This file is a plain ASCII file and you can use your favorite editor for
configuration. For simple configuration, see enclosed sample file.
Configuration commands in /etc/apcupsd.conf are:
CONTROL -- <path|filename> for All machines.
Name of control script that "apcupsd" calls.
The default file is /sbin/powersc.
UPSCABLE -- <cable model> for Master machine.
The following are valid types:
[ simple | smart | 940-0020B ]
[ 940-0023A ] broken code....
[ 940-0024B | 940-0024C | 940-0095A ]
[ 940-0095C | ether ]
UPSTYPE -- <Type of APCC UPS> for Master machine.
The following are valid types:
[ backups | sharebasic | netups ]
[ backupspro | smartvsups | newbackupspro ]
[smartups | matrixups | sharesmart ]
These are known and tested models.
[ backups | netups ]
[ backupspro | smartvsups ]
[ newbackupspro | smartups ]
These models are being tested.
[ sharebasic | sharesmart ]
This model is unknown but should work as a smartups.
[ matrixups ]
UPSCLASS -- <class of operation> for All machines.
The following are valid types:
[ standalone ]
[ shareslave | sharemaster ]
[ netslave | netmaster ]
This is the only known and tested class.
[ standalone | netslave | netmaster ]
These classes are being tested.
[ shareslave | sharemaster ]
Default for all machines is standalone.
Change to shareslave if and only if you are using a ShareUPS and
connected to a BASIC Port with Simple Signal. Change to sharemaster
if and only if you are using a ShareUPS and connected to the
ADVANCED Port Smart Signal control. Change to netslave
if and only if you are not connected to an UPS other than for power.
Change to netmaster if and only if you are on a TCP/UDP network
and connected to an UPS of any kind with other Linux Boxes.
UPSMODE -- <mode of extended operation> for All machines.
The following are valid types:
[ disable | share | net | sharenet ]
This is the only known and tested class.
[ disable | net ]
This class is being tested.
[ share | sharenet ]
BETA [ share ] For two or seven (2/7) additional simple signal
ports on a SmartAccessories(tm) (internal/external box) for SmartUPSes.
DEVICE -- <name of serial port> for Master machine.
Please specify which device is used for UPS communication.
The default is /dev/ttyS[0|1|2|3].
LOCKFILE -- <path to lockfile>
By supplying this argument "apcupsd" tries to create a lockfile in the
specified directory.
ANNOY -- <time in seconds> for All machines.
Please specify time in seconds for "apcupsd" to harrass logged in
users to get off the system.
DELAY -- <time in seconds> for All machines.
Please specify time in seconds for "apcupsd" to delay harrassing logged
in users to get off the system. This rate is reset if there is a power
state change. If ANNOY == DELAY then DELAY is disabled.
PROCFS -- <time in seconds> Now valid for All machines.
Please specify time in seconds for "apcupsd" to update the psuedo proc
fs file /etc/apcupsd.status. This rate is reset if there is a power
state change.
LOGGING -- <time in seconds> Now valid for All machines.
Please specify time in seconds for "apcupsd" to update the log file
/var/log/apcupsd.log. This rate is reset if there is a power state change.
TIMEOUT -- <time in seconds> for Master machine.
This is the timeout between power failure and system shutdown. The
timeout for master is always 30 seconds longer than slaves.
BATTERYLEVEL -- <percent of battery> for Master machine.
Only valid for Newer BackUPS Pro and SmartUPS. Instead of setting
TIMEOUT, "apcupsd" can react based on the remaining charge left
in the batteries.
SENSITIVITY -- <sets sensitiviy level> for Master machine.
Only valid for UPSes capable of Internal EPROM programming.
(H)igh, (M)edium, (L)ow
WAKEUP -- <set wakeup delay> for Master machine.
Only valid for UPSes capable of Internal EPROM programming.
0,60,180,300 Cycles default 0
SLEEP -- <set sleep delay> for Master machine.
Only valid for UPSes capable of Internal EPROM programming.
20,180,300,600 Cycles default 20
LOTRANSFER -- <sets lower limit of ups batt. transfer> for Master machine.
Only valid for UPSes capable of Internal EPROM programming.
0,1,2,3
HITRANSFER -- <sets upper limit of ups batt. transfer> for Master machine.
Only valid for UPSes capable of Internal EPROM programming.
0,1,2,3
RETURNCHARGE -- <sets min. batt. charge level before power> for Master machine.
Only valid for UPSes capable of Internal EPROM programming.
0,1,2,3
BEEPSTATE -- <sets alarm beep state> for Master machine.
Only valid for UPSes capable of Internal EPROM programming.
0 always
T low batt + 30
L low batt
N never
UPSNAME -- <string> default UPS_IDEN
Only valid for UPSes capable of Internal EPROM programming.
BATTCMD -- <path|filename> for Master machine.
Name of the program to run when the battery fails.
TIMECMD -- <path|filename> for Master machine.
Name of the program to run when TIMEOUT has expired.
LOADCMD -- <path|filename> for Master machine.
Name of the program to run when the BATTERYLEVEL has dropped
below the set limits.
PWRCMD -- <path|filename> for Master machine.
Name of the program to run when the power fails.
RETCMD -- <path|filename> for Master machine.
Name of the program to run when the power returns.
NETTIME -- <time in seconds> for Master machine.
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> for All machines.
This 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 authorised to send commands to this slave.
Currently not installed.
SLAVE -- <name of slave(s)> for Master machine.
The name of the slave machine attached to the master.
There can be max. 10 slaves attached to one master.
USERMAGIC -- < user defined magic> for Slave machine.
The second level of magic security. It must be (17) characters long
without spaces. This is passed to the master machine during
initialization of sockets. This string should be different for
each and every slave on the network.
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.
TIMEOUT and BATTERYLEVEL can be set togather without problems.
The daemon will react to the first case or test that is valid.
SHAREUPS
Special note for ShareUPS users, both BATTERYLEVEL and TIMEOUT
are disabled or set to default values. Currently, there is not a known
way of early signals to be sent to BASIC Ports.
CABLES
Firstly, you will need the cable between APC Smart UPS and PC computer
running Linux. You can use either the special cable which is enclosed with
the PowerChute (TM) software or you can make your own cable connected as
follows:
SMART-CUSTOM
PC (9 pin) APC (9 pin)
2 RxD 2
3 TxD 1
5 GND 9
SIMPLE-CUSTOM
DB9/25F PC Side DB9M UPS Side
4/20 DTR (5vcc) nc (*)
8/5 CTS (low-batt) 5 (*)
2/3 RxD (other line-fail) 3 (*)
5/7 Ground (Signal) 4
1/8 CD (line-fail from ups) 2
7/4 RTS (shutdown ups) 1
nc/1 Frame/Case Gnd (optional) 9
List if componets one needs to make this CABLE:
1) One (1) DB9 use solder type connector only.
2) One (1) DB9/25F use solder type connector only.
3) two (2) 4.7K ohm 1/4 watt %5 resistors.
4) one (1) foot of 3/32" (inch) shrink wrap/boot.
5) rosin core solder.
6) three (3) to five (5) feet of 22AWG multi-stranded five
(5) conductor cable.
First solder both of the resistors into pin# (4) DB9 or (20) DB25 the DTR.
This will be used as the Vcc pull-up voltage for testing the outputs on
any "UPS by APC" ONLY in Simple Signal mode. This may not work on a
BackUPS Pro if the default communications are Smart Signal mode. This
cable is valid for ShareUPS BASIC Port mode if there are no other
cables that can be gotten.
Next bend each of the resistors so that one connects to (8) DB9 or (5) DB25
the CTS (aka battery low signal) and the other to (2) DB9 or (3) DB25 the
RxD (aka another line fail signal). This line is not currently used, but
it will be in the near future.
(*) 8/5 is also wire to pin# 5 on UPS cable side.
(*) 2/3 is also wire to pin# 3 on UPS cable side.
(*) we use the DTR as our +5 volts power for the circuit.
The rest of the wire connections are listed above.
If you have one of the following cables supplied by APCC, "apcupsd"
will support off the shelf cables.
940-0020B Simple Signal Only, all models.
940-0024[B/C] SmartMode Only, SU and BKPro only.
940-0095[A/C] PnP (Plug and Play), all models.
940-0023A Simple Signal UNIX, [BROKEN STILL].
FILES
/etc/apcupsd.conf -- configuration file.
/etc/apcupsd.status -- psuedo procfs-type file.
APC : 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 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)
UTEMP : Current UPS Temp. in Degrees Cel.
BackUPS Pro and SmartUPS v/s Smart Signals:
LINEFAIL : OnlineStatus
BATTSTAT : BatteryStatus
LINEVOLT : LineVoltageState
LASTEVNT : LastEventObserved
BackUPS and NetUPS Simple Signals:
LINEFAIL : OnlineStatus
BATTSTAT : BatteryStatus
/var/log/apcupsd.log -- the UPS status is logged.
SmartUPS MatrixUPS Smart Signals:
LineVoltage LineMax LineMin LineFreq OutputVoltage UPSLoad
BattVoltage BatteryLoad UPSLoad UPSTemp
Newer BackUPS Pro Smart Signals:
LineVoltage LineMax LineMin LineFreq OutputVoltage UPSLoad
BattVoltage BatteryLoad UPSLoad
BackUPS Pro and SmartUPS v/s Smart Signals:
OnlineStatus BatteryStatus LineVoltageState LastEventObserved
BackUPS and NetUPS Simple Signals:
OnlineStatus BatteryStatus
FILE FORMAT
Both "apcupsd.log" and "apcupsd.status" are simple ascii files with
several floating point numbers on one line or text. The format varies
based on the type of UPS that you are using.
AUTHOR
"Andre M. Hedrick" <hedrick@astro.dyer.vanderbilt.edu>
RETIRED Co-AUTHOR
"Christopher J. Reimer" <reimer@doe.carleton.ca>
THE BRAVE UNAMED PATCH-WORKS and TESTERS
"Daniel Quinlan" <quinlan@pathname.com>
"Tom Kunicki" <kunicki@surgery.wisc.edu>
"Karsten Wiborg" <4wiborg@informatik.uni-hamburg.de>
"Jean-Michel Rouet" <JM.ROUET@maisel-gw.enst-bretagne.fr>
"Chris Adams" <cadams@ro.com>
"Jason Orendorf" <orendorf@sprintmail.com>
"Neil McAllister" <pcm2@sentient.com>
"Werner Panocha" <WPanocha@t-online.de>
"Lee Maisel" <martian@rt66.com>
"Brian Schau" <bsc@fleggaard.dk>
"Riccardo Facchetti" <riccardo@master.oasi.gpa.it>
THE INFORMATION HELPERS and TESTERS.
"Eric S. Raymond" <esr@snark.thyrsus.com>
"Chris Hanson" <cph@martigny.ai.mit.edu>
"Pavel Alex" <pavel@petrolbank.mldnet.com>
"Theo Van Dinter" <felicity@kluge.net>
"Thomas Porter" <txporter@mindspring.com>
"Alan Davis" <davis@ele.uri.edu>
"Oliver Hvrmann" <ollo@compuserve.com>
"Scott Horton" <Scott.Horton1@bridge.bellsouth.com>
"Matt Hyne" <mhyne@tip.CSIRO.AU>
"Chen Shiyuan" <csy@hjc.edu.sg>
OTHER CREDITS
"Miquel van Smoorenburg" <miquels@drinkel.cistron.nl>
"The Doctor What" <docwhat@itek.net>
"Pavel Korensky" <pavelk@dator3.anet.cz>
BUGS AND LIMITATIONS
Any other name will cause an error when loading the /etc/apcupsd.conf
file. There are some known problems and limitations. There can be a
problem with the newest types of APC Smart UPS add-ons. Any and All
Network Modes is not supported, yet. No bugs in standard stuff. I
am sure, well pretty sure. Possible bugs in all ShareUPS mode types.
