This specification includes only the commands and their responses.
An implementation of the Attachment Daemon (2.1) has an internal state machine, and some
complex implementations of the Management Daemon (2.6) include an internal state
machine; for example to assist the system shutdown of a complex
installation. The Management Daemon (2.6) is required to remember the
previous ups.status value it received from the Attachment Daemon (2.1) and compare
it with the next. Other than that the management protocol used
between them is effectively stateless.¶
The commands address the UPS to which they apply
by <upsname> where¶
Examples: myups, UPS-97B@bigserver.example.com¶
Note: Experimental Management Daemons (2.6) use an extended form
of <upsname> in configuration files and in program
parameters, where¶
-
<upsname> ::= [<group>:]<ups>[@<hostname>[:<port>]]¶
-
<group> is an experimental extension to provide for groups of UPSs. It is not in common current practice.¶
-
<ups> is defined by the Attachment Daemon (2.1) configuration files.¶
- The default
<hostname> is localhost¶
Examples: ups-1@example.com:3493, HB:heartbeat1@example.com:3493¶
In a configuration such
as Figure 4 in which a UPS protects more than
one system, the Primary (2.8) Management Daemon (2.6) needs to know how many Secondaries (2.9) are
currently "active", i.e., powered by the UPS, either on wall
or battery power. The Attachment Daemon (2.1) supports this by keeping a count of all
the "active" systems powered by a UPS. The count is
initialised, one secondary at a time by the ATTACH command,
which should be understood as "count this secondary as
active". ATTACH is one of a trio of commands for Secondary (2.9)
counting: command DETACH (4.2.2) decrements the count and a Management Daemon (2.6) may read
the count at any time using command NUMATTACH (4.2.4.3).¶
The ATTACH command is also sent to the Attachment Daemon (2.1) for the
Primary (2.8) so during normal, fully protected operation, the count is 1
(the Primary (2.8)) + the number of Secondaries (2.9). During a full system shutdown,
the count drops as each Secondary (2.9) Management Daemon (2.6) executes command DETACH (4.2.2) during
its own shutdown. When the count drops to 1, only the Primary (2.8) is
"active" and it knows that all the Secondaries (2.9) have shut down.¶
Command: ATTACH <upsname>¶
If the command succeeds, the response is OK, otherwise
see the error responses (4.3.2).¶
Note: Historically, this command was known as LOGIN.
Since that LOGIN was not the conventional user access to a
shell or program the name was changed to avoid confusion.¶
This companion command to ATTACH (4.2.1) reduces the
count of "active" Secondaries (2.9). It should be understood as "this
secondary is no longer active", and is usually used during system
shutdown to decrement a count of how many Secondaries (2.9) are still "active".¶
Command: DETACH¶
If the command succeeds, the response is OK Goodbye,
otherwise see the error
responses (4.3.2).¶
Note: Historically, this command was known as LOGOUT.¶
Command: FSD <upsname>¶
If the command succeeds, the response is OK FSD-SET,
otherwise see the error
responses (4.3.2).¶
In current practice, commands such as FSD are made
available only to a high-level administrative user (2.2) authorized to send such a mission
critical command. The security provisions for administrative users
are discussed in section 6.5.¶
Retrieve a text description of a command.¶
Command: GET CMDDESC <upsname> <cmdname>¶
Response:
CMDDESC <upsname> <cmdname> "<description>"¶
For example: GET CMDDESC su700 load.on and
response CMDDESC su700 load.on "Turn on the load immediately"¶
This is like DESC (4.2.4.2), but it applies to an instant command (2.5).¶
Retrieve a text description of a variable.¶
Command: GET DESC <upsname> <varname>¶
Response: DESC <upsname> <varname> "<description>"¶
where <description> is a string that gives a brief
explanation of the named variable. The Attachment Daemon (2.1) may return "Unavailable"
if the file which provides this description is not installed.¶
For example command GET DESC su700 ups.status and
response DESC su700 ups.status "UPS status"¶
Retrieve the count kept by the Attachment Daemon (2.1) of all the
"active" systems protected by this UPS.¶
Command: GET NUMATTACH <upsname>¶
Response: NUMATTACH <upsname> <value>¶
where <value> is a count of the Primary (2.8) and the number of
Secondaries (2.9) currently powered by this UPS.¶
For example command GET ATTACH su700 and
response NUMATTACH su700 1¶
This information is needed by the Management Daemon (2.6) to determine how many
Secondaries (2.9) are still connected during the system shutdown process.¶
Note: Historically, this sub-command was known
as NUMLOGINS. Since LOGIN was not the conventional
user access to a shell or program the name was changed to avoid
confusion.¶
Command: GET TYPE <upsname> <varname>¶
Response: TYPE <upsname> <varname> <type>...¶
where <type> can be one or more of the following tokens.
Multiple types may be returned.¶
For example command GET TYPE su700 input.transfer.low and
response TYPE su700 input.transfer.low ENUM¶
Table 1:
Variable Types
| Type
|
Meaning
|
RW |
This is a read/write variable. It may be read with
command GET VAR (4.2.4.6) and set to a different value with command
SET (4.2.11)
|
ENUM |
An enumerated type, which supports specific
predetermined values
|
STRING:n |
This is a string of maximum
length n
|
RANGE |
This is a number, either integer or
float, comprised in the range which may be seen with the
command LIST RANGE (4.2.7.4)¶
|
NUMBER |
This is a single numeric value, either
integer or float
|
Notes:¶
-
ENUM, STRING:n and RANGE are usually associated with
RW, but not always. The default <type>, when omitted, is
numeric, so either integer or float. Each Driver (2.3) is then responsible
for handling values as either integer or float.¶
- Current practice is to represent floating point values using
locale
C.utf8 which is a decimal (base 10) US English-based
representation. Hexadecimal, exponents, and comma for thousands
separator are not allowed. For example: "1200.20" is valid, while
"1,200.20" and "1200,20" are not valid.¶
Retrieve a text description of a UPS.¶
Command: GET UPSDESC <upsname>¶
Response: UPSDESC <upsname> "<description>"¶
where <description> is defined by the Attachment Daemon (2.1) configuration. If
it is not set, current practice is for the Attachment Daemon (2.1) to return
"Unavailable".¶
For example command GET UPSDESC su700 and response
UPSDESC su700 "Development box"¶
This can be used to provide human-readable descriptions instead of
a cryptic ups@hostname string.¶
Command: GET VAR <upsname>
<varname>¶
Response: VAR <upsname> <varname> "<value>"¶
For example command GET VAR su700 ups.status and response
VAR su700 ups.status "OB LB"¶
Return a list of the commands supported by the Attachment Daemon (2.1).
This command is intended for human as well as program use.¶
Command HELP¶
For example, the following command line sequence executed on an
Attachment Daemon (2.1):¶
netcat localhost 3493
HELP
Commands: HELP VER GET LIST SET INSTCMD ATTACH DETACH
USERNAME PASSWORD STARTTLS¶
Note:
Historically, this command also
returned LOGIN and LOGOUT. Since LOGIN was
not the conventional user access to a shell or program, the command
names were changed to ATTACH and DETACH avoid confusion.¶
Command: INSTCMD <upsname> <cmdname>¶
where <upsname> is the name of the UPS
and <cmdname> is the instant command (2.5) to be issued to that UPS.¶
If the command succeeds, the response is OK, otherwise
see the error responses (4.3.2).¶
For example the command: INSTCMD su700 test.panel.start
and the response OK¶
The LIST commands all produce a response
with a common container format. The response will begin with BEGIN
LIST and then repeat the initial query. A list then follows,
with as many lines as are necessary. The response ends with END
LIST followed by the initial query.¶
The formatting may seem a bit redundant, but it makes a different
form of client possible. A client can send a LIST (4.2.7) query and then
go off and wait for the response. When it arrives, the Management Daemon (2.6) doesn't
need a complicated state machine to remember which list is which.¶
Note: The current NUT Project (2.7) implementation of the
Attachment Daemon (2.1), upsd, sends back the response to a LIST (4.2.7) command as
a sequence of messages. The Management Daemon (2.6) should continue reading these
messages until it receives the line beginning END
LIST.¶
The possible subcommands are:¶
Command: LIST CLIENT <upsname>¶
The response
is¶
BEGIN LIST CLIENT <upsname>
CLIENT <upsname> <client_IP_address>
...
END LIST CLIENT <upsname>
¶
For example, the command LIST CLIENT ups1 and the response:¶
BEGIN LIST CLIENT ups1
CLIENT ups1 ::1
CLIENT ups1 198.51.100.2
END LIST CLIENT ups1
¶
Command: LIST CMD <upsname>¶
The response is:¶
BEGIN LIST CMD <upsname>
CMD <upsname> <cmdname>
...
END LIST CMD <cmdname>
¶
where <upsname> is the name of the UPS,
and <cmdname> is the name of the command which may be
issued to the UPS.¶
For example the command: LIST CMD su700 and the response:¶
BEGIN LIST CMD su700
CMD su700 load.on
CMD su700 test.panel.start
...
END LIST CMD su700
¶
Command: LIST ENUM <upsname> <varname>¶
The response
is:¶
BEGIN LIST ENUM <upsname> <varname>
ENUM <upsname> <varname> "<value>"
...
END LIST ENUM <upsname> <varname>
¶
where <upsname> is the name of the UPS,
<varname> is the UPS variable (2.12) and <value> is
one of the possible values of that UPS variable (2.12). Note that in current
practice the output is an unordered list. Note also that the U+0022
QUOTATION MARK characters are part of the response.¶
For example the command: LIST ENUM su700 input.transfer.low
and the
response:¶
BEGIN LIST ENUM su700 input.transfer.low
ENUM su700 input.transfer.low "103"
ENUM su700 input.transfer.low "100"
...
END LIST ENUM su700 input.transfer.low
¶
Command: LIST RANGE <upsname> <varname>¶
The response
is:¶
BEGIN LIST RANGE <upsname> <varname>
RANGE <upsname> <varname> "<min>" "<max>"
...
END LIST RANGE <upsname> <varname>
¶
where <upsname> is the name of the UPS,
<varname> is the UPS variable (2.12) and
{<min>,<max>} is the interval of valid
values of that UPS variable (2.12). Note that the U+0022 QUOTATION MARK characters
are part of the response.¶
For example, the command LIST RANGE su700
input.transfer.low and the response:¶
BEGIN LIST RANGE su700 input.transfer.low
RANGE su700 input.transfer.low "90" "105"
END LIST RANGE su700 input.transfer.low
¶
Command: LIST RW <upsname>¶
The response is:¶
BEGIN LIST RW <upsname>
RW <upsname> <varname> "<value>"
...
END LIST RW <upsname>
¶
where <upsname> is the name of the UPS,
<varname> is the UPS variable (2.12) and
<value> is the value of that UPS variable (2.12). Note that
the U+0022 QUOTATION MARK characters are part of the response.¶
For example the command: LIST RW su700 and the response:¶
BEGIN LIST RW su700
RW su700 output.voltage.nominal "115"
RW su700 ups.delay.shutdown "020"
...
END LIST RW su700
¶
The command calls for the Attachment Daemon (2.1) to report a list of
the UPS units to which it is attached.¶
Command: LIST UPS¶
The response is:¶
BEGIN LIST UPS
UPS <upsname> "<description>"
...
END LIST UPS
¶
where <upsname> is the name of a UPS, and <description>
is the description maintained by the Attachment Daemon (2.1) if available. It is set to
"Unavailable" otherwise. Note that the U+0022 QUOTATION MARK
characters are part of the response.¶
This command can also be used to determine what values of
<upsname> are valid before calling other functions on the
server. This is also a good way to handle situations where a single
Attachment Daemon (2.1) supports multiple UPS's. It is also useful for clients which
perform a UPS discovery process.¶
For example, the response:¶
BEGIN LIST UPS
UPS su700 "Development box"
END LIST UPS
¶
Command: LIST VAR <upsname>¶
The response is:¶
BEGIN LIST VAR <upsname>
VAR <upsname> <varname> "<value>"
...
END LIST VAR <upsname>
¶
where <upsname> is the name of the UPS,
<varname> is the UPS variable (2.12) and
<value> is the value of that variable. Note that
the U+0022 QUOTATION MARK characters are part of the response.¶
The response to this command lists the UPS variables (2.12) available for this
UPS and their current values. For example the command LIST VAR
su700 and the response:¶
BEGIN LIST VAR su700
VAR su700 ups.mfr "Example Mfg"
VAR su700 ups.mfr.date "10/17/96"
...
END LIST VAR su700
¶
Command: PRIMARY <upsname>¶
where <upsname> is the name of the UPS.¶
If the Attachment Daemon (2.1) has the authority, the response is OK, otherwise
see the error responses (4.3.2).¶
Note: Historically, this command was known as MASTER.¶
Return the implementation version of the
command/response protocol used by the Attachment Daemon (2.1). This command is intended
for human as well as program use.¶
Command PROTVER¶
For example, the following command line sequence in the Attachment Daemon (2.1):¶
netcat localhost 3493
PROTVER
1.2
¶
Note: There are no U+0022 QUOTATION MARK characters in the response.¶
Note: Historically, this command was known as NETVER and
current practice is to use NETVER instead of PROTVER (4.2.10)¶
Command: SET VAR <upsname> <varname>
"<value>"¶
where <upsname> is the name of the UPS,
<varname> is the UPS variable (2.12) and
<value> is the value to be assigned to that variable.
Note that the U+0022 QUOTATION MARK characters are part of the
command.¶
If the command succeeds, the response is OK, otherwise
see the error responses (4.3.2).¶
For example the command: SET VAR su700 ups.id "My UPS" and
the response OK¶
The client tells the Attachment Daemon (2.1) to switch to TLS
encrypted communication. When the client receives OK it also
switches to TLS encryption. The choice of TLS version is a matter for
site security policy and is not specified in this document.¶
Command: STARTTLS¶
If the command succeeds, the response is OK STARTTLS, otherwise
see the error responses (4.3.2).¶
Return the implementation version of the Attachment Daemon (2.1). This
command is intended for human as well as program use.¶
Command VER¶
For example, the following command line sequence:¶
netcat localhost 3493
VER
Network UPS Tools upsd 2.7.4 - http://www.networkupstools.org/
¶
Note: There are no U+0022 QUOTATION MARK characters in the response.¶