Imported Upstream version 2.4.3
This commit is contained in:
arnaud.quette@free.fr
commit
26fb71b504
446 changed files with 148951 additions and 0 deletions
225
docs/sock-protocol.txt
Normal file
225
docs/sock-protocol.txt
Normal file
|
|
@ -0,0 +1,225 @@
|
|||
Desc: Driver/server socket protocol
|
||||
File: sock-protocol.txt
|
||||
Date: 1 May 2003
|
||||
Auth: Russell Kroll <rkroll@exploits.org>
|
||||
|
||||
Here's a brief explanation of the text-based protocol which is now used
|
||||
between the drivers and server.
|
||||
|
||||
The drivers may send things on the socket at any time. They will send
|
||||
out changes to their local storage immediately, without any sort of
|
||||
prompting from the server. As a result, the server must always check on
|
||||
any driver sockets for activity.
|
||||
|
||||
Formatting
|
||||
==========
|
||||
|
||||
All parsing on either side of the socket is done by parseconf, so the
|
||||
same rules about escaping characters and "quoting multi-word elements"
|
||||
apply here. Values which may contain odd characters are typically
|
||||
sent through pconf_encode to apply \ characters where necessary.
|
||||
|
||||
The "" construct is used throughout to force a multi-word value to stay
|
||||
together on its way to the other end.
|
||||
|
||||
Commands used by the drivers
|
||||
============================
|
||||
|
||||
SETINFO
|
||||
-------
|
||||
|
||||
SETINFO <varname> "<value>"
|
||||
|
||||
SETINFO ups.status "OB LB"
|
||||
|
||||
There is no "ADDINFO" - if a given variable does not exist, it is
|
||||
created upon receiving the first SETINFO command.
|
||||
|
||||
DELINFO
|
||||
-------
|
||||
|
||||
DELINFO <varname>
|
||||
|
||||
DELINFO ups.temperature
|
||||
|
||||
ADDENUM
|
||||
-------
|
||||
|
||||
ADDENUM <varname> "<value>"
|
||||
|
||||
ADDENUM input.transfer.low "95"
|
||||
|
||||
DELENUM
|
||||
-------
|
||||
|
||||
DELENUM <varname> "<value>"
|
||||
|
||||
DELENUM input.transfer.low "98"
|
||||
|
||||
SETAUX
|
||||
------
|
||||
|
||||
SETAUX <varname> <numeric value>
|
||||
|
||||
SETAUX ups.id 8
|
||||
|
||||
This overrides any previous value. The auxiliary value is presently
|
||||
used as a length byte for read-write variables that are strings.
|
||||
|
||||
SETFLAGS
|
||||
--------
|
||||
|
||||
SETFLAGS <varname> <flag>...
|
||||
|
||||
SETFLAGS ups.id RW STRING
|
||||
|
||||
Note that this command takes a variable number of arguments, as multiple
|
||||
flags are supported. Also note that they are not crammed together in
|
||||
"", since "RW STRING" would mean something completely different.
|
||||
|
||||
This also replaces any previous flags for a given variable.
|
||||
|
||||
ADDCMD
|
||||
------
|
||||
|
||||
ADDCMD <cmdname>
|
||||
|
||||
ADDCMD load.off
|
||||
|
||||
DELCMD
|
||||
------
|
||||
|
||||
DELCMD <cmdname>
|
||||
|
||||
DELCMD load.on
|
||||
|
||||
DUMPDONE
|
||||
--------
|
||||
|
||||
DUMPDONE
|
||||
|
||||
This is only used to tell the server that every possible item has been
|
||||
transmitted in response to its DUMPALL request. Once this has been
|
||||
received by the server, it can be sure that it knows everything that the
|
||||
driver does.
|
||||
|
||||
PONG
|
||||
----
|
||||
|
||||
PONG
|
||||
|
||||
This is sent in response to a PING from the server. It is only used as
|
||||
a sanity check to make sure that the driver has not gotten stuck
|
||||
somewhere.
|
||||
|
||||
DATAOK
|
||||
------
|
||||
|
||||
DATAOK
|
||||
|
||||
This means that the driver is able to communicate with the UPS, and the
|
||||
data should be treated as usable. It is always sent at the end of the
|
||||
dump if the data is not stale. It may also be sent at other times.
|
||||
|
||||
DATASTALE
|
||||
---------
|
||||
|
||||
DATASTALE
|
||||
|
||||
This is sent by the driver to inform any listeners that the data is no
|
||||
longer usable. This usually means that the driver is unable to get any
|
||||
sort of meaningful response from the UPS. You must not rely on any
|
||||
status information once this has been sent.
|
||||
|
||||
This will be sent in the beginning of a dump if the data is stale, and
|
||||
may be repeated. It is cleared by DATAOK.
|
||||
|
||||
Commands sent by the server
|
||||
===========================
|
||||
|
||||
PING
|
||||
----
|
||||
|
||||
PING
|
||||
|
||||
This is sent to check on the health of a driver. The server should only
|
||||
send this when it hasn't heard anything valid from a driver recently.
|
||||
Some drivers have very little to say in terms of updates, and this may
|
||||
be the only communications they have with the server on a normal basis.
|
||||
|
||||
If a driver does not respond with the PONG within a few seconds at the
|
||||
most, it should be treated as dead/unavailable. Data stored in the
|
||||
server must not be passed on to the clients when this happens.
|
||||
|
||||
INSTCMD
|
||||
-------
|
||||
|
||||
INSTCMD <cmdname>
|
||||
|
||||
INSTCMD panel.test.start
|
||||
|
||||
SET
|
||||
---
|
||||
|
||||
SET <varname> "<value>"
|
||||
|
||||
SET ups.id "Data room"
|
||||
|
||||
DUMPALL
|
||||
-------
|
||||
|
||||
DUMPALL
|
||||
|
||||
The server uses this to request a complete copy of everything the driver
|
||||
knows. This is returned in the form of the same commands (SETINFO,
|
||||
etc.) that would be used if they were being updated normally. As a
|
||||
result, the same parsing happens either way.
|
||||
|
||||
The server can tell when it has a full copy of the data by waiting for
|
||||
DUMPDONE. That special response from the driver is sent once the entire
|
||||
set has been transmitted.
|
||||
|
||||
Design notes
|
||||
============
|
||||
|
||||
Requests
|
||||
--------
|
||||
|
||||
There is no way to request just one variable. This was done on purpose
|
||||
to limit the complexity of the drivers. Their job is to send out
|
||||
updates and handle a few simple requests. DUMPALL is provided to give
|
||||
the server a known foundation.
|
||||
|
||||
To track a limited set of variables, a server just needs to do DUMPALL,
|
||||
then only have handlers that remember values for the variables that
|
||||
matter. Anything else should be ignored.
|
||||
|
||||
Access/Security
|
||||
---------------
|
||||
|
||||
There are no access controls in the drivers. Anything that can connect
|
||||
to their sockets can make requests, including SET and INSTCMD if
|
||||
supported by the driver and hardware. These sockets must be kept
|
||||
secure. If your operating system does not honor permissions or modes on
|
||||
sockets, then you must store them in a directory with suitable
|
||||
permissions to limit access.
|
||||
|
||||
Command limitations
|
||||
-------------------
|
||||
|
||||
As parseconf is used to handle decoding and chunking of the data, there
|
||||
are some limits on what may be used. These default to 32 arguments of
|
||||
512 characters each, which should be more than enough for everything
|
||||
which is currently needed by the software.
|
||||
|
||||
These limits are strictly for sanity purposes, and may be raised if
|
||||
necessary. parseconf itself can handle vast numbers of arguments and
|
||||
characters, with some speed penalty as things get really big.
|
||||
|
||||
Re-establishing communications
|
||||
------------------------------
|
||||
|
||||
If the server loses its connection to the driver and later reconnects,
|
||||
it must flush any local storage and start again with DUMPALL. The
|
||||
driver may have changed the internal state considerably during that
|
||||
time, and anything other approach could leave old elements behind.
|
||||
Loading…
Add table
Add a link
Reference in a new issue