On Network design
  -RF

- DATA TRANSFER
First issue is which kind of data transfer use to solve
the endianess problems and size of basic data types.
Since the beginning I wanted to implement the
data transfer in ascii form that allow us to forget about
endianess and size of types. Transferring in ascii gives
us these benefits:

  . Endianess problems are not present.
  . Size of data types (e.g. sizeof(int)) are solved locally by sscanf.
  . The UPS status is human readable even on a 'telnet' connection.
  . Ascii transfers fits very well with all the other transfers (commands)
    and chatting between clients and server.

As discussed with Kern, ASCII data transfer does not alone solve every
problem. In 32/64 bits architectures the use of sscanf may force us to
pick correctly the format strings. I think we can deal with this on a
per-architecture basis as this is the only customization needed for the
data transfer to work correctly.

Another thing discussed with Kern is transmission format. The initial design
is totally ASCII for ease of debugging. In the future, if we will need,
we can switch to semi-binary interface where we announce the number of
transmitted lines before starting a transmission.

- CLIENT/SERVER COMMAND INTERFACE
As for data transfers, the client/server command interface is in ascii form.
This design allowed to reuse the same interface for commands, answers and
UPS
data transfers.
This command interface is a set of commands that the client can give to the
server
to ask for data. This command set is easily expandable and even if expanded,
will
mantain total backward compatibility with the initial implementation.
In the future we will add for example front panel led test command but this
will be
totally transparent and clients of previous 4.x versions will be always able
to
talk with the new daemon as the older commands will not be touched.
The command interface have commands for:

  . Authentication (clid, clpw, powerpw) for read (clpw) and write
(powerpw).
  . Selection of UPS (ulist, uselect) from the daemon's known UPSes:
multi-UPS.
  . gathering of UPS information (ustat).
  . Sending service messages from client to server (msg),
    for example to notify shutdown started.
  . Polling interval setup (poll) so that clients can notify server if they
use
    slow or fast polling. This is interesting for slow connections where the
    polling time may be long. Server will timeout on polling time and close
the
    connection. This is done for handling stuck clients.

The command set as defined is not definitive. Don't forget that we are still
in
alpha devel so I'm ready to change/add commands.

- SERVER
The server is an apcupsd child that will serve (based on config file
directives)
the UPSes info over the network.
The daemon do not fork but instead uses select() on multiple file
descriptors.
To handle slow clients it reads data in O_NDELAY so that a slow client will
not
block other, faster, clients. With this architecture I'm sure the apcupsd is
able
to handle thousand of clients regardless of the speed of their connection
with only
very limited delay (read the already available data and process them).
Security checks include:

  . Two levels password authentication.
  . Tcpwrappers verification.
  . Selection of listening interface.

The advantages of this design include:

  . Human understandable chatting.
  . Almost unlimited number of clients.
  . TCP connections always-on (this solves the high number of TIME_WAIT
connections).
  . Easy security implementation.
  . Network connections treated just like serial connections (transparent to
do_events()).
  . Cleaner command set implementation.

- CLIENTS

We can have different kinds of clients, but they will all share the same
communication
layer. The network layer of apcupsd is built to deliver all the information
known to the server
and not only a subset, like the current 3.x implementation.
The advantages of this are:

  . Single communication protocol shared by all the clients (no need anymore
for the two
    communication protocols present in 3.x)
  . Clients are all the same (no difference from the server view between
other apcupsd on
    network, cgi-bin clients, powerflute or other clients).
  . Common library functions for usual client tasks (login, ustat,
disconnection).

Of course this means that with time even cgi-bin  can be rewritten to make
use of the new
networking. At this time, cgi-bin still uses the NIS server and this will
remain the same
as long as cgi-bin will not be revamped.

I hope to have been clear enough with my description.
All of this is already implemented and tested but of course we need more
tests and
there is still work on many areas like win32, cgi-bin for multi-ups,
apccontrol and of
course we still need to define once and forever the config file format.