1APCACCESS(8)              BSD System Manager's Manual             APCACCESS(8)
2

NAME

4     apcaccess — retrieve status information from apcupsd(8)
5

SYNOPSIS

7     apcaccess [-f <config-file>] [-h <host>[:<port>]] [-p <parameter-name>]
8               [-u] [<command>] [<host>[:<port>]]
9

DESCRIPTION

11     apcaccess is a program which prints out the complete status of most Amer‐
12     ican Power Conversion Corp. (APC) UPSes provided you have the apcupsd(8)
13     daemon installed, properly configured and running. It can access status
14     information from any APC UPS attached to the localhost or attached to any
15     computer on the network which is running apcuspd in NIS mode.
16
17     The command line options are:
18
19     -f         configuration file of apcupsd (default is usually
20                /etc/apcupsd/apcupsd.conf)
21
22     -h         hostname and port of apcupsd to communicate with.  The default
23                hostname and port are obtained from the configuration file.
24
25     -p         Report only the value of the named parameter instead of all
26                parameters and values.
27
28     -u         Remove units field for easier parsing by scripts.
29
30     <command>  An optional command, unless a hostname is also being speci‐
31                fied. The only implemented command is status Shorthand for
32                status localhost:3551.  This produces a full printout of the
33                available status information for the associated UPS.
34
35     <host>     An optional hostname which may be a bare machine name, fully
36                qualified domain name or IP address.
37
38     :<port>    An optional port number where a hostname argument has been
39                specified. The default is 3551, the official port number
40                assigned by IANA for the apcupsd NIS server.  The default
41                hostname and port are obtained from the configuration file.
42
43     apcaccess uses apcupsd's inbuilt Network Information Server (NIS) -- no
44     relation to Sun's NIS/YP service -- to obtain the current status informa‐
45     tion from the UPS on the local or remote computer. It is therefore neces‐
46     sary to have the following configuration directives:
47
48             NETSERVER on
49             NISPORT 3551
50
51     in the /etc/apcupsd/apcupsd.conf configuration file so that the Network
52     Information Server will be accessible.  Firewall rules for appropriate
53     network access may also be needed.
54

STATUS REPORT FORMAT

56     The status report output format is simple ASCII. Generally there is a
57     single piece of information on each line of output. The content varies
58     based on the model of UPS being used and, in some cases, the firmware
59     version.
60

EXAMPLES

