This document describes the command/response protocol currently
used in the management of Uninterruptible Power Supply (UPS) units and
other power devices often deployed in small offices, and in IT
installations subject to an erratic public power supply. The UPS
units typically interface to an Attachment Daemon in the system they
protect. This daemon is in turn polled by a Management Daemon which
notifies users and system administrators of power supply incidents,
and automates system shutdown decisions. The commands and responses
described by this document are exchanged between the UPS Attachment
Daemon and the Management Daemon. Current practice when this text was
written risks weak security and this is addressed in the Security
Considerations sections of this document.¶
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task
Force (IETF). Note that other groups may also distribute working
documents as Internet-Drafts. The list of current Internet-Drafts is
at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."¶
Copyright (c) 2021 IETF Trust and the persons identified as the
document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with
respect to this document. Code Components extracted from this
document must include Revised BSD License text as described in
Section 4.e of the Trust Legal Provisions and are provided without
warranty as described in the Revised BSD License.¶
The editor recommends that you read the HTML
version of this document. It renders the protocol symbols such as
OL correctly without quotation marks.¶
To lighten the text, the term "UPS" is used when "Managed Power
Device" would be more complete. The reader should understand the
simple "UPS" to include other managed power devices.¶
The statuses and events appearing in this document are named with
short text-form names, some of which are abbreviations. A full list
of the statuses can be found in section Status Symbols (5.1) while the events are listed in
section Events (5.2).¶
This document refers to the "public power supply". Other texts
frequently refer to "utility power", "input source power" or even
"wall power".¶
This document describes UPS management techniques
and current UPS management practice published by the NUT Project (2.7) which has
been operational since 1998. Appendix The Shutdown Story (B) describes the current UPS management
practice for performing a managed shutdown of unattended
infrastructure after an unscheduled failure of the public power supply
to minimise the risk of corruption to data processed by this
infrastructure.¶
Since May 2002, the protocol described by this document has been
operating on IANA port nut/3493 running over TCP.¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described
in RFC 2119 [RFC2119].¶
The Attachment Daemon retrieves status from the UPS and
sends commands to it often through a Driver (2.3) specific to the
hardware model and the connection medium, e.g., USB, serial. It
maintains an abstracted view of the hardware through the use
of hardware statuses (2.11). A Management Daemon (2.6) may
consult the abstracted view using the commands described in this
document. An Attachment Daemon is launched as system user "root" to
allow direct access to the hardware
(e.g. /proc, /dev). For better security, the daemon
then drops privilege to run as a detached software service for a
dedicated system user. It must support statuses (2.11) OB and OL. It must also support status LB if
the UPS provides such information.¶
In current practice, the commands and other functions
offered by the Attachment Daemon (2.1) to each Management Daemon (2.6) are made available to a set of
Management Daemon (2.6) users which authenticate to the Attachment Daemon (2.1) with basic credentials
(username and password). These users are not system users, they are
specific to an Attachment Daemon (2.1) and are listed in a text file which is read by
the Attachment Daemon (2.1) (currently upsd.users) and which assigns to each of
them the password, instant commands (2.5) and actions which are allowed, together with
the Primary (2.8) or Secondary (2.9) status of the Management Daemon (2.6). For details,
see section (6.5.1). Typically a
high-level user will be able to send command FSD (4.2.3) but a low-level
user might only be allowed to access the test panel. The security
provisions for administrative users are discussed in
section 6.5.¶
A Driver is that part of an Attachment Daemon which
is specific to the UPS hardware, the connection medium and the
connection protocol, e.g., USB, serial. In current practice the
Attachment Daemon has a driver for each hardware interface type it
supports. Although this document considers the driver to be part of
the Attachment Daemon, current practice is to see it as a separate
software unit running as a daemon "in front of" the Attachment Daemon.
The protocol for data exchange between the Driver and the Attachment
Daemon is outside the scope of this document.¶
A command which when sent to the Attachment Daemon (2.1) is passed to the
driver and sent to the hardware without any configured delay to
perform a function. For example INSTCMD su700
test.panel.start . See INSTCMD (4.2.6).¶
The Management Daemon is primarily responsible for
managing the hardware and orchestrating system-wide actions after a
power event. Using commands sent to the Attachment Daemon (2.1) it follows the status
of the UPS and determines when UPS events occur. It takes decisions
based on the events, such as calling for
a system
shutdown (B). Although the term includes the word "daemon" nothing
requires that it be implemented as a detached software service. The
Management Daemon may also provide administrative functions such as a
graphic interface to view the hardware activity.¶
When a power device such as a UPS unit supplies power
to more than one system, the computer running the driver is known as
the primary. The others are secondaries. See
figure 4. Common current
practice for system administrators is to consider the Management Daemon (2.6) in the
primary to be the Primary Management Daemon which is in charge of the
shutdown of all the systems powered by the UPS. The Primary
Management Daemon sets status symbol FSD to order the
secondaries to shut down.¶
Note: Historically, the primary was known as the "Master".¶
When a hardware device such as a UPS unit supplies
power to more than one system, the system which communicates directly
with the UPS unit e.g. using a USB, RS232, or network connection, is
known as the Primary (2.8). The other are secondaries. There is no Attachment Daemon (2.1)
in a secondary. See figure 4.
Common current practice for system administrators is to consider the
Management Daemon (2.6) in a secondary to be a Secondary Management Daemon which
understands status symbol FSD as an order to shut down.¶
Note: Historically, the secondary was known as the "Slave".¶
The Management Daemon (2.6) may initiate a TCP session with a specified
device such as a UPS known to the Attachment Daemon (2.1). The session structure
provides for audit and security as well as access to mission critical
UPS functions. For example good practice requires a password
protection for an instant command (2.5) which turns off a UPS outlet. Other than the
commands and responses used, the details of session management are
outside the scope of this document.¶
The status of a hardware device such as a UPS unit is a
symbolic description of the state of the unit. It consists of a space
separated list of symbols from the set {ALARMBOOSTBYPASSCALCHRGCOMMDISCHRGFSDLBNOCOMMOBOFFOLOVERRBTESTTRIM}. The symbols TICK and
TOCK are experimental additions to the statuses and are not in
common current practice. See section Status Symbols (5.1) which specifies each of these symbols.
The statuses LB, OB and OL MUST be supported for all units.
The other statuses are OPTIONAL and depend on the feature set of the
hardware.¶
The metrics and identifiers provided by each UPS are
represented by variables giving the value representing that metric or
identifier, The UPS variable is an abstraction of the UPS hardware
configuration and activity maintained by the Attachment Daemon (2.1).
See the appendix (Appendix A, Paragraph 1) which provides examples
of variables. For example the variable battery.charge
contains the current charge of the UPS battery as a percentage value.
A full list is available in source code file
docs/nut-names.txt [gitvars] which serves as the Recording Document.¶
Note: Some variables are constants, e.g. battery type,
manufacturer.¶
The reference configuration in figure 1 shows a single UPS unit which has a power supply link
(===) and a data link (---) attached to a system
running an Attachment Daemon (2.1). The UPS provides power supply protection to the
system running the Attachment Daemon.¶
In practice there may be more than one UPS unit, and a unit may
provide power protection to more than one system. The figure also
shows a single Management Daemon (2.6). In practice there may be more than one
Management Daemon, and any one Management Daemon may manage more than
one UPS Attachment Daemon.¶
The protocol applies to connections between the Attachment Daemon
and the Management daemon which act as server
and client respectively. The Management daemon sends
commands over TCP to the Attachment Daemon and receives responses over
TCP from that daemon.¶
The two daemons may run in the same system, or may be connected
through a local or wide area network. In simple cases, as shown in
figure 2, the Attachment Daemon (2.1)
and the Management Daemon (2.6) are in the same system, the one protected by the UPS.
The commands and responses are exchanged through an internal loopback
interface.¶
The reference configuration does not require any specific
design. For example figure 3
shows an arrangement in which the Attachment Daemon (2.1) is closely associated with, or
even included in the UPS system setup. This is becoming more
prevalent with the availability of low cost processors able to run the
Attachment Daemon (2.1) thereby effectively creating a network attached UPS running a
standard protocol.¶
As the power requirements for processors decrease, it is becoming
increasingly common to use a single UPS to protect multiple systems as
shown in figure 4. However
there is only one data line (---) from the UPS to the Primary (2.8)
system. The others have only power connections (===) to the
UPS, and are known as Secondaries (2.9). A Secondary (2.9) does not run an Attachment Daemon (2.1),
it connects over a network to the Attachment Daemon (2.1) in the
primary. Figure 4 shows the
Attachment Daemon (2.1) and the primary Management Daemon (2.6) in the same system. This is common
practice but it is not a technical requirement.¶
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.¶
See for example table (5.2) which
maps the new ups.status response and the
previous ups.status response to an Event (5.2) which is taken as
the basis for Management Daemon (2.6) action.¶
The character set used for commands and responses
is UTF-8 but current practice is to limit the character set used to
the single byte UTF-8 characters 0-127.¶
Multi-word elements are contained within U+0022 QUOTATION MARK
characters for easier parsing. E.g., "UPS on fire". Embedded quotation
marks are escaped with U+005C REVERSE SOLIDUS \ often known as
backslashes. Embedded backslashes are also escaped by representing
them as \\.¶
Commands and responses have no leading or
trailing whitespace, and are terminated with a single new
line character U+000A LINE FEED (LF).¶
White space within commands and responses is reduced to one U+0020
SPACE (SP).¶
The <port> is the number of the TCP port on which
the Attachment Daemon (2.1) is listening. The default is 3493. This is supported by
all current Management Daemons (2.6).¶
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 from the
public power supply or from 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 three
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 so during normal, fully protected operation, the count is 1
for the primary + the number of secondaries. During a full system
shutdown, the count drops as each secondary Management Daemon (2.6) executes command
DETACH (4.2.2) during its own shutdown. When the count drops to 1, only
the primary is "active" and it knows that all the secondaries
have shut down.¶
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".¶
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 privileged administrative user (2.2) authorized to send such a mission
critical command. The security provisions for administrative users
are discussed in section 6.5.¶
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"¶
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.¶
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.¶
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.¶
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.¶
The LIST commands all produce a response
with a common 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
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.¶
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
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
The command calls for the Attachment Daemon (2.1) to report a list of the
UPS variables (2.12) associated with a given UPS which may be read and written by
the Management Daemon (2.6). These variables are the abstracted view of the UPS
hardware capabilities. An economical UPS may support few variables
but a professional model should support at least the variables which
are needed for an automatic
shutdown and restart (B).¶
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
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.¶
The command calls for the Attachment Daemon (2.1) to report a list
of all the UPS variables (2.12) which it maintains for a given UPS, and the values
of those variables.¶
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
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.¶
There are no U+0022 QUOTATION MARK characters in the response.¶
Historically, this command was known as NETVER and
current practice is to use NETVER instead of PROTVER.¶
The implementation version of the protocol returned by PROTVER is
different to the implementation version of the Attachment Daemon (2.1) returned by
VER (4.2.14).¶
The command calls for the Attachment Daemon (2.1) to set a UPS variable (2.12) to a
given value. Whether this has an effect on the UPS hardware is
specific to the Driver (2.3) and the UPS model. Some variables are
read-only due to the design of the UPS or its driver.¶
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 parameters and versions of
cryptographic libraries are those of the Attachment Daemon's
underlying OS and are outside the scope of this document.¶
The Attachment Daemon (2.1) limits access to clients whose
credentials match those in the file upsd.users. There is no
anonymous access. A Management Daemon (2.6) program or script uses
command USERNAME and its companion command PASSWORD (4.2.8) to
open a Session (2.10) for an administrative user (2.2) with the Attachment Daemon (2.1), Note that this command is
for program or script use and is not the familiar login command typed
on a command line to gain access to a shell.¶
where <error-name> is a single word token taken from
the 27 characters A-Z and U+002D HYPHEN-MINUS. Implementations may if
needed add an additional optional <extra>. Current
practice does not make use of this possibility.¶
The <error-name> may have one of the following
values:¶
The Attachment Daemon (2.1) is connected to the
Driver (2.3) for the UPS, but that driver isn't providing regular updates
or has specifically marked the data as stale. Current practice is for
the Attachment Daemon (2.1) to refuse to provide the Management Daemon (2.6) with variables on stale units
to avoid false readings.¶
This generally means that the Driver (2.3) is running, but it has lost
communication with the hardware. Check the physical connection to the
equipment.¶
DRIVER-NOT-CONNECTED
The Attachment Daemon (2.1) can't perform the
requested command, since the Driver (2.3) for that UPS is not
connected. This usually means that the driver is not running, or if it
is, is misconfigured.
FEATURE-NOT-CONFIGURED
This instance of the Attachment Daemon (2.1)
hasn't been configured properly to allow the requested feature to
operate. In current practice this error response is possible only for
command STARTTLS (4.2.12).
FEATURE-NOT-SUPPORTED
This instance of Attachment Daemon (2.1) does
not support the requested feature. In current practice this error
response is possible only for command STARTTLS (4.2.12).
INSTCMD-FAILED
The Attachment Daemon (2.1) failed to deliver the
instant command (2.5) request to the Driver (2.3). No further information is available to
the client. This typically indicates a dead or broken driver.
INVALID-ARGUMENT
The client sent an argument to a
command which is not recognized or is otherwise not valid in this
context. This is typically caused by sending a valid command such as
GET (4.2.4) with a subcommand which is not valid.
INVALID-PASSWORD
The client sent a non valid
password.
INVALID-USERNAME
The client sent an non valid
username.
INVALID-VALUE
The value specified in the request
is not valid. This usually applies to a SET (4.2.11) of an ENUM (4.2.7.3) type
which is using a value not in the list of allowed values.
PASSWORD-REQUIRED
The command requires a password
for authentication, but the client hasn't provided one.
READONLY
The requested variable in a SET (4.2.11)
command is not writable.
SET-FAILED
The Attachment Daemon (2.1) failed to deliver the set
request to the Driver (2.3). This is similar to INSTCMD-FAILED.
TLS-ALREADY-ENABLED
TLS mode is already enabled
on this connection, so the Attachment Daemon (2.1) can't start it again.¶
Note: Historically, this message was ALREADY-SSL-MODE.¶
TLS-NOT-ENABLED
TLS mode has not yet been
enabled on this connection, so the Attachment Daemon (2.1) can't send commands.¶
Note: This message is experimental and not in current common
use.¶
TOO-LONG
The requested value in a SET (4.2.11) command
is too long.
The UPS specified in the request is
not known to the Attachment Daemon (2.1). This usually means that it didn't match
anything in the Attachment Daemon (2.1) configuration.
USERNAME-REQUIRED
The command requires a username
for authentication, but the client hasn't provided one.
VAR-NOT-SUPPORTED
The specified UPS doesn't
support the UPS variable (2.12) in the command.
These symbols resume the abstracted view of the
UPS hardware maintained by the Attachment Daemon (2.1). The
variable ups.status contains one or more space-separated
status symbols which together describe the UPS state at that instant.
In current practice the Management Daemon (2.6) will poll variable ups.status
every 5 seconds with a command such as GET VAR su700
ups.status and response VAR su700 ups.status "OB LB" to
discover changes in the UPS status. These changes will indicate UPS
events.¶
The UPS has determined that the voltage level of the input power
supply is too low, and is boosting it to the required level. The UPS
continues to supply the protected system from the input power supply.
BYPASS
The UPS is feeding current directly from the input power supply to
the protected system. The backup facilities are disconnected. This
state allows maintenance personnel to change the batteries without
interrupting the protected system.
CAL
The UPS is calibrating itself, for example to determine at what
charge the LB status is raised or lowered.
CHRG
The UPS battery is charging. This usually implies that the UPS
also has status OL, but may not be the case if the UPS also has
status OFF.¶
On Battery. The UPS is taking energy from it's battery.
The battery is discharging. A UPS must have status OB or OL,
otherwise it is deemed dead.
OFF
The UPS is in state "Off". It does not react to failure in the
input power supply. The exact meaning depends on the model.
OL
Online. The UPS is online, receiving energy from the input power
supply. The battery is charging. A UPS must have status OB or
OL, otherwise it is deemed dead.
OVER
Overloaded. The UPS reports that the load on it is beyond it's
normal operating maximum.
RB
Replace battery. The UPS reports that it's battery/batteries should
be replaced.
TEST
Under test. The UPS is currently undergoing a test, which may have
been called for manually or internally.
TICK
Heartbeat. A software UPS in the Attachment Daemon (2.1) provides a regular signal
monitored by the Management Daemon (2.6) as a way of verifying effective end-to-end
management. TICK and TOCK are companions, they are considered
experimental.
TOCK
Heartbeat. See TICK
TRIM
The UPS has determined that the voltage level of the input power
supply is too high, and is reducing it to the required level. The UPS
continues to supply the protected system from the input power supply.
A Management Daemon (2.6) detexts the occurrence of a UPS Event from a
change in the UPS status (2.11) received from the Attachment Daemon (2.1). The following table
summarizes the process. A status of "none" means that the status
symbol is not present in the variable ups.status.¶
The Management Daemon (2.6) should retrieve the variable ups.status from the
Attachment Daemon (2.1) at regular intervals. If the interval is too short, compute and
network resources will be wasted, but if the interval is too large,
the Management Daemon (2.6) risks missing short-lived changes in the UPS status.¶
A default value of 5 seconds is recommended, but an implementation
may make this value configurable. By default the "old" status is
therefore the previous value retrieved 5 seconds ago.¶
Current practice is for the Management Daemon (2.6) to assign names to certain
events. These is shown in the table in parentheses.¶
If the status OB is present, current practice
takes Management Daemon (2.6) reception of LB as an order to perform an emergency
system shutdown.¶
The use of a software defined UPS to provide a
heartbeat is experimental and is not part of common current practice.¶
Current practice is: if the UPS has not responded for 15 seconds,
the Management Daemon (2.6) assumes that the UPS is "dead" (NOCOMM), and if
the last known OL/OB status was OB a system shutdown
(FSD) is called for.¶
The security issues raised by UPS management are those
of the power industry in general: they are addressed in detail in
Technical Specification IEC 62351-1 [IEC62351-1].
In addition to equipment security, cyber security is now an essential
consideration.¶
With the computer systems for power operations presumably
kept isolated from the Internet, many utility personnel do not see any
reason for adding security measures to these systems. However, as
clearly seen from these Subclauses, this may not be true anymore as
networking becomes more prevalent and additional information access
requirements grow.¶
Additionally the UPS management protocol provides means for a Management Daemon (2.6)
to shut down a working system and it's power supply as described
in The Shutdown Story (B). A
malicious client acting as a Management Daemon (2.6) could turn off the UPS power
outlets causing the system to fail.¶
Most of these issues are well known IT issues concerning system
protection and disaster recovery, and are beyond the scope of this
document, however the protocol itself has security considerations:¶
It should not be possible for non-authorized agents to open
sessions and send mission-critical commands such as
FSD (4.2.3) to the Attachment Daemon (2.1).¶
In current NUT Project (2.7) practice, the use of TLS is optional and to
enforce it the system administator must set
declarations FORCESSL to 1 and CERTVERIFY to 1 in
the Management Daemon (2.6) configuration file.¶
At present the command STARTTLS (4.2.12) is too frequently refused, and
traffic proceeds unencrypted, with plain text transmission of
passwords and status values.¶
Some system administrators currently use techniques such
as stunnel [stunnel] to encrypt the commands and
responses, but the NUT Project (2.7) has no procedure to enforce this on sites.¶
Experience over the last 20 years shows that new UPS
management software releases are not frequent, and when installed,
stay unmodified for some years. This is probably because UPS
management is a mature hardware dependent activity. A limited number
of system administrators have access to the UPS hardware and software
and tend to assume a certain "security by obscurity" since many
installations have a configuration as shown in
figure 5 which uses port
nut/3493 between the two daemons running in the same system. The
traffic is often not encrypted, and when encrypted uses deprecated
early versions of SSL/TLS.¶
,-----, ,--------------------,---------------------,
| UPS |---| Attachment <-Commands Management |
| |===| Daemon Responses-> Daemon |
/-----\ '--------------------'---------------------'
Listens on
port nut/3493
for localhost
This situation is now changing as low cost processors become
available, costing significantly less than a UPS unit. This evolution
makes it interesting to shift to a configuration as shown in
figure 6, but it also
exacerbates the security weakness of figure 5 since the traffic between the daemons is now over an
exposed network.¶
UPS management needs to move to a more secure
practice in which all traffic is encrypted, but this cannot be imposed
by a wave of the hand: it cannot be implemented quickly and without
impact to many deployed systems. The ideal would be an easy-to-follow
migration plan which provides the required encryption but tolerates
the slow moving updates of the UPS software.¶
Here are four examples of possible temporary solutions.¶
A possible technique introduces shims between the Attachment Daemon (2.1) and the
network, and between the network and the Management Daemon (2.6) as shown in
figure 7. These shims
provide TLS support [RFC8446], allowing the Attachment Daemon (2.1)
and Management Daemon (2.6) to continue temporarily without native TLS. The technique
has been successfully tested, but the principal difficulty is that the
shims make use of a second port which is not currently available.¶
TLS shim listens TLS shim listens
on port TBD1 on port 3493
,-----,------------,----, ,----,--------------,
| UPS - Attachment |TLS | <-STARTTLS | TLS| Management |
| | Daemon |shim| OK--> |shim| Daemon |
/-----'------------'----\ '----'--------------'
Listens on
port nut/3493
The shim in front of the Attachment Daemon (2.1) listens to incoming traffic on a
port to be specified. When it receives the command STARTTLS (4.2.12) it¶
Returns OK to the client and sets up TLS encapsulation.¶
Another possible technique is the use of SSH tunnels, using a
software such as stunnel [stunnel] which adds
OpenSSL-based TLS support without modifying the Attachment Daemon (2.1) or Management Daemon (2.6).¶
In figure (8) there are two
VLANS: The main traffic between the protected server and its clients
uses the production VLAN. The UPS management traffic between the
attachment and management daemons uses the UPS management VLAN.¶
In the long term, enforcing secure communication requires
tightening up the Attachment Daemon (2.1) to require the use of command STARTTLS (4.2.12) for
commands sent over the global Internet. In such a situation an Attachment Daemon (2.1)
listening for traffic other than from the localhost:¶
The "SHOULD" rather than "MUST" in 1 above allows system administrators to enforce secure
communication using other techniques which do not involve the
STARTTLS (4.2.12) command.¶
If an Attachment Daemon (2.1) requires that all commands be encrypted as required by
the "MUST" in 2 above, then
automatically each Management Daemon (2.6) must encrypt as well, since it has to do so in
order to gain access.¶
The "SHALL" in 3 above applies to
traffic from the global Internet. An Attachment Daemon (2.1) MAY accept unencrypted
commands from localhost if the local installation's security
practices allow it, for example in a dedicated appliance.¶
Note that the separate management of strongly secure traffic from
the global Internet and weakly secure traffic from localhost
can be achieved by using two ports: nut/3493 for the current
weakly secure traffic from localhost, and some other port,
perhaps ups/TBD1, for enforced secure communication, much in
the manner of http and https.¶
Administrative commands such as FSD (4.2.3), INSTCMD (4.2.6)
and SET (4.2.11) are powerful and can have a deep effect on system
integrity, For example, the command FSD (4.2.3) is involved in mission
critical system shutdown decisions. Access to them needs to be
managed and restricted. This clause presents the current practice.¶
The Attachment Daemon (2.1) maintains a file
(currently upsd.users) defining each administrative user (2.2). Note that these
users are independent of those recorded in file /etc/passwd.
Each administrative user gets its own section in
file upsd.users. The declarations in that section set the
parameters which define that user's privileges. The section begins
with the name of the user enclosed in square brackets, U+005B LEFT
SQUARE BRACKET [ and U+005D RIGHT SQUARE BRACKET ], and continues
until the next user name in brackets or EOF.¶
Allow the user to do certain things in the Attachment Daemon (2.1). To
specify multiple actions, use multiple instances of the
declaration. Valid actions are:¶
FSD Set the "Forced Shutdown" flag for this UPS.
See FSD (4.2.3).¶
Let a user initiate specific instant commands. See section
INSTCMD (4.2.6). Use value ALL to grant all commands
automatically. To specify multiple commands, use multiple
instances of the instcmds field. For the full list of what a
given UPS supports, use client upscmd -l supplied by
the NUT Project (2.7).
password
Set the password for this user. Your password should be
more secure than the examples shown.
upsmon
Add the necessary actions for a Management Daemon (2.6) to process a system
shutdown. In current practice the value is still master
or slave. Note that there is no U+003D EQUALS SIGN =.
In this simple example of current practice, the system
administrator sets the battery level at which an Attachment Daemon (2.1) will raise the
status LB, represented by variable battery.charge.low, to
35% of full charge. A system administrator types the following command
to call the client upsrw supplied by the
NUT Project (2.7).¶
In this second example of current practice, the long-running
Attachment Daemon (2.1)upsmon which is responsible for initiating system
shutdowns and which is provided by the NUT Project (2.7) issues commands
USERNAME (4.2.13) and PASSWORD (4.2.8) when it starts up. The data needed for the
USERNAME (4.2.13) and PASSWORD (4.2.8) is provided by a configuration
file upsmon.conf which contains the
line¶
This says that the UPS to be monitored
is UPS-1@example.com, it provides 1 single power supply, the
administrative user (2.2) is admin with password secret. The Management Daemon (2.6) acts
as a Primary (2.8), although current practice uses the term master.¶
Current NUT Project (2.7) experience after more than 20 years is that the UPS
management area advances slowly, and that there are few requests to
modify or extend the Commands, Responses, Statuses and Variables. When
this does occur, the NUT Project (2.7) has been able to settle the matter
without difficulty in the project mailing list. It is therefore
proposed to not burden IANA with this namespace management and to
continue with the current process in which the project in its mailing
list acts as a Working Group.¶
The Commands, Responses, Statuses and Variables are currently
recorded as follows:¶
In 2008 IANA assigned ups/401
"Uninterruptible Power Supply" to Mr. Charles Bennett as both
assignee and contact. We have been unable to find any protocol
document or other published activity report for this port other than
the One Windows Trojan. Mr. Bennett himself died in 2015,
see obituary [Bennett]. Since his email address
was registered by IANA as bennettc@ohio.edu it is possible
that the University of Ohio is a successor in interest. The editor
tried to contact the IT support department of the university by email
and telephone but was rejected.
Ed: My non-contact was Mr. Keith Brock, IT Support Senior
Specialist, brock@ohio.edu +1 740 597 2136¶
or by providing a choice of ports through which an Attachment Daemon (2.1) may
receive commands: one for "legacy" traffic, the other for fully
secured traffic.¶
The project needs a second registered port. Since ports are a
limited resource, it would be better to re-use an existing port rather
than request a new one, and the project is interested in using
existing port ups/TBD1. Let's look more closely at this:¶
The port name "ups" satisfies the Principle of Least Surprise. It
is not surprising for a port called "ups" to be used to manage UPSs.
It is unlikely to be used for anything else.¶
There are no other known users of this port and no other published
protocols or usage reports.¶
The currently assigned port number 401 is for a system port.
The project has no imperative need for such a port; a user port, TBD1,
would be sufficient. The Attachment Daemon (2.1) is a system activity, but it can be
launched by root and dropped to a non-privileged user perfectly well
on a user port.¶
Note: In Unix-like systems a port with a number below 1024 is
privileged and requires elevated permissions to manage.¶
System ports are more likely to attract malicious scans than user
ports.¶
The project does not need to be assigned this port. The need is
to be able to use port "ups".¶
UPS management does not need a
system port (7.2.3). If port number 401 were freed and the
name ups assigned to user port TBD1, that would be equally
effective.¶
The document shepherd is requested to replace the port number
TBD1 by any number that IANA assigns to port name
ups.¶
The NUT Project (2.7) advises IANA that port ups/401
has no effective registrant (7.2.2). The
project does not have an imperative need to be the registrant but
will accept to become the registrant if IANA deems such change desirable.
Such a change in registrant could be accompanied by an allocation of a
user port number TBD1.¶
The NUT Project (2.7) implemented an Attachment Daemon (2.1) as program upsd and a set of
hardware specific drivers, all written in K&R C. upsd
supported all of the protocol commands and responses defined by this
document.¶
An experimental program written in Python3 provided
a TLS 1.3 [RFC8446] shim daemon as shown
in figure (7) which ran in front
of upsd, making it appear that upsd supported TLS
1.3.¶
There are several examples of a Management Daemon (2.6): the NUT Project (2.7)
provided upsmon which takes the system shutdown decision when
utility power fails. Further configuration options such as timers
were provided by helper program upssched.¶
The programs upsd, upsmon, upssched,
upsc, upscmd and upsrw have been included
in the package known as "nut" in the package systems of many
distributions: all the major Linux distributions, and Unix
distributions such as OpenBSD and OpenSolaris. A Microsoft Windows
version has been developed but was not maintained.¶
This document is based on the
NUT Project (2.7)documentation [devguide]. The editor
acknowledges the work of Charles Lepple, Arjen de Korte, Arnaud
Quette, Jim Klimov, Russell Kroll, Manuel Wolfshant, Mark Hansen and
many others who contribute to
the nut-upsuser [nut-upsuser].
and nut-upsdev [nut-upsdev] mailing lists.¶
The source for this document is marked up using
an SGML DTD [SGML] and an XML meta-DTD as defined
by
HyTime Annex A [HyTimeA].
The sgmlnorm [sgmlnorm] program generates
XML which program xml2rfc [RFC7991] uses
to prepare the HTML and text renderings. The editor acknowledges the
help received from Carsten Bormann and Julian Reschke in the xml2rfc
mailing list.¶
The editor thanks Adrian Farrel for advice received during the
preparation of this document. Many helpful comments were received
from Bart Smit, David Zomaya, Joyce Norris and Ted Mittelstaedt.¶
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/info/rfc2119>.
"International Standard ISO/IEC 10744 -- Hypermedia/Time-based Structuring Language, Annex A, SGML Extended Facilities", ISO/IEC JTC 1/SC 34 Document description and processing languages, .
[IEC62351-1]
"IEC TS 62351-1 Power systems management and associated information exchange -- Data and communications security. Part 1: Communication network and system security -- Introduction to security issues", IEC Technical Specification Reference number IEC/TS 62351-1:2007(E), 35 pages, CHF 205, Technical Committee TC 57 - Power systems management and associated information exchange, , <https://nanopdf.com/download/technical-iec-specification-ts-62351-1_pdf>.
Sheffer, Y. and A. Farrel, "Improving Awareness of Running Code: The Implementation Status Section", BCP 205, RFC 7942, DOI 10.17487/RFC7942, , <https://www.rfc-editor.org/info/rfc7942>.
Goldfarb, Charles F., "The SGML Handbook", ISBN 0-19-853737-9, .
[sgmlnorm]
Clark, James., "SGMLNORM An SGML System Conforming to International Standard ISO 8879 -- Standard Generalized Markup Language", <http://www.jclark.com/sp/sgmlnorm.htm>.
[stunnel]
Trojnara, Michal., "Stunnel proxy adds TLS encryption functionality to existing clients and servers", <https://www.stunnel.org/>.
The number of variables used in a given deployment depends on the
sophistication of the UPS product: this annex shows a typical example
of the subset of variables used for a reasonably complete "consumer
grade" UPS. The NUT Project (2.7) maintains a large
library of the variable subsets [Library] used by different UPS models.¶
Note that successive versions of a given product may add or delete
features causing a change in the subset of variables used. An example
is the removal of ups.delay.start from a "consumer grade"
UPS. The manufacturer reserves the feature for the "professional"
product.¶
Some of the features of a UPS are represented by
variables which may be tuned by the user. The following variables are
typical of such tunable features. The precise list depends on the
model of UPS. An implementation of a Management Daemon (2.6) acting as a utility
program may provide a listing of the variables available, as well as
acting on them, for example utility
program upsrwas included in the
NUT package (9.2).¶
Some of the features of a UPS are actions known
as instant commands (2.5) which may be
ordered by the user. The following variables represent such instant
commands. The precise list depends on the model of UPS. An
implementation of a Management Daemon (2.6) acting as a utility program may provide a
listing of the variables available, as well as acting on them, for
example utility program upscmdas
included in the NUT package (9.2).¶
This appendix provides background material
helpful for a general understanding of the relation between system and
UPS. It does not define any feature of the command-response protocol.¶
We consider the steps involved in the shutdown and restart of a
long-running unattended server protected by a single UPS. The Management Daemon (2.6)
runs in the server as shown in
figure Figure 9.¶
Wall power on -- The system runs
normally. Every 5 seconds, variable ups.status reports
OL. -- Days, weeks, months go by...¶
Winter storm. Tree falls on power lines. Wall power fails
-- The server remains operational running on the UPS battery. The
Management Daemon (2.6) polls the Attachment Daemon (2.1), and detects status change OL->OB.¶
The Management Daemon (2.6) logs warning messages. The server is still operational
running on the UPS battery. -- Minutes go by...¶
The battery discharges below the level specified by variable
battery.charge.low. The server remains operational, but the
UPS battery will not last much longer. The Management Daemon (2.6) polls the Attachment Daemon (2.1), and
detects status change OB->OB+LB.¶
The Management Daemon (2.6) decides to call for a system shutdown and issues the
system shutdown command.¶
The operating system's shutdown process takes
over. During the system shutdown, a NUT Project (2.7) specific script or an
equivalent systemd service unit runs the command upsdrvctl
shutdown. This tells the UPS that it is to shut down N seconds
later where the default is N=20.
Note that the "shutdown" of a UPS removes power
from the outlet sockets, but may not turn the UPS off completely.
A delayed shutdown is sometimes audible, and the characteristic
beeping of the UPS stops.¶
The system shuts down and powers down, hopefully before the N=20
seconds have passed.¶
N seconds after item 7 -- The UPS shuts down, i.e., it turns off its
outlet sockets when N=20 seconds have passed. With some UPS units,
there is an audible "clunk". The absence of AC power to the protected
system for a sufficient time has the effect of resetting the server's
BIOS options, and in particular the option "Restore power on AC
return". This BIOS option will be needed to restart the box. How long
is a sufficient time for the BIOS to reset? This depends very much on
the box. Some need more than 10 seconds. What if wall power returns
before the "sufficient time" has elapsed? The UPS unit should be able
to wait a configurable time with default 30 seconds. These two timers
start from the moment the UPS receives the
upsdrvctl shutdown command. -- Minutes, hours, days go
by...¶
Some time later, maybe much later, wall power returns --
The UPS reconnects it's outlets to send power to the protected system.¶
The system BIOS option "Restore power on AC return" has hopefully
been selected and the system powers up. The bootstrap process of the
operating system begins.¶
After some time, the battery charges above
the battery.charge.low threshold and the Attachment Daemon (2.1) declares the
status change OL+LB->OL. We are now back in the same
situation as 1 above.¶
There are many changes in this version following the ISE review.
See reply to ISE review: http://rogerprice.org/NUT/ISE-comments-2021-06-14.reply.html Among other changes are:¶
Section (2) added "They
are listed in alphabetical order."¶
Section (2.1) Change "talks to the
UPS" -> "retrieves status from the UPS and sends commands to it".¶
Section (2.1) Change "... launched
as system user root and drops privilege ..." -> "... launched as
system user root to allow direct access to the hardware
(e.g. /proc, /dev). For better security, the daemon
then drops privilege ..."¶
Section (2.6) Change "the system
reaction to power loss." -> "orchestrating system-wide actions
after a power event."¶
Section (2.7) Title "NUT Project"
-> "NUT Software Project".¶
Section (2.8) Change "the system to
which the data lead is connected" -> "the computer running the
driver".¶
Section (2.9) Replaced and clarified
"data lead" not present with secondaries.¶
Section (2.10) Change "may open a
session" -> "may initiate a TCP session".¶
Section (2.11) Change "are considered
fundamental and are" -> "MUST be".¶
Section (2.11) Change "other statuses
depend" -> "other statuses are OPTIONAL and depend".¶
Section (2.12) Change "The features"
-> "The metrics and identifiers".¶
Section (2.12) Change "current value
attached to that feature" -> "value representing that metric or
identifier".¶
Section (2.12) Added a note: "Note:
Some variables are constants, e.g. battery type, manufacturer."¶
Section (3) Rewrote
paragraph to clarify "the Attachment Daemon and the Management daemon
which act as server and client
respectively."¶
Section (3) Change "run the
Attachment Daemon (2.1)." -> "run the Attachment Daemon (2.1), thereby
effectively creating a network attached UPS running a standard
protocol."¶
Figure (4) In the note:
replaced "but if the UPS had status OB the Secondary shuts down." by
"but if the UPS had status OB the Secondary may choose to shut down
as a precaution."¶
Section (4.2)
Change "of the port" -> "of the TCP port".¶
Section (4.2.1) Change "the count is
1 (the Primary (2.8)) + the number of Secondaries (2.9)" -> "the count
is 1 for the primary + the number of secondaries". Change "a trio of"
to "three".¶
Section (4.2.3) Clarify that "FSD" means
"Forced Shutdown".¶
Section (4.2.3) Change "only to a
high-level" -> "only to a privileged".¶
Section (4.2.4) Added prefix GET to
all the subcommands.¶
Section (4.2.7) Added prefix LIST to
all the subcommands.¶
Section (4.2.11) Changed "and the UPS
model." -> "and the UPS model. Some variables are read-only due to the
design of the UPS or its driver."¶
Section (4.2.12) Changed "The choice
of TLS version is a matter for site security policy and is not
specified in this document." -> "The parameters and versions of
cryptographic libraries are those of the Attachment Daemon's
underlying OS and are outside the scope of this document."¶
Section (4.2.13) Change "provides
facilities to limit access to the UPS unit(s) to which it is
attached." -> "limits access to clients whose credentials match those
in the file upsd.users. There is no anonymous access."¶
Appendix (B)item (7)
Change Note that the "shut down" of a UPS does not turn the UPS
off completely. It disconnects the outlet sockets. Such a delayed
shutdown is audible since the characteristic beeping of a UPS
stops. -> Note that the "shutdown" of a UPS removes power
from the outlet sockets, but may not turn the UPS off completely.
A delayed shutdown is sometimes audible, and the characteristic
beeping of the UPS stops.¶