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 that 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. The practice current when this protocol was first
developed risks weak security, and this is addressed in the Security
Considerations sections of this document.¶
This document is not an Internet Standards Track specification; it is
published for informational purposes.¶
This is a contribution to the RFC Series, independently of any
other RFC stream. The RFC Editor has chosen to publish this
document at its discretion and makes no statement about its value
for implementation or deployment. Documents approved for
publication by the RFC Editor are not candidates for any level of
Internet Standard; see Section 2 of RFC 7841.¶
Information about the current status of this document, any
errata, and how to provide feedback on it may be obtained at
https://www.rfc-editor.org/info/rfc9271.¶
Copyright (c) 2022 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.¶
This document describes UPS management techniques and current UPS
management practice published by the Network UPS Tools (NUT) Project.
The document is based on version 2.8.0 of the NUT Project software,
which supports version 1.3 of the NUT protocol.¶
Since May 2002, the protocol described by this document has been
operating on IANA port 3493/TCP (nut).¶
The primary goal of the Network UPS Tools (NUT)
Project software [NUT] is to provide support for power
devices, such as UPSs. The project has been
in operation since 1998, with a major rework in 2003. It operates
through a user mailing list [nut-upsuser], a
developer mailing list [nut-upsdev],
a website [NUT], and
a GitHub repository [nut-repository]. See
[githist] and Appendix J of [History] for
a history of the project.¶
The Shutdown Story section (see Appendix B)
describes the current UPS management practice for performing a managed
shutdown of unattended infrastructure after an unscheduled failure of
the public power supply in order to minimize the risk of corruption to data
processed by this infrastructure.¶
As a simplification to ease reading, 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 5.1, while
the events are listed in
Section 5.2.¶
This document refers to the "public power supply". Other texts
frequently refer to "utility power", "input source power", or even
"wall power".¶
Additional information about the NUT Project is available in
the project documentation [Documentation].
Requests for further information about this protocol and related
technical matters may be addressed to
the mailing list [nut-upsuser] of the NUT Project.¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED",
"MAY", and "OPTIONAL" in this document are to be interpreted as
described in BCP 14 [RFC2119][RFC8174]
when, and only when, they appear in all capitals, as shown here.¶
In current practice, the commands and other functions offered by
the Attachment Daemon are made available to a set of users known as Management Daemons. These
Management Daemons authenticate to the Attachment Daemon with basic credentials (username and
password). Although called "users", the administrative users are not
system users; they are specific to an Attachment Daemon and are listed in a text
file (currently upsd.users) that is read by the Attachment Daemon and
that assigns to each of them the password, Instant Commands, and
actions that are allowed, together with the Primary or Secondary
status of the Management Daemon. For details,
see Appendix E.1. For details of the Primary, see
Section 2.7; for details of the Secondary, see Section 2.8. Typically, a
high-level user will be able to send command FSD, but a
low-level user might only be allowed to access the test panel. The
security provisions for administrative users are discussed in
Appendix E.¶
The Attachment Daemon retrieves the status from the UPS and sends
commands to it often through a Driver specific to the hardware model
and the connection medium, e.g., USB, serial. See Section 2.3. It
maintains an abstracted view of the hardware through the use of
hardware statuses. See Section 2.10. A Management Daemon may
consult the abstracted view using the commands described in this
document.¶
See Section 8.2 for details of the recommended
minimum support of variables, which calls for Attachment Daemon support
of statuses OB, OL, LB, and FSD.¶
The NUT Project has implemented an Attachment Daemon as program upsd
and a set of hardware-specific Drivers, all written in K&R C [C2ndEd]. The
Attachment Daemon is launched as system user "root" but for better security; then, it
drops the privilege to run as a detached software service.¶
A Driver is that part of an Attachment Daemon that 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 UPS event occurs in the Management Daemon when a change in the UPS status is
received from the Attachment Daemon. This event is internal to the Management Daemon.
See Section 5.2.¶
An Instant Command is a command that, when sent to the Attachment Daemon,
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 Section 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, 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. See
Appendix 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.¶
There are several examples of a Management Daemon: the NUT Project
provides upsmon, which takes the system shutdown decision when
the public power supply fails. Further configuration options, such as timers, are
provided by the helper program upssched.¶
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 in the Primary to be the Primary Management
Daemon that 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.¶
When a hardware device, such as a UPS unit, supplies power to more
than one system, the system that communicates directly with the UPS
unit, e.g., using a USB, RS-232, or a network connection, is known as the
Primary. The others are Secondaries. There is no Attachment Daemon in a
Secondary. See Figure 4.
Common current practice for system administrators is to consider the
Management Daemon in a Secondary to be a Secondary Management Daemon that
understands status symbol FSD as an order to shut down.¶
The Management Daemon may initiate a TCP session with a specified device, such
as a UPS known to the Attachment Daemon. The session structure provides for audit
and security, as well as access to mission-critical UPS functions. For
example, good practice requires password protection for an Instant
Command that 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 5.1, which
specifies each of these symbols.¶
See Section 8.2 for details of the recommended
minimum support of status symbols OB, OL, LB,
and FSD.¶
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. See Appendix A,
which provides examples of variables. For example, the
variable battery.charge contains the current charge of the
UPS battery as a percentage value.¶
Note: Some variables are constants, e.g., battery type and
manufacturer.¶
Figure 1 shows a reference
configuration in which the command/response protocol applies. The UPS
shown is representative of all managed power devices.¶
The reference configuration in Figure 1 shows a single UPS unit that
has a power supply link
(===) and a data link (---) attached to a system
running an Attachment Daemon. 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. 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 the 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
and the Management Daemon 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 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, thereby effectively creating a network-attached UPS running a
published 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
system. The others have only power connections (===) to the
UPS and are known as Secondaries. A Secondary does not run an Attachment Daemon;
it connects over a network to the Attachment Daemon in the
Primary. Figure 4 shows the
Attachment Daemon and the Primary Management Daemon 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 has an internal state machine, and some
complex implementations of the Management Daemon include an internal state
machine, for example, to assist the system shutdown of a complex
installation. The Management Daemon is required to remember the
previous ups.status value it received from the Attachment Daemon and
compare it with the next. Other than that, the management protocol
used between them is effectively stateless.¶
For example, see Section 5.2, which shows a map of the
new ups.status response and the previous ups.status
response to an event, which is taken as the basis for Management Daemon action.¶
The character set used for commands
and responses is US-ASCII; see [RFC0020].¶
Multi-word elements are contained between
quotation mark characters for easier parsing, e.g., "UPS on
fire". Embedded quotation marks are escaped with reverse slant (\), often known as backslashes. Embedded
backslashes are also escaped by representing them as \\.¶
Commands and responses have no leading or
trailing blank space and are terminated with a single new
line character line feed (LF).¶
Blank space within commands and responses is reduced to
one space (SP).¶
The <port> is the number of the TCP port on which
the Attachment Daemon is listening. The default is 3493. This is supported by
all current Management Daemons.¶
In a configuration like the one shown
in Figure 4, in which a UPS protects more than
one system, the Primary Management Daemon needs to know how many Secondaries are
currently active, i.e., powered by the UPS, either from the
public power supply or from battery power. The Attachment Daemon supports this by keeping a
count of all the active systems powered by a UPS. The
count is initialized, 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
counting. Additionally, command DETACH decrements the count, and a Management Daemon may
read the count at any time using the command NUMATTACH.¶
The ATTACH command is also sent to the Attachment Daemon 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 executes command
DETACH 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.¶
This companion command to ATTACH reduces the count of
"active" Secondaries. 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 are still active.¶
A Management Daemon that is Primary and has the required authority uses this
command to set status symbol FSD, meaning "Forced Shutdown", in
the Attachment Daemon. In current practice, the Primary Management Daemon uses the symbol to
tell the Secondaries to shut down.¶
In current practice, commands such as FSD are made
available only to a privileged administrative user authorized to send
such a mission-critical command. The security provisions for
administrative users are discussed in Appendix E.¶
Note: The symbol FSD is also used for an event.
See Table 5.¶
<description> is a string that gives a brief
explanation of the named variable. The Attachment Daemon MAY return
"Unavailable" if the file that provides this description is not
installed.¶
For example: command GET DESC su700 ups.status and
response DESC su700 ups.status "UPS status"¶
This is a read/write variable. It may be read with
command GET VAR (see Section 4.2.4.6) and set to a different value
with command SET (see Section 4.2.11).
ENUM
This is 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 that may be seen with the command LIST
RANGE (see Section 4.2.7.4).¶
NUMBER
This is a single numeric value, either
integer or float.
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 is then responsible for
handling values as either integer or float.¶
Current practice is to represent floating point values using
a decimal (base 10)
English-based representation. Hexadecimals, exponents, and commas used as separators for
thousands are not allowed. For example, "1200.20" is valid,
while "1,200.20" and "1200,20" are not valid.¶
<description> is defined by the Attachment Daemon configuration. If
it is not set, current practice is for the Attachment Daemon 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.¶
All the LIST commands produce a response with a common
format. The response begins with BEGIN LIST and then
repeats 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 command
and then wait for the response. When it arrives, the Management Daemon doesn't
need a complicated state machine to remember which list is which.¶
Note: The current NUT Project implementation of the
Attachment Daemon, upsd, sends back the response to the LIST
command as a sequence of messages. The Management Daemon should continue reading
these messages until it receives the line beginning END LIST.¶
The command calls for the Attachment Daemon to report a list of the Instant
Commands that the Management Daemon may send to the Attachment Daemon. This Instant Command
list is the abstracted view of the UPS hardware capabilities. An
economical UPS will support few or no Instant Commands, but a
professional model should support more.¶
<upsname> is the name of the UPS,
<varname> is the UPS variable,
and <value> is one of the possible values of that UPS
variable. Note that, in current practice, the output is an unordered
list. Also note that the quotation marks are part of
the response.¶
For example: command LIST ENUM su700 input.transfer.low
and 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
<upsname> is the name of the UPS,
<varname> is the UPS variable, and
{<min>,<max>} is the interval of valid
values of that UPS variable. Note that the quotation
marks are part of the response.¶
For example: command LIST RANGE su700
input.transfer.low and 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 to report a list of the UPS
variables associated with a given UPS that may be read and written by
the Management Daemon. 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 that
are needed for an automatic shutdown and restart;
see Appendix B. Also,
see Section 8.2 for details of the recommended
minimum support of variables. A full list of variables is available
in source code file docs/nut-names.txt [gitvars],
which serves as the Recording Document.¶
<upsname> is the name of the UPS,
<varname> is the UPS variable, and
<value> is the value of that UPS variable. Note that
the quotation marks are part of the response.¶
<upsname> is the name of a UPS, and
<description> is the description maintained by the
Attachment Daemon, if available. It is set to "Unavailable" otherwise. Note that
the quotation marks 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 supports multiple UPSs. It is also useful for clients
that perform a UPS discovery process.¶
The command calls for the Attachment Daemon to report a list of all the UPS
variables that it maintains for a given UPS and the values of those
UPS variables.¶
<upsname> is the name of the UPS,
<varname> is the UPS variable, and
<value> is the value of that variable. Note that
the quotation marks are part of the response.¶
The response to this command lists the UPS variables available for
this UPS and their current values.¶
This command is a companion to USERNAME and is used by a
Management Daemon to specify the password required to enter a session with the
Attachment Daemon; see Section 2.9.¶
In current practice, the Attachment Daemon records in local
file upsd.users that an administrative user is a Primary.
See Appendix E.1 for an example. When a Management Daemon
starts up and opens a session with the Attachment Daemon, it lays claim to being a
Primary by sending command PRIMARY to the Attachment Daemon, thus
claiming that it has the required authority to perform critical
actions, such as setting status symbol FSD.¶
The command calls for the Attachment Daemon to set a UPS variable to a given
value. Whether this has an effect on the UPS hardware is specific to
the Driver and the UPS model. Some variables are read-only due to the
design of the UPS or its Driver.¶
<upsname> is the name of the UPS,
<varname> is the UPS variable, and
<value> is the value to be assigned to that variable.
Note that the quotation marks are part of the command.¶
If the command succeeds, the response is OK; otherwise, see
the error responses in Section 4.3.2.¶
For example: command SET VAR su700 ups.id "My UPS" and
response OK¶
The client tells the Attachment Daemon to switch to communication encrypted by
TLS [RFC8446]. When the
client receives OK, it also switches to TLS encryption.¶
If the command succeeds, the response is OK STARTTLS;
otherwise, see the error responses
in Section 4.3.2.¶
If the client does not send command STARTTLS to the Attachment Daemon,
communication continues unencrypted; however, an Attachment Daemon MAY refuse
unencrypted communication.¶
NUT 2.8.0 supports the encryption of communications between the
Attachment Daemon and the Management Daemon using TLS
1.3 [RFC8446] with X.509 v3 certificates, as
defined by [RFC5280] and updates.
See Appendix D for details of the
encryption of communications in previous release 2.7.4.¶
The very restricted nature of UPS management makes it of
interest to consider self-signed certificates.¶
In the World Wide Web, there are millions of servers and hundreds
of millions of potential clients for each one. The servers do not
know who their clients will be, so they entrust the management of a
Public Key Infrastructure (PKI) to Certificate Authorities that they
trust. The encryption of communications
between the client and server requires that the browsers carry a list of
Certificate Authorities that the clients have to trust. This is
a many-to-many relationship.¶
The management of UPS units is not a many-to-many relationship; it
is frequently one to one. In the closely restrained world of UPS
management, there are a very limited number of clients for each
server, rarely more than three, and unlike the World Wide Web, the
server administrators know exactly who they are. These clients visit
very few servers, typically one only. This situation is totally
different from the World Wide Web. The use of external Certificate
Authorities is a potential security weakness that must be accepted for
the World Wide Web but which can be avoided for UPS management by
either generating the private and public keys locally or, for larger
organizations, using a PKI.¶
The security policies for UPS management may be subordinate to an
organization's own internal IT security plans and procedures, possibly
based on [RFC7030]
and [RFC8894], but in simple cases, it is possible
to obtain better security using self-signed certificates.¶
The Attachment Daemon limits access to clients whose credentials match those in
the file upsd.users. There is no anonymous access. A Management Daemon
program or script uses command USERNAME and its companion
command PASSWORD to open a session with the Attachment Daemon for an
administrative user. 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.¶
<error-name> is a single word token taken from
the 27 characters A-Z and hyphen
(-). 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 client's host and/or
authentication details supplied by USERNAME
and PASSWORD are not sufficient to execute the requested
command.
ALREADY-ATTACHED
The client has already sent a
successful ATTACH command for a given UPS and can't do it again.¶
ALREADY-SET-PASSWORD
The client has already
supplied a PASSWORD and is attempting to repeat the command
in the same session.
ALREADY-SET-USERNAME
The client has already
supplied a USERNAME and is attempting to repeat the command
within the same session.
CMD-NOT-SUPPORTED
The specified UPS doesn't
support the Instant Command.
DATA-STALE
The Attachment Daemon is connected to the
Driver 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 to refuse to provide the Management Daemon with variables on stale units
to avoid false readings.¶
This generally means that the Driver is running, but it has lost
communication with the hardware. Check the physical connection to the
equipment.¶
DRIVER-NOT-CONNECTED
The Attachment Daemon can't perform the
requested command, since the Driver 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
hasn't been configured properly to allow the requested feature to
operate. In current practice, this error response is possible only for
command STARTTLS.
FEATURE-NOT-SUPPORTED
This instance of Attachment Daemon does
not support the requested feature. In current practice, this error
response is possible only for command STARTTLS.
INSTCMD-FAILED
The Attachment Daemon failed to deliver the
Instant Command request to the Driver. 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 that is not recognized or is otherwise not valid in this
context. This is typically caused by sending a valid command, such as
GET, with a subcommand that is not valid.
INVALID-PASSWORD
The client sent a nonvalid
PASSWORD.
INVALID-USERNAME
The client sent a nonvalid
USERNAME.
INVALID-VALUE
The value specified in the request
is not valid. This usually applies to a SET of
an ENUM type that is using a value not in the list of
allowed values. See Section 4.2.7.3.
PASSWORD-REQUIRED
The command requires
a PASSWORD for authentication, but the client hasn't provided
one.
READONLY
The requested variable in a SET
command is not writable.
SET-FAILED
The Attachment Daemon failed to deliver
the SET request to the Driver. This is similar
to INSTCMD-FAILED.
TLS-ALREADY-ENABLED
TLS mode is already enabled
on this connection, so the Attachment Daemon can't start it again.¶
Note: Historically, this message was ALREADY-SSL-MODE.¶
TLS-NOT-ENABLED
TLS mode is required but has
not yet been enabled on this connection, so the Attachment Daemon can't send
commands.¶
Note: This message is experimental and not in current common
use.¶
TOO-LONG
The requested value in a SET
command is too long.
UNKNOWN-COMMAND
The Attachment Daemon doesn't recognize the
command.
UNKNOWN-UPS
The UPS specified in the request is
not known to the Attachment Daemon. This usually means that it didn't match
anything in the Attachment Daemon 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 in the command.
This section repeats the syntax of Section 4.2
but in Augmented Backus-Naur Form (ABNF). It does not define any
additional features. For further details of each command and the
response, see Section 4.2.¶
The commands may be presented in ABNF
[RFC5234][RFC7405] and
represented using US-ASCII [RFC0020].¶
Current practice tolerates mixed-case command names, but it is
RECOMMENDED to use uppercase only for commands.
See Figure 5.¶
;-------------------------------------------------------------------
; This grammar is case sensitive. Terminal keywords SHOULD be
; written in uppercase, as shown.
; The following basic rules written with uppercase names are
; taken from RFC 5234, Appendix B.1.
SP = 1*%x20 ; At least one SPACE
LF = %x0A ; Linefeed
DIGIT = %x30-39 ; Digit 0 through 9
ALPHA = %x41-5A / %x61-7A ; A-Z / a-z
DQUOTE = %x22 ; Double quote "
VCHAR = %x21-7E ; Visible (printing) characters
; Additional basic rules needed by this grammar
LC = %x61-7A ; Letter a through z
DOT = 1%x2E ; Exactly one .
COLON = 1%x3A ; Exactly one :
AT = 1%x40 ; Exactly one @
SEP = 1"-" / 1"_" / 1"." ; A single - or _ or .
JOIN = COLON / AT ; A single : or @
; Frequently used in this grammar
cmdname = 1*LC *62(DOT 1*LC) ; E.g., load.off.delay
upschar = DIGIT / ALPHA / SEP
ups = 1*ALPHA *62upschar ; E.g., Example-Mfg-999
group = ups ; E.g., HB (Not in common use)
hostname = ups ; E.g., example.com
port = 1*5DIGIT ; E.g., 3493
upsname = [group COLON] ups [AT hostname [COLON port]]
; Fully Qualified UPS name
; E.g.,
; HB:[email protected]:3493
username = ups ; E.g., Power-Dept.6
varname = 1*LC *62( DOT 1*(DIGIT / LC) )
; E.g., outlet.1.status
;-------------------------------------------------------------------
commandLine = command LF ; LF is a single %x0A
command = attach / detach / fsd / get / help / instcmd /
list / password / primary / protver / set /
starttls / username / ver
;
attach = "ATTACH" SP upsname
;
detach = "DETACH"
;
fsd = "FSD" SP upsname
;
get = "GET" SP getsubcommnd
getsubcommand = getcmddesc / getdesc / getnumattach /
gettype / getupsdesc / getvar
;
getcmddesc = "CMDDESC" SP upsname SP cmdname
getdesc = "DESC" SP upsname SP varname
getnumattach = "NUMATTACH" SP upsname
gettype = "TYPE" SP upsname SP varname
getupsdesc = "UPSDESC" SP upsname
getvar = "VAR" SP upsname SP varname
;
help = "HELP"
;
instcmd = "INSTCMD" SP upsname SP cmdname
;
list = "LIST" listsubcommand
listsubcommand = listclient / listcmd / listenum / listrange /
listrw / listups / listvar
;
listclient = "CLIENT" SP upsname
listcmd = "CMD" SP upsname
listenum = "ENUM" SP upsname SP varname
listrange = "RANGE" SP upsname SP varname
listrw = "RW" SP upsname
listups = "UPS"
listvar = "VAR" SP upsname
;
session-password = "PASSWORD" SP *63VCHAR
; A sequence of printable characters defined
; in a server configuration file. Local
; security practices may mandate a minimum
; and maximum number of characters.
;
primary = "PRIMARY" SP upsname
;
protver = "PROTVER"
;
value = *63VCHAR ; Local practices may limit the choice of
; characters and require non-US-ASCII.
set = "SET" SP %s"VAR" SP upsname SP varname SP
DQUOTE value DQUOTE
;
starttls = "STARTTLS"
;
session-username = "USERNAME" SP username
;
ver = "VER"
;-------------------------------------------------------------------
The grammar is case sensitive. The terminal key words SHOULD
be written in uppercase, as specified.¶
The repetition factor in front of an expression has the form
<min>*<max>, where <min> is the minimum number of
repetitions, and <max> is the maximum number.¶
If <min> is omitted, its value is 0. If <max> is
omitted, its value is infinity.¶
The notation n*n, meaning "exactly n copies", may be
written as n.¶
Square brackets around an expression mean that the expression is
optional. This could be written as 0*1.¶
The responses to the commands are encoded
in US-ASCII [RFC0020] and fall into two groups:¶
Short replies to action commands; see Section 4.3.¶
Long replies to requests for information. In this case, the reply
is sent in a sequence of messages. The last message will contain a
line beginning END LIST . For
example, see Section 4.2.7.1.¶
These symbols resume the abstracted view of the UPS hardware
maintained by the Attachment Daemon. 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 will poll
variable ups.status every 5 seconds with a command, such
as GET VAR su700 ups.status, and a response, such as 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 public power supply is
too low and is boosting it to the required level. The UPS continues
to supply the protected system from the public power supply.
BYPASS
The UPS is feeding current directly from the public 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.¶
COMM
The Attachment Daemon has effective contact with the UPS.
DISCHRG
The UPS battery is discharging. This usually implies that the UPS
also has status OB but may not be the case if the UPS also has
status OFF.¶
FSD
This "Forced Shutdown" status signals that the final shutdown
sequence has begun.
LB
Low Battery. The battery level of the UPS is below a chosen limit.
The UPS may be in status OL or OB.
NOCOMM
The Attachment Daemon has no effective contact with the UPS.
OB
On Battery. The UPS is taking energy from its 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
public power supply. The exact meaning depends on the model.
OL
Online. The UPS is online, receiving energy from the public 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 its
normal operating maximum.
RB
Replace battery. The UPS reports that its battery or batteries should
be replaced.
TEST
Under test. The UPS is currently undergoing a test that may have
been requested manually or internally.
TICK
Heartbeat. A software UPS in the Attachment Daemon provides a regular signal
monitored by the Management Daemon 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 public power supply is
too high and is reducing it to the required level. The UPS continues
to supply the protected system from the public power supply.
A Management Daemon detects the occurrence of a UPS event from a change in the
UPS status received from the Attachment Daemon. 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 should retrieve the variable ups.status from the
Attachment Daemon 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 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 to assign names to certain
events. These are shown in the table in parentheses.¶
If the status OB is present, current practice
takes Management Daemon 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 the following: if the UPS has not responded for
15 seconds, the Management Daemon assumes that the UPS is dead
(event NOCOMM), and if the last known OL/OB status was OB, a
system shutdown (command FSD) is requested.¶
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 activity, part of site management. 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 like the one shown in
Figure 6, which uses port
3493/TCP (nut) between the two daemons running in the same system.
The traffic is often not encrypted, and when it is encrypted, it uses deprecated
early versions of SSL/TLS.¶
,-----, ,--------------------,---------------------,
| UPS |---| Attachment <-Commands Management |
| |===| Daemon Responses-> Daemon |
/-----\ '--------------------'---------------------'
Listens on
port 3493/TCP
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 like the one shown in
Figure 7, but it also
exacerbates the security weakness of Figure 6, since the traffic between the daemons is now over an
exposed network.¶
These security issues raised by UPS management are those of the
power industry in general; they are addressed in detail in
IEC Technical Specification 62351 [IEC62351-1].
In addition to equipment security, cyber security is now an essential
consideration.¶
Quoting from IEC 62351-1[IEC62351-1],
Introduction to the standard, clause 5.2.3.5:¶
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.¶
In IEC 62351-1[IEC62351-1], clause 5.3.5 lists
typical security attacks: Eavesdropping, Masquerade,
Man-in-the-Middle, Replay, and Resource Exhaustion.
[RFC3552] adds message insertion/deletion/modification
and denial of service.¶
Enforcing secure communication requires tightening up the Attachment Daemon to
require the use of command
STARTTLS for commands sent over the global Internet. In such a
situation, an Attachment Daemon listening for traffic other than from
localhost:¶
The SHOULD, rather than MUST,
in Section 6.2, Paragraph 2, Item 1 above allows system administrators to
enforce secure communication using other techniques that do not
involve the STARTTLS command.¶
If an Attachment Daemon requires that all commands be encrypted as required by
the MUST in Section 6.2, Paragraph 2, Item 2 above, then, automatically,
each Management Daemon MUST encrypt as well, since it has to do so in order to
gain access.¶
The SHALL in Section 6.2, Paragraph 2, Item 3 above applies to
traffic from the global Internet. An Attachment Daemon MAY accept unencrypted
commands from localhost if the local installation's security
practices allow it, for example, in a dedicated appliance.¶
Firewalls SHOULD be used to restrict the communication between
the Attachment Daemon and the accepted Management Daemons, prohibiting and discarding traffic
from any systems that are not part of the envisioned power management
setup. Note: See Section 6.2, Paragraph 4, Item 1 above on the use
of SHOULD.¶
In long-lived installations, such as those found in UPS management,
careful certificate management is essential, whether the certificate
is provided by a Certificate Authority or is a self-signed
certificate. For example, the expiration times of both the
certificate containing the public key and the signing certificate
should be specified.¶
The defense against eavesdropping is encryption of the commands and
responses passed between the client Management Daemon and server Attachment Daemon. The protocol
provides command STARTTLS, see Section 4.2.12, which calls on
the Attachment Daemon to support TLS encryption of the communication. If this
command is accepted, the Management Daemon also encrypts.¶
In current NUT Project practice, the use of TLS is optional;
however, a Management Daemon may refuse to accept unencrypted communication. This
is done by setting declarations FORCESSL to 1
and CERTVERIFY to 1 in the Management Daemon configuration file.¶
A further weakness is that the FORCESSL
and CERTVERIFY declarations, which enforce use of encryption,
are in the client Management Daemon configuration file and not in the Attachment Daemon.
Secure practice requires enforcement by the server Attachment Daemon, rather than a
possibly rogue client Management Daemon out on the Internet.¶
This weakness may be mitigated with strict firewall rules that
would prevent the rogue client Management Daemon from accessing the Attachment Daemon.¶
Although version 2.8.0 of NUT supports TLS
1.3 [RFC8446] with X.509 v3 certificates as
defined by [RFC5280], previous version
2.7.4 only supported earlier SSL/TLS versions. To overcome this
weakness, The following techniques have been used:¶
The protocol allows a malicious client acting
as a Management Daemon to send command FSD to an Attachment Daemon to shut down a
working system and its power supply, as described in The Shutdown
Story section (see Appendix B). Similarly, a
malicious client could turn off the UPS power outlets, causing the
system to fail.¶
The protocol provides commands USERNAME (see Section 4.2.13)
and PASSWORD (see Section 4.2.8), which allow an administrative
user in a Management Daemon to authenticate itself to the Attachment Daemon, as a defense
against masquerade attacks. The administrative username and password
need protection against local malicious users. This is done by
restricting access to the configuration files.¶
The protocol relies on TLS encryption to prevent message insertion,
deletion, and modification attacks.
See Appendix D for defense methods
used for previous NUT version 2.7.4.¶
The protocol relies on a very tightly specified firewall to prevent
denial-of-service attacks. Only designated client Management Daemons should be
able to reach the server Attachment Daemon.¶
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, i.e., all the major Linux distributions and Unix
distributions, such as OpenBSD and OpenSolaris. A Microsoft Windows
version has been developed but was not maintained.¶
The features provided by current UPS units vary widely. However,
experience shows that a minimum feature set is needed for satisfactory
use of the NUT Project software. A full list of variables is
available in source code file
docs/nut-names.txt [gitvars], which serves as the Recording Document.¶
The following variables form a minimum set suitable for a desktop PC.
It is expected that, on public power supply failure, the PC will be halted. It
will not restart automatically when power returns.¶
The following additional variables are needed in a minimum set
suitable for an unattended server. It is expected that, on public power supply
failure, the server will be halted. It will restart automatically
when power returns.¶
In order to ease migration from software version 2.7.4, which
supported protocol version 1.2, software version 2.8.0 also supports
the technical terms used in protocol version 1.2.
See Appendix C for the differences.¶
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>.
[RFC5234]
Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/RFC5234, , <https://www.rfc-editor.org/info/rfc5234>.
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/info/rfc8174>.
IEC, "Power systems management and associated information exchange -- Data and communications security. Part 1: Communication network and system security -- Introduction to security issues", 35 pages, TC 57 - Power systems management and associated information exchange, IEC TS 62351-1:2007, , <https://nanopdf.com/download/technical-iec-specification-ts-62351-1_pdf>.
Rescorla, E. and B. Korver, "Guidelines for Writing RFC Text on Security Considerations", BCP 72, RFC 3552, DOI 10.17487/RFC3552, , <https://www.rfc-editor.org/info/rfc3552>.
[RFC5280]
Cooper, D., Santesson, S., Farrell, S., Boeyen, S., Housley, R., and W. Polk, "Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, , <https://www.rfc-editor.org/info/rfc5280>.
[RFC7030]
Pritikin, M., Ed., Yee, P., Ed., and D. Harkins, Ed., "Enrollment over Secure Transport", RFC 7030, DOI 10.17487/RFC7030, , <https://www.rfc-editor.org/info/rfc7030>.
The UPS variables represent the abstracted state of the UPS unit.
Certain variables represent not only the state of some hardware
feature but also provide tunable values and Instant Commands;
see Section 2.5. The full set of variables is recorded
in the reference document for variable
names [gitvars].¶
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 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.¶
An implementation of a Management Daemon acting as a utility program may
provide a listing of the variables available for a given product, for
example, utility program upsc, as included in the NUT package;
see Section 2.6, Paragraph 3.¶
The following sections illustrate the use of variables by taking
the values associated with a typical product. The example is a 1600 Va
1000 W UPS.¶
Some of the features of a UPS are represented by variables that
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 acting as a utility program may provide a
listing of the variables available, as well as acting on them, for
example, utility program upsrw, as included in the NUT package;
see Section 2.6, Paragraph 3.¶
Some of the features of a UPS are actions known as Instant
Commands (see Section 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 acting as a utility program may provide a listing of the
variables available, as well as acting on them, for example, utility
program upscmd, as included in the NUT package;
see Section 2.6, Paragraph 3.¶
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
runs in the server as shown in Figure 8.¶
The public power supply is 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. The public power supply fails.
The server remains operational, running on the UPS battery. The
Management Daemon polls the Attachment Daemon and detects status change OL->OB.¶
The Management Daemon 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 polls the Attachment Daemon and
detects status change OB->OB+LB.¶
The Management Daemon logs the low battery event.¶
The Management Daemon decides to call for a system shutdown.
It sets status FSD in the Attachment Daemon to call on any Secondaries to
shut down and waits for command GET NUMATTACH to report one
single attachment, i.e., the Primary itself. The Management Daemon then issues the
system shutdown command for itself.¶
The operating system's shutdown process takes
over. During the system shutdown, a specific script to the NUT Project or an
equivalent system 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".¶
What if the public power supply returns before the UPS shuts down? 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, the public power supply returns.
The UPS reconnects its outlets to send power to the protected system.¶
The system BIOS option "Restore power on AC
return" or "Restore to previous state" has hopefully been selected and
the system powers up. The bootstrap process of the operating system
begins.¶
The operating system starts the Attachment Daemon and the Management Daemon. The Attachment Daemon
starts the Driver and scans the UPS. The UPS status becomes
OL+LB.¶
After some time, the battery charges above
the battery.charge.low threshold, and the Attachment Daemon declares the
status change OL+LB->OL. We are now back in the same
situation as item 1 above.¶
This appendix lists the major differences between the technical
terms used in NUT software release 2.8.0 and documented in this text,
as well as those used in previous version 2.7.4 of the NUT Project.¶
Previous version 2.7.4 of NUT did not support TLS
1.3 [RFC8446]. Where such protection is needed
for version 2.7.4, a possible technique introduces shims between the
Attachment Daemon and the network and between the network and the Management Daemon, as shown
in Figure 9. These shims
provide TLS 1.3 support, thus allowing the Attachment Daemon and Management Daemon to continue
temporarily without having TLS implementations themselves. The technique has been successfully
tested.¶
TLS shim listens TLS shim listens
on port TBD1/TCP on port 3493/TCP
,-----,------------,----, ,----,--------------,
| UPS - Attachment |TLS | <-STARTTLS | TLS| Management |
| | Daemon |shim| OK--> |shim| Daemon |
/-----'------------'----\ '----'--------------'
Listens on
port 3493/TCP
Another technique is the use of TLS
tunnels [RFC8446], using a software, such as
stunnel [stunnel], which adds OpenSSL-based TLS
support without modifying the Attachment Daemon or Management Daemon. The NUT Project has no
procedure to enforce this on sites.¶
A further option to secure communications is very similar
to TLS tunneling [RFC8446] and consists of
routing the NUT traffic through a Virtual Private Network (VPN).¶
In Figure 10, there are two VLANS: the main
traffic between the protected server and its clients using the
production VLAN. The UPS management traffic between the Attachment and
Management Daemons uses the UPS management VLAN marked as
~~~~~~~~~~~~~.¶
Administrative commands, such as FSD, INSTCMD,
and SET, are powerful and can have a deep effect on system
integrity. For example, the command FSD is involved in
mission-critical system shutdown decisions. Access to them needs to
be managed and restricted. This section presents the current practice.¶
The Attachment Daemon maintains a file (currently upsd.users) that defines
each administrative user. 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 that define that user's
privileges. The section begins with the name of the user enclosed in
square brackets, opening bracket ([)
and closing bracket (]), and continues until
the next username in brackets or EOF.¶
For example, the following file declares two administrative users,
admin and pfy:¶
Allow the user to do certain things in the Attachment Daemon. To
specify multiple actions, use multiple instances of the
declaration. Valid actions are:¶
FSD Set the "Forced Shutdown" flag for this UPS.
See Section 4.2.3.¶
SET Change the value of a UPS variable. See Section 4.2.11.¶
instcmds
Let a user initiate specific Instant Commands. See
Section 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. The LIST CMD command is issued within
the client upscmd.
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 to process a system
shutdown. In current practice, the value is still master
or slave. Note that there is no
EQUALS =.
The following examples show the current security practices for
administrative users of a client Management Daemon. They also illustrate the
command pair USERNAME and PASSWORD. See Sections 4.2.13
and 4.2.8.¶
In this simple example of current practice, the system
administrator sets the battery level at which an Attachment Daemon 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.¶
Option -s specifies the variable and the value,
option -u specifies the USERNAME, option -p
specifies the PASSWORD, and [email protected] is the
UPS. The USERNAME and PASSWORD commands are issued
within the client upsrw, and the session is of short duration.¶
Note: Your password should be stronger than the example shown.¶
In this second example of current practice, the long-running
Management Daemon upsmon, which is responsible for initiating system
shutdowns and which is provided by the NUT Project, issues commands
USERNAME and PASSWORD when it starts up. The data
values needed for the
USERNAME and PASSWORD commands are provided by a
configuration file upsmon.conf, which contains the
line:¶
This says that the UPS to be monitored
is [email protected]. It provides 1 single power supply. The
administrative user is admin with
password sekret. The Management Daemon acts as a Primary, although
current practice still uses the former term master.¶
The USERNAME and PASSWORD commands are contained
within the client upsmon, and the session is of long duration.¶
This document is based on the
NUT Project documentation [devguide]. The editor
acknowledges the work of Charles Lepple, Arjen de Korte, Arnaud Quette,
Jim Klimov, Russell Kroll,
Manuel Wolfshant, Greg Troxel,
Mark Hansen, and many others who contribute to
the nut-upsuser [nut-upsuser]
and nut-upsdev [nut-upsdev] mailing lists.¶
Earlier draft versions of this document were prepared using an SGML DTD [SGML]
and an XML meta-DTD defined by HyTime Annex A [HyTimeA]. Unlike
XML, SGML offers markup minimization, and the earlier drafts took
advantage of this. The osgmlnorm [sgmlnorm] program generated the
XML that was used as input to xml2rfc [RFC7991], which then created
the document's current source. The editor acknowledges the help received
from Carsten Bormann and Julian Reschke in the xml2rfc mailing list.¶
Many helpful comments were received from Eliot Lear,
Bart Smit, David Zomaya,
Joyce Norris, and Ted Mittelstaedt.¶