Desc: Network protocol info
File: protocol.txt
Date: 11 July 1999

Here's a quick description of how the network protocol works...

This protocol is run over both TCP and UDP, uses English words to perform
operations, and consists of lines terminated by a CR/LF pair.  It is not
case sensitive, but the examples here will be all uppercase to clearly
show what is being sent and received.

LISTVARS
========

Form: LISTVARS [upsname]

upsname is an identifier given to a UPS on a host.  These are specified
in the upsd.conf.  To use the first/default UPS, don't give any upsname.

Returns: VARS <varlist>
Returns: VARS <upsname> <varlist>	(when upsname specified)

<varlist> is a space delimited list of all possible variables that
the server process knows about for this UPS.

REQ
===

Form: REQ <varname>[@upsname]

<varname> is a variable name returned by LISTVARS
<upsname> is an identifier as seen above with LISTVARS.

Returns: ANS <varname> <value>
Returns: ANS <varname>@<upsname> value	(when upsname specified)

<varname> is the variable you requested, repeated just to be sure

<value> is the current value as the server knows it, or a special meaning:

NOT-SUPPORTED: this UPS model doesn't gather data for this variable
   DATA-STALE: the server hasn't gotten an update for this data recently

LOGOUT
======

Form: LOGOUT

TCP mode only.  Used to disconnect gracefully from the server.

LOGIN
=====

Form: LOGIN [upsname]

Returns: OK	(upon success)
	 or various errors

Use this to announce to upsd that you are drawing power from that UPS
so it should wait until you have logged out when a shutdown is necessary.

PASSWORD
========

Form: PASSWORD <password>

Returns: OK	(upon success)
	 or various errors

Sets the password associated with a connection.  Used for later authentication
for commands that require it.

Other commands
==============

HELP - lists the commands supported by this server
VER  - shows the version of the server currently in use

These two are not intended to be used directly by programs.  Humans can
make use of this program by using telnet for TCP or netcat for UDP.  Try
either "telnet localhost 3305" for TCP or "nc -u localhost 3305" for UDP
and it should talk to you.

Error responses
===============

ERR <message>

There are a variety of errors that can be returned.  They are not all
documented at this time.