62     Set out below is a sample of the status output which may be generated for
63     the specified UPS models.
64
65   All models
66     APC         : version, number of records and number of bytes following
67     DATE        : Date and time of last update from UPS
68     HOSTNAME    : hostname of computer running apcupsd
69     VERSION     : apcupsd version number, date and operating system
70     UPSNAME     : UPS name from configuration file (dumb) or EEPROM (smart)
71     CABLE       : Cable type specified in the configuration file
72     MODEL       : UPS model derived from UPS information
73     UPSMODE     : Mode in which UPS is operating
74     STARTTIME   : Date and time apcupsd was started
75     STATUS      : UPS status.  One or more of the following (space-sepa‐
76                 rated): CAL TRIM BOOST ONLINE ONBATT OVERLOAD LOWBATT
77                 REPLACEBATT NOBATT SLAVE SLAVEDOWN
78                 or
79                 COMMLOST
80                 or
81                 SHUTTING DOWN
82     MASTERUPD   : Last time the master sent an update to the slave
83     ENDAPC      : Date and time of status information was written
84
85   Smart-UPS and Matrix-UPS (Smart Signalling)
86     LINEV     : Current input line voltage
87     LOADPCT   : Percentage of UPS load capacity used as estimated by UPS
88     BCHARGE   : Current battery capacity charge percentage
89     TIMELEFT  : Remaining runtime left on battery as estimated by the UPS
90     MBATTCHG  : Min battery charge % (BCHARGE) required for system shutdown
91     MINTIMEL  : Min battery runtime (MINUTES) required for system shutdown
92     MAXTIME   : Max battery runtime (TIMEOUT) after which system is shutdown
93     MAXLINEV  : Maximum input line voltage since apcupsd started
94     MINLINEV  : Min (observed) input line voltage since apcupsd started
95     OUTPUTV   : Current UPS output voltage
96     SENSE     : Current UPS sensitivity setting for voltage fluctuations
97     DWAKE     : Time UPS waits after power off when the power is restored
98     DSHUTD    : Delay before UPS powers down after command received
99     DLOWBATT  : Low battery signal sent when this much runtime remains
100     LOTRANS   : Input line voltage below which UPS will switch to battery
101     HITRANS   : Input line voltage above which UPS will switch to battery
102     RETPCT    : Battery charge % required after power off to restore power
103     ITEMP     : UPS internal temperature in degrees Celcius
104     ALARMDEL  : Delay period before UPS starts sounding alarm
105     BATTV     : Current battery voltage
106     LINEFREQ  : Current line frequency in Hertz
107     LASTXFER  : Reason for last transfer to battery since apcupsd startup
108     NUMXFERS  : Number of transfers to battery since apcupsd startup
109     XONBATT   : Date, time of last transfer to battery since apcupsd startup
110     TONBATT   : Seconds currently on battery
111     CUMONBATT : Cumulative seconds on battery since apcupsd startup
112     XOFFBAT   : Date, time of last transfer off battery since apcupsd startup
113     SELFTEST  : Date and time of last self test since apcupsd startup
114     STESTI    : Self-test interval
115     STATFLAG  : UPS status flag in hex
116     DIPSW     : Current UPS DIP switch settings
117     REG1      : Fault register 1 in hex
118     REG2      : Fault register 2 in hex
119     REG3      : Fault register 3 in hex
120     MANDATE   : UPS date of manufacture
121     SERIALNO  : UPS serial number
122     BATTDATE  : Date battery last replaced (if set)
123     NOMOUTV   : Nominal output voltage to supply when on battery power
124     NOMBATTV  : Nominal battery voltage
125     EXTBATTS  : Number of external batteries (for XL models)
126     BADBATTS  : Number of bad external battery packs (for XL models)
127     FIRMWARE  : UPS firmware version
128     APCMODEL  : APC model information
129
130   Newer Back-UPS Pro (Smart Signalling)
131     LINEV     : Current input line voltage
132     LOADPCT   : Percentage of UPS load capacity used
133     MBATTCHG  : Min battery charge % (BCHARGE) required for system shutdown
134     MINTIMEL  : Min battery runtime (MINUTES) required for system shutdown
135     MAXTIME   : Max battery runtime (TIMEOUT) after which system is shutdown
136     MAXLINEV  : Maximum input line voltage since apcupsd startup
137     MINLINEV  : Minimum input line voltage since apcupsd startup
138     OUTPUTV   : Current UPS output voltage
139     BATTV     : Current battery charge voltage
140     STATFLAG  : UPS status flag in hex
141
142   Back-UPS RS 1500 (USB)
143     LINEV     : Current input line voltage
144     LOADPCT   : Percentage of UPS load capacity used
145     BCHARGE   : Current battery capacity charge percentage
146     TIMELEFT  : Remaining runtime left on battery as estimated by UPS
147     MBATTCHG  : Min battery charge % (BCHARGE) required for system shutdown
148     MINTIMEL  : Min battery runtime (MINUTES) required for system shutdown
149     MAXTIME   : Max battery runtime (TIMEOUT) after which system is shutdown
150     *OUTPUTV  : Current UPS output voltage
151     *DWAKE    : Time UPS waits after power off when the power is restored
152     *DSHUTD   : Delay before UPS powers down after command received
153     LOTRANS   : Input line voltage below which UPS will switch to battery
154     HITRANS   : Input line voltage above which UPS will switch to battery
155     *RETPCT   : Battery charge % required after power off to restore power
156     *ITEMP    : UPS internal temperature in degrees Celcius
157     ALARMDEL  : Delay period before UPS starts sounding alarm
158     BATTV     : Current battery voltage
159     *LINEFREQ : Current line frequency in Hertz
160     *LASTXFER : Reason for last transfer to battery since apcupsd startup
161     NUMXFERS  : Number of transfers to battery since apcupsd startup
162     XONBATT   : Date, time of last transfer to battery since apcupsd startup
163     TONBATT   : Seconds currently on battery
164     CUMONBATT : Cumulative seconds on battery since apcupsd startup
165     XOFFBAT   : Date, time of last transfer off battery since apcupsd startup
166     SELFTEST  : Date and time of last self test since apcupsd startup
167     STATFLAG  : UPS status flag in hex
168     MANDATE   : UPS date of manufacture
169     SERIALNO  : UPS serial number
170     BATTDATE  : Date battery last replaced (if set)
171     NOMBATTV  : Nominal battery voltage
172     FIRMWARE  : UPS firmware version
173     APCMODEL  : APC model information
174     * presence dependant on USB firmware version.
175
176   Web/SNMP (AP9716) or PowerNet SNMP (AP9605) SmartSlot Card
177     LINEV     : Current input line voltage
178     LOADPCT   : Percentage of UPS load capacity used as estimated by UPS
179     BCHARGE   : Current battery capacity charge percentage
180     TIMELEFT  : Remaining runtime left on battery as estimated by UPS
181     MBATTCHG  : Min battery charge % (BCHARGE) required for system shutdown
182     MINTIMEL  : Min battery runtime (MINUTES) required for system shutdown
183     MAXTIME   : Max battery runtime (TIMEOUT) after which system is shutdown
184     MAXLINEV  : Maximum input line voltage since apcupsd startup
185     MINLINEV  : Minimum input line voltage since apcupsd startup
186     OUTPUTV   : UPS output voltage
187     SENSE     : Current UPS sensitivity setting for voltage fluctuations
188     DWAKE     : Time UPS waits after power off when the power is restored
189     DSHUTD    : Delay before UPS powers down after command received
190     DLOWBATT  : Low battery signal sent when this much runtime remains
191     LOTRANS   : Input line voltage below which UPS will switch to battery
192     HITRANS   : Input line voltage above which UPS will switch to battery
193     RETPCT    : Battery charge % required after power off to restore power
194     ITEMP     : UPS internal temperature in degrees Celcius
195     ALARMDEL  : Delay period before UPS starts sounding alarm
196     LINEFREQ  : Current line frequency in Hertz
197     NUMXFERS  : Number of transfers to battery since apcupsd startup
198     TONBATT   : Seconds currently on battery
199     CUMONBATT : Cumulative seconds on battery since apcupsd startup
200     XOFFBATT  : Date, time of last transfer off battery since apcupsd startup
201     STESTI    : Self-test interval
202     STATFLAG  : UPS status flag in hex
203     DIPSW     : Current UPS DIP switch settings
204     MANDATE   : UPS date of manufacture
205     SERIALNO  : UPS serial number
206     BATTDATE  : Date battery last replaced (if set)
207     NOMOUTV   : Nominal output voltage to supply when on battery power
208     NOMPOWER  : Nominal power output in watts
209     EXTBATTS  : Number of external batteries (for XL models)
210     BADBATTS  : Number of bad external battery packs (for XL models)
211     FIRMWARE  : UPS firmware version
212     APCMODEL  : APC model information
213
214   Share-UPS (AP9270) (Basic port)
215     MBATTCHG  : Min battery charge % (BCHARGE) required for system shutdown
216     MINTIMEL  : Min battery runtime (MINUTES) required for system shutdown
217     MAXTIME   : Max battery runtime (TIMEOUT) after which system is shutdown
218     NUMXFERS  : Number of transfers to battery since apcupsd startup
219     TONBATT   : Seconds currently on battery
220     CUMONBATT : Cumulative seconds on battery since apcupsd startup
221     XOFFBATT  : Date, time of last transfer off battery since apcupsd startup
222     STATFLAG  : UPS status flag in hex
223
224   UPS Environmental Monitoring SmartSlot Card (AP9612TH)
225     HUMIDITY  : Ambient humidity
226     AMBTEMP   : Ambient temperature
227
228   Back-UPS Pro and Smart-UPS v/s (Smart Signalling)
229     LINEFAIL  : Input line voltage status.
230     BATTSTAT  : Battery status.
231     LASTXFER  : Last (observed) transfer to battery.
232
233   Back-UPS and Net-UPS (Simple Signalling)
234     LINEFAIL  : Input line voltage status.
235     BATTSTAT  : Battery status.
236     STATFLAG  : UPS status flag in hex.
237

FILES

239     /etc/apcupsd/apcupsd.conf
240

SEE ALSO

242     apcupsd.conf(5), apcupsd(8).
243
244     The HTML apcupsd manual installed on your system or available online at
245     http://www.apcupsd.org/
246

AUTHORS

248   This page
249     Trevor Roydhouse
250
251   Software
252     Adam Kropelin (current Project Manager and Code Maintainer)
253     Kern Sibbald (former Project Manager and Code Maintainer)
254     Riccardo Facchetti (former Project Manager and Code Maintainer)
255     Andre M. Hedrick (Project Founder and former Code Maintainer)
256
257   Contributors
258     An enormous number of users who have devoted their time and energy to
259     this project -- thanks.
260
261apcaccess v3.14.6               March 28, 2014               apcaccess v3.14.6
Impressum