Uninterruptible Power Supply (UPS) Management Protocol -- Commands and Responses
draft-rprice-ups-management-protocol-05
The information below is for an old version of the document.
| Document | Type |
This is an older version of an Internet-Draft that was ultimately published as RFC 9271.
|
|
|---|---|---|---|
| Author | Roger Price | ||
| Last updated | 2021-12-29 (Latest revision 2021-12-28) | ||
| RFC stream | Independent Submission | ||
| Formats | |||
| IETF conflict review | conflict-review-rprice-ups-management-protocol, conflict-review-rprice-ups-management-protocol, conflict-review-rprice-ups-management-protocol, conflict-review-rprice-ups-management-protocol, conflict-review-rprice-ups-management-protocol, conflict-review-rprice-ups-management-protocol | ||
| Stream | ISE state | In ISE Review | |
| Consensus boilerplate | Unknown | ||
| Document shepherd | Eliot Lear | ||
| IESG | IESG state | Became RFC 9271 (Informational) | |
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | rfc-ise@rfc-editor.org |
draft-rprice-ups-management-protocol-05
IETF R. Price, Ed.
Internet-Draft Network UPS Tools Project
Intended status: Informational 28 December 2021
Expires: 1 July 2022
Uninterruptible Power Supply (UPS) Management Protocol -- Commands and
Responses
draft-rprice-ups-management-protocol-05
Abstract
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.
Status of This Memo
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."
This Internet-Draft will expire on 1 July 2022.
Copyright Notice
Copyright (c) 2021 IETF Trust and the persons identified as the
document authors. All rights reserved.
Price Expires 1 July 2022 [Page 1]
Internet-Draft UPS management protocol December 2021
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.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1. How to Read this Document . . . . . . . . . . . . . . . . 4
1.2. Current Practice . . . . . . . . . . . . . . . . . . . . 5
1.3. Requirements Language . . . . . . . . . . . . . . . . . . 5
1.4. Additional Information . . . . . . . . . . . . . . . . . 5
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.1. Attachment Daemon . . . . . . . . . . . . . . . . . . . . 5
2.2. Administrative User . . . . . . . . . . . . . . . . . . . 6
2.3. Driver . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.4. Event . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.5. Instant Command . . . . . . . . . . . . . . . . . . . . . 6
2.6. Management Daemon . . . . . . . . . . . . . . . . . . . . 7
2.7. NUT (Network UPS Tools) Software Project . . . . . . . . 7
2.8. Primary . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.9. Secondary . . . . . . . . . . . . . . . . . . . . . . . . 7
2.10. Session . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.11. UPS Status . . . . . . . . . . . . . . . . . . . . . . . 8
2.12. UPS Variable . . . . . . . . . . . . . . . . . . . . . . 8
3. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 8
4. Protocol Specification . . . . . . . . . . . . . . . . . . . 11
4.1. Notation Used in this Specification . . . . . . . . . . . 11
4.2. Commands . . . . . . . . . . . . . . . . . . . . . . . . 12
4.2.1. ATTACH . . . . . . . . . . . . . . . . . . . . . . . 12
4.2.2. DETACH . . . . . . . . . . . . . . . . . . . . . . . 13
4.2.3. FSD . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.2.4. GET . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.2.4.1. GET CMDDESC . . . . . . . . . . . . . . . . . . . 14
4.2.4.2. GET DESC . . . . . . . . . . . . . . . . . . . . 14
4.2.4.3. GET NUMATTACH . . . . . . . . . . . . . . . . . . 14
4.2.4.4. GET TYPE . . . . . . . . . . . . . . . . . . . . 15
4.2.4.5. GET UPSDESC . . . . . . . . . . . . . . . . . . . 16
4.2.4.6. GET VAR . . . . . . . . . . . . . . . . . . . . . 16
4.2.5. HELP . . . . . . . . . . . . . . . . . . . . . . . . 16
4.2.6. INSTCMD . . . . . . . . . . . . . . . . . . . . . . . 17
4.2.7. LIST . . . . . . . . . . . . . . . . . . . . . . . . 17
4.2.7.1. LIST CLIENT . . . . . . . . . . . . . . . . . . . 18
4.2.7.2. LIST CMD . . . . . . . . . . . . . . . . . . . . 18
Price Expires 1 July 2022 [Page 2]
Internet-Draft UPS management protocol December 2021
4.2.7.3. LIST ENUM . . . . . . . . . . . . . . . . . . . . 19
4.2.7.4. LIST RANGE . . . . . . . . . . . . . . . . . . . 19
4.2.7.5. LIST RW . . . . . . . . . . . . . . . . . . . . . 20
4.2.7.6. LIST UPS . . . . . . . . . . . . . . . . . . . . 21
4.2.7.7. LIST VAR . . . . . . . . . . . . . . . . . . . . 21
4.2.8. PASSWORD . . . . . . . . . . . . . . . . . . . . . . 22
4.2.9. PRIMARY . . . . . . . . . . . . . . . . . . . . . . . 22
4.2.10. PROTVER . . . . . . . . . . . . . . . . . . . . . . . 23
4.2.11. SET . . . . . . . . . . . . . . . . . . . . . . . . . 23
4.2.12. STARTTLS . . . . . . . . . . . . . . . . . . . . . . 24
4.2.13. USERNAME . . . . . . . . . . . . . . . . . . . . . . 24
4.2.14. VER . . . . . . . . . . . . . . . . . . . . . . . . . 24
4.3. Summary of Responses . . . . . . . . . . . . . . . . . . 25
4.3.1. Response when Command Succeeds . . . . . . . . . . . 25
4.3.2. Error Responses . . . . . . . . . . . . . . . . . . . 26
5. Statuses and Events . . . . . . . . . . . . . . . . . . . . . 29
5.1. Status Symbols . . . . . . . . . . . . . . . . . . . . . 29
5.2. Events . . . . . . . . . . . . . . . . . . . . . . . . . 31
6. Security Considerations . . . . . . . . . . . . . . . . . . . 33
6.1. Agent Verification . . . . . . . . . . . . . . . . . . . 34
6.2. Current Encryption Practice . . . . . . . . . . . . . . . 34
6.2.1. Secure Tunnels . . . . . . . . . . . . . . . . . . . 35
6.3. Current General Security Practice . . . . . . . . . . . . 35
6.4. Security Needs . . . . . . . . . . . . . . . . . . . . . 36
6.4.1. Shims . . . . . . . . . . . . . . . . . . . . . . . . 36
6.4.1.1. Attachment Daemon Shim . . . . . . . . . . . . . 36
6.4.1.2. Management Daemon Shim . . . . . . . . . . . . . 37
6.4.2. SSH Tunnels . . . . . . . . . . . . . . . . . . . . . 37
6.4.3. VPN . . . . . . . . . . . . . . . . . . . . . . . . . 37
6.4.4. VLAN . . . . . . . . . . . . . . . . . . . . . . . . 37
6.4.5. Long Term: Enforced Secure Communication . . . . . . 38
6.5. Administrative Security . . . . . . . . . . . . . . . . . 39
6.5.1. Management of Administrative Users . . . . . . . . . 39
6.5.2. An Administrative User of a Client Management
Daemon . . . . . . . . . . . . . . . . . . . . . . . 40
6.5.2.1. An Administrative User Logs into a Short
Session . . . . . . . . . . . . . . . . . . . . . . 41
6.5.2.2. An Administrative User Logs into a Long
Session . . . . . . . . . . . . . . . . . . . . . . 41
7. Codepoint Management . . . . . . . . . . . . . . . . . . . . 41
7.1. Namespaces used by Command, Responses, Statuses and
Variables . . . . . . . . . . . . . . . . . . . . . . . . 42
7.2. Port Name and Number used to Manage UPS Units . . . . . . 42
7.2.1. Port nut/3493 . . . . . . . . . . . . . . . . . . . . 42
7.2.2. Port ups/401 . . . . . . . . . . . . . . . . . . . . 43
7.2.3. NUT Project Requirement . . . . . . . . . . . . . . . 43
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 44
8.1. Port Name ups: Reference to this Document . . . . . . . . 44
Price Expires 1 July 2022 [Page 3]
Internet-Draft UPS management protocol December 2021
8.2. Change of Registrant . . . . . . . . . . . . . . . . . . 44
9. Implementation Status . . . . . . . . . . . . . . . . . . . . 44
9.1. An Implementation of the Attachment Daemon . . . . . . . 45
9.2. An Implementations of the Management Daemon . . . . . . . 45
9.3. Inclusion in Software Distributions . . . . . . . . . . . 45
10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 46
11. Normative References . . . . . . . . . . . . . . . . . . . . 46
12. Informative References . . . . . . . . . . . . . . . . . . . 46
Appendix A. Variables . . . . . . . . . . . . . . . . . . . . . 48
A.1. Typical UPS Variables . . . . . . . . . . . . . . . . . . 49
A.2. Typical UPS Readable and Writable Variables . . . . . . . 52
A.3. Typical UPS Instant Commands . . . . . . . . . . . . . . 54
Appendix B. The Shutdown Story for System and UPS . . . . . . . 54
Appendix C. Technical Terms: Historical Differences . . . . . . 56
Appendix D. Change Log . . . . . . . . . . . . . . . . . . . . . 57
D.1. Changes in Version 01 . . . . . . . . . . . . . . . . . . 57
D.2. Changes in Version 02 . . . . . . . . . . . . . . . . . . 57
D.3. Changes in Version 03 . . . . . . . . . . . . . . . . . . 57
D.4. Changes in Version 04 . . . . . . . . . . . . . . . . . . 58
D.5. Changes in Version 05 . . . . . . . . . . . . . . . . . . 58
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 61
1. Introduction
1.1. How to Read this Document
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".
Price Expires 1 July 2022 [Page 4]
Internet-Draft UPS management protocol December 2021
1.2. Current Practice
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.
1.3. Requirements Language
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].
1.4. Additional Information
Additional information about the NUT Project (2.7) 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 (2.7).
2. Terminology
The following technical terms appear in this document. They are
listed in alphabetical order.
2.1. Attachment Daemon
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.
Price Expires 1 July 2022 [Page 5]
Internet-Draft UPS management protocol December 2021
2.2. Administrative User
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.
2.3. Driver
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.
2.4. Event
A UPS Event occurs in the Management Daemon (2.6) when a change in
UPS status (2.11) is received from the Attachment Daemon (2.1). This
event is internal to the Management Daemon (2.6). See Section 5.2,
Paragraph 1.
2.5. Instant Command
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).
Price Expires 1 July 2022 [Page 6]
Internet-Draft UPS management protocol December 2021
2.6. Management Daemon
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.
2.7. NUT (Network UPS Tools) Software Project
The primary goal of the NUT software project [NUT] is to provide
support for Power Devices, such as Uninterruptible Power Supplies.
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] and a web site [NUT]. See the
history of the project [History].
2.8. Primary
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".
2.9. Secondary
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".
Price Expires 1 July 2022 [Page 7]
Internet-Draft UPS management protocol December 2021
2.10. Session
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.
2.11. UPS Status
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 {ALARM BOOST BYPASS CAL CHRG
COMM DISCHRG FSD LB NOCOMM OB OFF OL OVER RB TEST TRIM}. 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.
2.12. UPS Variable
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.
3. Protocol Overview
Figure 1 shows a reference configuration in which the command/
response protocol applies. The UPS shown is representative of all
power devices,
Price Expires 1 July 2022 [Page 8]
Internet-Draft UPS management protocol December 2021
"The client"
,--------------, ,--------------,
,-----, | UPS | <-Commands | UPS |
| UPS |---| Attachment |---------------| Management |
| |===| Daemon | Responses-> | Daemon |
/-----\ '--------------' '--------------'
UPS Attachment UPS Management
System Network System
Figure 1: Reference Configuration
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 client"
,--------------------,---------------------,
,-----, | UPS <-Commands UPS |
| UPS |---| Attachment | Management |
| |===| Daemon Responses-> Daemon |
/-----\ '--------------------'---------------------'
Internal
loopback
UPS Attachment and Management System
Figure 2: Simplified single-system configuration
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
Price Expires 1 July 2022 [Page 9]
Internet-Draft UPS management protocol December 2021
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.
"The client"
,-----,------------, ,--------------,
| | UPS | <-Commands | UPS |
| UPS - Attachment |---------------| Management |
| | Daemon | Responses-> | Daemon |
/-----'------------\ '--------------'
UPS Attachment UPS Management
System Network System
Figure 3: UPS and Attachment Daemon integration
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.
"The client"
,--------------------,---------------------,
,-----, | UPS <-Commands Primary |
| |---| Attachment | Management | Primary
| |===| Daemon Responses-> Daemon |
| | '--------------------'---------------------'
| UPS | ^
| | '<-Commands---Responses->,
| | v
| | ,--------------,-----------------,
| |============| | Secondary |
/-----\ | | Management | Secondary
| | Daemon |
'--------------'-----------------'
Figure 4: UPS protects multiple systems
Price Expires 1 July 2022 [Page 10]
Internet-Draft UPS management protocol December 2021
| Note: Should the Primary fail or go off-line, the fate of the
| Secondaries depends on the UPS status (2.11) when the Primary
| failed. If the UPS had status OL the Secondary continues
| operation, but if the UPS had status OB the Secondary may
| choose to shut down as a precaution.
4. Protocol Specification
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.
4.1. Notation Used in this Specification
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.
| Historical note: UTF-8 characters 0-127 were originally known
| as the American Standard Code for Information Interchange, US-
| ASCII, first published in 1963.
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).
Price Expires 1 July 2022 [Page 11]
Internet-Draft UPS management protocol December 2021
4.2. Commands
The commands address the UPS to which they apply by <upsname> where
* <upsname> ::= <ups>[@<hostname>[:<port>]]
* <ups> is defined by the Attachment Daemon (2.1) configuration
files.
* The default <hostname> is localhost
* 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).
Examples: myups, UPS-97B@bigserver.example.com
Note: Experimental Management Daemons (2.6) use an extended form of
<upsname> in configuration files and in program parameters, where
* <upsname> ::= [<group>:]<ups>[@<hostname>[:<port>]]
* <group> is an experimental extension to provide for groups of
UPSs. It is not in common current practice.
* <ups> is defined by the Attachment Daemon (2.1) configuration
files.
* The default <hostname> is localhost
Examples: ups-1@example.com:3493, HB:heartbeat1@example.com:3493
4.2.1. ATTACH
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.
Price Expires 1 July 2022 [Page 12]
Internet-Draft UPS management protocol December 2021
Command: ATTACH <upsname>
If the command succeeds, the response is OK, otherwise see the error
responses (4.3.2).
Note: Historically, this command was known as LOGIN. Since that
LOGIN was not the conventional user access to a shell or program the
name was changed to avoid confusion.
4.2.2. DETACH
This companion command to ATTACH (4.2.1) reduces the count of
"active" Secondaries (2.9). It should be understood as "_this
secondary is no longer active_", and is usually used during system
shutdown to decrement a count of how many Secondaries (2.9) are still
"active".
Command: DETACH
If the command succeeds, the response is OK Goodbye, otherwise see
the error responses (4.3.2).
Note: Historically, this command was known as LOGOUT.
4.2.3. FSD
A Management Daemon (2.6) which is Primary (2.8) and has the required
authority, uses this command to set status symbol FSD meaning "Forced
Shutdown" in the Attachment Daemon (2.1). In current practice the
Primary (2.8) Management Daemon (2.6) uses the symbol to tell the
Secondaries (2.9) to shut down.
Command: FSD <upsname>
If the command succeeds, the response is OK FSD-SET, otherwise see
the error responses (4.3.2).
In current practice, commands such as FSD are made available only to
a 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.
4.2.4. GET
Retrieve a single response from the Attachment Daemon (2.1). The
possible sub-commands are:
Price Expires 1 July 2022 [Page 13]
Internet-Draft UPS management protocol December 2021
4.2.4.1. GET CMDDESC
Retrieve a text description of a command.
Command: GET CMDDESC <upsname> <cmdname>
Response: CMDDESC <upsname> <cmdname> "<description>"
For example: GET CMDDESC su700 load.on and response CMDDESC su700
load.on "Turn on the load immediately"
This is like DESC (4.2.4.2), but it applies to an instant command
(2.5).
4.2.4.2. GET DESC
Retrieve a text description of a variable.
Command: GET DESC <upsname> <varname>
Response: DESC <upsname> <varname> "<description>"
where <description> is a string that gives a brief explanation of the
named variable. The Attachment Daemon (2.1) may return "Unavailable"
if the file which provides this description is not installed.
For example command GET DESC su700 ups.status and response DESC su700
ups.status "UPS status"
4.2.4.3. GET NUMATTACH
Retrieve the count kept by the Attachment Daemon (2.1) of all the
"_active_" systems protected by this UPS.
Command: GET NUMATTACH <upsname>
Response: NUMATTACH <upsname> <value>
where <value> is a count of the Primary (2.8) and the number of
Secondaries (2.9) currently powered by this UPS.
For example command GET ATTACH su700 and response NUMATTACH su700 1
This information is needed by the Management Daemon (2.6) to
determine how many Secondaries (2.9) are still connected during the
system shutdown process.
Price Expires 1 July 2022 [Page 14]
Internet-Draft UPS management protocol December 2021
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.
4.2.4.4. GET TYPE
Retrieve the type of a UPS variable (2.12).
Command: GET TYPE <upsname> <varname>
Response: TYPE <upsname> <varname> <type>...
where <type> can be one or more of the following tokens. Multiple
types may be returned.
For example command GET TYPE su700 input.transfer.low and response
TYPE su700 input.transfer.low ENUM
+==============+================================================+
| Type | Meaning |
+==============+================================================+
| RW | This is a read/write variable. It may be read |
| | with command GET VAR (4.2.4.6) and set to a |
| | different value with command SET (4.2.11) |
+--------------+------------------------------------------------+
| ENUM | An enumerated type, which supports specific |
| | predetermined values |
+--------------+------------------------------------------------+
| STRING:n | This is a string of maximum length n |
+--------------+------------------------------------------------+
| RANGE | This is a number, either integer or float, |
| | comprised in the range which may be seen with |
| | the command LIST RANGE (4.2.7.4) |
+--------------+------------------------------------------------+
| NUMBER | This is a single numeric value, either integer |
| | or float |
+--------------+------------------------------------------------+
Table 1: Variable Types
Notes:
* ENUM, STRING:n and RANGE are usually associated with RW, but not
always. The default <type>, when omitted, is numeric, so either
integer or float. Each Driver (2.3) is then responsible for
handling values as either integer or float.
Price Expires 1 July 2022 [Page 15]
Internet-Draft UPS management protocol December 2021
* 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.
4.2.4.5. GET UPSDESC
Retrieve a text description of a UPS.
Command: GET UPSDESC <upsname>
Response: UPSDESC <upsname> "<description>"
where <description> is defined by the Attachment Daemon (2.1)
configuration. If it is not set, current practice is for the
Attachment Daemon (2.1) to return "Unavailable".
For example command GET UPSDESC su700 and response UPSDESC su700
"Development box"
This can be used to provide human-readable descriptions instead of a
cryptic ups@hostname string.
4.2.4.6. GET VAR
Retrieve the value of a UPS variable (2.12).
Command: GET VAR <upsname> <varname>
Response: VAR <upsname> <varname> "<value>"
For example command GET VAR su700 ups.status and response VAR su700
ups.status "OB LB"
4.2.5. HELP
Return a list of the commands supported by the Attachment Daemon
(2.1). This command is intended for human as well as program use.
Command HELP
For example, the following command line sequence executed on an
Attachment Daemon (2.1):
Price Expires 1 July 2022 [Page 16]
Internet-Draft UPS management protocol December 2021
netcat localhost 3493
HELP
Commands: HELP VER GET LIST SET INSTCMD ATTACH DETACH
USERNAME PASSWORD STARTTLS
Note: Historically, this command also returned LOGIN and LOGOUT.
Since LOGIN was not the conventional user access to a shell or
program, the command names were changed to ATTACH and DETACH avoid
confusion.
4.2.6. INSTCMD
Send an instant command (2.5) to the UPS.
Command: INSTCMD <upsname> <cmdname>
where <upsname> is the name of the UPS and <cmdname> is the instant
command (2.5) to be issued to that UPS.
If the command succeeds, the response is OK, otherwise see the error
responses (4.3.2).
For example the command: INSTCMD su700 test.panel.start and the
response OK
4.2.7. LIST
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.
The possible subcommands are:
Price Expires 1 July 2022 [Page 17]
Internet-Draft UPS management protocol December 2021
4.2.7.1. LIST CLIENT
The command calls for the Attachment Daemon (2.1) to report all the
current Management Daemon (2.6) clients of a given UPS.
Command: LIST CLIENT <upsname>
The response is
BEGIN LIST CLIENT <upsname>
CLIENT <upsname> <client_IP_address>
...
END LIST CLIENT <upsname>
For example, the command LIST CLIENT ups1 and the response:
BEGIN LIST CLIENT ups1
CLIENT ups1 ::1
CLIENT ups1 198.51.100.2
END LIST CLIENT ups1
4.2.7.2. LIST CMD
The command calls for the Attachment Daemon (2.1) to report a list of
the instant commands (2.5) which the Management Daemon (2.6) may send
to the Attachment Daemon (2.1). This instant command (2.5) list is
the abstracted view of the UPS hardware capabilities. An economical
UPS will support few or no instant commands (2.5) but a professional
model should support more.
Command: LIST CMD <upsname>
The response is:
BEGIN LIST CMD <upsname>
CMD <upsname> <cmdname>
...
END LIST CMD <cmdname>
where <upsname> is the name of the UPS, and <cmdname> is the name of
the command which may be issued to the UPS.
For example the command: LIST CMD su700 and the response:
Price Expires 1 July 2022 [Page 18]
Internet-Draft UPS management protocol December 2021
BEGIN LIST CMD su700
CMD su700 load.on
CMD su700 test.panel.start
...
END LIST CMD su700
4.2.7.3. LIST ENUM
The command calls for the Attachment Daemon (2.1) to report the set
of possible values of a UPS variable (2.12) which has predetermined
values.
Command: LIST ENUM <upsname> <varname>
The response is:
BEGIN LIST ENUM <upsname> <varname>
ENUM <upsname> <varname> "<value>"
...
END LIST ENUM <upsname> <varname>
where <upsname> is the name of the UPS, <varname> is the UPS variable
(2.12) and <value> is one of the possible values of that UPS variable
(2.12). Note that in current practice the output is an unordered
list. Note also that the U+0022 QUOTATION MARK characters are part
of the response.
For example the command: LIST ENUM su700 input.transfer.low and the
response:
BEGIN LIST ENUM su700 input.transfer.low
ENUM su700 input.transfer.low "103"
ENUM su700 input.transfer.low "100"
...
END LIST ENUM su700 input.transfer.low
4.2.7.4. LIST RANGE
The command calls for the Attachment Daemon (2.1) to report the
interval in which valid values of UPS variable (2.12) lie.
Command: LIST RANGE <upsname> <varname>
The response is:
Price Expires 1 July 2022 [Page 19]
Internet-Draft UPS management protocol December 2021
BEGIN LIST RANGE <upsname> <varname>
RANGE <upsname> <varname> "<min>" "<max>"
...
END LIST RANGE <upsname> <varname>
where <upsname> is the name of the UPS, <varname> is the UPS variable
(2.12) and {<min>,<max>} is the interval of valid values of that UPS
variable (2.12). Note that the U+0022 QUOTATION MARK characters are
part of the response.
For example, the command LIST RANGE su700 input.transfer.low and the
response:
BEGIN LIST RANGE su700 input.transfer.low
RANGE su700 input.transfer.low "90" "105"
END LIST RANGE su700 input.transfer.low
4.2.7.5. LIST RW
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).
Command: LIST RW <upsname>
The response is:
BEGIN LIST RW <upsname>
RW <upsname> <varname> "<value>"
...
END LIST RW <upsname>
where <upsname> is the name of the UPS, <varname> is the UPS variable
(2.12) and <value> is the value of that UPS variable (2.12). Note
that the U+0022 QUOTATION MARK characters are part of the response.
For example the command: LIST RW su700 and the response:
BEGIN LIST RW su700
RW su700 output.voltage.nominal "115"
RW su700 ups.delay.shutdown "020"
...
END LIST RW su700
Price Expires 1 July 2022 [Page 20]
Internet-Draft UPS management protocol December 2021
4.2.7.6. LIST UPS
The command calls for the Attachment Daemon (2.1) to report a list of
the UPS units to which it is attached.
Command: LIST UPS
The response is:
BEGIN LIST UPS
UPS <upsname> "<description>"
...
END LIST UPS
where <upsname> is the name of a UPS, and <description> is the
description maintained by the Attachment Daemon (2.1) if available.
It is set to "Unavailable" otherwise. Note that the U+0022 QUOTATION
MARK characters are part of the response.
This command can also be used to determine what values of <upsname>
are valid before calling other functions on the server. This is also
a good way to handle situations where a single Attachment Daemon
(2.1) supports multiple UPS's. It is also useful for clients which
perform a UPS discovery process.
For example, the response:
BEGIN LIST UPS
UPS su700 "Development box"
END LIST UPS
4.2.7.7. LIST VAR
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.
Command: LIST VAR <upsname>
The response is:
BEGIN LIST VAR <upsname>
VAR <upsname> <varname> "<value>"
...
END LIST VAR <upsname>
Price Expires 1 July 2022 [Page 21]
Internet-Draft UPS management protocol December 2021
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
4.2.8. PASSWORD
This command is a companion to USERNAME (4.2.13), and is used by a
Management Daemon (2.6) to specify the password required to enter a
Session (2.10) with the Attachment Daemon (2.1).
Command: PASSWORD <password>
If the command succeeds, the response is OK, otherwise see the error
responses (4.3.2).
For examples of the use of commands USERNAME (4.2.13) and PASSWORD by
administrative users (2.2) see Section 6.5.2, Paragraph 1.
4.2.9. PRIMARY
In current practice, an administrative user (2.2) is recorded by the
Attachment Daemon (2.1) in local file upsd.users as being a Primary
(2.8). See Management of Administrative Users (6.5.1) for an
example. When a Management Daemon (2.6) starts up and opens a
Session (2.10) with the Attachment Daemon (2.1), it lays claim to
being a Primary (2.8) by sending command PRIMARY to the Attachment
Daemon (2.1), thus claiming that it has the required authority to
perform such critical actions as setting status symbol FSD.
Command: PRIMARY <upsname>
where <upsname> is the name of the UPS.
If the Attachment Daemon (2.1) has the authority, the response is OK,
otherwise see the error responses (4.3.2).
Note: Historically, this command was known as MASTER.
Price Expires 1 July 2022 [Page 22]
Internet-Draft UPS management protocol December 2021
4.2.10. PROTVER
Return the implementation version of the command/response protocol
used by the Attachment Daemon (2.1). This command is intended for
human as well as program use.
Command PROTVER
For example, the following command line sequence in the Attachment
Daemon (2.1):
netcat localhost 3493
PROTVER
1.2
Notes:
1. There are no U+0022 QUOTATION MARK characters in the response.
2. Historically, this command was known as NETVER and current
practice is to use NETVER instead of PROTVER.
3. 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).
4.2.11. SET
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.
Command: SET VAR <upsname> <varname> "<value>"
where <upsname> is the name of the UPS, <varname> is the UPS variable
(2.12) and <value> is the value to be assigned to that variable.
Note that the U+0022 QUOTATION MARK characters are part of the
command.
If the command succeeds, the response is OK, otherwise see the error
responses (4.3.2).
For example the command: SET VAR su700 ups.id "My UPS" and the
response OK
Price Expires 1 July 2022 [Page 23]
Internet-Draft UPS management protocol December 2021
4.2.12. STARTTLS
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.
Command: STARTTLS
If the command succeeds, the response is OK STARTTLS, otherwise see
the error responses (4.3.2).
4.2.13. USERNAME
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.
Command: USERNAME <username>
If the command succeeds, the response is OK, otherwise see the error
responses (4.3.2).
For examples of the use of commands USERNAME and PASSWORD (4.2.8) by
administrative users (2.2) see Section 6.5.2, Paragraph 1.
4.2.14. VER
Return the implementation version of the Attachment Daemon (2.1).
This command is intended for human as well as program use.
Command VER
For example, the following command line sequence:
netcat localhost 3493
VER
Network UPS Tools upsd 2.7.4 - http://www.networkupstools.org/
Notes:
1. There are no U+0022 QUOTATION MARK characters in the response.
Price Expires 1 July 2022 [Page 24]
Internet-Draft UPS management protocol December 2021
2. The implementation version of the Attachment Daemon (2.1)
returned by VER is different to the protocol version returned by
PROTVER (4.2.10).
4.3. Summary of Responses
4.3.1. Response when Command Succeeds
If the command succeeds, the response has the following command-
dependent form:
+===================+======================+============+
| Command | Response | Note |
+===================+======================+============+
| ATTACH (4.2.1) | OK | Was LOGIN |
+-------------------+----------------------+------------+
| DETACH (4.2.2) | OK Goodbye | Was LOGOUT |
+-------------------+----------------------+------------+
| FSD (4.2.3) | OK FSD-SET | |
+-------------------+----------------------+------------+
| GET (4.2.4) | Sub command specific | |
+-------------------+----------------------+------------+
| HELP (4.2.5) | List of commands | |
+-------------------+----------------------+------------+
| INSTCMD (4.2.6) | OK | |
+-------------------+----------------------+------------+
| LIST (4.2.7) | Sub command specific | |
+-------------------+----------------------+------------+
| PASSWORD (4.2.8) | OK | |
+-------------------+----------------------+------------+
| PRIMARY (4.2.9) | OK | |
+-------------------+----------------------+------------+
| PROTVER (4.2.10) | Protocol version | Was NETVER |
+-------------------+----------------------+------------+
| SET (4.2.11) | OK | |
+-------------------+----------------------+------------+
| STARTTLS (4.2.12) | OK STARTTLS | |
+-------------------+----------------------+------------+
| USERNAME (4.2.13) | OK | |
+-------------------+----------------------+------------+
| VER (4.2.14) | Program version | |
+-------------------+----------------------+------------+
Table 2: Response if command succeeds
Price Expires 1 July 2022 [Page 25]
Internet-Draft UPS management protocol December 2021
4.3.2. Error Responses
Error responses have the following format:
ERR <error-name> [<extra>]
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 error name token | Meaning |
| <error-name> | |
+==============================+=================================+
| ACCESS-DENIED | The client's host and/or |
| | authentication details |
| | (username, password) are not |
| | sufficient to execute the |
| | requested command. |
+------------------------------+---------------------------------+
| ALREADY-ATTACHED | The client has already sent a |
| | successful ATTACH (4.2.1) |
| | command for a given UPS and |
| | can't do it again. |
| | |
| | Note: Historically, this error |
| | response was ALREADY-LOGGED-IN. |
+------------------------------+---------------------------------+
| ALREADY-SET-PASSWORD | The client has already supplied |
| | a PASSWORD and is attempting to |
| | repeat the command in the same |
| | Session (2.10). |
+------------------------------+---------------------------------+
| ALREADY-SET-USERNAME | The client has already supplied |
| | a USERNAME, and is attempting |
| | to repeat the command within |
| | the same Session (2.10). |
+------------------------------+---------------------------------+
| CMD-NOT-SUPPORTED | The specified UPS doesn't |
| | support the instant command |
| | (2.5) command. |
+------------------------------+---------------------------------+
| DATA-STALE | The Attachment Daemon (2.1) is |
| | connected to the Driver (2.3) |
Price Expires 1 July 2022 [Page 26]
Internet-Draft UPS management protocol December 2021
| | 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. |
Price Expires 1 July 2022 [Page 27]
Internet-Draft UPS management protocol December 2021
+------------------------------+---------------------------------+
| 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) |
Price Expires 1 July 2022 [Page 28]
Internet-Draft UPS management protocol December 2021
| | 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. |
+------------------------------+---------------------------------+
| UNKNOWN-COMMAND | The Attachment Daemon (2.1) |
| | doesn't recognize the command. |
+------------------------------+---------------------------------+
| UNKNOWN-UPS | 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. |
+------------------------------+---------------------------------+
Table 3: Error responses
5. Statuses and Events
5.1. Status Symbols
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.
Price Expires 1 July 2022 [Page 29]
Internet-Draft UPS management protocol December 2021
+=========+======================================================+
| Status | Meaning |
| Symbol | |
+=========+======================================================+
| ALARM | The UPS reports that it requires intervention. |
+---------+------------------------------------------------------+
| BOOST | 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. |
+---------+------------------------------------------------------+
| COMM | The Attachment Daemon (2.1) 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 (2.1) has no effective contact |
| | with the UPS. |
+---------+------------------------------------------------------+
| OB | 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. |
Price Expires 1 July 2022 [Page 30]
Internet-Draft UPS management protocol December 2021
+---------+------------------------------------------------------+
| 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. |
+---------+------------------------------------------------------+
Table 4: UPS Status Symbols
5.2. Events
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.
Price Expires 1 July 2022 [Page 31]
Internet-Draft UPS management protocol December 2021
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.
+=======+=========+===============++=========+========+=============+
|Old | New |Event || Old | New |Event |
|status | status | || status | status | |
+=======+=========+===============++=========+========+=============+
|none | ALARM |Alarm on || ALARM | none |Alarm off |
+-------+---------+---------------++---------+--------+-------------+
|none | BOOST |Boosting || BOOST | none |Not boosting |
| | |voltage || | | |
+-------+---------+---------------++---------+--------+-------------+
|none | BYPASS |Bypass on || BYPASS | none |Bypass off |
+-------+---------+---------------++---------+--------+-------------+
|none | CAL |Calibrating || CAL | none |Not |
| | | || | |calibrating |
+-------+---------+---------------++---------+--------+-------------+
|none | CHRG |Charging || CHRG | none |Not charging |
+-------+---------+---------------++---------+--------+-------------+
|none | COMM |UPS || COMM | none |See note 4 |
| | |communicating || | | |
| | |(COMMOK) || | | |
+-------+---------+---------------++---------+--------+-------------+
|none | DISCHRG |Discharging || DISCHRG | none |Not |
| | | || | |discharging |
+-------+---------+---------------++---------+--------+-------------+
|none | FSD |System shutdown|| FSD | none |Shutdown |
| | |(FSD) || | |abandoned. |
| | |(SHUTDOWN) || | |See note 1 |
+-------+---------+---------------++---------+--------+-------------+
|none | LB |Low battery. || LB | none |Battery not |
| | |See note 2 || | |low |
| | |(LOWBATT) || | | |
+-------+---------+---------------++---------+--------+-------------+
|none | NOCOMM |UPS dead? See || NOCOMM | none |See note 4 |
| | |note 4 || | | |
| | |(COMMBAD) || | | |
| | |(NOCOMM) || | | |
+-------+---------+---------------++---------+--------+-------------+
|none | OFF |UPS turned off || OFF | none |UPS not |
| | | || | |turned off |
+-------+---------+---------------++---------+--------+-------------+
|OB | OL |Receiving wall || OL | OB |Wall power |
| | |power || | |lost |
Price Expires 1 July 2022 [Page 32]
Internet-Draft UPS management protocol December 2021
| | |(ONLINE) || | |(ONBATT) |
+-------+---------+---------------++---------+--------+-------------+
|none | OVER |UPS overloaded || OVER | none |Overload gone|
+-------+---------+---------------++---------+--------+-------------+
|none | RB |Replace battery|| RB | none |Replacement |
| | |(REPLBATT) || | |canceled |
+-------+---------+---------------++---------+--------+-------------+
|none | TEST |Test starts || TEST | none |Test finished|
+-------+---------+---------------++---------+--------+-------------+
|none | TICK |Heartbeat || TICK | none |No heartbeat.|
| | |event. See || | |See note 3 |
| | |note 3 || | | |
+-------+---------+---------------++---------+--------+-------------+
|none | TOCK |Heartbeat || TOCK | none |No heartbeat.|
| | |event. See || | |See note 3 |
| | |note 3 || | | |
+-------+---------+---------------++---------+--------+-------------+
|none | TRIM |Trimming || TRIM | none |Not trimming |
| | |voltage || | | |
+-------+---------+---------------++---------+--------+-------------+
Table 5: Event deduction from status changes
Notes
1. Current practice does not include this event.
2. 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.
3. The use of a software defined UPS to provide a heartbeat is
experimental and is not part of common current practice.
4. 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.
6. Security Considerations
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.
Quoting from IEC 62351-1 clause 5.2.3.5 [IEC62351-1]:
| 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
Price Expires 1 July 2022 [Page 33]
Internet-Draft UPS management protocol December 2021
| clearly seen from these Subclauses, this may not be true anymore
| as networking becomes more prevalent and additional information
| access requirements grow.
Clause 5.3.5 [IEC62351-1] lists the typical security attacks:
| Eavesdropping, Masquerade, Man-in-the-Middle, Replay, Resource
| Exhaustion
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:
1. 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).
2. It should not be possible to intercept the traffic between the
Attachment Daemon (2.1) and the Management Daemon (2.6).
Let's look more closely at these requirements.
6.1. Agent Verification
The protocol provides commands USERNAME (4.2.13) and PASSWORD (4.2.8)
which allow an administrative user (2.2) in a Management Daemon (2.6)
to authenticate itself to the Attachment Daemon (2.1). The
administrative user (2.2) name and password need protection from
sniffing: this is done by encrypting the traffic.
6.2. Current Encryption Practice
The protocol provides command STARTTLS (4.2.12) which calls on the
Attachment Daemon (2.1) to support TLS encryption of the
communication. If this command is accepted, the Management Daemon
(2.6) also encrypts.
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.
Price Expires 1 July 2022 [Page 34]
Internet-Draft UPS management protocol December 2021
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.
A further weakness is that the FORCESSL and CERTVERIFY declarations
are in the Management Daemon (2.6) configuration file and not in the
Attachment Daemon (2.1). Secure practice requires enforcement by the
Attachment Daemon (2.1) rather than a possibly rogue Management
Daemon (2.6) out on the Internet.
6.2.1. Secure Tunnels
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.
6.3. Current General Security Practice
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
Figure 5: Common single-system configuration
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.
Price Expires 1 July 2022 [Page 35]
Internet-Draft UPS management protocol December 2021
,-----,------------, ,--------------,
| UPS - Attachment | <-Commands | Management |
| | Daemon | Responses-> | Daemon |
/-----'------------\ '--------------'
Listens on
port nut/3493
Figure 6: Integration of UPS and Attachment Daemon
6.4. Security Needs
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.
6.4.1. Shims
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
Figure 7: Shims provide TLS support during migration
6.4.1.1. Attachment Daemon Shim
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
1. Returns OK to the client and sets up TLS encapsulation.
Price Expires 1 July 2022 [Page 36]
Internet-Draft UPS management protocol December 2021
2. Does not send STARTTLS (4.2.12) to the Attachment Daemon (2.1)
port nut/3493.
All other commands and responses are passed through.
6.4.1.2. Management Daemon Shim
The shim in front of the Management Daemon (2.6) listens for incoming
traffic on port nut/3493. When it receives the command STARTTLS
(4.2.12) it
1. Returns FEATURE-NOT-CONFIGURED to the client.
2. Sends STARTTLS (4.2.12) to the Attachment Daemon (2.1) on a port
to be specified.
All other commands and responses are passed through.
6.4.2. SSH Tunnels
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).
6.4.3. VPN
A further option to secure communications is very similar to SSH
tunnelling and consists of routing the NUT traffic through a VPN.
| Since NUT uses the TCP protocol exclusively, this VPN can use
| ISO network layer three TUN devices and does not require layer
| two TAP devices.
6.4.4. VLAN
A fourth option is to isolate the UPS management traffic at the
network switching level using a VLAN technique.
Price Expires 1 July 2022 [Page 37]
Internet-Draft UPS management protocol December 2021
,-------------, ,-------------,
,-----, | Attachment | | Management |
| UPS |---| Daemon | | Daemon |
| | |-------------| UPS |-------------|
| |===| | Management | UPS |
/-----\ | Protected |---------------| Management |
| Server | VLAN | Client |
| | '-------------'
'-------------'
Production | VLAN
,---|-------,
,-----------,|
,-----------,|'
| Clients |'
'-----------'
Figure 8: UPS Management Protocol runs over its own VLAN
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.
6.4.5. Long Term: Enforced Secure Communication
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:
1. SHOULD require and accept command STARTTLS (4.2.12),
2. MUST encrypt all communication with a Management Daemon (2.6),
3. SHALL refuse all non-encrypted commands except an initial
STARTTLS (4.2.12).
Notes:
* 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.
Price Expires 1 July 2022 [Page 38]
Internet-Draft UPS management protocol December 2021
* 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.
6.5. Administrative Security
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.
6.5.1. Management of Administrative Users
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.
For example the following file declares two administrative users
(2.2) admin and pfy:
[admin]
password = sekret
upsmon master
actions = SET
instcmds = ALL
[pfy]
password = sekret
instcmds = test.panel.start
instcmds = test.panel.stop
Within each section the administrative user (2.2) declarations are:
Price Expires 1 July 2022 [Page 39]
Internet-Draft UPS management protocol December 2021
+=============+==========================================+
| Declaration | Meaning |
+=============+==========================================+
| actions | 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). |
| | |
| | * SET Change the value of a UPS |
| | variable (2.12). See SET (4.2.11). |
+-------------+------------------------------------------+
| instcmds | 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 |
| | =. |
+-------------+------------------------------------------+
Table 6: Administrative user declarations
6.5.2. An Administrative User of a Client Management Daemon
The following examples show the current security practices for
administrative users (2.2) of a client Management Daemon (2.6) They
also illustrate the command pair USERNAME (4.2.13) and PASSWORD
(4.2.8).
Price Expires 1 July 2022 [Page 40]
Internet-Draft UPS management protocol December 2021
6.5.2.1. An Administrative User Logs into a Short Session
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).
upsrw -s battery.charge.low=35 -u admin -p sekret UPS-1@example.com
The USERNAME (4.2.13) and PASSWORD (4.2.8) commands are issued within
the client upsrw and the Session (2.10) is of short duration.
6.5.2.2. An Administrative User Logs into a Long Session
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
MONITOR UPS-1@example.com 1 admin secret master
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.
The USERNAME (4.2.13) and PASSWORD (4.2.8) commands are contained
within the client upsmon and the Session (2.10) is of long duration.
7. Codepoint Management
This document raises five matters of codepoint management:
1. The namespaces occupied by the protocol commands (4.2) described
in this document.
2. The namespaces occupied by the protocol responses (4.3.2)
described in this document.
3. The namespace occupied by UPS status (2.11) names,
4. The namespace occupied by UPS variable (2.12) names,
5. The port name and port number used to manage UPS units.
Price Expires 1 July 2022 [Page 41]
Internet-Draft UPS management protocol December 2021
7.1. Namespaces used by Command, Responses, Statuses and Variables
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:
+========================+====================+===================+
| Namespace | Recording document | Reference |
+========================+====================+===================+
| Commands and Responses | This document | Commands (4.2), |
| | | Responses (4.3) |
+------------------------+--------------------+-------------------+
| (Idem, historical | Project Developer | Developer Guide |
| record) | Guide Ch 9 | [devguide] |
+------------------------+--------------------+-------------------+
| Statuses | This document | Statuses (5.1) |
+------------------------+--------------------+-------------------+
| (Idem, historical | Source code | GitHub repository |
| record) | clients/status.h | [gitstats] |
+------------------------+--------------------+-------------------+
| Variables | Source code file | GitHub repository |
| | docs/nut-names.txt | [gitvars] |
+------------------------+--------------------+-------------------+
Table 7: Project records of namespace allocation
7.2. Port Name and Number used to Manage UPS Units
See the IANA Registry [Registry] for the latest situation.
7.2.1. Port nut/3493
In 2002 IANA assigned port nut/3493 to project lead Russell Kroll,
and updated the assignment to the NUT Project (2.7) itself in 2020.
Price Expires 1 July 2022 [Page 42]
Internet-Draft UPS management protocol December 2021
7.2.2. Port ups/401
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
7.2.3. NUT Project Requirement
The NUT Project (2.7) needs to address the current weak security
(6.3) of UPS management deployments, for example
* by implementing the "shim" technique (Figure 7) in section (6.4)
for providing secure access to the Attachment Daemon (2.1),
* 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".
Price Expires 1 July 2022 [Page 43]
Internet-Draft UPS management protocol December 2021
8. IANA Considerations
8.1. Port Name ups: Reference to this Document
The NUT Project (2.7) has a requirement to use a second port (7.2.3),
and would like to use port name ups as well as port nut. The project
requests that IANA authorise such use, perhaps by updating the
Service Name and Transport Protocol Port Number Registry [Registry]
for ports ups and nut/3493 to include a reference to this document.
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.
8.2. Change of Registrant
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.
9. Implementation Status
This section presents a very short report on the status of the
Network UPS tools project
* May 1996: The first hack as a cron job.
* September 1997: The first server-client code.
* March 1998: First public release.
* June 1999: Code rewrite with a UPS driver smartups, an Attachment
Daemon (2.1) upsd and a simple Management Daemon (2.6).
* September 1999: The project became "Network UPS Tools". The
Management Daemon (2.6) upsmon supported primary/secondary
configurations.
* June 2001: Common core for multiple drivers. Arnaud Quette took
over the project lead from Russell Kroll.
* May 2002: IANA granted port nut/3493. August: release 1.0.0.
November: OpenSSL support.
* April 2003: The initial set of command and variable names was
designed.
* March 2016: Version 2.7.4 released, supported over 100 device
manufacturers and hundreds of UPS models.
Price Expires 1 July 2022 [Page 44]
Internet-Draft UPS management protocol December 2021
* November 2020: Evgeny "Jim" Klimov took over project lead from
Arnaud Quette.
For a much more detailed history of the NUT Project (2.7) see the
User Manual, Appendix J [History]
9.1. An Implementation of the Attachment Daemon
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.
9.2. An Implementations of the Management Daemon
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.
Other programs representing the Management Daemon (2.6):
* upsc reported the values of the variables (8) defined for a given
UPS.
* upsrw reported on and changed the values of the readable and
writable configuration variables (A.2) defined for a given UPS.
* upscmd reported on and executed the instant action commands
(4.2.6) defined for a given UPS.
* UPSmon.py was an experimental Python3 rewrite of upsmon and
upssched which included support for TLS 1.3 [RFC8446].
9.3. Inclusion in Software Distributions
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.
Price Expires 1 July 2022 [Page 45]
Internet-Draft UPS management protocol December 2021
10. Acknowledgments
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.
11. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
12. Informative References
[Bennett] "Charles Bennett Obituary", Publisher: Jagers and Sons
Funeral Home, 24 Morris Ave., Athens OH,
<https://www.legacy.com/obituaries/name/charles-bennett-
obituary?pid=174356861>.
[devguide] "Network UPS Tools (NUT) Project Developer Guide",
<https://networkupstools.org/docs/developer-guide.chunked/
ar01s09.html>.
[Documentation]
"Network UPS Tools Documentation",
<https://networkupstools.org/documentation.html>.
[gitstats] "GitHub Network UPS Tools code repository, status names",
<https://github.com/networkupstools/nut/blob/master/
clients/status.h>.
Price Expires 1 July 2022 [Page 46]
Internet-Draft UPS management protocol December 2021
[gitvars] "GitHub Network UPS Tools code repository, variable
names",
<https://github.com/networkupstools/nut/blob/master/docs/
nut-names.txt>.
[History] "Network UPS Tools User Manual, Appendix J Project
history",
<https://networkupstools.org/docs/user-manual.pdf>.
[HyTimeA] "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, 1997.
[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, 15 May
2007, <https://nanopdf.com/download/technical-iec-
specification-ts-62351-1_pdf>.
[Library] "GitHub Network UPS Tools, Devices Dumps Library",
<https://networkupstools.org/ddl/>.
[NUT] "Network UPS Tools (NUT) Project",
<https://www.networkupstools.org>.
[nut-upsdev]
"Network UPS Tools (NUT) Project Mailing List for
developers", <https://alioth-lists.debian.net/cgi-
bin/mailman/listinfo/nut-upsdev>.
[nut-upsuser]
"Network UPS Tools (NUT) Project Mailing List for users",
<https://alioth-lists.debian.net/cgi-bin/mailman/listinfo/
nut-upsuser>.
[Registry] "Service Name and Transport Protocol Port Number
Registry", Publisher: IANA,
<https://www.iana.org/assignments/service-names-port-
numbers/service-names-port-numbers.xhtml>.
Price Expires 1 July 2022 [Page 47]
Internet-Draft UPS management protocol December 2021
[RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running
Code: The Implementation Status Section", BCP 205,
RFC 7942, DOI 10.17487/RFC7942, July 2016,
<https://www.rfc-editor.org/info/rfc7942>.
[RFC7991] Hoffman, P., "The "xml2rfc" Version 3 Vocabulary",
RFC 7991, December 2016,
<https://www.rfc-editor.org/info/rfc7991>.
[RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol
Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
<https://www.rfc-editor.org/info/rfc8446>.
[SGML] Goldfarb, Charles F., "The SGML Handbook",
ISBN 0-19-853737-9, 1990.
[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/>.
Appendix A. Variables
The UPS variables (2.12) 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 (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 (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.
An implementation of a Management Daemon (2.6) 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 (9.2).
Price Expires 1 July 2022 [Page 48]
Internet-Draft UPS management protocol December 2021
The following sections illustrate the use of variables by taking the
values associated with a typical product example of a 1600Va 1000W
UPS.
A.1. Typical UPS Variables
+===============================+============+====================+
| Variable | Typical | Default |
| | value | description |
+===============================+============+====================+
| battery.charge | 100 | "Battery charge |
| | | (percent of full)" |
+-------------------------------+------------+--------------------+
| battery.charge.low | 20 | "Remaining battery |
| | | level when UPS |
| | | switches to LB |
| | | (percent)" |
+-------------------------------+------------+--------------------+
| battery.runtime | 1481 | "Battery runtime |
| | | (seconds)" |
+-------------------------------+------------+--------------------+
| battery.type | PbAc | "Battery |
| | | chemistry" |
+-------------------------------+------------+--------------------+
| device.mfr | Example | "" |
| | Mfg | |
+-------------------------------+------------+--------------------+
| device.model | Economy | "" |
| | 1600 | |
+-------------------------------+------------+--------------------+
| device.serial | 1234567890 | "" |
+-------------------------------+------------+--------------------+
| device.type | ups | "" |
+-------------------------------+------------+--------------------+
| driver.name | usbhid-ups | "Driver name" |
+-------------------------------+------------+--------------------+
| driver.parameter.lowbatt | 37 | "Driver parameter: |
| | | <name>" |
+-------------------------------+------------+--------------------+
| driver.parameter.offdelay | 30 | "Driver parameter: |
| | | <name>" |
+-------------------------------+------------+--------------------+
| driver.parameter.ondelay | 40 | "Driver parameter: |
| | | <name>" |
+-------------------------------+------------+--------------------+
| driver.parameter.pollfreq | 30 | "Driver parameter: |
| | | <name>" |
+-------------------------------+------------+--------------------+
Price Expires 1 July 2022 [Page 49]
Internet-Draft UPS management protocol December 2021
| driver.parameter.pollinterval | 2 | "Driver parameter: |
| | | <name>" |
+-------------------------------+------------+--------------------+
| driver.parameter.port | auto | "Driver parameter: |
| | | <name>" |
+-------------------------------+------------+--------------------+
| driver.parameter.synchronous | no | "Driver parameter: |
| | | <name>" |
+-------------------------------+------------+--------------------+
| driver.parameter.vendorid | 0999 | "Driver parameter: |
| | | <name>" |
+-------------------------------+------------+--------------------+
| driver.version | 2.7.4 | "Driver version - |
| | | NUT release" |
+-------------------------------+------------+--------------------+
| driver.version.data | HID 1.39 | "" |
+-------------------------------+------------+--------------------+
| driver.version.internal | 0.41 | "Internal driver |
| | | version" |
+-------------------------------+------------+--------------------+
| input.transfer.high | 264 | "High voltage |
| | | transfer point |
| | | (V)" |
+-------------------------------+------------+--------------------+
| input.transfer.low | 184 | "Low voltage |
| | | transfer point |
| | | (V)" |
+-------------------------------+------------+--------------------+
| outlet.1.desc | PowerShare | "Outlet |
| | Outlet 1 | description" |
+-------------------------------+------------+--------------------+
| outlet.1.id | 2 | "Outlet system |
| | | identifier" |
+-------------------------------+------------+--------------------+
| outlet.1.status | on | "Outlet switch |
| | | status" |
+-------------------------------+------------+--------------------+
| outlet.1.switchable | no | "Outlet switch |
| | | ability" |
+-------------------------------+------------+--------------------+
| outlet.2.desc | PowerShare | "Outlet |
| | Outlet 2 | description" |
+-------------------------------+------------+--------------------+
| outlet.2.id | 3 | "Outlet system |
| | | identifier" |
+-------------------------------+------------+--------------------+
| outlet.2.status | on | "Outlet switch |
| | | status" |
Price Expires 1 July 2022 [Page 50]
Internet-Draft UPS management protocol December 2021
+-------------------------------+------------+--------------------+
| outlet.2.switchable | no | "Outlet switch |
| | | ability" |
+-------------------------------+------------+--------------------+
| outlet.desc | Main | "Outlet |
| | Outlet | description" |
+-------------------------------+------------+--------------------+
| outlet.id | 1 | "Outlet system |
| | | identifier" |
+-------------------------------+------------+--------------------+
| outlet.power | 25 | "" |
+-------------------------------+------------+--------------------+
| outlet.switchable | no | "Outlet switch |
| | | ability" |
+-------------------------------+------------+--------------------+
| output.frequency.nominal | 50 | "Nominal output |
| | | frequency (Hz)" |
+-------------------------------+------------+--------------------+
| output.voltage | 230.0 | "Output voltage |
| | | (V)" |
+-------------------------------+------------+--------------------+
| output.voltage.nominal | 230 | "Nominal output |
| | | voltage (V)" |
+-------------------------------+------------+--------------------+
| ups.beeper.status | enabled | "UPS beeper |
| | | status" |
+-------------------------------+------------+--------------------+
| ups.delay.shutdown | 20 | "Interval to wait |
| | | after shutdown |
| | | with delay command |
| | | (seconds)" |
+-------------------------------+------------+--------------------+
| ups.delay.start | 30 | "Interval to wait |
| | | before |
| | | (re)starting the |
| | | load (seconds)" |
+-------------------------------+------------+--------------------+
| ups.firmware | 02 | "UPS firmware" |
+-------------------------------+------------+--------------------+
| ups.load | 20 | "Load on UPS |
| | | (percent of full)" |
+-------------------------------+------------+--------------------+
| ups.mfr | Example | "UPS manufacturer" |
| | Mfg | |
+-------------------------------+------------+--------------------+
| ups.model | Economy | "UPS model" |
| | 1600 | |
+-------------------------------+------------+--------------------+
Price Expires 1 July 2022 [Page 51]
Internet-Draft UPS management protocol December 2021
| ups.power.nominal | 1600 | "UPS power rating |
| | | (VA)" |
+-------------------------------+------------+--------------------+
| ups.productid | ffff | "Product ID for |
| | | USB devices" |
+-------------------------------+------------+--------------------+
| ups.serial | 000000000 | "UPS serial |
| | | number" |
+-------------------------------+------------+--------------------+
| ups.status | OL | "UPS status" |
+-------------------------------+------------+--------------------+
| ups.timer.shutdown | 0 | "Time before the |
| | | load will be |
| | | shutdown |
| | | (seconds)" |
+-------------------------------+------------+--------------------+
| ups.timer.start | 0 | "Time before the |
| | | load will be |
| | | started (seconds)" |
+-------------------------------+------------+--------------------+
| ups.vendorid | 0999 | "Vendor ID for USB |
| | | devices" |
+-------------------------------+------------+--------------------+
Table 8: Typical UPS Variables
A.2. Typical UPS Readable and Writable Variables
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 upsrw as included in the
NUT package (9.2).
Price Expires 1 July 2022 [Page 52]
Internet-Draft UPS management protocol December 2021
+========================+============+=========================+
| Variable | Typical | Default description |
| | value | provided as response to |
| | | the command GET DESC |
+========================+============+=========================+
| battery.charge.low | 20 | "Remaining battery |
| | | level when UPS switches |
| | | to LB (percent)" |
+------------------------+------------+-------------------------+
| input.transfer.high | 264 | "High voltage transfer |
| | | point (V)" |
+------------------------+------------+-------------------------+
| input.transfer.low | 184 | "Low voltage transfer |
| | | point (V)" |
+------------------------+------------+-------------------------+
| outlet.1.desc | PowerShare | "Outlet description" |
| | Outlet 1 | |
+------------------------+------------+-------------------------+
| outlet.2.desc | PowerShare | "Outlet description" |
| | Outlet 2 | |
+------------------------+------------+-------------------------+
| outlet.2.switchable | no | "Outlet switch ability" |
+------------------------+------------+-------------------------+
| outlet.desc | Main | "Outlet description" |
| | Outlet | |
+------------------------+------------+-------------------------+
| outlet.power | 25 | "Description |
| | | unavailable" |
+------------------------+------------+-------------------------+
| output.voltage.nominal | 230 | "Nominal output voltage |
| | | (V)" |
+------------------------+------------+-------------------------+
| ups.delay.shutdown | 20 | "Interval to wait after |
| | | shutdown with delay |
| | | command (seconds)" |
+------------------------+------------+-------------------------+
| ups.delay.start | 30 | "Interval to wait |
| | | before (re)starting the |
| | | load (seconds)" |
+------------------------+------------+-------------------------+
Table 9: Typical readable and writable UPS Variables
Price Expires 1 July 2022 [Page 53]
Internet-Draft UPS management protocol December 2021
A.3. Typical UPS Instant Commands
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
upscmd as included in the NUT package (9.2).
+==================+==========================================+
| Command | Meaning |
+==================+==========================================+
| beeper.disable | Disable the UPS beeper |
+------------------+------------------------------------------+
| beeper.enable | Enable the UPS beeper |
+------------------+------------------------------------------+
| beeper.mute | Temporarily mute the UPS beeper |
+------------------+------------------------------------------+
| load.off | Turn off the load immediately |
+------------------+------------------------------------------+
| load.off.delay | Turn off the load with a delay (seconds) |
+------------------+------------------------------------------+
| load.on | Turn on the load immediately |
+------------------+------------------------------------------+
| load.on.delay | Turn on the load with a delay (seconds) |
+------------------+------------------------------------------+
| shutdown.return | Turn off the load and return when power |
| | is back |
+------------------+------------------------------------------+
| shutdown.stayoff | Turn off the load and remain off |
+------------------+------------------------------------------+
| shutdown.stop | Stop a shutdown in progress |
+------------------+------------------------------------------+
Table 10: Typical Instant Commands
Appendix B. The Shutdown Story for System and UPS
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.
Price Expires 1 July 2022 [Page 54]
Internet-Draft UPS management protocol December 2021
,------------------SERVER------------------,
| | |
,-----, | UPS <-Commands UPS |
| UPS |---| Attachment | Management |
| |===| Daemon Responses-> Daemon |
/-----\ '--------------------'---------------------'
Internal
loopback
Figure 9: Long-running unattended server
1. _Wall power on_ -- The system runs normally. Every 5 seconds,
variable ups.status reports OL. -- _Days, weeks, months go
by..._
2. _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.
3. The Management Daemon (2.6) logs warning messages. The server
is still operational running on the UPS battery. -- _Minutes go
by..._
4. 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.
5. The Management Daemon (2.6) logs the low battery event.
6. The Management Daemon (2.6) decides to call for a system
shutdown and issues the system shutdown command.
7. 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.
8. The system shuts down and powers down, hopefully before the N=20
seconds have passed.
Price Expires 1 July 2022 [Page 55]
Internet-Draft UPS management protocol December 2021
9. _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..._
10. _Some time later, maybe much later, wall power returns_ -- The
UPS reconnects it's outlets to send power to the protected
system.
11. 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.
12. The operating system starts the Attachment Daemon (2.1) and the
Management Daemon (2.6). The Attachment Daemon (2.1) starts the
Driver (2.3) and scans the UPS. The UPS status becomes OL+LB.
13. 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.
Appendix C. Technical Terms: Historical Differences
This appendix lists the major differences between the technical terms
used in this document and those used in version 2.7.4 of the NUT
Project (2.7).
Price Expires 1 July 2022 [Page 56]
Internet-Draft UPS management protocol December 2021
+===================+===============================+
| Term in NUT 2.7.4 | Term in this document |
+===================+===============================+
| ALREADY-LOGGED-IN | ALREADY-ATTACHED (Table 3) |
+-------------------+-------------------------------+
| ALREADY-SSL-MODE | TLS-ALREADY-ENABLED (Table 3) |
+-------------------+-------------------------------+
| LOGIN | ATTACH (4.2.1) |
+-------------------+-------------------------------+
| LOGOUT | DETACH (4.2.2) |
+-------------------+-------------------------------+
| Master | Primary (2.8) |
+-------------------+-------------------------------+
| NETVER | PROTVER (4.2.10) |
+-------------------+-------------------------------+
| NUMLOGINS | NUMATTACH (4.2.4.3) |
+-------------------+-------------------------------+
| Slave | Secondary (2.9) |
+-------------------+-------------------------------+
Table 11
Appendix D. Change Log
This section is to be removed before publishing as an RFC.
// Ed: To be removed on publication.
D.1. Changes in Version 01
1. There is exactly one newline (4.1) at the end of commands and
responses.
2. Added descriptions to variables in Annex (A).
3. Added clause Events (5.2).
D.2. Changes in Version 02
1. Extended acknowledgments.
2. Added reference to possible use of RFC1628 between driver and
Attachment Daemon (2.1).
3. Clarified response to command LIST CLIENT.
D.3. Changes in Version 03
1. Clarified description of Attachment Daemon (2.1).
2. Added Implementation status section as recommended by RFC 7942
[RFC7942].
Price Expires 1 July 2022 [Page 57]
Internet-Draft UPS management protocol December 2021
3. Rewrote Section 7.2.3, Paragraph 1.
4. Clarified Appendix A, Paragraph 1 as being merely an example of
variables used for a specific UPS product.
5. Added definition of <upsname> in Section 4.2, Paragraph 1.
D.4. Changes in Version 04
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:
1. Section (7) becomes "Codepoint Management".
2. Editorial cleanup. All <aside> elements labelled as notes.
3. Added implementation note to Section 4.2.7, Paragraph 1.
4. Error message ALREADY-SSL-MODE becomes ALREADY-TSL-ENABLED.
5. Added error message TSL-NOT-ENABLED.
6. Typo in clause UPS status (Section 2.11, Paragraph 1).
7. Removed all reference to use of RFC1628 between driver and
Attachment Daemon (2.1).
8. In Section 4.2, Paragraph 1 field [:<port>] is always available
in <upsname>
9. Added technical term administrative user (2.2).
10. Added appendix Technical terms: Historical differences (C)
11. Added table of "successful" responses: Response when command
succeeds (4.3.1)
12. Three commands change name LOGIN -> ATTACH (4.2.1), LOGOUT ->
DETACH (4.2.2) and NUMLOGINS -> NUMATTACH (4.2.4.3).
13. Error message ALREADY-LOGGED-IN becomes ALREADY-ATTACHED.
D.5. Changes in Version 05
This version includes changes made following comments by the
reviewers.
1. Abstract: Change "takes" -> "automates".
2. Abstract: Change "Current practice" -> "Current practice when
this text was written".
3. Abstract: Change "leads to" -> "risks".
4. Section (1.1), Added sentence on use of "public power supply".
5. Section (1.2), Change "shutting down..." -> "performing a
managed shutdown of unattended..."
6. Section (1.4) added link to NUT documentation.
7. Section (2) added "They are listed in alphabetical order."
8. Section (2.1) Change "talks to the UPS" -> "retrieves status
from the UPS and sends commands to it".
Price Expires 1 July 2022 [Page 58]
Internet-Draft UPS management protocol December 2021
9. 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 ..."
10. Section (2.2) Change "Management Daemon (2.6) users." ->
"Management Daemon (2.6) users which authenticate to the
attachment daemon with basic credentials (username and
password)."
11. Section (2.2) Change "... and are defined by a file in the ..."
-> "... and are listed in a text file which is read by the ...".
12. Section (2.2) Added link to Section 6.5.1, Paragraph 1.
13. Section (2.3) Change "specific to the hardware" -> "specific to
the UPS hardware"
14. Section (2.5) Change "causes the hardware" -> "is passed to the
driver and sent to the hardware".
15. Section (2.5) Change "to immediately" -> "without any configured
delay to".
16. Section (2.6) Change "the system reaction to power loss." ->
"orchestrating system-wide actions after a power event."
17. Section (2.7) Title "NUT Project" -> "NUT Software Project".
18. Section (2.8) Change "the system to which the data lead is
connected" -> "the computer running the driver".
19. Section (2.9) Replaced and clarified "data lead" not present
with secondaries.
20. Section (2.10) Change "may open a session" -> "may initiate a
TCP session".
21. Section (2.11) Change "are considered fundamental and are" ->
"MUST be".
22. Section (2.11) Change "other statuses depend" -> "other statuses
are OPTIONAL and depend".
23. Section (2.12) Change "The features" -> "The metrics and
identifiers".
24. Section (2.12) Change "current value attached to that feature"
-> "value representing that metric or identifier".
25. Section (2.12) Added a note: "Note: Some variables are
constants, e.g. battery type, manufacturer."
26. Section (3) Rewrote paragraph to clarify "the Attachment Daemon
and the Management daemon which act as *server* and *client*
respectively."
27. 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."
28. 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."
29. Section (4.1) Added scholarly historical note.
30. Section (4.2) Change "of the port" -> "of the TCP port".
Price Expires 1 July 2022 [Page 59]
Internet-Draft UPS management protocol December 2021
31. 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".
32. Section (4.2.3) Clarify that "FSD" means "Forced Shutdown".
33. Section (4.2.3) Change "only to a high-level" -> "only to a
privileged".
34. Section (4.2.4) Added prefix GET to all the subcommands.
35. Section (4.2.7) Added prefix LIST to all the subcommands.
36. Section (4.2.7) Change "common container" -> "common".
37. Section (4.2.7) Change "then go off and wait for the response"
to "wait".
38. Section (4.2.10) Added note differentiating PROTVER (4.2.10) and
VER (4.2.14).
39. 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."
40. 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."
41. 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."
42. Section (4.2.14) Added note differentiating VER (4.2.14) and
PROTVER (4.2.10).
43. Section (5.1) Change "public supply", "wall power" and "input
supply" -> "input power supply", nine places.
44. Section (5.1) Remove notes from CHRG and DISCHARG.
45. Section (5.1) OB: Removed "offline".
46. Section (5.2) Change "deduces" -> "detects".
47. Section (5.2) Change "valuable resources" -> "compute and
network resources" .
48. Section (5.2) Change "will not have up-to-date information about
the UPS status" -> "risks missing short-lived changes in the UPS
status"
49. Section (6.4) After "imposed by a wave of the hand" added "it
cannot be implemented quickly and without impact to many
deployed systems".
50. Section (6.4.3) Added section.
51. Section (6.4.4) Added section with figure.
52. Section (7.2.3) Added "Note: In Unix-like systems a port with a
number below 1024 is privileged and requires elevated
permissions to manage."
53. Section (8.2) Change "but accepts" -> "but will accept".
54. Appendix (A) Change "domestic" -> "consumer grade".
Price Expires 1 July 2022 [Page 60]
Internet-Draft UPS management protocol December 2021
55. 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._
Author's Address
Roger Price (editor)
Network UPS Tools Project
France
Email: ietf@rogerprice.org
Price Expires 1 July 2022 [Page 61]