1
1
Desc: Network UPS Tools design document
4
4
Auth: Russell Kroll <rkroll@exploits.org>
6
Here is the general layout for the software. It has a layered scheme,
7
in which clients, the server, and the drivers are separated. Layers
8
communicate with each other using an agreed-upon protocol.
6
This software is designed around a layered scheme with drivers, a
7
server and clients. These layers communicate with text-based
8
protocols for easier maintenance and diagnostics.
41
41
The core of all DRIVERS maintains internal storage for every variable
42
that is known, and all of the auxiliary data for those variables. It
42
that is known along with the auxiliary data for those variables. It
43
43
sends updates to this data to any process which connects to the Unix
46
The DRIVERS will also provide a full copy of their internal knowledge
47
upon receiving the "DUMPALL" command on the socket. The dump is in the
48
same format as updates, and is followed by "DUMPDONE". When "DUMPDONE"
49
has been received, the view is complete.
46
The DRIVERS will also provide a full atomic copy of their internal
47
knowledge upon receiving the "DUMPALL" command on the socket. The dump
48
is in the same format as updates, and is followed by "DUMPDONE". When
49
"DUMPDONE" has been received, the view is complete.
51
51
The SERVER will connect to the socket of each DRIVER and will request a
52
52
dump at that time. It retains this data in local storage for later use.
53
It continues to listen on the socket for additional updates .
53
It continues to listen on the socket for additional updates.
55
55
This protocol is documented in sock-protocol.txt.
71
71
Instant commands is the term given to a set of actions that result in
72
something happening to the UPS. Some of the common ones are BTEST1 to
73
initiate a battery test and FPTEST to test the front panel of the UPS.
72
something happening to the UPS. Some of the common ones are
73
test.battery.start to initiate a battery test and test.panel.start to
74
test the front panel of the UPS.
75
76
They are passed to the SERVER from a CLIENT using an authenticated
76
77
network connection. The SERVER first checks to make sure that the instant
81
82
At this point, there is no confirmation to the SERVER of the command's
82
execution. This is planned for a future release. This has been delayed
83
since returning a response involves some potentially interesting timing
84
issues. Remember that upsd services clients in a round-robin fashion,
85
so all queries must be lightweight and speedy.
83
execution. This is (still) planned for a future release. This has been
84
delayed since returning a response involves some potentially interesting
85
timing issues. Remember that upsd services clients in a round-robin
86
fashion, so all queries must be lightweight and speedy.
90
Some variables in the DRIVER can be changed, and carry the FLAG_RW flag.
91
Upon receiving a SET command from the CLIENT, the SERVER first verifies
92
that it is valid for that DRIVER in terms of writability and data type.
93
If those checks pass, it then sends the SET command through the socket,
94
much like the instant command design.
91
Some variables in the DRIVER or EQUIPMENT can be changed, and carry the
92
FLAG_RW flag. Upon receiving a SET command from the CLIENT, the SERVER
93
first verifies that it is valid for that DRIVER in terms of writability
94
and data type. If those checks pass, it then sends the SET command
95
through the socket, much like the instant command design.
96
97
The DRIVER is expected to commit the value to the EQUIPMENT and update
97
98
its internal representation of that variable.
110
111
1. EQUIPMENT reports on battery by setting flag in status register
112
2. DRIVER notices this flag and stores it in the status variable as
113
2. DRIVER notices this flag and stores it in the ups.status variable as
113
114
OB. This update gets pushed out to any listeners via the sockets.
115
116
3. SERVER upsd sees activity on the socket, reads it, parses it, and
116
117
commits the new data to its local version of the status variable.
118
4. CLIENT upsmon does a routine poll of SERVER for "STATUS" and gets "OB".
119
4. CLIENT upsmon does a routine poll of SERVER for "ups.status" and
120
122
5. CLIENT upsmon then invokes its NOTIFYCMD which is upssched.
181
Very old versions of this software only supported the notion of state
182
files. Status was written into a static array ("the info array") by
183
drivers, and that array was stored on disk. upsd would periodically
184
read that file into a local copy of that array.
183
The oldest versions of this software (1998) had no separation between
184
the driver and the network server and only supported the latest APC
185
Smart-UPS hardware as a result. The network protocol used brittle
186
binary structs. This had numerous bad implications for compatibility
189
After the driver and server were separated, data was shared through the
190
state file concept. Status was written into a static array (the "info
191
array") by drivers, and that array was stored on disk. upsd would
192
periodically read that file into a local copy of that array.
186
194
Shared memory mode was added a bit later, and that removed some of the
187
195
lag from the status updates. Unfortunately, it didn't have any locking
added
removed
docs/design.txt
