1APCACCESS(8) BSD System Manager's Manual APCACCESS(8)
2
4 apcaccess — retrieve status information from apcupsd(8)
5
7 apcaccess [-f <config-file>] [-h <host>[:<port>]] [-p <parameter-name>]
8 [-u] [<command>] [<host>[:<port>]]
9
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
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
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
239 /etc/apcupsd/apcupsd.conf
240
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
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