Name: Network UPS Tools design document
File: design.txt
Date: 16 February 2001
Auth: Russell Kroll <rkroll@exploits.org>

Here is the general layout for the software.  It has a layered scheme,
in which clients, the server, and the drivers are separated.  Layers 
communicate with each other using an agreed-upon protocol.

The layering
============

  CLIENTS: upsmon, upsc, multimon, upsstats, upsset, etc.
  
           < network: TCP or UDP sockets, typically on port 3305 >

   SERVER: upsd

           < local communications: state files typically in /var/state/ups >
           < *or* SysV shared memory attached by both driver and server    >
           < either way, they use the "info array" to share data           >

           < also SysV message queues for instant commands                 >

  DRIVERS: apcsmart, bestups, fentonups, powercom, etc.

           < usually serial communications, but others are certainly possible >

EQUIPMENT: Smart-UPS 700, Fenton PowerPal 660, etc. (actual UPS hardware)

How information gets around
===========================

From the equipment
------------------

DRIVERS talk to the EQUIPMENT and receive updates.  For most hardware this
is polled (DRIVER asks EQUIPMENT about a variable), but forced updates are
also possible.  The exact method is not important, as it is abstracted
by the driver.

From the driver
---------------

DRIVERS publish the data they obtain from the EQUIPMENT in the
"info array" - a standard C array of struct info.  The finer points of
this structure are documented in the new-modules.txt document, and will
not be repeated here.

The actual array can exist in two forms.  The default form is to create
a file on the disk that simply contains the array.  This file is known as
a "state file" since it contains all the state information on the
EQUIPMENT.  In this mode, the DRIVER refreshes the data every few seconds
and the SERVER reads from it at similar intervals.  The server uses the
Unix ctime data to know when the file is "stale" - not being updated.
For this reason, the driver must keep this file fresh, even if nothing
changes.  This design introduces a slight lag in data propagation - the
time after the DRIVER writes out the array, but before the SERVER reads
it.

The other form uses shared memory.  This has a number of advantages, one
being that the data acquired from the EQUIPMENT becomes available
immediately in the SERVER.  The state file lag is thus eliminated.  There
is still the need for a "state file", but it is much smaller and only
written once.  This stub file only contains one entry, which serves to
direct the SERVER at the appropriate shared memory ID.  See the entry for
INFO_SHMID in the new-modules.txt for additional information on this.

From the server
---------------

Regardless of the storage method of the state file (actual file or shared
memory struct), the SERVER will have an info array available for every
DRIVER being monitored.  When a request for data arrives from a CLIENT,
the SERVER will look through the right info array and return that data
if it exists.  The format for these requests is the same whether it comes
from a UDP or TCP socket, although there are restrictions on what may
happen over a UDP socket.  This is documented in protocol.txt.

XXX: *** work in progress: this file is not yet complete. ***

remaining topics:

 - instant command implementation

