<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<title>Apcupsd STATUS</title>
<meta name="Author" content="Kern Sibbald">
<link rel=stylesheet href="apcupsd-styles.css" type="text/css">
</head>
<body>
<h2>Apcupsd STATUS Logging</h2>
There is a good deal of information available about the
UPS and apcupsd's status. This document describes the format
of that information.
<h2>STATUS format</h2>
The STATUS output is in ASCII format with a single data value
or piece of information on each line output. Because not all
UPSes supply the same information, the output varies based on
the type of UPS that you are using. In general, if the information
is not available for your UPS, the data portion of the output
record will contain an <b>N/A</b> indicating that the information
is not available.
<P>Status logging consists of periodically logging ALL available
information concerning the UPS. Since the volume of data is
rather large (over 1000 bytes per status), the STATUS data
is not automatically sent to the system log file,
instead, it is written as a series of data
records to a specific file (normally <b>/etc/apcupsd/apcupsd.status</b>).
</P>
<P>After each write, the file is rewound so that the size of the file
remains constant. At the current time, this file is 1135 bytes. The
format of this file is very similar to the old apcupsd procfs file.
The STATUS file is kept for backwards compatibility and will be
eliminated in a future version of <b>apcupsd</b>. The preferred method
for obtaining this information is from <a href="apcaccess.html"><b>apcaccess status</b></a> or
by using the <b>apcupsd</b> <a href="cgiprogs.html">network information server</a>.
<h3>SmartUps</h3>
From the following models:
<pre>
UPSTYPE Descriptive Name
=========== =================
newbackupspro Smarter BackUPS Pro
backupspropnp Smarter BackUPS Pro
smartups SmartUPS
matrixups MatrixUPS
sharesmart ShareUPS Advanced Port
</pre>
<H3>STATUS logging</H3>
</P>
<P>To make reading the status data reliable via a named pipe, the
first record written contains a version number, the number of records
that follow the first record, and the total number of bytes in those
subsequent records. An actual example of such a status file
(/etc/apcupsd/apcupsd.status) is:
</P>
<P>Consequently, the first record always consists of 24 bytes (23
characters followed by a newline). This record starts with APC and as
indicated in the example above is followed by 28 records consisting
of 675 bytes. The last record begins with END APC and contains the
date and time matching the DATE record.
</P>
<P>Documentation of each record needs to be written. In the coming
weeks, I plan to add additional records and possibly change the names
of some of the fields.
</P>
<P>When this data is written to a file, it is written as two records,
the first record, and all the other records together. In reading the
file, it can be either be read a record at a time, or in one big
read.
</P>
<P>When this data is written to syslog(), it is written a record at a
time. The first record is the first 24 bytes. By having the number of
records and the size in the first record, the complete status can be
reliably reassembled.
</P>
<p>
An example of output from an international SmartUPS 1000 follows:
<PRE>
DATE : Wed Sep 27 17:30:23 CEST 2000
HOSTNAME : polymatou.sibbald.com
RELEASE : 3.7.3-20000925
CABLE : Custom Cable Smart
MODEL : SMART-UPS 1000
UPSMODE : Stand Alone
STARTTIME: Wed Sep 27 10:39:23 CEST 2000
UPSNAME : UPS_IDEN
STATUS : ONLINE
LINEV : 235.3 Volts
LOADPCT : 9.3 Percent Load Capacity
BCHARGE : 100.0 Percent
TIMELEFT : 130.0 Minutes
MBATTCHG : 5 Percent
MINTIMEL : 3 Minutes
MAXTIME : 0 Seconds
MAXLINEV : 239.2 Volts
MINLINEV : 234.0 Volts
OUTPUTV : 236.6 Volts
SENSE : High
DWAKE : 000 Seconds
DSHUTD : 020 Seconds
DLOWBATT : 02 Minutes
LOTRANS : 196.0 Volts
HITRANS : 253.0 Volts
RETPCT : 000.0 Percent
ITEMP : 32.8 C Internal
ALARMDEL : 5 seconds
BATTV : 27.9 Volts
LINEFREQ : 50.0 Hz
LASTXFER : Line voltage notch or spike
NUMXFERS : 0
XONBATT : N/A
TONBATT : 0 seconds
CUMONBATT: 0 seconds
XOFFBATT : N/A
SELFTEST : NO
STESTI : 336
STATFLAG : 0x08 Status Flag
DIPSW : 0x00 Dip Switch
REG1 : 0x00 Register 1
REG2 : 0x00 Register 2
REG3 : 0x00 Register 3
MANDATE : 07/31/99
SERIALNO : QS9931125245
BATTDATE : 07/31/99
NOMOUTV : 230
NOMBATTV : 24.0
HUMIDITY : N/A
AMBTEMP : N/A
EXTBATTS : 0
BADBATTS : N/A
FIRMWARE : 60.11.I
APCMODEL : IWI
END APC : Wed Sep 27 17:30:31 CEST 2000
</PRE>
<p>The meaning of the above variables are:
<dl style="margin-left: 0.39in">
<dt>APC<dd>is the header record indicating the STATUS format
revision level, the number of records that follow the APC statement,
and the number of bytes that follow the record.
<dt>DATE<dd>is the date and time that the information was
last obtained from the UPS.
<dt>HOSTNAME<dd>is the name of the machine that collected the UPS data.
<dt>RELEASE<dd>is the <b>apcupsd</b> release number.
<dt>CABLE<dd>is the cable as specified in the configuration file.
<dt>MODEL<dd>is the UPS model as derived from information from the UPS.
<dt>UPSMODE<dd>is the mode in which <b>apcupsd</b> is operating.
<dt>STARTTIME<dd>is the time/date that <b>apcupsd</b> was started.
<dt>UPSNAME<dd>is the name of the UPS as stored in the EEPROM.
<dt>STATUS<dd>is the current status of the UPS (ONLINE, CHARGING, ONBATT,...)
<dt>MASTERUPD<dd>is the last time the master sent an update to the slave.
This value is present only in slave configurations.
<dt>LINEV<dd>is the current line voltage as returned by the UPS.
<dt>LOADPCT<dd>is the percentage of load capacity as estimated by the UPS.
<dt>BCHARGE<dd>is the percentage charge on the batteries.
<dt>TIMELEFT<dd>is the remaining runtime left on batteries as estimated by the UPS.
<dt>MBATTCHG<dd>if the battery charge percentage (BCHARGE) drops below this
value, <b>apcupsd</b> will shutdown your system.
<dt>MINTIMEL<dd><b>apcupsd</b> will shutdown your system if the
remaining runtime equals or is below this point.
<dt>MAXTIME<dd><b>apcupsd</b> will shutdown your system if the time on batteries
exceeds this value. A value of zero disables the feature.
<dt>MAXLINEV<dd>is the maximum line voltage since the last STATUS as returned by the UPS.
<dt>MINLINEV<dd>is the minimum line voltage since the last STATUS as returned by the UPS.
<dt>OUTPUTV<dd>is the voltage the UPS is supplying to your equipment.
<dt>SENSE<dd>is the sensitivity level of the UPS to line voltage fluctuations.
<dt>DWAKE<dd>is the amount of time the UPS will wait after a power off condition
when the power is restored.
<dt>DSHUTD<dd>is the grace delay that the UPS gives after receiving a power down
command from <b>apcupsd</b> before it powers off your equipment.
<dt>DLOWBATT<dd>is the remaining runtime below which the UPS sends the low
battery signal. At this point <b>apcupsd</b> will force an immediate
emergency shutdown.
<dt>LOTRANS<dd>is the line voltage below which the UPS will switch to batteries.
<dt>HITRANS<dd>is the line voltage above which the UPS will switch to batteries.
<dt>RETPCT<dd>is the percentage charge that the batteries must have after a
power off condition before the UPS will restore power to your equipment.
<dt>STATFLAG<dd>is a status flag indicating the UPS status. See STATUS.
<dt>ITEMP<dd>is the internal UPS temperature as supplied by the UPS.
<dt>ALARMDEL<dd>is the delay period for the UPS alarm.
<dt>BATTV<dd>is the battery voltage as supplied by the UPS.
<dt>LINEFREQ<dd>is the line frequency in Hertz as given by the UPS.
<dt>LASTXFER<dd>is the reason for the last transfer to batteries.
<dt>NUMXFERS<dd>the number of transfers to batteries since <b>apcupsd</b> startup.
<dt>XONBATT<dd>time and date of last transfer to batteries, or N/A.
<dt>TONBATT<dd>time in seconds currently on batteries, or 0.
<dt>CUMONBATT<dd>total (cumulative) time on batteries in seconds since <b>apcupsd</b> startup.
<dt>XOFFBATT<dd>time and date of last transfer from batteries, or N/A.
<dt>SELFTEST<dd>is the results of the last self test, and may have the
following values:
<br>
<br>OK - self test indicates good battery
<br>BT - self test failed due to insufficient battery capacity
<br>NG - self test failed due to overload
<br>NO - No results (i.e. no self test performed in the last 5 minutes).
<dt>STESTI<dd>is the interval in hours between automatic self tests.
<dt>STATFLAG<dd>status flag. English version is given by STATUS.
<dt>DIPSW<dd>is the dip switch settings.
<dt>REG1<dd>is the value from the UPS fault register 1.
<dt>REG2<dd>is the value from the UPS fault register 2.
<dt>REG3<dd>is the value from the UPS fault register 3.
<dt>MANDATE<dd>is the date the UPS was manufactured.
<dt>SERIALNO<dd>is the UPS serial number.
<dt>BATTDATE<dd>is the date that batteries were last replaced.
<dt>NOMOUTV<dd>is the output voltage that the UPS will attempt to
supply when on battery power.
<dt>NOMBATTV<dd>is the nominal battery voltage.
<dt>HUMIDITY<dd>is the humidity as measured by the UPS.
<dt>AMBTEMP<dd>is the ambient temperature as measured by the UPS.
<dt>EXTBATTS<dd>is the number of external batteries as defined by
the user. A correct number here helps the UPS compute the
remaining runtime more accurately.
<dt>BADBATTS<dd>is the number of bad battery packs.
<dt>FIRMWARE<dd>is the firmware revision number.
<dt>APCMODEL<dd>is the old APC model identification code.
<dt>END APC<dd>is the time and date that the STATUS record was
written.
</dl></p>
<h3>BackUPS Pro and SmartUPS v/s Smart Signals</h3>
<pre>
LINEFAIL : OnlineStatus
BATTSTAT : BatteryStatus
LINEVOLT : LineVoltageState
LASTEVNT : LastEventObserved
</pre>
<h3>BackUPS and NetUPS Simple Signals</h3>
<pre>
LINEFAIL : OnlineStatus
BATTSTAT : BatteryStatus
</pre>
<h3>BackUPS Pro and SmartUPS v/s Smart Signals</h3>
OnlineStatus BatteryStatus LineVoltageState
LastEventObserved
<h3>BackUPS and NetUPS Simple Signals</h3>
OnlineStatus BatteryStatus
<h2>Logging the STATUS Information</h2>
If specified in the configuration file, the STATUS data will also be written
to the system log file. Please note, that it would not normally be
wise to write this data to a normal system log file as there is no
mechanism in syslog() to rewind the file and hence the log file would
quickly become enormous. However, in two cases, it can be very useful
to use syslog() to write this information.
</P>
<P>The first case is to setup your syslog.conf file so that the data
is written to a named pipe. In this case, normally not more than
about 8192 bytes of data will be kept before it is discarded by the
system.
</P>
<P>The second case is to setup your syslog.conf file so that the
status data is sent to another machine, which presumably then writes
it to a named pipe. Consequently, with this mechanism, provides a
simple means of networking apcupsd STATUS information.
<p>
Although we mention system logging of STATUS information,
we strongly recommend that you use the <b>apcupsd</b>
<a href="cgiprogs.html">network information server</a> to
network this information. Also, see the
<a href="logging.html">system logging</a> section
of this manual.
<hr>
<a href="security.html" target="_self"><img src="back.gif" border=0 alt="Back"></a>
<a href="upsbible.html" target="_self"><img src="next.gif" border=0 alt="Next"></a>
<a href="index.html"><img src="home.gif" border=0 alt="Home"></a>
</body>
</html>
