1
1
Desc: Network protocol info
4
4
Auth: Russell Kroll <rkroll@exploits.org>
6
This protocol primarily runs over TCP, but there is some lingering
7
support for UDP. UDP support may be removed completely if there is no
8
interest. All clients shipped with the package use upsclient and
9
therefore TCP exclusively.
11
6
As of May 2002, this protocol now has an official port number from IANA,
12
7
which is 3493. The old number (3305) was a relic of the original code's
13
8
ancestry, and conflicted with other services. Version 0.50.0 and up
14
9
use 3493 by default.
16
============================================================================
17
New commands (April 2003)
18
============================================================================
20
These commands were added to support the new long variable names. They
21
do not recognize the older names, and will not perform any sort of
22
"mapping". If you need to do something with an old variable name, use
23
the older commands below.
25
The big difference to note here is that the notion of "@upsname" is
26
gone. The upsname is now a required part of many commands, and there is
27
no "default" UPS for any of these new commands. This was done to remove
28
ambiguity and to clean up a lot of ugly code in the server.
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
Old command removal notice
16
==========================
18
Before version 1.5.0, a number of old commands were supported. These
19
have been removed from the specification. For more information, consult
20
an older version of the software.
30
25
Multi-word elements are contained within "quotes" for easier parsing.
31
26
Embedded quotes are escaped with backslashes. Embedded backslashes are
267
253
Form: INSTCMD <upsname> <cmdname>
268
254
INSTCMD su700 test.panel.start
270
============================================================================
272
============================================================================
274
These commands continue to be supported for backwards compatibility.
275
While the drivers are actually using the newer variable names
276
("ups.status" instead of STATUS), upsd will internally convert when
279
The commands which use the old variable names will be going away after
280
the 1.x series, so you should upgrade any clients that are using them.
285
Form: LISTVARS [<upsname>]
287
upsname is an identifier given to a UPS on a host. These are specified
288
in the ups.conf. If it is not specified, the server will refer to the
289
first entry from that file.
291
Returns: VARS <varlist>
292
Returns: VARS @<upsname> <varlist> (when upsname specified)
294
<varlist> is a space delimited list of all possible variables that
295
the server process knows about for this UPS.
297
Requires: MONITOR access
299
* Obsolete: switch to "LIST VAR".
304
Form: REQ <varname>[@<upsname>]
306
<varname> is a variable name returned by LISTVARS or a reserved word:
310
NUMLOGINS - Number of systems currently monitoring this UPS
311
(incremented by LOGIN commands from authorized clients)
313
<upsname> is an identifier as seen above with LISTVARS.
315
Returns: ANS <varname> <value>
316
Returns: ANS <varname>@<upsname> <value> (when upsname specified)
318
<varname> is the variable you requested, repeated just to be sure
320
<value> is the current value as the server knows it
322
*** Old versions of upsd also have a few special responses for <value>:
325
- upsd doesn't recognize this variable.
326
Replaced with "ERR VAR-UNKNOWN".
329
- this UPS driver doesn't gather data for this variable
330
Replaced with "ERR VAR-NOT-SUPPORTED".
333
- the server hasn't gotten an update for this data recently
334
Replaced with "ERR DATA-STALE".
336
Requires: MONITOR access
338
* Obsolete: switch to "GET VAR".
343
Form: LISTRW [<upsname>]
345
Returns: RW <read-write variable list>
346
RW @<upsname> <read-write variable list> (when upsname specified)
348
Requires: MONITOR access
350
Lists all variables that allow modification of their values within the
353
* Obsolete - switch to "LIST RW".
358
Form: VARTYPE <varname>[@<upsname>]
360
Returns: TYPE <vartype> <extravalue>
362
Requires: MONITOR access
364
<vartype> is one of ENUM or STRING.
366
ENUM: Enumerated type, <extravalue> is how many possibilities exist
367
STRING: Character string, <extravalue> is how long it may be
369
Lists the type of a read-write variable.
371
* Obsolete - switch to "GET TYPE".
376
Form: VARDESC <varname>
378
Returns: DESC "<variable description>"
380
Requires: MONITOR access
382
<variable description> is a short explanation of what a variable means.
384
* Obsolete - switch to "GET DESC".
389
Form: ENUM <varname>[@<upsname>]
391
Returns: multi-line return:
394
OPTION "<optval>" [SELECTED] may repeat multiple times
397
Requires: MONITOR access
399
<optval> is a valid option for <varname>. SELECTED will be included if
400
<varname> is currently set to <optval> in the hardware.
402
Shows the possible values for an enumerated type R/W variable.
404
* Obsolete - switch to "LIST ENUM".
409
Form: INSTCMD <command>[@<upsname>]
411
Requires: "INSTCMD" action granted in upsd.users
412
"<command>" instcmd granted in upsd.users
414
<command> is an instant command name. See LISTINSTCMD and shared.h.
416
* Obsolete - switch to new form: "INSTCMD <upsname> <cmdname>"
421
Form: LISTINSTCMD [<upsname>]
423
Returns: INSTCMDS [@<upsname>] <cmd1> <cmd2> ... <cmdn>
425
Requires: MONITOR access
427
Shows all the instant commands available on a given UPS.
429
* Obsolete - switch to "LIST CMD"
434
Form: INSTCMDDESC <cmdname>
436
Requires: MONITOR access
438
Returns: DESC "<description>"
440
Shows the description for a given instant command suitable for showing
443
* Obsolete - switch to "LIST CMDDESC"
448
Form: SET <varname>[@upsname] <value>
450
<value> is an acceptable sequence for the variable <varname>.
452
Requires: "SET" action granted in upsd.users
454
Sets the R/W variable <varname> to <value>, assuming it is allowed.
456
* Obsolete - switch to new form: "SET VAR <upsname> <varname> <value>".
458
============================================================================
460
============================================================================
462
These commands are not affected by the variable name change.
573
359
VER - shows the version of the server currently in use
575
361
These two are not intended to be used directly by programs. Humans can
576
make use of this program by using telnet for TCP or netcat for UDP. Try
577
either "telnet localhost 3493" for TCP or "nc -u localhost 3493" for UDP
578
and it should talk to you.
362
make use of this program by using telnet or netcat. If you use
363
telnet, make sure you don't have it set to negotiate extra options.
364
upsd doesn't speak telnet and will probably misunderstand your first
365
request due to the extra junk in the buffer.
583
This list is not yet in sync with the changes that appeared in 1.3.
585
370
ERR <message> [<extra>...]
587
372
<message> is always one element; it never contains spaces. This may
713
498
applies to a SET of an ENUM type which is using a value which is
714
499
not in the list of allowed values.
719
These are only used by the compatibility functions in upsd for the old
720
variable/command names and (naturally) by older versions of upsd.
724
- The client requested an unrecognized variable. This only applies
725
to old variable names, as there is a finite list of them.
729
- The client requested VARTYPE of something that is not recognized
730
by upsd. This should never happen.
734
- The client tried to start an unrecognized command. This is also
735
only for old command names, as they also have a finite list.
739
- The client's request is missing at least one argument. This is
740
used for compatibility with older clients.
added
removed
docs/protocol.txt
