Apcupsd STATUS Logging

STATUS format

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 /etc/apcupsd/apcupsd.status).

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 apcupsd. The preferred method for obtaining this information is from apcaccess status or by using the apcupsd network information server.

SmartUps

UPSTYPE            Descriptive Name
===========        =================
newbackupspro      Smarter BackUPS Pro
backupspropnp      Smarter BackUPS Pro
smartups           SmartUPS
matrixups          MatrixUPS
sharesmart         ShareUPS Advanced Port

STATUS logging

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:

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.

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.

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.

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.

An example of output from an international SmartUPS 1000 follows:

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

The meaning of the above variables are:

APC

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.

DATE

is the date and time that the information was last obtained from the UPS.

HOSTNAME

is the name of the machine that collected the UPS data.

RELEASE

is the apcupsd release number.

CABLE

is the cable as specified in the configuration file.

MODEL

is the UPS model as derived from information from the UPS.

UPSMODE

is the mode in which apcupsd is operating.

STARTTIME

is the time/date that apcupsd was started.

UPSNAME

is the name of the UPS as stored in the EEPROM.

STATUS

is the current status of the UPS (ONLINE, CHARGING, ONBATT,...)

MASTERUPD

is the last time the master sent an update to the slave. This value is present only in slave configurations.

LINEV

is the current line voltage as returned by the UPS.

LOADPCT

is the percentage of load capacity as estimated by the UPS.

BCHARGE

is the percentage charge on the batteries.

TIMELEFT

is the remaining runtime left on batteries as estimated by the UPS.

MBATTCHG

if the battery charge percentage (BCHARGE) drops below this value, apcupsd will shutdown your system.

MINTIMEL

apcupsd will shutdown your system if the remaining runtime equals or is below this point.

MAXTIME

apcupsd will shutdown your system if the time on batteries exceeds this value. A value of zero disables the feature.

MAXLINEV

is the maximum line voltage since the last STATUS as returned by the UPS.

MINLINEV

is the minimum line voltage since the last STATUS as returned by the UPS.

OUTPUTV

is the voltage the UPS is supplying to your equipment.

SENSE

is the sensitivity level of the UPS to line voltage fluctuations.

DWAKE

is the amount of time the UPS will wait after a power off condition when the power is restored.

DSHUTD

is the grace delay that the UPS gives after receiving a power down command from apcupsd before it powers off your equipment.

DLOWBATT

is the remaining runtime below which the UPS sends the low battery signal. At this point apcupsd will force an immediate emergency shutdown.

LOTRANS

is the line voltage below which the UPS will switch to batteries.

HITRANS

is the line voltage above which the UPS will switch to batteries.

RETPCT

is the percentage charge that the batteries must have after a power off condition before the UPS will restore power to your equipment.

STATFLAG

is a status flag indicating the UPS status. See STATUS.

ITEMP

is the internal UPS temperature as supplied by the UPS.

ALARMDEL

is the delay period for the UPS alarm.

BATTV

is the battery voltage as supplied by the UPS.

LINEFREQ

is the line frequency in Hertz as given by the UPS.

LASTXFER

is the reason for the last transfer to batteries.

NUMXFERS

the number of transfers to batteries since apcupsd startup.

XONBATT

time and date of last transfer to batteries, or N/A.

TONBATT

time in seconds currently on batteries, or 0.

CUMONBATT

total (cumulative) time on batteries in seconds since apcupsd startup.

XOFFBATT

time and date of last transfer from batteries, or N/A.

SELFTEST

is the results of the last self test, and may have the following values:
 
OK - self test indicates good battery
BT - self test failed due to insufficient battery capacity
NG - self test failed due to overload
NO - No results (i.e. no self test performed in the last 5 minutes).

STESTI

is the interval in hours between automatic self tests.

STATFLAG

status flag. English version is given by STATUS.

DIPSW

is the dip switch settings.

REG1

is the value from the UPS fault register 1.

REG2

is the value from the UPS fault register 2.

REG3

is the value from the UPS fault register 3.

MANDATE

is the date the UPS was manufactured.

SERIALNO

is the UPS serial number.

BATTDATE

is the date that batteries were last replaced.

NOMOUTV

is the output voltage that the UPS will attempt to supply when on battery power.

NOMBATTV

is the nominal battery voltage.

HUMIDITY

is the humidity as measured by the UPS.

AMBTEMP

is the ambient temperature as measured by the UPS.

EXTBATTS

is the number of external batteries as defined by the user. A correct number here helps the UPS compute the remaining runtime more accurately.

BADBATTS

is the number of bad battery packs.

FIRMWARE

is the firmware revision number.

APCMODEL

is the old APC model identification code.

END APC

is the time and date that the STATUS record was written.

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

BackUPS Pro and SmartUPS v/s Smart Signals

BackUPS and NetUPS Simple Signals

Logging the STATUS Information

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.

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.

Although we mention system logging of STATUS information, we strongly recommend that you use the apcupsd network information server to network this information. Also, see the system logging section of this manual.