1
Desc: Network protocol info
4
Auth: Russell Kroll <rkroll@exploits.org>
6
As of May 2002, this protocol now has an official port number from IANA,
7
which is 3493. The old number (3305) was a relic of the original code's
8
ancestry, and conflicted with other services. Version 0.50.0 and up
11
This protocol runs over TCP. UDP support was dropped in July 2003. It
12
had been deprecated for some time and was only capable of the simplest
13
query commands as authentication is impossible over a UDP socket.
15
A library, named libupsclient, that implement this protocol is provided
16
in both static and shared version to help the client application development.
18
Old command removal notice
19
==========================
21
Before version 1.5.0, a number of old commands were supported. These
22
have been removed from the specification. For more information, consult
23
an older version of the software.
28
Multi-word elements are contained within "quotes" for easier parsing.
29
Embedded quotes are escaped with backslashes. Embedded backslashes are
30
also escaped by representing them as \\. This protocol is intended to
31
be interpreted with parseconf or something similar.
36
Retrieve a single response from the server.
38
Possible sub-commands:
43
Form: GET NUMLOGINS <upsname>
46
Response: NUMLOGINS <upsname> <value>
49
<value> is the number of clients which have done LOGIN for this UPS.
50
This is used by the master upsmon to determine how many clients are
51
still connected when starting the shutdown process.
53
This replaces the old "REQ NUMLOGINS" command.
58
Form: GET UPSDESC <upsname>
61
Response: UPSDESC <upsname> "<description>"
62
UPSDESC su700 "Development box"
64
<description> is the value of "desc=" from ups.conf for this UPS. If it
65
is not set, upsd will return "Unavailable".
67
This can be used to provide human-readable descriptions instead of a
68
cryptic "upsname@hostname" string.
73
Form: GET VAR <upsname> <varname>
74
GET VAR su700 ups.status
76
Response: VAR <upsname> <varname> "<value>"
77
VAR su700 ups.status "OL"
79
This replaces the old "REQ" command.
84
Form: GET TYPE <upsname> <varname>
85
GET TYPE su700 input.transfer.low
87
Response: TYPE <upsname> <varname> <type>...
88
TYPE su700 input.transfer.low ENUM
90
<type> can be several values, and multiple words may be returned:
92
RW - this variable may be set to another value with SET
93
ENUM - an enumerated type, which supports a few specific values
94
STRING:n - this is a string of maximum length n
96
ENUM and STRING are usually associated with RW, but not always.
98
This replaces the old "VARTYPE" command.
103
Form: GET DESC <upsname> <varname>
104
GET DESC su700 ups.status
106
Response: DESC <upsname> <varname> "<description>"
107
DESC su700 ups.status "UPS status"
109
<description> is a string that gives a brief explanation of the named
110
variable. upsd may return "Unavailable" if the file which provides this
111
description is not installed.
113
Different versions of this file may be used in some situations to
114
provide for localization and internationalization.
116
This replaces the old "VARDESC" command.
121
Form: GET CMDDESC <upsname> <cmdname>
122
GET CMDDESC su700 load.on
124
Response: CMDDESC <upsname> <cmdname> "<description>"
125
CMDDESC su700 load.on "Turn on the load immediately"
127
This is like DESC above, but it applies to the instant commands.
129
This replaces the old "INSTCMDDESC" command.
134
The LIST functions all share a common container format. They will
135
return "BEGIN LIST" and then repeat the initial query. The list then
136
follows, with as many lines are necessary to convey it. "END LIST" with
137
the initial query attached then follows.
139
The formatting may seem a bit redundant, but it makes a different form
140
of client possible. You can send a LIST query and then go off and wait
141
for it to get back to you. When it arrives, you don't need complicated
142
state machines to remember which list is which.
149
Response: BEGIN LIST UPS
150
UPS <upsname> "<description>"
155
UPS su700 "Development box"
158
<upsname> is a name from ups.conf, and <description> is the value of
159
desc= from ups.conf, if available. It will be set to "Unavailable"
162
This can be used to determine what values of <upsname> are valid before
163
calling other functions on the server. This is also a good way to
164
handle situations where a single upsd supports multiple drivers.
166
Clients which perform a UPS discovery process may find this useful.
171
Form: LIST VAR <upsname>
174
Response: BEGIN LIST VAR <upsname>
175
VAR <upsname> <varname> "<value>"
177
END LIST VAR <upsname>
180
VAR su700 ups.mfr "APC"
181
VAR su700 ups.mfr.date "10/17/96"
185
This replaces the old "LISTVARS" command.
190
Form: LIST RW <upsname>
193
Response: BEGIN LIST RW <upsname>
194
RW <upsname> <varname> "<value>"
196
END LIST RW <upsname>
199
RW su700 output.voltage.nominal "115"
200
RW su700 ups.delay.shutdown "020"
204
This replaces the old "LISTRW" command.
209
Form: LIST CMD <upsname>
212
Response: BEGIN LIST CMD <upsname>
213
CMD <upsname> <cmdname>
215
END LIST CMD <cmdname>
219
CMD su700 test.panel.start
223
This replaces the old "LISTINSTCMD" command.
228
Form: LIST ENUM <upsname> <varname>
229
LIST ENUM su700 input.transfer.low
231
Response: BEGIN LIST ENUM <upsname> <varname>
232
ENUM <upsname> <varname> "<value>"
234
END LIST ENUM <upsname> <varname>
236
BEGIN LIST ENUM su700 input.transfer.low
237
ENUM su700 input.transfer.low "103"
238
ENUM su700 input.transfer.low "100"
240
END LIST ENUM su700 input.transfer.low
242
This replaces the old "ENUM" command.
244
Note: this does not support the old "SELECTED" notation. You must
245
request the current value separately.
250
Form: SET VAR <upsname> <varname> "<value>"
251
SET VAR su700 ups.id "My UPS"
256
Form: INSTCMD <upsname> <cmdname>
257
INSTCMD su700 test.panel.start
264
Returns: OK Goodbye (recent versions)
266
Used to disconnect gracefully from the server.
268
Older versions just said "Goodbye...".
273
Form: LOGIN <upsname>
275
Returns: OK (upon success)
278
Requires: "upsmon slave" or "upsmon master" in upsd.users
280
Use this to log the fact that a system is drawing power from this UPS.
281
The upsmon master will wait until the count of attached systems reaches
282
1 - itself. This allows the slaves to shut down first.
284
NOTE: You probably shouldn't send this command unless you are upsmon,
285
or a upsmon replacement.
290
Form: MASTER <upsname>
292
Returns: OK (upon success)
295
Requires: "upsmon master" in upsd.users
297
This function doesn't do much by itself. It is used by upsmon to make
298
sure that master-level functions like FSD are available if necessary.
305
Returns: OK FSD-SET (success)
308
Requires: "upsmon master" in upsd.users
309
or "FSD" action granted in upsd.users
311
upsmon in master mode is the primary user of this function. It sets this
312
"forced shutdown" flag on any UPS when it plans to power it off. This is
313
done so that slave systems will know about it and shut down before the
316
Setting this flag makes "FSD" appear in a STATUS request for this UPS.
317
Finding "FSD" in a status request should be treated just like a "OB LB".
319
It should be noted that FSD is currently a latch - once set, there is
320
no way to clear it short of restarting upsd or dropping then re-adding
321
it in the ups.conf. This may cause issues when upsd is running on a
322
system that is not shut down due to the UPS event.
327
Form: PASSWORD <password>
329
Returns: OK (upon success)
332
Sets the password associated with a connection. Used for later
333
authentication for commands that require it.
338
Form: USERNAME <username>
340
Returns: OK (upon success)
343
Sets the username associated with a connection. This is also used for
344
authentication, specifically in conjunction with the upsd.users file.
354
This tells upsd to switch to TLS mode internally, so all future
355
communications will be encrypted. You must also change to TLS mode in
356
the client after receiving the OK, or the connection will be useless.
361
HELP - lists the commands supported by this server
362
VER - shows the version of the server currently in use
364
These two are not intended to be used directly by programs. Humans can
365
make use of this program by using telnet or netcat. If you use
366
telnet, make sure you don't have it set to negotiate extra options.
367
upsd doesn't speak telnet and will probably misunderstand your first
368
request due to the extra junk in the buffer.
373
ERR <message> [<extra>...]
375
<message> is always one element; it never contains spaces. This may
376
be used to allow additional information (<extra>) in the future.
380
- The client's host and/or authentication details (username, password)
381
are not sufficient to execute the requested command.
385
- The UPS specified in the request is not known to upsd. This usually
386
means that it didn't match anything in ups.conf.
390
- The specified UPS doesn't support the variable in the request.
392
This is also sent for unrecognized variables which are in a space
393
which is handled by upsd, such as server.*.
397
- The specified UPS doesn't support the instant command in the request.
401
- The client sent an argument to a command which is not recognized or
402
is otherwise invalid in this context. This is typically caused by
403
sending a valid command like GET with an invalid subcommand.
407
- upsd failed to deliver the instant command request to the driver.
408
No further information is available to the client. This typically
409
indicates a dead or broken driver.
413
- upsd failed to deliver the set request to the driver. This is
414
just like INSTCMD-FAILED above.
418
- The requested variable in a SET command is not writable.
422
- The requested value in a SET command is too long.
424
FEATURE-NOT-SUPPORTED
426
- This instance of upsd does not support the requested feature. This
427
is only used for TLS/SSL mode (STARTTLS) at the moment.
429
FEATURE-NOT-CONFIGURED
431
- This instance of upsd hasn't been configured properly to allow the
432
requested feature to operate. This is also limited to STARTTLS for
437
- TLS/SSL mode is already enabled on this connection, so upsd can't
442
- upsd can't perform the requested command, since the driver for that
443
UPS is not connected. This usually means that the driver is not
444
running, or if it is, the ups.conf is misconfigured.
448
- upsd is connected to the driver for the UPS, but that driver isn't
449
providing regular updates or has specifically marked the data
450
as stale. upsd refuses to provide variables on stale units to avoid
453
This generally means that the driver is running, but it has lost
454
communications with the hardware. Check the physical connection
459
- The client already sent LOGIN for a UPS and can't do it again.
460
There is presently a limit of one LOGIN record per connection.
464
- The client sent an invalid PASSWORD - perhaps an empty one.
468
- The client already set a PASSWORD and can't set another. This also
469
should never happen with normal NUT clients.
473
- The client sent an invalid USERNAME.
477
- The client has already set a USERNAME, and can't set another. This
478
should never happen with normal NUT clients.
482
- The requested command requires a username for authentication,
483
but the client hasn't set one.
487
- The requested command requires a passname for authentication,
488
but the client hasn't set one.
492
- upsd doesn't recognize the requested command.
494
This can be useful for backwards compatibility with older versions
495
of upsd. Some NUT clients will try GET and fall back on REQ after
496
receiving this response.
500
- The value specified in the request is not valid. This usually
501
applies to a SET of an ENUM type which is using a value which is
502
not in the list of allowed values.
510
The LIST commands may be given the ability to handle options some day.
511
For example, "LIST VARS <ups> +DESC" would return the current value
512
like now, but it would also append the description of that variable.
517
After sending an INSTCMD or SET, a client will eventually be able to
518
poll to see whether it was completed successfully by the driver.