rfc9271.original   rfc9271.txt 
IETF R. Price, Ed. Independent Submission R. Price, Ed.
Internet-Draft Network UPS Tools Project Request for Comments: 9271 Network UPS Tools Project
Intended status: Informational 18 May 2022 Category: Informational July 2022
Expires: 19 November 2022 ISSN: 2070-1721
Uninterruptible Power Supply (UPS) Management Protocol -- Commands and Uninterruptible Power Supply (UPS) Management Protocol -- Commands and
Responses Responses
draft-rprice-ups-management-protocol-15
Abstract Abstract
This document describes the command/response protocol currently used This document describes the command/response protocol currently used
in the management of Uninterruptible Power Supply (UPS) units and in the management of Uninterruptible Power Supply (UPS) units and
other power devices often deployed in small offices, and in IT other power devices often deployed in small offices and in IT
installations subject to an erratic public power supply. The UPS installations subject to an erratic public power supply. The UPS
units typically interface to an Attachment Daemon in the system they units typically interface to an Attachment Daemon in the system they
protect. This daemon is in turn polled by a Management Daemon which protect. This daemon is in turn polled by a Management Daemon that
notifies users and system administrators of power supply incidents, notifies users and system administrators of power supply incidents
and automates system shutdown decisions. The commands and responses and automates system shutdown decisions. The commands and responses
described by this document are exchanged between the UPS Attachment described by this document are exchanged between the UPS Attachment
Daemon and the Management Daemon. The practice current when this Daemon and the Management Daemon. The practice current when this
protocol was first developed risks weak security and this is protocol was first developed risks weak security, and this is
addressed in the Security Considerations sections of this document. addressed in the Security Considerations sections of this document.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This document is not an Internet Standards Track specification; it is
provisions of BCP 78 and BCP 79. published for informational purposes.
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 This is a contribution to the RFC Series, independently of any other
and may be updated, replaced, or obsoleted by other documents at any RFC stream. The RFC Editor has chosen to publish this document at
time. It is inappropriate to use Internet-Drafts as reference its discretion and makes no statement about its value for
material or to cite them other than as "work in progress." implementation or deployment. Documents approved for publication by
the RFC Editor are not candidates for any level of Internet Standard;
see Section 2 of RFC 7841.
This Internet-Draft will expire on 19 November 2022. Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
https://www.rfc-editor.org/info/rfc9271.
Copyright Notice Copyright Notice
Copyright (c) 2022 IETF Trust and the persons identified as the Copyright (c) 2022 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/ Provisions Relating to IETF Documents
license-info) in effect on the date of publication of this document. (https://trustee.ietf.org/license-info) in effect on the date of
Please review these documents carefully, as they describe your rights publication of this document. Please review these documents
and restrictions with respect to this document. Code Components carefully, as they describe your rights and restrictions with respect
extracted from this document must include Revised BSD License text as to this document.
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 Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction
1.1. Current Practice . . . . . . . . . . . . . . . . . . . . 4 1.1. Current Practice
1.1.1. NUT Software Project . . . . . . . . . . . . . . . . 4 1.1.1. NUT Project
1.1.2. The "Shutdown Story" . . . . . . . . . . . . . . . . 4 1.1.2. The Shutdown Story
1.1.3. How to Read this Document . . . . . . . . . . . . . . 5 1.1.3. How to Read this Document
1.2. Additional Information . . . . . . . . . . . . . . . . . 5 1.2. Additional Information
1.3. Requirements Language . . . . . . . . . . . . . . . . . . 5 1.3. Requirements Language
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 2. Terminology
2.1. Administrative User . . . . . . . . . . . . . . . . . . . 5 2.1. Administrative User
2.2. Attachment Daemon . . . . . . . . . . . . . . . . . . . . 6 2.2. Attachment Daemon
2.3. Driver . . . . . . . . . . . . . . . . . . . . . . . . . 6 2.3. Driver
2.4. Event . . . . . . . . . . . . . . . . . . . . . . . . . . 6 2.4. Event
2.5. Instant Command . . . . . . . . . . . . . . . . . . . . . 6 2.5. Instant Command
2.6. Management Daemon . . . . . . . . . . . . . . . . . . . . 7 2.6. Management Daemon
2.7. Primary . . . . . . . . . . . . . . . . . . . . . . . . . 7 2.7. Primary
2.8. Secondary . . . . . . . . . . . . . . . . . . . . . . . . 8 2.8. Secondary
2.9. Session . . . . . . . . . . . . . . . . . . . . . . . . . 8 2.9. Session
2.10. UPS Status . . . . . . . . . . . . . . . . . . . . . . . 8 2.10. UPS Status
2.11. UPS Variable . . . . . . . . . . . . . . . . . . . . . . 8 2.11. UPS Variable
3. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 9 3. Protocol Overview
4. Protocol Specification . . . . . . . . . . . . . . . . . . . 11 4. Protocol Specification
4.1. Notation Used in this Specification . . . . . . . . . . . 11 4.1. Notation Used in this Specification
4.2. Commands . . . . . . . . . . . . . . . . . . . . . . . . 12 4.2. Commands
4.2.1. ATTACH . . . . . . . . . . . . . . . . . . . . . . . 12 4.2.1. ATTACH
4.2.2. DETACH . . . . . . . . . . . . . . . . . . . . . . . 13 4.2.2. DETACH
4.2.3. FSD . . . . . . . . . . . . . . . . . . . . . . . . . 13 4.2.3. FSD
4.2.4. GET . . . . . . . . . . . . . . . . . . . . . . . . . 14 4.2.4. GET
4.2.4.1. GET CMDDESC . . . . . . . . . . . . . . . . . . . 14 4.2.4.1. GET CMDDESC
4.2.4.2. GET DESC . . . . . . . . . . . . . . . . . . . . 14 4.2.4.2. GET DESC
4.2.4.3. GET NUMATTACH . . . . . . . . . . . . . . . . . . 15 4.2.4.3. GET NUMATTACH
4.2.4.4. GET TYPE . . . . . . . . . . . . . . . . . . . . 15 4.2.4.4. GET TYPE
4.2.4.5. GET UPSDESC . . . . . . . . . . . . . . . . . . . 16 4.2.4.5. GET UPSDESC
4.2.4.6. GET VAR . . . . . . . . . . . . . . . . . . . . . 17 4.2.4.6. GET VAR
4.2.5. HELP . . . . . . . . . . . . . . . . . . . . . . . . 17 4.2.5. HELP
4.2.6. INSTCMD . . . . . . . . . . . . . . . . . . . . . . . 17 4.2.6. INSTCMD
4.2.7. LIST . . . . . . . . . . . . . . . . . . . . . . . . 18 4.2.7. LIST
4.2.7.1. LIST CLIENT . . . . . . . . . . . . . . . . . . . 18 4.2.7.1. LIST CLIENT
4.2.7.2. LIST CMD . . . . . . . . . . . . . . . . . . . . 19 4.2.7.2. LIST CMD
4.2.7.3. LIST ENUM . . . . . . . . . . . . . . . . . . . . 19 4.2.7.3. LIST ENUM
4.2.7.4. LIST RANGE . . . . . . . . . . . . . . . . . . . 20 4.2.7.4. LIST RANGE
4.2.7.5. LIST RW . . . . . . . . . . . . . . . . . . . . . 20 4.2.7.5. LIST RW
4.2.7.6. LIST UPS . . . . . . . . . . . . . . . . . . . . 21 4.2.7.6. LIST UPS
4.2.7.7. LIST VAR . . . . . . . . . . . . . . . . . . . . 22 4.2.7.7. LIST VAR
4.2.8. PASSWORD . . . . . . . . . . . . . . . . . . . . . . 23 4.2.8. PASSWORD
4.2.9. PRIMARY . . . . . . . . . . . . . . . . . . . . . . . 23 4.2.9. PRIMARY
4.2.10. PROTVER . . . . . . . . . . . . . . . . . . . . . . . 23 4.2.10. PROTVER
4.2.11. SET . . . . . . . . . . . . . . . . . . . . . . . . . 24 4.2.11. SET
4.2.12. STARTTLS . . . . . . . . . . . . . . . . . . . . . . 24 4.2.12. STARTTLS
4.2.12.1. Key Infrastructure and Self-signed 4.2.12.1. Key Infrastructure and Self-Signed Certificates
Certificates . . . . . . . . . . . . . . . . . . . 25 4.2.13. USERNAME
4.2.13. USERNAME . . . . . . . . . . . . . . . . . . . . . . 26 4.2.14. VER
4.2.14. VER . . . . . . . . . . . . . . . . . . . . . . . . . 26 4.3. Summary of Responses
4.3. Summary of Responses . . . . . . . . . . . . . . . . . . 26 4.3.1. Response When Command Succeeds
4.3.1. Response when Command Succeeds . . . . . . . . . . . 26 4.3.2. Error Responses
4.3.2. Error Responses . . . . . . . . . . . . . . . . . . . 27 4.4. An ABNF of the Commands
4.4. An ABNF of the Commands . . . . . . . . . . . . . . . . . 31 4.4.1. Responses to Commands
4.4.1. Responses to Commands . . . . . . . . . . . . . . . . 33 5. Statuses and Events
5. Statuses and Events . . . . . . . . . . . . . . . . . . . . . 34 5.1. Status Symbols
5.1. Status Symbols . . . . . . . . . . . . . . . . . . . . . 34 5.2. Events
5.2. Events . . . . . . . . . . . . . . . . . . . . . . . . . 36 6. Security Considerations
6. Security Considerations . . . . . . . . . . . . . . . . . . . 38 6.1. Current General Security Practice
6.1. Current General Security Practice . . . . . . . . . . . . 38 6.2. Communication Security Requirements
6.2. Communication Security Requirements . . . . . . . . . . . 39 6.2.1. Certificate Security
6.2.1. Certificate security . . . . . . . . . . . . . . . . 40 6.3. Attacks and Defenses
6.3. Attacks and Defences . . . . . . . . . . . . . . . . . . 40 6.3.1. Eavesdropping
6.3.1. Eavesdropping . . . . . . . . . . . . . . . . . . . . 40 6.3.1.1. Misplaced Declarations Requiring TLS
6.3.1.1. Misplaced declarations requiring TLS . . . . . . 41 6.3.1.2. Weak Protection in Previous Version 2.7.4
6.3.1.2. Weak protection in previous version 2.7.4 . . . . 41 6.3.2. Man-in-the-Middle
6.3.2. Man in the Middle . . . . . . . . . . . . . . . . . . 41 6.3.3. Masquerade Attack: Agent Verification
6.3.3. Masquerade Attack: Agent Verification . . . . . . . . 41 6.3.4. Message Insertion, Deletion, and Modification
6.3.4. Message insertion, deletion, modification . . . . . . 42 6.3.5. Replay
6.3.5. Replay . . . . . . . . . . . . . . . . . . . . . . . 42 6.3.6. Denial of Service
6.3.6. Denial of Service . . . . . . . . . . . . . . . . . . 42 7. IANA Considerations
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 42 8. Implementation Status
8. Implementation Status . . . . . . . . . . . . . . . . . . . . 42 8.1. Inclusion in Software Distributions
8.1. Inclusion in Software Distributions . . . . . . . . . . . 43 8.2. Recommended Minimum Support
8.2. Recommended Minimum Support . . . . . . . . . . . . . . . 43 8.2.1. Desktop PC Variables
8.2.1. Desktop PC Variables . . . . . . . . . . . . . . . . 43 8.2.2. Unattended Servers and Additional Variables
8.2.2. Unattended Servers, Additional Variables . . . . . . 44 8.2.3. Commands and Other Technical Terms
8.2.3. Commands and other Technical Terms . . . . . . . . . 44 8.2.4. Support for Earlier Versions
8.2.4. Support for Earlier Versions . . . . . . . . . . . . 44 9. References
9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 44 9.1. Normative References
10. Normative References . . . . . . . . . . . . . . . . . . . . 44 9.2. Informative References
11. Informative References . . . . . . . . . . . . . . . . . . . 45 Appendix A. Variables
Appendix A. Variables . . . . . . . . . . . . . . . . . . . . . 47 A.1. Typical UPS Variables
A.1. Typical UPS Variables . . . . . . . . . . . . . . . . . . 48 A.2. Typical UPS Readable and Writable Variables
A.2. Typical UPS Readable and Writable Variables . . . . . . . 52 A.3. Typical UPS Instant Commands
A.3. Typical UPS Instant Commands . . . . . . . . . . . . . . 54 Appendix B. The Shutdown Story for System and UPS
Appendix B. The Shutdown Story for System and UPS . . . . . . . 54 Appendix C. Technical Terms: Historical Differences
Appendix C. Technical Terms: Historical Differences . . . . . . 56 Appendix D. Security Defenses in Release 2.7.4
Appendix D. Security Defences in Release 2.7.4 . . . . . . . . . 57 D.1. Shims
D.1. Shims . . . . . . . . . . . . . . . . . . . . . . . . . . 57 D.1.1. Attachment Daemon Shim
D.1.1. Attachment Daemon Shim . . . . . . . . . . . . . . . 58 D.1.2. Management Daemon Shim
D.1.2. Management Daemon Shim . . . . . . . . . . . . . . . 58 D.2. TLS Tunnels
D.2. TLS Tunnels . . . . . . . . . . . . . . . . . . . . . . . 58 D.3. VPN
D.3. VPN . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 D.4. VLAN
D.4. VLAN . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Appendix E. Administrative Security
Appendix E. Administrative Security . . . . . . . . . . . . . . 59 E.1. Management of Administrative Users
E.1. Management of Administrative Users . . . . . . . . . . . 59 E.2. An Administrative User of a Client Management Daemon
E.2. An Administrative User of a Client Management Daemon . . 61 E.2.1. An Administrative User Logs into a Short Session
E.2.1. An Administrative User Logs into a Short Session . . 62 E.2.2. An Administrative User Logs into a Long Session
E.2.2. An Administrative User Logs into a Long Session . . . 62 Acknowledgments
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 62 Author's Address
1. Introduction 1. Introduction
1.1. Current Practice 1.1. Current Practice
This document describes UPS management techniques and current UPS This document describes UPS management techniques and current UPS
management practice published by the NUT (Network UPS Tools) Project. management practice published by the Network UPS Tools (NUT) Project.
The document is based on version 2.8.0 of the NUT Project software The document is based on version 2.8.0 of the NUT Project software,
which supports version 1.3 of the NUT protocol. which supports version 1.3 of the NUT protocol.
Since May 2002, the protocol described by this document has been Since May 2002, the protocol described by this document has been
operating on IANA port 3493/TCP (nut). operating on IANA port 3493/TCP (nut).
1.1.1. NUT Software Project 1.1.1. NUT Project
The primary goal of the NUT (Network UPS Tools) Software Project The primary goal of the Network UPS Tools (NUT) Project software
[NUT] is to provide support for Power Devices, such as [NUT] is to provide support for power devices, such as UPSs. The
Uninterruptible Power Supplies. The Project has been in operation project has been in operation since 1998, with a major rework in
since 1998 with a major rework in 2003. It operates through a user 2003. It operates through a user mailing list [nut-upsuser], a
mailing list [nut-upsuser], a developer mailing list [nut-upsdev], a developer mailing list [nut-upsdev], a website [NUT], and a GitHub
web site [NUT] and a GitHub repository [nut-repository]. See repository [nut-repository]. See [githist] and Appendix J of
[githist] and [History] for a history of the project. [History] for a history of the project.
1.1.2. The "Shutdown Story" 1.1.2. The Shutdown Story
"The Shutdown Story", see Appendix B, describes the current UPS The Shutdown Story section (see Appendix B) describes the current UPS
management practice for performing a managed shutdown of unattended management practice for performing a managed shutdown of unattended
infrastructure after an unscheduled failure of the public power infrastructure after an unscheduled failure of the public power
supply in order to minimise the risk of corruption to data processed supply in order to minimize the risk of corruption to data processed
by this infrastructure. by this infrastructure.
1.1.3. How to Read this Document 1.1.3. How to Read this Document
As a simplification to ease reading, the term "UPS" is used when As a simplification to ease reading, the term "UPS" is used when
"Managed Power Device" would be more complete. The reader should "Managed Power Device" would be more complete. The reader should
understand the simple "UPS" to include other managed power devices. understand the simple "UPS" to include other managed power devices.
The statuses and events appearing in this document are named with The statuses and events appearing in this document are named with
short text-form names, some of which are abbreviations. A full list short text-form names, some of which are abbreviations. A full list
of the statuses can be found in Section 5.1 while the events are of the statuses can be found in Section 5.1, while the events are
listed in Section 5.2. listed in Section 5.2.
This document refers to the "public power supply". Other texts This document refers to the "public power supply". Other texts
frequently refer to "utility power", "input source power" or even frequently refer to "utility power", "input source power", or even
"wall power". "wall power".
1.2. Additional Information 1.2. Additional Information
Additional information about the NUT Project is available in the Additional information about the NUT Project is available in the
project documentation [Documentation]. Requests for further project documentation [Documentation]. Requests for further
information about this protocol and related technical matters may be information about this protocol and related technical matters may be
addressed to the mailing list [nut-upsuser] of the NUT Project. addressed to the mailing list [nut-upsuser] of the NUT Project.
1.3. Requirements Language 1.3. Requirements Language
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in
14 [RFC2119] [RFC8174] when, and only when, they appear in all BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
2. Terminology 2. Terminology
The following technical terms appear in this document. They are The following technical terms appear in this document. They are
listed in alphabetical order. listed in alphabetical order.
2.1. Administrative User 2.1. Administrative User
In current practice, the commands and other functions offered by the In current practice, the commands and other functions offered by the
Attachment Daemon are made available to a set of users known as Attachment Daemon are made available to a set of users known as
Management Daemons. These Management Daemons authenticate to the Management Daemons. These Management Daemons authenticate to the
Attachment Daemon with basic credentials (username and password). Attachment Daemon with basic credentials (username and password).
Although called "users", the administrative users are not system Although called "users", the administrative users are not system
users, they are specific to an Attachment Daemon and are listed in a users; they are specific to an Attachment Daemon and are listed in a
text file (currently upsd.users) which is read by the Attachment text file (currently upsd.users) that is read by the Attachment
Daemon and which assigns to each of them the password, Instant Daemon and that assigns to each of them the password, Instant
Commands and actions which are allowed, together with the Primary or Commands, and actions that are allowed, together with the Primary or
Secondary status of the Management Daemon. For details, see Secondary status of the Management Daemon. For details, see
Appendix E.1. For details of Primary see Section 2.7, and for Appendix E.1. For details of the Primary, see Section 2.7; for
details of Secondary see Section 2.8. Typically a high-level user details of the Secondary, see Section 2.8. Typically, a high-level
will be able to send command FSD but a low-level user might only be user will be able to send command FSD, but a low-level user might
allowed to access the test panel. The security provisions for only be allowed to access the test panel. The security provisions
administrative users are discussed in Appendix E. for administrative users are discussed in Appendix E.
2.2. Attachment Daemon 2.2. Attachment Daemon
The Attachment Daemon retrieves status from the UPS and sends The Attachment Daemon retrieves the status from the UPS and sends
commands to it often through a Driver specific to the hardware model commands to it often through a Driver specific to the hardware model
and the connection medium, e.g., USB, serial. See Section 2.3. It and the connection medium, e.g., USB, serial. See Section 2.3. It
maintains an abstracted view of the hardware through the use of maintains an abstracted view of the hardware through the use of
hardware statuses. See Section 2.10. A Management Daemon may hardware statuses. See Section 2.10. A Management Daemon may
consult the abstracted view using the commands described in this consult the abstracted view using the commands described in this
document. document.
See Section 8.2 for details of the recommended minimum support of See Section 8.2 for details of the recommended minimum support of
variables which calls for Attachment Daemon support of statuses OB, variables, which calls for Attachment Daemon support of statuses OB,
OL, LB and FSD. OL, LB, and FSD.
The NUT Project has implemented an Attachment Daemon as program upsd The NUT Project has implemented an Attachment Daemon as program upsd
and a set of hardware specific drivers, all written in K&R C. The and a set of hardware-specific Drivers, all written in K&R C
Attachment Daemon is launched as system user "root", but for better [C2ndEd]. The Attachment Daemon is launched as system user "root"
security, then drops privilege to run as a detached software service. but for better security; then, it drops the privilege to run as a
detached software service.
2.3. Driver 2.3. Driver
A Driver is that part of an Attachment Daemon which is specific to A Driver is that part of an Attachment Daemon that is specific to the
the UPS hardware, the connection medium and the connection protocol, UPS hardware, the connection medium, and the connection protocol,
e.g., USB, serial. In current practice the Attachment Daemon has a e.g., USB, serial. In current practice, the Attachment Daemon has a
driver for each hardware interface type it supports. Although this Driver for each hardware interface type it supports. Although this
document considers the driver to be part of the Attachment Daemon, document considers the Driver to be part of the Attachment Daemon,
current practice is to see it as a separate software unit running as 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 a daemon "in front of" the Attachment Daemon. The protocol for data
exchange between the Driver and the Attachment Daemon is outside the exchange between the Driver and the Attachment Daemon is outside the
scope of this document. scope of this document.
2.4. Event 2.4. Event
A UPS Event occurs in the Management Daemon when a change in UPS A UPS event occurs in the Management Daemon when a change in the UPS
status is received from the Attachment Daemon. This event is status is received from the Attachment Daemon. This event is
internal to the Management Daemon. See Section 5.2. internal to the Management Daemon. See Section 5.2.
2.5. Instant Command 2.5. Instant Command
A command which when sent to the Attachment Daemon is passed to the An Instant Command is a command that, when sent to the Attachment
driver and sent to the hardware without any configured delay to Daemon, is passed to the Driver and sent to the hardware without any
perform a function. For example INSTCMD su700 test.panel.start . See configured delay to perform a function. For example, INSTCMD su700
Section 4.2.6. test.panel.start. See Section 4.2.6.
2.6. Management Daemon 2.6. Management Daemon
The Management Daemon is primarily responsible for managing the The Management Daemon is primarily responsible for managing the
hardware and orchestrating system-wide actions after a power event. hardware and orchestrating system-wide actions after a power event.
Using commands sent to the Attachment Daemon it follows the status of Using commands sent to the Attachment Daemon, it follows the status
the UPS and determines when UPS events occur. It takes decisions of the UPS and determines when UPS events occur. It takes decisions
based on the events, such as calling for a system shutdown. See based on the events, such as calling for a system shutdown. See
Appendix B. Although the term includes the word "Daemon" nothing Appendix B. Although the term includes the word "Daemon", nothing
requires that it be implemented as a detached software service. The requires that it be implemented as a detached software service. The
Management Daemon may also provide administrative functions such as a Management Daemon may also provide administrative functions, such as
graphic interface to view the hardware activity. a graphic interface to view the hardware activity.
There are several examples of a Management Daemon: the NUT Project There are several examples of a Management Daemon: the NUT Project
provides upsmon which takes the system shutdown decision when the provides upsmon, which takes the system shutdown decision when the
public power supply fails. Further configuration options such as public power supply fails. Further configuration options, such as
timers are provided by helper program upssched. timers, are provided by the helper program upssched.
Other programs represent the Management Daemon: Other programs represent the Management Daemon:
* upsc reports the values of the variables defined for a given UPS, * upsc reports the values of the variables defined for a given UPS;
see Table 6. see Table 6.
* upsrw reports on and changes the values of the readable and * upsrw reports on and changes the values of the readable and
writable configuration variables defined for a given UPS, see writable configuration variables defined for a given UPS; see
Appendix A.2. Appendix A.2.
* upscmd reports on and executes the instant action commands defined * upscmd reports on and executes the instant action commands defined
for a given UPS, see Section 4.2.6. for a given UPS; see Section 4.2.6.
* UPSmon.py is an experimental Python3 rewrite of upsmon and * UPSmon.py is an experimental Python3 rewrite of upsmon and
upssched which includes support for TLS 1.3 [RFC8446]. upssched that includes support for TLS 1.3 [RFC8446].
2.7. Primary 2.7. Primary
When a power device such as a UPS unit supplies power to more than 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. one system, the computer running the Driver is known as the Primary.
The others are Secondaries. See figure 4. Common current practice The others are Secondaries. See Figure 4. Common current practice
for system administrators is to consider the Management Daemon in the for system administrators is to consider the Management Daemon in the
Primary to be the Primary Management Daemon which is in charge of the Primary to be the Primary Management Daemon that is in charge of the
shutdown of all the systems powered by the UPS. The Primary shutdown of all the systems powered by the UPS. The Primary
Management Daemon sets status symbol FSD to order the secondaries to Management Daemon sets status symbol FSD to order the Secondaries to
shut down. shut down.
Note: Historically, the Primary was known as the "Master". | Note: Historically, the Primary was known as the "Master".
2.8. Secondary 2.8. Secondary
When a hardware device such as a UPS unit supplies power to more than When a hardware device, such as a UPS unit, supplies power to more
one system, the system which communicates directly with the UPS unit than one system, the system that communicates directly with the UPS
e.g. using a USB, RS232, or network connection, is known as the unit, e.g., using a USB, RS-232, or a network connection, is known as
Primariy. The other are Secondaries. There is no Attachment Daemon the Primary. The others are Secondaries. There is no Attachment
in a Secondary. See figure 4. Common current practice for system Daemon in a Secondary. See Figure 4. Common current practice for
administrators is to consider the Management Daemon in a Secondary to system administrators is to consider the Management Daemon in a
be a Secondary Management Daemon which understands status symbol FSD Secondary to be a Secondary Management Daemon that understands status
as an order to shut down. symbol FSD as an order to shut down.
Note: Historically, the Secondary was known as the "Slave". | Note: Historically, the Secondary was known as the "Slave".
2.9. Session 2.9. Session
The Management Daemon may initiate a TCP session with a specified The Management Daemon may initiate a TCP session with a specified
device such as a UPS known to the Attachment Daemon. The session device, such as a UPS known to the Attachment Daemon. The session
structure provides for audit and security as well as access to structure provides for audit and security, as well as access to
mission critical UPS functions. For example good practice requires a mission-critical UPS functions. For example, good practice requires
password protection for an Instant Command which turns off a UPS password protection for an Instant Command that turns off a UPS
outlet. Other than the commands and responses used, the details of outlet. Other than the commands and responses used, the details of
session management are outside the scope of this document. session management are outside the scope of this document.
2.10. UPS Status 2.10. UPS Status
The status of a hardware device such as a UPS unit is a symbolic 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 description of the state of the unit. It consists of a space-
separated list of symbols from the set {ALARM BOOST BYPASS CAL CHRG 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 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 TICK and TOCK are experimental additions to the statuses and are not
in common current practice. See Section 5.1 which specifies each of in common current practice. See Section 5.1, which specifies each of
these symbols. these symbols.
See Section 8.2 for details of the recommended minimum support of See Section 8.2 for details of the recommended minimum support of
status symbols OB, OL, LB and FSD. status symbols OB, OL, LB, and FSD.
2.11. UPS Variable 2.11. UPS Variable
The metrics and identifiers provided by each UPS are represented by The metrics and identifiers provided by each UPS are represented by
variables giving the value representing that metric or identifier, variables giving the value representing that metric or identifier.
The UPS variable is an abstraction of the UPS hardware configuration The UPS variable is an abstraction of the UPS hardware configuration
and activity maintained by the Attachment Daemon. See Appendix A and activity maintained by the Attachment Daemon. See Appendix A,
which provides examples of variables. For example the variable which provides examples of variables. For example, the variable
battery.charge contains the current charge of the UPS battery as a battery.charge contains the current charge of the UPS battery as a
percentage value. percentage value.
Note: Some variables are constants, e.g. battery type, manufacturer. Note: Some variables are constants, e.g., battery type and
manufacturer.
See Section 8.2 for details of the recommended minimum support of See Section 8.2 for details of the recommended minimum support of
variables. A full list of possible variables is available in source variables. A full list of possible variables is available in source
code file docs/nut-names.txt [gitvars] which serves as the Recording code file docs/nut-names.txt [gitvars], which serves as the Recording
Document. Document.
3. Protocol Overview 3. Protocol Overview
Figure 1 shows a reference configuration in which the command/ Figure 1 shows a reference configuration in which the command/
response protocol applies. The UPS shown is representative of all response protocol applies. The UPS shown is representative of all
managed power devices, managed power devices.
"The client" "The client"
,--------------, ,--------------, ,--------------, ,--------------,
,-----, | UPS | <-Commands | UPS | ,-----, | UPS | <-Commands | UPS |
| UPS |---| Attachment |---------------| Management | | UPS |---| Attachment |---------------| Management |
| |===| Daemon | Responses-> | Daemon | | |===| Daemon | Responses-> | Daemon |
/-----\ '--------------' '--------------' /-----\ '--------------' '--------------'
UPS Attachment UPS Management UPS Attachment UPS Management
System Network System System Network System
Figure 1: Reference Configuration Figure 1: Reference Configuration
The reference configuration in figure 1 shows a single UPS unit which The reference configuration in Figure 1 shows a single UPS unit that
has a power supply link (===) and a data link (---) attached to a has a power supply link (===) and a data link (---) attached to a
system running an Attachment Daemon. The UPS provides power supply system running an Attachment Daemon. The UPS provides power supply
protection to the system running the Attachment Daemon. protection to the system running the Attachment Daemon.
In practice there may be more than one UPS unit, and a unit may 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 provide power protection to more than one system. The figure also
shows a single Management Daemon. In practice there may be more than shows a single Management Daemon. In practice, there may be more
one Management Daemon, and any one Management Daemon may manage more than one Management Daemon, and any one Management Daemon may manage
than one UPS Attachment Daemon. more than one UPS Attachment Daemon.
The protocol applies to connections between the Attachment Daemon and The protocol applies to connections between the Attachment Daemon and
the Management Daemon which act as *server* and *client* the Management Daemon, which act as the *server* and *client*,
respectively. The Management Daemon sends commands over TCP to the respectively. The Management Daemon sends commands over TCP to the
Attachment Daemon and receives responses over TCP from that daemon. Attachment Daemon and receives responses over TCP from that daemon.
The two daemons may run in the same system, or may be connected 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 through a local or wide area network. In simple cases, as shown in
figure 2, the Attachment Daemon and the Management Daemon are in the Figure 2, the Attachment Daemon and the Management Daemon are in the
same system, the one protected by the UPS. The commands and same system, the one protected by the UPS. The commands and
responses are exchanged through an internal loopback interface. responses are exchanged through an internal loopback interface.
"The client" "The client"
,--------------------,---------------------, ,--------------------,---------------------,
,-----, | UPS <-Commands UPS | ,-----, | UPS <-Commands UPS |
| UPS |---| Attachment | Management | | UPS |---| Attachment | Management |
| |===| Daemon Responses-> Daemon | | |===| Daemon Responses-> Daemon |
/-----\ '--------------------'---------------------' /-----\ '--------------------'---------------------'
Internal Internal
loopback Loopback
UPS Attachment and Management System UPS Attachment and Management System
Figure 2: Simplified single-system configuration Figure 2: Simplified Single-System Configuration
The reference configuration does not require any specific design. The reference configuration does not require any specific design.
For example figure 3 shows an arrangement in which the Attachment For example, Figure 3 shows an arrangement in which the Attachment
Daemon is closely associated with, or even included in the UPS system Daemon is closely associated with, or even included in, the UPS
setup. This is becoming more prevalent with the availability of low system setup. This is becoming more prevalent with the availability
cost processors able to run the Attachment Daemon thereby effectively of low-cost processors able to run the Attachment Daemon, thereby
creating a network attached UPS running a published protocol. effectively creating a network-attached UPS running a published
protocol.
"The client" "The client"
,-----,------------, ,--------------, ,-----,------------, ,--------------,
| | UPS | <-Commands | UPS | | | UPS | <-Commands | UPS |
| UPS - Attachment |---------------| Management | | UPS - Attachment |---------------| Management |
| | Daemon | Responses-> | Daemon | | | Daemon | Responses-> | Daemon |
/-----'------------\ '--------------' /-----'------------\ '--------------'
UPS Attachment UPS Management UPS Attachment UPS Management
System Network System System Network System
Figure 3: UPS and Attachment Daemon integration Figure 3: UPS and Attachment Daemon Integration
As the power requirements for processors decrease, it is becoming As the power requirements for processors decrease, it is becoming
increasingly common to use a single UPS to protect multiple systems increasingly common to use a single UPS to protect multiple systems,
as shown in figure 4. However there is only one data line (---) from as shown in Figure 4. However, there is only one data line (---)
the UPS to the Primary system. The others have only power from the UPS to the Primary system. The others have only power
connections (===) to the UPS, and are known as Secondaries. A connections (===) to the UPS and are known as Secondaries. A
Secondary does not run an Attachment Daemon, it connects over a Secondary does not run an Attachment Daemon; it connects over a
network to the Attachment Daemon in the Primary. Figure 4 shows the network to the Attachment Daemon in the Primary. Figure 4 shows the
Attachment Daemon and the Primary Management Daemon in the same Attachment Daemon and the Primary Management Daemon in the same
system. This is common practice but it is not a technical system. This is common practice, but it is not a technical
requirement. requirement.
"The client" "The client"
,--------------------,---------------------, ,--------------------,---------------------,
,-----, | UPS <-Commands Primary | ,-----, | UPS <-Commands Primary |
| |---| Attachment | Management | Primary | |---| Attachment | Management | Primary
| |===| Daemon Responses-> Daemon | | |===| Daemon Responses-> Daemon |
| | '--------------------'---------------------' | | '--------------------'---------------------'
| UPS | ^ | UPS | ^
| | '<-Commands---Responses->, | | '<-Commands---Responses->,
| | v | | v
| | ,--------------,-----------------, | | ,--------------,-----------------,
| |============| | Secondary | | |============| | Secondary |
/-----\ | | Management | Secondary /-----\ | | Management | Secondary
| | Daemon | | | Daemon |
'--------------'-----------------' '--------------'-----------------'
Figure 4: UPS protects multiple systems Figure 4: UPS Protects Multiple Systems
| Note: Should the Primary fail or go off-line, the fate of the | Note: Should the Primary fail or go offline, the fate of the
| Secondaries depends on the UPS status when the Primary failed. | Secondaries depends on the UPS status when the Primary failed.
| If the UPS had status OL the Secondary continues operation, but | If the UPS had status OL, the Secondary continues operation,
| if the UPS had status OB the Secondary may choose to shut down | but if the UPS had status OB, the Secondary may choose to shut
| as a precaution. | down as a precaution.
4. Protocol Specification 4. Protocol Specification
This specification includes only the commands and their responses. This specification includes only the commands and their responses.
An implementation of the Attachment Daemon has an internal state An implementation of the Attachment Daemon has an internal state
machine, and some complex implementations of the Management Daemon machine, and some complex implementations of the Management Daemon
include an internal state machine; for example to assist the system include an internal state machine, for example, to assist the system
shutdown of a complex installation. The Management Daemon is shutdown of a complex installation. The Management Daemon is
required to remember the previous ups.status value it received from required to remember the previous ups.status value it received from
the Attachment Daemon and compare it with the next. Other than that the Attachment Daemon and compare it with the next. Other than that,
the management protocol used between them is effectively stateless. the management protocol used between them is effectively stateless.
See for example Section 5.2 which shows a map of the new ups.status For example, see Section 5.2, which shows a map of the new ups.status
response and the previous ups.status response to an Event which is response and the previous ups.status response to an event, which is
taken as the basis for Management Daemon action. taken as the basis for Management Daemon action.
4.1. Notation Used in this Specification 4.1. Notation Used in this Specification
The character set used for commands and responses is US-ASCII, see The character set used for commands and responses is US-ASCII; see
[RFC0020]. [RFC0020].
Multi-word elements are contained between QUOTATION MARK characters Multi-word elements are contained between quotation mark characters
for easier parsing. E.g., "UPS on fire". Embedded quotation marks for easier parsing, e.g., "UPS on fire". Embedded quotation marks
are escaped with REVERSE SLANT \ often known as backslashes. are escaped with reverse slant (\), often known as backslashes.
Embedded backslashes are also escaped by representing them as \\. Embedded backslashes are also escaped by representing them as \\.
Commands and responses have no leading or trailing whitespace, and Commands and responses have no leading or trailing blank space and
are terminated with a single new line character LINE FEED (LF). are terminated with a single new line character line feed (LF).
White space within commands and responses is reduced to one SPACE Blank space within commands and responses is reduced to one space
(SP). (SP).
4.2. Commands 4.2. Commands
The commands address the UPS to which they apply by <upsname> where The commands address the UPS to which they apply by <upsname>, where
* <upsname> ::= <ups>[@<hostname>[:<port>]] * <upsname> ::= <ups>[@<hostname>[:<port>]]
* <ups> is defined by the Attachment Daemon configuration files. * <ups> is defined by the Attachment Daemon configuration files.
* The default <hostname> is localhost * The default <hostname> is localhost.
* The <port> is the number of the TCP port on which the Attachment * The <port> is the number of the TCP port on which the Attachment
Daemon is listening. The default is 3493. This is supported by Daemon is listening. The default is 3493. This is supported by
all current Management Daemons. all current Management Daemons.
Examples: myups, UPS-97B@bigserver.example.com Examples: myups, UPS-97B@bigserver.example.com
ABNF: see variable upsname in Figure 5. ABNF: See variable upsname in Figure 5.
Note: Experimental Management Daemons use an extended form of Note: Experimental Management Daemons use an extended form of
<upsname> in configuration files and in program parameters, where <upsname> in configuration files and in program parameters, where:
* <upsname> ::= [<group>:]<ups>[@<hostname>[:<port>]] * <upsname> ::= [<group>:]<ups>[@<hostname>[:<port>]]
* <group> is an experimental extension to provide for groups of * <group> is an experimental extension to provide for groups of
UPSs. It is not in common current practice. UPSs. It is not in common current practice.
* <ups> is defined by the Attachment Daemon configuration files. * <ups> is defined by the Attachment Daemon configuration files.
* The default <hostname> is localhost * The default <hostname> is localhost.
Examples: ups-1@example.com:3493, HB:heartbeat1@example.com:3493 Examples: ups-1@example.com:3493, HB:heartbeat1@example.com:3493
| _Implementation note:_ In the current implementation, the names | _Implementation note:_ In the current implementation, the names
| of commands and subcommands are not case sensitive. For | of commands and subcommands are not case sensitive. For
| example GET VAR may be written as Get var, but in this | example, GET VAR may be written as Get var, but in this
| specification they are always written in upper case. | specification, they are always written in uppercase.
| Similarly, <upsname> and <varname> are not case sensitive. For | Similarly, <upsname> and <varname> are not case sensitive. For
| example UPS341 ups.id may be written as ups341 Ups.Id, but in | example, UPS341 ups.id may be written as ups341 Ups.Id, but in
| this specification <varname> is always written in lower case. | this specification, <varname> is always written in lower case.
4.2.1. ATTACH 4.2.1. ATTACH
In a configuration such as that shown in Figure 4 in which a UPS In a configuration like the one shown in Figure 4, in which a UPS
protects more than one system, the Primary Management Daemon needs to protects more than one system, the Primary Management Daemon needs to
know how many Secondaries are currently "_active_", i.e., powered by know how many Secondaries are currently _active_, i.e., powered by
the UPS, either from the public power supply or from battery power. the UPS, either from the public power supply or from battery power.
The Attachment Daemon supports this by keeping a count of all the The Attachment Daemon supports this by keeping a count of all the
"_active_" systems powered by a UPS. The count is initialised, one _active_ systems powered by a UPS. The count is initialized, one
Secondary at a time by the ATTACH command, which should be understood Secondary at a time by the ATTACH command, which should be understood
as "_count this Secondary as active_". ATTACH is one of three as _count this Secondary as active_. ATTACH is one of three commands
commands for Secondary counting: command DETACH decrements the count for Secondary counting. Additionally, command DETACH decrements the
and a Management Daemon may read the count at any time using command count, and a Management Daemon may read the count at any time using
NUMATTACH. the command NUMATTACH.
The ATTACH command is also sent to the Attachment Daemon for the The ATTACH command is also sent to the Attachment Daemon for the
Primary so during normal, fully protected operation, the count is 1 Primary, so during normal, fully protected operation, the count is 1
for the Primary + the number of secondaries. During a full system for the Primary + the number of Secondaries. During a full system
shutdown, the count drops as each Secondary Management Daemon shutdown, the count drops as each Secondary Management Daemon
executes command DETACH during its own shutdown. When the count executes command DETACH during its own shutdown. When the count
drops to 1, only the Primary is "_active_" and it knows that all the drops to 1, only the Primary is _active_, and it knows that all the
secondaries have shut down. Secondaries have shut down.
Command: ATTACH <upsname> Command: ATTACH <upsname>
If the command succeeds, the response is OK, otherwise see the error If the command succeeds, the response is OK; otherwise, see the error
responses in Section 4.3.2. responses in Section 4.3.2.
ABNF: See variable attach in Figure 5, ABNF: See variable attach in Figure 5.
Note: Historically, this command was known as LOGIN. Since that | Note: Historically, this command was known as LOGIN. However,
LOGIN was not the conventional user access to a shell or program the | because LOGIN was not the conventional user access to a shell
name was changed to avoid confusion. | or program, the name was changed to avoid confusion.
4.2.2. DETACH 4.2.2. DETACH
This companion command to ATTACH reduces the count of "active" This companion command to ATTACH reduces the count of "active"
Secondaries. It should be understood as "_this Secondary is no Secondaries. It should be understood as _this Secondary is no longer
longer active_", and is usually used during system shutdown to active_ and is usually used during system shutdown to decrement a
decrement a count of how many Secondaries are still "active". count of how many Secondaries are still _active_.
Command: DETACH Command: DETACH
If the command succeeds, the response is OK Goodbye, otherwise see If the command succeeds, the response is OK Goodbye; otherwise, see
the error responses in Section 4.3.2. the error responses in Section 4.3.2.
ABNF: See variable detach in Figure 5, ABNF: See variable detach in Figure 5.
Note: Historically, this command was known as LOGOUT. | Note: Historically, this command was known as LOGOUT.
4.2.3. FSD 4.2.3. FSD
A Management Daemon which is Primary and has the required authority, A Management Daemon that is Primary and has the required authority
uses this command to set status symbol FSD meaning "Forced Shutdown" uses this command to set status symbol FSD, meaning "Forced
in the Attachment Daemon. In current practice the Primary Management Shutdown", in the Attachment Daemon. In current practice, the
Daemon uses the symbol to tell the Secondaries to shut down. Primary Management Daemon uses the symbol to tell the Secondaries to
shut down.
Command: FSD <upsname> Command: FSD <upsname>
If the command succeeds, the response is OK FSD-SET, otherwise see If the command succeeds, the response is OK FSD-SET; otherwise, see
the error responses in Section 4.3.2. the error responses in Section 4.3.2.
ABNF: See variable fsd in Figure 5. ABNF: See variable fsd in Figure 5.
In current practice, commands such as FSD are made available only to In current practice, commands such as FSD are made available only to
a privileged administrative user authorized to send such a mission a privileged administrative user authorized to send such a mission-
critical command. The security provisions for administrative users critical command. The security provisions for administrative users
are discussed in Appendix E. are discussed in Appendix E.
Note: The symbol "FSD" is also used for an Event. See Table 5. Note: The symbol FSD is also used for an event. See Table 5.
4.2.4. GET 4.2.4. GET
Retrieve a single response from the Attachment Daemon. Retrieve a single response from the Attachment Daemon.
ABNF: See variable get in Figure 5. ABNF: See variable get in Figure 5.
The possible sub-commands are: The possible subcommands are listed in the sections below.
4.2.4.1. GET CMDDESC 4.2.4.1. GET CMDDESC
Retrieve a text description of a command. Retrieve a text description of a command.
Command: GET CMDDESC <upsname> <cmdname> Command: GET CMDDESC <upsname> <cmdname>
Response: CMDDESC <upsname> <cmdname> "<description>" Response: CMDDESC <upsname> <cmdname> "<description>"
For example: GET CMDDESC su700 load.on and response CMDDESC su700 For example: command GET CMDDESC su700 load.on and response CMDDESC
load.on "Turn on the load immediately" su700 load.on "Turn on the load immediately"
This is like GET DESC, but it applies to an Instant Command;. See This is like GET DESC, but it applies to an Instant Command. See
Section 4.2.4.2. Section 4.2.4.2.
4.2.4.2. GET DESC 4.2.4.2. GET DESC
Retrieve a text description of a UPS variable. See Section 2.11. Retrieve a text description of a UPS variable. See Section 2.11.
Command: GET DESC <upsname> <varname> Command: GET DESC <upsname> <varname>
Response: DESC <upsname> <varname> "<description>" Response: DESC <upsname> <varname> "<description>"
where <description> is a string that gives a brief explanation of the <description> is a string that gives a brief explanation of the named
named variable. The Attachment Daemon MAY return "Unavailable" if variable. The Attachment Daemon MAY return "Unavailable" if the file
the file which provides this description is not installed. that provides this description is not installed.
For example command GET DESC su700 ups.status and response DESC su700 For example: command GET DESC su700 ups.status and response DESC
ups.status "UPS status" su700 ups.status "UPS status"
4.2.4.3. GET NUMATTACH 4.2.4.3. GET NUMATTACH
Retrieve the count kept by the Attachment Daemon of all the Retrieve the count kept by the Attachment Daemon of all the _active_
"_active_" systems protected by this UPS. systems protected by this UPS.
Command: GET NUMATTACH <upsname> Command: GET NUMATTACH <upsname>
Response: NUMATTACH <upsname> <value> Response: NUMATTACH <upsname> <value>
where <value> is a count of the Primary and the number of Secondaries <value> is a count of the Primary and the number of Secondaries
currently powered by this UPS. currently powered by this UPS.
For example command GET ATTACH su700 and response NUMATTACH su700 1 For example: command GET ATTACH su700 and response NUMATTACH su700 1
This information is needed by the Management Daemon to determine how This information is needed by the Management Daemon to determine how
many Secondaries are still connected during the system shutdown many Secondaries are still connected during the system shutdown
process. process.
Note: Historically, this sub-command was known as NUMLOGINS. Since | Note: Historically, this subcommand was known as NUMLOGINS.
LOGIN was not the conventional user access to a shell or program the | Since LOGIN was not the conventional user access to a shell or
name was changed to avoid confusion. | program, the name was changed to avoid confusion.
4.2.4.4. GET TYPE 4.2.4.4. GET TYPE
Retrieve the type of a UPS variable. See Section 2.11. Retrieve the type of a UPS variable. See Section 2.11.
Command: GET TYPE <upsname> <varname> Command: GET TYPE <upsname> <varname>
Response: TYPE <upsname> <varname> <type>... Response: TYPE <upsname> <varname> <type>...
where <type>... can be one or more of the following tokens. Multiple <type>... can be one or more of the following tokens. Multiple types
types may be returned. may be returned.
For example command GET TYPE su700 input.transfer.low and response For example: command GET TYPE su700 input.transfer.low and response
TYPE su700 input.transfer.low ENUM TYPE su700 input.transfer.low ENUM
+==============+=============================================+
| Type | Meaning |
+==============+=============================================+
| RW | This is a read/write variable. It may be |
| | read with command GET VAR, see |
| | Section 4.2.4.6, and set to a different |
| | value with command SET, see Section 4.2.11. |
+--------------+---------------------------------------------+
| ENUM | 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, see |
| | Section 4.2.7.4. |
+--------------+---------------------------------------------+
| NUMBER | This is a single numeric value, either |
| | integer or float. |
+--------------+---------------------------------------------+
Table 1: Variable Types +==============+==============================================+
| Type | Meaning |
+==============+==============================================+
| RW | This is a read/write variable. It may be |
| | read with command GET VAR (see |
| | Section 4.2.4.6) and set to a different |
| | value with command SET (see Section 4.2.11). |
+--------------+----------------------------------------------+
| ENUM | This is an enumerated type, which supports |
| | specific predetermined values. |
+--------------+----------------------------------------------+
| STRING:n | This is a string of maximum length n. |
+--------------+----------------------------------------------+
| RANGE | This is a number, either integer or float, |
| | comprised in the range that may be seen with |
| | the command LIST RANGE (see |
| | Section 4.2.7.4). |
+--------------+----------------------------------------------+
| NUMBER | This is a single numeric value, either |
| | integer or float. |
+--------------+----------------------------------------------+
Table 1: Variable Types
Notes: Notes:
* ENUM, STRING:n and RANGE are usually associated with RW, but not * ENUM, STRING:n, and RANGE are usually associated with RW but not
always. The default <type>, when omitted, is numeric, so either always. The default <type>, when omitted, is numeric, so either
integer or float. Each Driver is then responsible for handling integer or float. Each Driver is then responsible for handling
values as either integer or float. values as either integer or float.
* Current practice is to represent floating point values using a * Current practice is to represent floating point values using a
decimal (base 10) US English-based representation. Hexadecimal, decimal (base 10) English-based representation. Hexadecimals,
exponents, and comma for thousands separator are not allowed. For exponents, and commas used as separators for thousands are not
example: "1200.20" is valid, while "1,200.20" and "1200,20" are allowed. For example, "1200.20" is valid, while "1,200.20" and
not valid. "1200,20" are not valid.
4.2.4.5. GET UPSDESC 4.2.4.5. GET UPSDESC
Retrieve a text description of a UPS. Retrieve a text description of a UPS.
Command: GET UPSDESC <upsname> Command: GET UPSDESC <upsname>
Response: UPSDESC <upsname> "<description>" Response: UPSDESC <upsname> "<description>"
where <description> is defined by the Attachment Daemon <description> is defined by the Attachment Daemon configuration. If
configuration. If it is not set, current practice is for the it is not set, current practice is for the Attachment Daemon to
Attachment Daemon to return "Unavailable". return "Unavailable".
For example command GET UPSDESC su700 and response UPSDESC su700 For example: command GET UPSDESC su700 and response UPSDESC su700
"Development box" "Development box"
This can be used to provide human-readable descriptions instead of a This can be used to provide human-readable descriptions, instead of a
cryptic ups@hostname string. cryptic ups@hostname string.
4.2.4.6. GET VAR 4.2.4.6. GET VAR
Retrieve the value of a UPS variable. See Section 2.11. Retrieve the value of a UPS variable. See Section 2.11.
Command: GET VAR <upsname> <varname> Command: GET VAR <upsname> <varname>
Response: VAR <upsname> <varname> "<value>" Response: VAR <upsname> <varname> "<value>"
For example command GET VAR su700 ups.status and response VAR su700 For example: command GET VAR su700 ups.status and response VAR su700
ups.status "OB LB" ups.status "OB LB"
4.2.5. HELP 4.2.5. HELP
Return a list of the commands supported by the Attachment Daemon. Return a list of the commands supported by the Attachment Daemon.
This command is intended for human as well as program use. This command is intended for human, as well as program, use.
Command HELP Command: HELP
For example, the following command line sequence executed on an For example: the following command line sequence executed on an
Attachment Daemon: Attachment Daemon
netcat localhost 3493 netcat localhost 3493
HELP HELP
Commands: HELP VER GET LIST SET INSTCMD ATTACH DETACH Commands: HELP VER GET LIST SET INSTCMD ATTACH DETACH
USERNAME PASSWORD STARTTLS USERNAME PASSWORD STARTTLS
ABNF: See variable help in Figure 5. ABNF: See variable help in Figure 5.
Note: Historically, this command also returned LOGIN and LOGOUT. | Note: Historically, this command also returned LOGIN and
Since LOGIN was not the conventional user access to a shell or | LOGOUT. Because LOGIN was not the conventional user access to
program, the command names were changed to ATTACH and DETACH to avoid | a shell or program, the command names were changed to ATTACH
confusion. | and DETACH to avoid confusion.
4.2.6. INSTCMD 4.2.6. INSTCMD
Send an Instant Command to the UPS. Send an Instant Command to the UPS.
Command: INSTCMD <upsname> <cmdname> Command: INSTCMD <upsname> <cmdname>
where <upsname> is the name of the UPS and <cmdname> is the Instant <upsname> is the name of the UPS, and <cmdname> is the Instant
Command to be issued to that UPS. See Appendix A.3 for examples of Command to be issued to that UPS. See Appendix A.3 for examples of
instant commands. Instant Commands.
If the command succeeds, the response is OK, otherwise see the error If the command succeeds, the response is OK; otherwise, see the error
responses, Section 4.3.2. responses in Section 4.3.2.
For example the command: INSTCMD su700 test.panel.start and the For example: command INSTCMD su700 test.panel.start and response OK
response OK
ABNF: See variable instcmd in Figure 5. ABNF: See variable instcmd in Figure 5.
4.2.7. LIST 4.2.7. LIST
All the LIST commands produce a response with a common format. The All the LIST commands produce a response with a common format. The
response will begin with BEGIN LIST and then repeat the initial response begins with BEGIN LIST and then repeats the initial query.
query. A list then follows, with as many lines as are necessary. A list then follows, with as many lines as are necessary. The
The response ends with END LIST followed by the initial query. response ends with END LIST, followed by the initial query.
The formatting may seem a bit redundant, but it makes a different The formatting may seem a bit redundant, but it makes a different
form of client possible. A client can send a LIST command and then form of client possible. A client can send a LIST command and then
wait for the response. When it arrives, the Management Daemon wait for the response. When it arrives, the Management Daemon
doesn't need a complicated state machine to remember which list is doesn't need a complicated state machine to remember which list is
which. which.
Note: The current NUT Project implementation of the Attachment Note: The current NUT Project implementation of the Attachment
Daemon, upsd, sends back the response to the LIST command as a Daemon, upsd, sends back the response to the LIST command as a
sequence of messages. The Management Daemon should continue reading sequence of messages. The Management Daemon should continue reading
these messages until it receives the line beginning END LIST. these messages until it receives the line beginning END LIST.
ABNF: See variable list in Figure 5. ABNF: See the variable list in Figure 5.
The possible subcommands are: The possible subcommands are listed in the sections below.
4.2.7.1. LIST CLIENT 4.2.7.1. LIST CLIENT
The command calls for the Attachment Daemon to report all the current The command calls for the Attachment Daemon to report all the current
Management Daemon clients of a given UPS. Management Daemon clients of a given UPS.
Command: LIST CLIENT <upsname> Command: LIST CLIENT <upsname>
The response is Response:
BEGIN LIST CLIENT <upsname> BEGIN LIST CLIENT <upsname>
CLIENT <upsname> <client_IP_address> CLIENT <upsname> <client_IP_address>
... ...
END LIST CLIENT <upsname> END LIST CLIENT <upsname>
For example, the command LIST CLIENT ups1 and the response: For example: command LIST CLIENT ups1 and response
BEGIN LIST CLIENT ups1 BEGIN LIST CLIENT ups1
CLIENT ups1 ::1 CLIENT ups1 ::1
CLIENT ups1 203.0.113.1 CLIENT ups1 203.0.113.1
END LIST CLIENT ups1 END LIST CLIENT ups1
4.2.7.2. LIST CMD 4.2.7.2. LIST CMD
The command calls for the Attachment Daemon to report a list of the The command calls for the Attachment Daemon to report a list of the
Instant Commands which the Management Daemon may send to the Instant Commands that the Management Daemon may send to the
Attachment Daemon. This Instant Command list is the abstracted view Attachment Daemon. This Instant Command list is the abstracted view
of the UPS hardware capabilities. An economical UPS will support few of the UPS hardware capabilities. An economical UPS will support few
or no Instant Commands but a professional model should support more. or no Instant Commands, but a professional model should support more.
Command: LIST CMD <upsname> Command: LIST CMD <upsname>
The response is: Response:
BEGIN LIST CMD <upsname> BEGIN LIST CMD <upsname>
CMD <upsname> <cmdname> CMD <upsname> <cmdname>
... ...
END LIST CMD <upsname> END LIST CMD <upsname>
where <upsname> is the name of the UPS, and <cmdname> is the name of <upsname> is the name of the UPS, and <cmdname> is the name of the
the Instant Command which may be issued to the UPS. Instant Command that may be issued to the UPS.
For example the command: LIST CMD su700 and the response: For example: command LIST CMD su700 and response
BEGIN LIST CMD su700 BEGIN LIST CMD su700
CMD su700 load.on CMD su700 load.on
CMD su700 test.panel.start CMD su700 test.panel.start
... ...
END LIST CMD su700 END LIST CMD su700
4.2.7.3. LIST ENUM 4.2.7.3. LIST ENUM
The command calls for the Attachment Daemon to report the set of The command calls for the Attachment Daemon to report the set of
possible values of a UPS variable which has predetermined values. possible values of a UPS variable that has predetermined values.
Command: LIST ENUM <upsname> <varname> Command: LIST ENUM <upsname> <varname>
The response is: Response:
BEGIN LIST ENUM <upsname> <varname> BEGIN LIST ENUM <upsname> <varname>
ENUM <upsname> <varname> "<value>" ENUM <upsname> <varname> "<value>"
... ...
END LIST ENUM <upsname> <varname> END LIST ENUM <upsname> <varname>
where <upsname> is the name of the UPS, <varname> is the UPS variable
and <value> is one of the possible values of that UPS variable. Note
that in current practice the output is an unordered list. Note also
that the QUOTATION MARKS are part of the response.
For example the command: LIST ENUM su700 input.transfer.low and the <upsname> is the name of the UPS, <varname> is the UPS variable, and
response: <value> is one of the possible values of that UPS variable. Note
that, in current practice, the output is an unordered list. Also
note that the quotation marks are part of the response.
For example: command LIST ENUM su700 input.transfer.low and response
BEGIN LIST ENUM su700 input.transfer.low BEGIN LIST ENUM su700 input.transfer.low
ENUM su700 input.transfer.low "103" ENUM su700 input.transfer.low "103"
ENUM su700 input.transfer.low "100" ENUM su700 input.transfer.low "100"
... ...
END LIST ENUM su700 input.transfer.low END LIST ENUM su700 input.transfer.low
4.2.7.4. LIST RANGE 4.2.7.4. LIST RANGE
The command calls for the Attachment Daemon to report the interval in The command calls for the Attachment Daemon to report the interval in
which valid values of UPS variable lie. which valid values of UPS variable lie.
Command: LIST RANGE <upsname> <varname> Command: LIST RANGE <upsname> <varname>
The response is: Response:
BEGIN LIST RANGE <upsname> <varname> BEGIN LIST RANGE <upsname> <varname>
RANGE <upsname> <varname> "<min>" "<max>" RANGE <upsname> <varname> "<min>" "<max>"
... ...
END LIST RANGE <upsname> <varname> END LIST RANGE <upsname> <varname>
where <upsname> is the name of the UPS, <varname> is the UPS variable <upsname> is the name of the UPS, <varname> is the UPS variable, and
and {<min>,<max>} is the interval of valid values of that UPS {<min>,<max>} is the interval of valid values of that UPS variable.
variable. Note that the QUOTATION MARKS are part of the response. Note that the quotation marks are part of the response.
For example, the command LIST RANGE su700 input.transfer.low and the For example: command LIST RANGE su700 input.transfer.low and response
response:
BEGIN LIST RANGE su700 input.transfer.low BEGIN LIST RANGE su700 input.transfer.low
RANGE su700 input.transfer.low "90" "105" RANGE su700 input.transfer.low "90" "105"
END LIST RANGE su700 input.transfer.low END LIST RANGE su700 input.transfer.low
4.2.7.5. LIST RW 4.2.7.5. LIST RW
The command calls for the Attachment Daemon to report a list of the The command calls for the Attachment Daemon to report a list of the
UPS variables associated with a given UPS which may be read and UPS variables associated with a given UPS that may be read and
written by the Management Daemon. These variables are the abstracted written by the Management Daemon. These variables are the abstracted
view of the UPS hardware capabilities. An economical UPS may support view of the UPS hardware capabilities. An economical UPS may support
few variables but a professional model should support at least the few variables, but a professional model should support at least the
variables which are needed for an automatic shutdown and restart, see variables that are needed for an automatic shutdown and restart; see
Appendix B. See also Section 8.2 for details of the recommended Appendix B. Also, see Section 8.2 for details of the recommended
minimum support of variables. A full list of variables is available minimum support of variables. A full list of variables is available
in source code file docs/nut-names.txt [gitvars] which serves as the in source code file docs/nut-names.txt [gitvars], which serves as the
Recording Document. Recording Document.
Command: LIST RW <upsname> Command: LIST RW <upsname>
The response is: Response:
BEGIN LIST RW <upsname> BEGIN LIST RW <upsname>
RW <upsname> <varname> "<value>" RW <upsname> <varname> "<value>"
... ...
END LIST RW <upsname> END LIST RW <upsname>
where <upsname> is the name of the UPS, <varname> is the UPS variable <upsname> is the name of the UPS, <varname> is the UPS variable, and
and <value> is the value of that UPS variable. Note that the <value> is the value of that UPS variable. Note that the quotation
QUOTATION MARKS are part of the response. marks are part of the response.
For example the command: LIST RW su700 and the response: For example: command LIST RW su700 and response
BEGIN LIST RW su700 BEGIN LIST RW su700
RW su700 output.voltage.nominal "115" RW su700 output.voltage.nominal "115"
RW su700 ups.delay.shutdown "020" RW su700 ups.delay.shutdown "020"
... ...
END LIST RW su700 END LIST RW su700
4.2.7.6. LIST UPS 4.2.7.6. LIST UPS
The command calls for the Attachment Daemon to report a list of the The command calls for the Attachment Daemon to report a list of the
UPS units to which it is attached. UPS units to which it is attached.
Command: LIST UPS Command: LIST UPS
The response is: Response:
BEGIN LIST UPS BEGIN LIST UPS
UPS <upsname> "<description>" UPS <upsname> "<description>"
... ...
END LIST UPS END LIST UPS
where <upsname> is the name of a UPS, and <description> is the <upsname> is the name of a UPS, and <description> is the description
description maintained by the Attachment Daemon if available. It is maintained by the Attachment Daemon, if available. It is set to
set to "Unavailable" otherwise. Note that the QUOTATION MARKS are "Unavailable" otherwise. Note that the quotation marks are part of
part of the response. the response.
This command can also be used to determine what values of <upsname> This command can also be used to determine what values of <upsname>
are valid before calling other functions on the server. This is also are valid before calling other functions on the server. This is also
a good way to handle situations where a single Attachment Daemon a good way to handle situations where a single Attachment Daemon
supports multiple UPS's. It is also useful for clients which perform supports multiple UPSs. It is also useful for clients that perform a
a UPS discovery process. UPS discovery process.
For example, the response: For example: response
BEGIN LIST UPS BEGIN LIST UPS
UPS su700 "Development box" UPS su700 "Development box"
END LIST UPS END LIST UPS
4.2.7.7. LIST VAR 4.2.7.7. LIST VAR
The command calls for the Attachment Daemon to report a list of all The command calls for the Attachment Daemon to report a list of all
the UPS variables which it maintains for a given UPS, and the values the UPS variables that it maintains for a given UPS and the values of
of those UPS variables. those UPS variables.
Command: LIST VAR <upsname> Command: LIST VAR <upsname>
The response is: Response:
BEGIN LIST VAR <upsname> BEGIN LIST VAR <upsname>
VAR <upsname> <varname> "<value>" VAR <upsname> <varname> "<value>"
... ...
END LIST VAR <upsname> END LIST VAR <upsname>
where <upsname> is the name of the UPS, <varname> is the UPS variable <upsname> is the name of the UPS, <varname> is the UPS variable, and
and <value> is the value of that variable. Note that the QUOTATION <value> is the value of that variable. Note that the quotation marks
MARKS are part of the response. are part of the response.
The response to this command lists the UPS variables available for The response to this command lists the UPS variables available for
this UPS and their current values. For example the command LIST VAR this UPS and their current values.
su700 and the response:
For example: command LIST VAR su700 and response
BEGIN LIST VAR su700 BEGIN LIST VAR su700
VAR su700 ups.mfr "Example Mfg" VAR su700 ups.mfr "Example Mfg"
VAR su700 ups.mfr.date "10/17/96" VAR su700 ups.mfr.date "10/17/96"
... ...
END LIST VAR su700 END LIST VAR su700
See Section 8.2 for details of the recommended minimum support of See Section 8.2 for details of the recommended minimum support of
variables. A full list of variables is available in source code file variables. A full list of variables is available in source code file
docs/nut-names.txt [gitvars] which serves as the Recording Document. docs/nut-names.txt [gitvars], which serves as the Recording Document.
4.2.8. PASSWORD 4.2.8. PASSWORD
This command is a companion to USERNAME, and is used by a Management This command is a companion to USERNAME and is used by a Management
Daemon to specify the password required to enter a Session with the Daemon to specify the password required to enter a session with the
Attachment Daemon, see Section 2.9. Attachment Daemon; see Section 2.9.
Command: PASSWORD <password> Command: PASSWORD <password>
If the command succeeds, the response is OK, otherwise see the error If the command succeeds, the response is OK; otherwise, see the error
responses, Section 4.3.2. responses in Section 4.3.2.
For examples of the use of commands USERNAME and PASSWORD by For examples of the use of commands USERNAME and PASSWORD by
administrative users, see Appendix E.2. administrative users, see Appendix E.2.
ABNF: See variable password in Figure 5. ABNF: See variable session-password in Figure 5.
4.2.9. PRIMARY 4.2.9. PRIMARY
In current practice, the Attachment Daemon records in local file In current practice, the Attachment Daemon records in local file
upsd.users that an administrative user is a Primary. See upsd.users that an administrative user is a Primary. See
Appendix E.1 for an example. When a Management Daemon starts up and Appendix E.1 for an example. When a Management Daemon starts up and
opens a Session with the Attachment Daemon, it lays claim to being a opens a session with the Attachment Daemon, it lays claim to being a
Primary by sending command PRIMARY to the Attachment Daemon, thus Primary by sending command PRIMARY to the Attachment Daemon, thus
claiming that it has the required authority to perform such critical claiming that it has the required authority to perform critical
actions as setting status symbol FSD. actions, such as setting status symbol FSD.
Command: PRIMARY <upsname> Command: PRIMARY <upsname>
where <upsname> is the name of the UPS. <upsname> is the name of the UPS.
If the Attachment Daemon has the authority, the response is OK, If the Attachment Daemon has the authority, the response is OK;
otherwise see the error responses in Section 4.3.2. otherwise, see the error responses in Section 4.3.2.
Note: Historically, this command was known as MASTER. | Note: Historically, this command was known as MASTER.
4.2.10. PROTVER 4.2.10. PROTVER
Return the version of the command/response protocol used by the Return the version of the command/response protocol used by the
Attachment Daemon. This command is intended for human as well as Attachment Daemon. This command is intended for human, as well as
program use. program, use.
Command PROTVER Command: PROTVER
For example, the following command line sequence in the Attachment For example: the following command line sequence in the Attachment
Daemon: Daemon
netcat localhost 3493 netcat localhost 3493
PROTVER PROTVER
1.3 1.3
Notes: Notes:
1. There are no QUOTATION MARKS in the response. 1. There are no quotation marks in the response.
2. The version of the protocol returned by PROTVER is different to 2. The version of the protocol returned by PROTVER is different than
the implementation version of the Attachment Daemon returned by the implementation version of the Attachment Daemon returned by
VER. VER.
3. To ease migration, NUT version 2.8.0 also supports the equivalent 3. To ease migration, NUT version 2.8.0 also supports the equivalent
NETVER command used in previous releases. See Section 8.2.4. NETVER command used in previous releases. See Section 8.2.4.
ABNF: See variable protver in Figure 5. ABNF: See variable protver in Figure 5.
4.2.11. SET 4.2.11. SET
The command calls for the Attachment Daemon to set a UPS variable to The command calls for the Attachment Daemon to set a UPS variable to
a given value. Whether this has an effect on the UPS hardware is a given value. Whether this has an effect on the UPS hardware is
specific to the Driver and the UPS model. Some variables are read- specific to the Driver and the UPS model. Some variables are read-
only due to the design of the UPS or its driver. only due to the design of the UPS or its Driver.
Command: SET VAR <upsname> <varname> "<value>" Command: SET VAR <upsname> <varname> "<value>"
where <upsname> is the name of the UPS, <varname> is the UPS variable <upsname> is the name of the UPS, <varname> is the UPS variable, and
and <value> is the value to be assigned to that variable. Note that <value> is the value to be assigned to that variable. Note that the
the QUOTATION MARKS are part of the command. quotation marks are part of the command.
If the command succeeds, the response is OK, otherwise see the error If the command succeeds, the response is OK; otherwise, see the error
responses in Section 4.3.2. responses in Section 4.3.2.
For example the command: SET VAR su700 ups.id "My UPS" and the For example: command SET VAR su700 ups.id "My UPS" and response OK
response OK
ABNF: See variable set in Figure 5. ABNF: See the variable set in Figure 5.
4.2.12. STARTTLS 4.2.12. STARTTLS
The client tells the Attachment Daemon to switch to TLS [RFC8446] The client tells the Attachment Daemon to switch to communication
encrypted communication. When the client receives OK it also encrypted by TLS [RFC8446]. When the client receives OK, it also
switches to TLS encryption. switches to TLS encryption.
Command: STARTTLS Command: STARTTLS
If the command succeeds, the response is OK STARTTLS, otherwise see If the command succeeds, the response is OK STARTTLS; otherwise, see
the error responses in Section 4.3.2. the error responses in Section 4.3.2.
If the client does not send command STARTTLS to the Attachment Daemon If the client does not send command STARTTLS to the Attachment
communication continues unencrypted, however an Attachment Daemon MAY Daemon, communication continues unencrypted; however, an Attachment
refuse unencrypted communication. Daemon MAY refuse unencrypted communication.
NUT 2.8.0 supports the encryption of communications between the NUT 2.8.0 supports the encryption of communications between the
Attachment Daemon and the Management Daemon using TLS 1.3 [RFC8446] Attachment Daemon and the Management Daemon using TLS 1.3 [RFC8446]
with X.509 v3 certificates as defined by [RFC5280] and updates. See with X.509 v3 certificates, as defined by [RFC5280] and updates. See
Appendix D for details of the encryption of communications in Appendix D for details of the encryption of communications in
previous relase 2.7.4. previous release 2.7.4.
ABNF: See variable starttls in Figure 5. ABNF: See variable starttls in Figure 5.
4.2.12.1. Key Infrastructure and Self-signed Certificates 4.2.12.1. Key Infrastructure and Self-Signed Certificates
_The very restricted nature of UPS management makes it of interest to _The very restricted nature of UPS management makes it of interest to
consider self-signed certificates._ consider self-signed certificates._
In the World Wide Web, there are millions of servers and hundreds of In the World Wide Web, there are millions of servers and hundreds of
millions of potential clients for each one. The servers do not know millions of potential clients for each one. The servers do not know
who their clients will be, so they entrust the management of a Public who their clients will be, so they entrust the management of a Public
Key Infrastructure (PKI) to Certificate Authorities that they trust, Key Infrastructure (PKI) to Certificate Authorities that they trust.
for some value of trust. The encryption of communications between The encryption of communications between the client and server
client and server requires that the browsers carry a list of requires that the browsers carry a list of Certificate Authorities
Certificate Authorities which the clients have to trust. _This is a that the clients have to trust. _This is a many-to-many
many-to-many relationship._ relationship._
The management of UPS units is not a many-to-many relationship, it is The management of UPS units is not a many-to-many relationship; it is
frequently one-to-one. In the closely restrained world of UPS frequently one to one. In the closely restrained world of UPS
management, there are a very limited number of clients for each management, there are a very limited number of clients for each
server, rarely more than three, and unlike the World Wide Web the server, rarely more than three, and unlike the World Wide Web, the
server administrators know exactly who they are. These clients visit server administrators know exactly who they are. These clients visit
very few servers, typically one only. This situation is totally very few servers, typically one only. This situation is totally
different to the World Wide Web. The use of external Certificate different from the World Wide Web. The use of external Certificate
Authorities is a potential security weakness that must be accepted Authorities is a potential security weakness that must be accepted
for the World Wide Web, but which can be avoided for UPS management for the World Wide Web but which can be avoided for UPS management by
by either generating locally the private and public keys, or for either generating the private and public keys locally or, for larger
larger organisations, using a Private Key Infrastructure.. organizations, using a PKI.
The security policies for UPS management may be subordinate to an The security policies for UPS management may be subordinate to an
organisation's own internal IT security plans and procedures, organization's own internal IT security plans and procedures,
possibly based on [RFC7030] and [RFC8894], but in simple cases it is possibly based on [RFC7030] and [RFC8894], but in simple cases, it is
possible to obtain better security using self-signed certificates. possible to obtain better security using self-signed certificates.
4.2.13. USERNAME 4.2.13. USERNAME
The Attachment Daemon limits access to clients whose credentials The Attachment Daemon limits access to clients whose credentials
match those in the file upsd.users. There is no anonymous access. A match those in the file upsd.users. There is no anonymous access. A
Management Daemon program or script uses command USERNAME and its Management Daemon program or script uses command USERNAME and its
companion command PASSWORD to open a Session with the Attachment companion command PASSWORD to open a session with the Attachment
Daemon for an administrative user. Note that this command is for Daemon for an administrative user. Note that this command is for
program or script use and is not the familiar login command typed on program or script use and is not the familiar login command typed on
a command line to gain access to a shell. a command line to gain access to a shell.
Command: USERNAME <username> Command: USERNAME <username>
If the command succeeds, the response is OK, otherwise see the error If the command succeeds, the response is OK; otherwise, see the error
responses in Section 4.3.2. responses in Section 4.3.2.
For examples of the use of commands USERNAME and PASSWORD by For examples of the use of commands USERNAME and PASSWORD by
administrative users, see Appendix E.2. administrative users, see Appendix E.2.
ABNF: See variable username in Figure 5. ABNF: See variable session-username in Figure 5.
4.2.14. VER 4.2.14. VER
Return the implementation version of the Attachment Daemon. This Return the implementation version of the Attachment Daemon. This
command is intended for human as well as program use. command is intended for human, as well as program, use.
Command VER Command: VER
For example, the following command line sequence: For example: the following command line sequence
netcat localhost 3493 netcat localhost 3493
VER VER
Network UPS Tools upsd 2.8.0 - http://www.networkupstools.org/ Network UPS Tools upsd 2.8.0 - http://www.networkupstools.org/
Notes: Notes:
1. There are no QUOTATION MARKS in the response. 1. There are no quotation marks in the response.
2. The implementation version of the Attachment Daemon returned by 2. The implementation version of the Attachment Daemon returned by
VER is different to the protocol version returned by PROTVER. VER is different than the protocol version returned by PROTVER.
ABNF: See variable ver in Figure 5. ABNF: See variable ver in Figure 5.
4.3. Summary of Responses 4.3. Summary of Responses
4.3.1. Response when Command Succeeds 4.3.1. Response When Command Succeeds
If the command succeeds, the response has the following command- If the command succeeds, the response has the following command-
dependent form: dependent form:
+==========+======================+================+============+ +==========+=====================+================+============+
| Command | Response | Reference | Note | | Command | Response | Reference | Note |
+==========+======================+================+============+ +==========+=====================+================+============+
| ATTACH | OK | Section 4.2.1 | Was LOGIN | | ATTACH | OK | Section 4.2.1 | Was LOGIN |
+----------+----------------------+----------------+------------+ +----------+---------------------+----------------+------------+
| DETACH | OK Goodbye | Section 4.2.2 | Was LOGOUT | | DETACH | OK Goodbye | Section 4.2.2 | Was LOGOUT |
+----------+----------------------+----------------+------------+ +----------+---------------------+----------------+------------+
| FSD | OK FSD-SET | Section 4.2.3 | | | FSD | OK FSD-SET | Section 4.2.3 | |
+----------+----------------------+----------------+------------+ +----------+---------------------+----------------+------------+
| GET | Sub command specific | Section 4.2.4 | | | GET | Subcommand specific | Section 4.2.4 | |
+----------+----------------------+----------------+------------+ +----------+---------------------+----------------+------------+
| HELP | List of commands | Section 4.2.5 | | | HELP | List of commands | Section 4.2.5 | |
+----------+----------------------+----------------+------------+ +----------+---------------------+----------------+------------+
| INSTCMD | OK | Section 4.2.6 | | | INSTCMD | OK | Section 4.2.6 | |
+----------+----------------------+----------------+------------+ +----------+---------------------+----------------+------------+
| LIST | Sub command specific | Section 4.2.7 | | | LIST | Subcommand specific | Section 4.2.7 | |
+----------+----------------------+----------------+------------+ +----------+---------------------+----------------+------------+
| PASSWORD | OK | Section 4.2.8 | | | PASSWORD | OK | Section 4.2.8 | |
+----------+----------------------+----------------+------------+ +----------+---------------------+----------------+------------+
| PRIMARY | OK | Section 4.2.9 | | | PRIMARY | OK | Section 4.2.9 | |
+----------+----------------------+----------------+------------+ +----------+---------------------+----------------+------------+
| PROTVER | Protocol version | Section 4.2.10 | Was NETVER | | PROTVER | Protocol version | Section 4.2.10 | Was NETVER |
+----------+----------------------+----------------+------------+ +----------+---------------------+----------------+------------+
| SET | OK | Section 4.2.11 | | | SET | OK | Section 4.2.11 | |
+----------+----------------------+----------------+------------+ +----------+---------------------+----------------+------------+
| STARTTLS | OK STARTTLS | Section 4.2.12 | | | STARTTLS | OK STARTTLS | Section 4.2.12 | |
+----------+----------------------+----------------+------------+ +----------+---------------------+----------------+------------+
| USERNAME | OK | Section 4.2.13 | | | USERNAME | OK | Section 4.2.13 | |
+----------+----------------------+----------------+------------+ +----------+---------------------+----------------+------------+
| VER | Program version | Section 4.2.14 | | | VER | Program version | Section 4.2.14 | |
+----------+----------------------+----------------+------------+ +----------+---------------------+----------------+------------+
Table 2: Response if command succeeds Table 2: Response If Command Succeeds
4.3.2. Error Responses 4.3.2. Error Responses
Error responses have the following format: Error responses have the following format:
ERR <error-name> [<extra>] ERR <error-name> [<extra>]
where <error-name> is a single word token taken from the 27 <error-name> is a single word token taken from the 27 characters A-Z
characters A-Z and HYPHEN (MINUS). Implementations MAY if needed add and hyphen (-). Implementations MAY, if needed, add an additional,
an additional optional <extra>. Current practice does not make use optional <extra>. Current practice does not make use of this
of this possibility. possibility.
The <error-name> may have one of the following values: The <error-name> may have one of the following values:
+==============================+==================================+ +==============================+==================================+
| The error name token | Meaning | | The Error Name Token | Meaning |
| <error-name> | | | <error-name> | |
+==============================+==================================+ +==============================+==================================+
| ACCESS-DENIED | The client's host and/or | | ACCESS-DENIED | The client's host and/or |
| | authentication details supplied | | | authentication details supplied |
| | by USERNAME and PASSWORD are not | | | by USERNAME and PASSWORD are not |
| | sufficient to execute the | | | sufficient to execute the |
| | requested command. | | | requested command. |
+------------------------------+----------------------------------+ +------------------------------+----------------------------------+
| ALREADY-ATTACHED | The client has already sent a | | ALREADY-ATTACHED | The client has already sent a |
| | successful ATTACH command for a | | | successful ATTACH command for a |
| | given UPS and can't do it again. | | | 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 | | ALREADY-SET-PASSWORD | The client has already supplied |
| | a PASSWORD and is attempting to | | | a PASSWORD and is attempting to |
| | repeat the command in the same | | | repeat the command in the same |
| | Session. | | | session. |
+------------------------------+----------------------------------+ +------------------------------+----------------------------------+
| ALREADY-SET-USERNAME | The client has already supplied | | ALREADY-SET-USERNAME | The client has already supplied |
| | a USERNAME, and is attempting to | | | a USERNAME and is attempting to |
| | repeat the command within the | | | repeat the command within the |
| | same Session. | | | same session. |
+------------------------------+----------------------------------+ +------------------------------+----------------------------------+
| CMD-NOT-SUPPORTED | The specified UPS doesn't | | CMD-NOT-SUPPORTED | The specified UPS doesn't |
| | support the Instant Command. | | | support the Instant Command. |
+------------------------------+----------------------------------+ +------------------------------+----------------------------------+
| DATA-STALE | The Attachment Daemon is | | DATA-STALE | The Attachment Daemon is |
| | connected to the Driver for the | | | connected to the Driver for the |
| | UPS, but that driver isn't | | | UPS, but that Driver isn't |
| | providing regular updates or has | | | providing regular updates or has |
| | specifically marked the data as | | | specifically marked the data as |
| | stale. Current practice is for | | | stale. Current practice is for |
| | the Attachment Daemon to refuse | | | the Attachment Daemon to refuse |
| | to provide the Management Daemon | | | to provide the Management Daemon |
| | with variables on stale units to | | | with variables on stale units to |
| | avoid false readings. | | | avoid false readings. |
| | | | | |
| | This generally means that the | | | This generally means that the |
| | Driver is running, but it has | | | Driver is running, but it has |
| | lost communication with the | | | lost communication with the |
| | hardware. Check the physical | | | hardware. Check the physical |
| | connection to the equipment. | | | connection to the equipment. |
+------------------------------+----------------------------------+ +------------------------------+----------------------------------+
| DRIVER-NOT-CONNECTED | The Attachment Daemon can't | | DRIVER-NOT-CONNECTED | The Attachment Daemon can't |
| | perform the requested command, | | | perform the requested command, |
| | since the Driver for that UPS is | | | since the Driver for that UPS is |
| | not connected. This usually | | | not connected. This usually |
| | means that the driver is not | | | means that the Driver is not |
| | running, or if it is, is | | | running or, if it is, is |
| | misconfigured. | | | misconfigured. |
+------------------------------+----------------------------------+ +------------------------------+----------------------------------+
| FEATURE-NOT-CONFIGURED | This instance of the Attachment | | FEATURE-NOT-CONFIGURED | This instance of the Attachment |
| | Daemon hasn't been configured | | | Daemon hasn't been configured |
| | properly to allow the requested | | | properly to allow the requested |
| | feature to operate. In current | | | feature to operate. In current |
| | practice this error response is | | | practice, this error response is |
| | possible only for command | | | possible only for command |
| | STARTTLS. | | | STARTTLS. |
+------------------------------+----------------------------------+ +------------------------------+----------------------------------+
| FEATURE-NOT-SUPPORTED | This instance of Attachment | | FEATURE-NOT-SUPPORTED | This instance of Attachment |
| | Daemon does not support the | | | Daemon does not support the |
| | requested feature. In current | | | requested feature. In current |
| | practice this error response is | | | practice, this error response is |
| | possible only for command | | | possible only for command |
| | STARTTLS. | | | STARTTLS. |
+------------------------------+----------------------------------+ +------------------------------+----------------------------------+
| INSTCMD-FAILED | The Attachment Daemon failed to | | INSTCMD-FAILED | The Attachment Daemon failed to |
| | deliver the Instant Command | | | deliver the Instant Command |
| | request to the Driver. No | | | request to the Driver. No |
| | further information is available | | | further information is available |
| | to the client. This typically | | | to the client. This typically |
| | indicates a dead or broken | | | indicates a dead or broken |
| | driver. | | | Driver. |
+------------------------------+----------------------------------+ +------------------------------+----------------------------------+
| INVALID-ARGUMENT | The client sent an argument to a | | INVALID-ARGUMENT | The client sent an argument to a |
| | command which is not recognized | | | command that is not recognized |
| | or is otherwise not valid in | | | or is otherwise not valid in |
| | this context. This is typically | | | this context. This is typically |
| | caused by sending a valid | | | caused by sending a valid |
| | command such as GET with a | | | command, such as GET, with a |
| | subcommand which is not valid. | | | subcommand that is not valid. |
+------------------------------+----------------------------------+ +------------------------------+----------------------------------+
| INVALID-PASSWORD | The client sent a non valid | | INVALID-PASSWORD | The client sent a nonvalid |
| | PASSWORD. | | | PASSWORD. |
+------------------------------+----------------------------------+ +------------------------------+----------------------------------+
| INVALID-USERNAME | The client sent an non valid | | INVALID-USERNAME | The client sent a nonvalid |
| | USERNAME. | | | USERNAME. |
+------------------------------+----------------------------------+ +------------------------------+----------------------------------+
| INVALID-VALUE | The value specified in the | | INVALID-VALUE | The value specified in the |
| | request is not valid. This | | | request is not valid. This |
| | usually applies to a SET of an | | | usually applies to a SET of an |
| | ENUM type which is using a value | | | ENUM type that is using a value |
| | not in the list of allowed | | | not in the list of allowed |
| | values. See Section 4.2.7.3. | | | values. See Section 4.2.7.3. |
+------------------------------+----------------------------------+ +------------------------------+----------------------------------+
| PASSWORD-REQUIRED | The command requires a PASSWORD | | PASSWORD-REQUIRED | The command requires a PASSWORD |
| | for authentication, but the | | | for authentication, but the |
| | client hasn't provided one. | | | client hasn't provided one. |
+------------------------------+----------------------------------+ +------------------------------+----------------------------------+
| READONLY | The requested variable in a SET | | READONLY | The requested variable in a SET |
| | command is not writable. | | | command is not writable. |
+------------------------------+----------------------------------+ +------------------------------+----------------------------------+
skipping to change at page 31, line 9 skipping to change at line 1398
+------------------------------+----------------------------------+ +------------------------------+----------------------------------+
| USERNAME-REQUIRED | The command requires a USERNAME | | USERNAME-REQUIRED | The command requires a USERNAME |
| | for authentication, but the | | | for authentication, but the |
| | client hasn't provided one. | | | client hasn't provided one. |
+------------------------------+----------------------------------+ +------------------------------+----------------------------------+
| VAR-NOT-SUPPORTED | The specified UPS doesn't | | VAR-NOT-SUPPORTED | The specified UPS doesn't |
| | support the UPS variable in the | | | support the UPS variable in the |
| | command. | | | command. |
+------------------------------+----------------------------------+ +------------------------------+----------------------------------+
Table 3: Error responses Table 3: Error Responses
| Note: Historically, this error response was ALREADY-LOGGED-IN.
4.4. An ABNF of the Commands 4.4. An ABNF of the Commands
This section repeats the syntax of Section 4.2, but in Augmented This section repeats the syntax of Section 4.2 but in Augmented
Bachus-Naur Form (ABNF). It does not define any additional feature. Backus-Naur Form (ABNF). It does not define any additional features.
For further details of each command and the response, see For further details of each command and the response, see
Section 4.2. Section 4.2.
The commands may be presented in ABNF [RFC5234][RFC7405], and The commands may be presented in ABNF [RFC5234] [RFC7405] and
represented using ASCII [RFC0020]. represented using US-ASCII [RFC0020].
Current practice tolerates mixed case command names, but it is Current practice tolerates mixed-case command names, but it is
RECOMMENDED to use upper case only for commands. See Figure 5. RECOMMENDED to use uppercase only for commands. See Figure 5.
;------------------------------------------------------------------- ;-------------------------------------------------------------------
; This grammar is case sensitive. Terminal keywords SHOULD be ; This grammar is case sensitive. Terminal keywords SHOULD be
; written in upper case as shown. ; written in uppercase, as shown.
; The following basic rules written with upper case names are ; The following basic rules written with uppercase names are
; taken from RFC5234 Appendix B.1. ; taken from RFC 5234, Appendix B.1.
SP = 1*%x20 ; At least one SPACE SP = 1*%x20 ; At least one SPACE
LF = %x0A ; Linefeed LF = %x0A ; Linefeed
DIGIT = %x30-39 ; Digit 0 through 9 DIGIT = %x30-39 ; Digit 0 through 9
ALPHA = %x41-5A / %x61-7A ; A-Z / a-z ALPHA = %x41-5A / %x61-7A ; A-Z / a-z
DQUOTE = %x22 ; Double quote " DQUOTE = %x22 ; Double quote "
VCHAR = %x21-7E ; Visible (printing) characters VCHAR = %x21-7E ; Visible (printing) characters
; Additional basic rules needed by this grammar ; Additional basic rules needed by this grammar
LC = %x61-7A ; Letter a through z LC = %x61-7A ; Letter a through z
DOT = 1%x2E ; Exactly one . DOT = 1%x2E ; Exactly one .
COLON = 1%x3A ; Exactly one : COLON = 1%x3A ; Exactly one :
AT = 1%x40 ; Exactly one @ AT = 1%x40 ; Exactly one @
SEP = 1"-" / 1"_" / 1"." ; A single - or _ or . SEP = 1"-" / 1"_" / 1"." ; A single - or _ or .
JOIN = COLON / AT ; A single : or @ JOIN = COLON / AT ; A single : or @
; Frequently used in this grammar ; Frequently used in this grammar
cmdname = 1*LC *62(DOT 1*LC) ; E.g. load.off.delay cmdname = 1*LC *62(DOT 1*LC) ; E.g., load.off.delay
upschar = DIGIT / ALPHA / SEP upschar = DIGIT / ALPHA / SEP
ups = 1*ALPHA *62upschar ; E.g. Example-Mfg-999 ups = 1*ALPHA *62upschar ; E.g., Example-Mfg-999
group = ups ; E.g. HB (Not in common use) group = ups ; E.g., HB (Not in common use)
hostname = ups ; E.g. example.com hostname = ups ; E.g., example.com
port = 1*5DIGIT ; E.g. 3493 port = 1*5DIGIT ; E.g., 3493
upsname = [group COLON] ups [AT hostname [COLON port]] upsname = [group COLON] ups [AT hostname [COLON port]]
; Fully Qualified UPS name ; Fully Qualified UPS name
; E.g. HB:heartbeat1@example.com:3493 ; E.g.,
; HB:heartbeat1@example.com:3493
username = ups ; E.g. Power-Dept.6 username = ups ; E.g., Power-Dept.6
varname = 1*LC *62( DOT 1*(DIGIT / LC) ) varname = 1*LC *62( DOT 1*(DIGIT / LC) )
; E.g. outlet.1.status ; E.g., outlet.1.status
;------------------------------------------------------------------- ;-------------------------------------------------------------------
commandLine = command LF ; LF is a single %x0A commandLine = command LF ; LF is a single %x0A
command = attach / detach / fsd / get / help / instcmd / command = attach / detach / fsd / get / help / instcmd /
list / password / primary / protver / set / list / password / primary / protver / set /
starttls / username / ver starttls / username / ver
; ;
attach = "ATTACH" SP upsname attach = "ATTACH" SP upsname
; ;
detach = "DETACH" detach = "DETACH"
; ;
skipping to change at page 32, line 47 skipping to change at line 1486
listrw / listups / listvar listrw / listups / listvar
; ;
listclient = "CLIENT" SP upsname listclient = "CLIENT" SP upsname
listcmd = "CMD" SP upsname listcmd = "CMD" SP upsname
listenum = "ENUM" SP upsname SP varname listenum = "ENUM" SP upsname SP varname
listrange = "RANGE" SP upsname SP varname listrange = "RANGE" SP upsname SP varname
listrw = "RW" SP upsname listrw = "RW" SP upsname
listups = "UPS" listups = "UPS"
listvar = "VAR" SP upsname listvar = "VAR" SP upsname
; ;
password = "PASSWORD" SP *63VCHAR session-password = "PASSWORD" SP *63VCHAR
; A sequence of printable characters defined ; A sequence of printable characters defined
; in a server configuration file. Local ; in a server configuration file. Local
; security practices may mandate a minimum ; security practices may mandate a minimum
; and maximum number of characters. ; and maximum number of characters.
; ;
primary = "PRIMARY" SP upsname primary = "PRIMARY" SP upsname
; ;
protver = "PROTVER" protver = "PROTVER"
; ;
value = *63VCHAR ; Local practices may limit the choice of value = *63VCHAR ; Local practices may limit the choice of
; characters, and require non US-ASCII. ; characters and require non-US-ASCII.
set = "SET" SP %s"VAR" SP upsname SP varname SP DQUOTE value DQUOTE set = "SET" SP %s"VAR" SP upsname SP varname SP
DQUOTE value DQUOTE
; ;
starttls = "STARTTLS" starttls = "STARTTLS"
; ;
username = "USERNAME" SP username session-username = "USERNAME" SP username
; ;
ver = "VER" ver = "VER"
;------------------------------------------------------------------- ;-------------------------------------------------------------------
Figure 5: ABNF for the Commands Figure 5: ABNF for the Commands
Notes: Notes:
1. _Implementation note:_ The ABNF is written using the provisions 1. _Implementation note:_ The ABNF is written using the provisions
of [RFC5234] [RFC7405] which are US-ASCII based [RFC0020]. of [RFC5234] and [RFC7405], which are US-ASCII based [RFC0020].
2. The grammar is case sensitive. The terminal key words SHOULD be 2. The grammar is case sensitive. The terminal key words SHOULD be
written in upper case as specified. written in uppercase, as specified.
3. The repetition factor in front of an expression has the form 3. The repetition factor in front of an expression has the form
<min>*<max> where <min> is the minimum number of repetitions and <min>*<max>, where <min> is the minimum number of repetitions,
<max> is the maximum number. and <max> is the maximum number.
4. If <min> is omitted its value is 0. If <max> is omitted, its 4. If <min> is omitted, its value is 0. If <max> is omitted, its
value is infinity. value is infinity.
5. The notation n*n meaning "exactly n copies" may be written as n. 5. The notation n*n, meaning "exactly n copies", may be written as
n.
6. Square brackets around an expression mean that the expression is 6. Square brackets around an expression mean that the expression is
optional. This could be written as 0*1. optional. This could be written as 0*1.
4.4.1. Responses to Commands 4.4.1. Responses to Commands
The responses to the commands are encoded in US-ASCII [RFC0020] and The responses to the commands are encoded in US-ASCII [RFC0020] and
fall into two groups: fall into two groups:
1. Short replies to action commands, see Section 4.3. 1. Short replies to action commands; see Section 4.3.
2. Long replies to requests for information. In this case the reply 2. Long replies to requests for information. In this case, the
is sent in a sequence of messages. The last message will contain reply is sent in a sequence of messages. The last message will
a line beginning END LIST . See for example Section 4.2.7.1. contain a line beginning END LIST . For example, see
Section 4.2.7.1.
5. Statuses and Events 5. Statuses and Events
5.1. Status Symbols 5.1. Status Symbols
These symbols resume the abstracted view of the UPS hardware These symbols resume the abstracted view of the UPS hardware
maintained by the Attachment Daemon. The variable ups.status maintained by the Attachment Daemon. The variable ups.status
contains one or more space-separated status symbols which together contains one or more space-separated status symbols, which together
describe the UPS state at that instant. In current practice the describe the UPS state at that instant. In current practice, the
Management Daemon will poll variable ups.status every 5 seconds with Management Daemon will poll variable ups.status every 5 seconds with
a command such as GET VAR su700 ups.status and response such as VAR a command, such as GET VAR su700 ups.status, and a response, such as
su700 ups.status "OB LB" to discover changes in the UPS status. VAR su700 ups.status "OB LB", to discover changes in the UPS status.
These changes will indicate UPS events. These changes will indicate UPS events.
+=========+======================================================+ +=========+======================================================+
| Status | Meaning | | Status | Meaning |
| Symbol | | | Symbol | |
+=========+======================================================+ +=========+======================================================+
| ALARM | The UPS reports that it requires intervention. | | ALARM | The UPS reports that it requires intervention. |
+---------+------------------------------------------------------+ +---------+------------------------------------------------------+
| BOOST | The UPS has determined that the voltage level of the | | BOOST | The UPS has determined that the voltage level of the |
| | public power supply is too low, and is boosting it | | | public power supply is too low and is boosting it to |
| | to the required level. The UPS continues to supply | | | the required level. The UPS continues to supply the |
| | the protected system from the public power supply. | | | protected system from the public power supply. |
+---------+------------------------------------------------------+ +---------+------------------------------------------------------+
| BYPASS | The UPS is feeding current directly from the public | | BYPASS | The UPS is feeding current directly from the public |
| | power supply to the protected system. The backup | | | power supply to the protected system. The backup |
| | facilities are disconnected. This state allows | | | facilities are disconnected. This state allows |
| | maintenance personnel to change the batteries | | | maintenance personnel to change the batteries |
| | without interrupting the protected system. | | | without interrupting the protected system. |
+---------+------------------------------------------------------+ +---------+------------------------------------------------------+
| CAL | The UPS is calibrating itself, for example to | | CAL | The UPS is calibrating itself, for example, to |
| | determine at what charge the LB status is raised or | | | determine at what charge the LB status is raised or |
| | lowered. | | | lowered. |
+---------+------------------------------------------------------+ +---------+------------------------------------------------------+
| CHRG | The UPS battery is charging. This usually implies | | CHRG | The UPS battery is charging. This usually implies |
| | that the UPS also has status OL, but may not be the | | | that the UPS also has status OL but may not be the |
| | case if the UPS also has status OFF. | | | case if the UPS also has status OFF. |
+---------+------------------------------------------------------+ +---------+------------------------------------------------------+
| COMM | The Attachment Daemon has effective contact with the | | COMM | The Attachment Daemon has effective contact with the |
| | UPS. | | | UPS. |
+---------+------------------------------------------------------+ +---------+------------------------------------------------------+
| DISCHRG | The UPS battery is discharging. This usually | | DISCHRG | The UPS battery is discharging. This usually |
| | implies that the UPS also has status OB, but may not | | | implies that the UPS also has status OB but may not |
| | be the case if the UPS also has status OFF. | | | be the case if the UPS also has status OFF. |
+---------+------------------------------------------------------+ +---------+------------------------------------------------------+
| FSD | This "Forced Shutdown" status signals that the final | | FSD | This "Forced Shutdown" status signals that the final |
| | shutdown sequence has begun. | | | shutdown sequence has begun. |
+---------+------------------------------------------------------+ +---------+------------------------------------------------------+
| LB | Low Battery. The battery level of the UPS is below | | LB | Low Battery. The battery level of the UPS is below |
| | a chosen limit. The UPS may be in status OL or OB. | | | a chosen limit. The UPS may be in status OL or OB. |
+---------+------------------------------------------------------+ +---------+------------------------------------------------------+
| NOCOMM | The Attachment Daemon has no effective contact with | | NOCOMM | The Attachment Daemon has no effective contact with |
| | the UPS. | | | the UPS. |
+---------+------------------------------------------------------+ +---------+------------------------------------------------------+
| OB | On Battery. The UPS is taking energy from it's | | OB | On Battery. The UPS is taking energy from its |
| | battery. The battery is discharging. A UPS must | | | battery. The battery is discharging. A UPS must |
| | have status OB or OL, otherwise it is deemed dead. | | | have status OB or OL; otherwise, it is deemed dead. |
+---------+------------------------------------------------------+ +---------+------------------------------------------------------+
| OFF | The UPS is in state "Off". It does not react to | | OFF | The UPS is in state "Off". It does not react to |
| | failure in the public power supply. The exact | | | failure in the public power supply. The exact |
| | meaning depends on the model. | | | meaning depends on the model. |
+---------+------------------------------------------------------+ +---------+------------------------------------------------------+
| OL | Online. The UPS is online, receiving energy from | | OL | Online. The UPS is online, receiving energy from |
| | the public power supply. The battery is charging. | | | the public power supply. The battery is charging. |
| | A UPS must have status OB or OL, otherwise it is | | | A UPS must have status OB or OL; otherwise, it is |
| | deemed dead. | | | deemed dead. |
+---------+------------------------------------------------------+ +---------+------------------------------------------------------+
| OVER | Overloaded. The UPS reports that the load on it is | | OVER | Overloaded. The UPS reports that the load on it is |
| | beyond it's normal operating maximum. | | | beyond its normal operating maximum. |
+---------+------------------------------------------------------+ +---------+------------------------------------------------------+
| RB | Replace battery. The UPS reports that it's battery/ | | RB | Replace battery. The UPS reports that its battery |
| | batteries should be replaced. | | | or batteries should be replaced. |
+---------+------------------------------------------------------+ +---------+------------------------------------------------------+
| TEST | Under test. The UPS is currently undergoing a test, | | TEST | Under test. The UPS is currently undergoing a test |
| | which may have been called for manually or | | | that may have been requested manually or internally. |
| | internally. |
+---------+------------------------------------------------------+ +---------+------------------------------------------------------+
| TICK | Heartbeat. A software UPS in the Attachment Daemon | | TICK | Heartbeat. A software UPS in the Attachment Daemon |
| | provides a regular signal monitored by the | | | provides a regular signal monitored by the |
| | Management Daemon as a way of verifying effective | | | Management Daemon as a way of verifying effective |
| | end-to-end management. TICK and TOCK are | | | end-to-end management. TICK and TOCK are |
| | companions, they are considered experimental. | | | companions; they are considered experimental. |
+---------+------------------------------------------------------+ +---------+------------------------------------------------------+
| TOCK | Heartbeat. See TICK | | TOCK | Heartbeat. See TICK |
+---------+------------------------------------------------------+ +---------+------------------------------------------------------+
| TRIM | The UPS has determined that the voltage level of the | | TRIM | The UPS has determined that the voltage level of the |
| | public power supply is too high, and is reducing it | | | public power supply is too high and is reducing it |
| | to the required level. The UPS continues to supply | | | to the required level. The UPS continues to supply |
| | the protected system from the public power supply. | | | the protected system from the public power supply. |
+---------+------------------------------------------------------+ +---------+------------------------------------------------------+
Table 4: UPS Status Symbols Table 4: UPS Status Symbols
5.2. Events 5.2. Events
A Management Daemon detects the occurrence of a UPS Event from a A Management Daemon detects the occurrence of a UPS event from a
change in the UPS status received from the Attachment Daemon. The change in the UPS status received from the Attachment Daemon. The
following table summarizes the process. A status of "none" means following table summarizes the process. A status of "none" means
that the status symbol is not present in the variable ups.status. that the status symbol is not present in the variable ups.status.
The Management Daemon should retrieve the variable ups.status from The Management Daemon should retrieve the variable ups.status from
the Attachment Daemon at regular intervals. If the interval is too the Attachment Daemon at regular intervals. If the interval is too
short, compute and network resources will be wasted, but if the short, compute and network resources will be wasted, but if the
interval is too large, the Management Daemon risks missing short- interval is too large, the Management Daemon risks missing short-
lived changes in the UPS status. lived changes in the UPS status.
A default value of 5 seconds is RECOMMENDED, but an implementation A default value of 5 seconds is RECOMMENDED, but an implementation
MAY make this value configurable. By default the "old" status is MAY make this value configurable. By default, the "old" status is
therefore the previous value retrieved 5 seconds ago. therefore the previous value retrieved 5 seconds ago.
Current practice is for the Management Daemon to assign names to Current practice is for the Management Daemon to assign names to
certain events. These is shown in the table in parentheses. certain events. These are shown in the table in parentheses.
+=======+=========+===============++=========+========+=============+ +=======+=========+===============++=========+========+=============+
|Old | New |Event || Old | New |Event | |Old | New |Event || Old | New |Event |
|status | status | || status | status | | |Status | Status | || Status | Status | |
+=======+=========+===============++=========+========+=============+ +=======+=========+===============++=========+========+=============+
|none | ALARM |Alarm on || ALARM | none |Alarm off | |none | ALARM |Alarm on || ALARM | none |Alarm off |
+-------+---------+---------------++---------+--------+-------------+ +-------+---------+---------------++---------+--------+-------------+
|none | BOOST |Boosting || BOOST | none |Not boosting | |none | BOOST |Boosting || BOOST | none |Not boosting |
| | |voltage || | | | | | |voltage || | | |
+-------+---------+---------------++---------+--------+-------------+ +-------+---------+---------------++---------+--------+-------------+
|none | BYPASS |Bypass on || BYPASS | none |Bypass off | |none | BYPASS |Bypass on || BYPASS | none |Bypass off |
+-------+---------+---------------++---------+--------+-------------+ +-------+---------+---------------++---------+--------+-------------+
|none | CAL |Calibrating || CAL | none |Not | |none | CAL |Calibrating || CAL | none |Not |
| | | || | |calibrating | | | | || | |calibrating |
+-------+---------+---------------++---------+--------+-------------+ +-------+---------+---------------++---------+--------+-------------+
|none | CHRG |Charging || CHRG | none |Not charging | |none | CHRG |Charging || CHRG | none |Not charging |
+-------+---------+---------------++---------+--------+-------------+ +-------+---------+---------------++---------+--------+-------------+
|none | COMM |UPS || COMM | none |See note 4 | |none | COMM |UPS || COMM | none |See note 4 |
| | |communicating || | | | | | |communicating || | | |
| | |(Event COMMOK) || | | | | | |(event COMMOK) || | | |
+-------+---------+---------------++---------+--------+-------------+ +-------+---------+---------------++---------+--------+-------------+
|none | DISCHRG |Discharging || DISCHRG | none |Not | |none | DISCHRG |Discharging || DISCHRG | none |Not |
| | | || | |discharging | | | | || | |discharging |
+-------+---------+---------------++---------+--------+-------------+ +-------+---------+---------------++---------+--------+-------------+
|none | FSD |System shutdown|| FSD | none |Shutdown | |none | FSD |System shutdown|| FSD | none |Shutdown |
| | |(Events FSD, || | |abandoned. | | | |(events FSD, || | |abandoned. |
| | |SHUTDOWN) || | |See note 1 | | | |SHUTDOWN) || | |See note 1 |
+-------+---------+---------------++---------+--------+-------------+ +-------+---------+---------------++---------+--------+-------------+
|none | LB |Low battery. || LB | none |Battery not | |none | LB |Low battery. || LB | none |Battery not |
| | |See note 2 || | |low | | | |See note 2 || | |low |
| | |(Event LOWBATT)|| | | | | | |(event LOWBATT)|| | | |
+-------+---------+---------------++---------+--------+-------------+ +-------+---------+---------------++---------+--------+-------------+
|none | NOCOMM |UPS dead? See || NOCOMM | none |See note 4 | |none | NOCOMM |UPS dead? See || NOCOMM | none |See note 4 |
| | |note 4 || | | | | | |note 4 || | | |
| | |(Events || | | | | | |(events || | | |
| | |COMMBAD, || | | | | | |COMMBAD, || | | |
| | |NOCOMM) || | | | | | |NOCOMM) || | | |
+-------+---------+---------------++---------+--------+-------------+ +-------+---------+---------------++---------+--------+-------------+
|none | OFF |UPS turned off || OFF | none |UPS not | |none | OFF |UPS turned off || OFF | none |UPS not |
| | | || | |turned off | | | | || | |turned off |
+-------+---------+---------------++---------+--------+-------------+ +-------+---------+---------------++---------+--------+-------------+
|OB | OL |Receiving power|| OL | OB |Power lost | |OB | OL |Receiving power|| OL | OB |Power lost |
| | |(Event ONLINE) || | |(Event | | | |(event ONLINE) || | |(event |
| | | || | |ONBATT) | | | | || | |ONBATT) |
+-------+---------+---------------++---------+--------+-------------+ +-------+---------+---------------++---------+--------+-------------+
|none | OVER |UPS overloaded || OVER | none |Overload gone| |none | OVER |UPS overloaded || OVER | none |Overload gone|
+-------+---------+---------------++---------+--------+-------------+ +-------+---------+---------------++---------+--------+-------------+
|none | RB |Replace battery|| RB | none |Replacement | |none | RB |Replace battery|| RB | none |Replacement |
| | |(Event || | |canceled | | | |(event || | |canceled |
| | |REPLBATT) || | | | | | |REPLBATT) || | | |
+-------+---------+---------------++---------+--------+-------------+ +-------+---------+---------------++---------+--------+-------------+
|none | TEST |Test starts || TEST | none |Test finished| |none | TEST |Test starts || TEST | none |Test finished|
+-------+---------+---------------++---------+--------+-------------+ +-------+---------+---------------++---------+--------+-------------+
|none | TICK |Heartbeat || TICK | none |No heartbeat.| |none | TICK |Heartbeat || TICK | none |No heartbeat.|
| | |event. See || | |See note 3 | | | |event. See || | |See note 3 |
| | |note 3 || | | | | | |note 3 || | | |
+-------+---------+---------------++---------+--------+-------------+ +-------+---------+---------------++---------+--------+-------------+
|none | TOCK |Heartbeat || TOCK | none |No heartbeat.| |none | TOCK |Heartbeat || TOCK | none |No heartbeat.|
| | |event. See || | |See note 3 | | | |event. See || | |See note 3 |
| | |note 3 || | | | | | |note 3 || | | |
+-------+---------+---------------++---------+--------+-------------+ +-------+---------+---------------++---------+--------+-------------+
|none | TRIM |Trimming || TRIM | none |Not trimming | |none | TRIM |Trimming || TRIM | none |Not trimming |
| | |voltage || | | | | | |voltage || | | |
+-------+---------+---------------++---------+--------+-------------+ +-------+---------+---------------++---------+--------+-------------+
Table 5: Event deduction from status changes 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 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, Notes:
the Management Daemon assumes that the UPS is "_dead_" (Event 1. Current practice does not include this event.
NOCOMM), and if the last known OL/OB status was OB a system 2. If the status OB is present, current practice takes Management
shutdown, command FSD, is called for. Daemon 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 the following: if the UPS has not
responded for 15 seconds, the Management Daemon assumes that
the UPS is _dead_ (event NOCOMM), and if the last known OL/OB
status was OB, a system shutdown (command FSD) is requested.
6. Security Considerations 6. Security Considerations
6.1. Current General Security Practice 6.1. Current General Security Practice
Experience over the last 20 years shows that new UPS management Experience over the last 20 years shows that new UPS management
software releases are not frequent, and when installed, stay software releases are not frequent and, when installed, stay
unmodified for some years. This is probably because UPS management unmodified for some years. This is probably because UPS management
is a mature activity, part of site mangement. A limited number of is a mature activity, part of site management. A limited number of
system administrators have access to the UPS hardware and software system administrators have access to the UPS hardware and software
and tend to assume a certain "security by obscurity" since many and tend to assume a certain "security by obscurity" since many
installations have a configuration as shown in figure 6 which uses installations have a configuration like the one shown in Figure 6,
port 3493/TCP (nut) between the two daemons running in the same which uses port 3493/TCP (nut) between the two daemons running in the
system. The traffic is often not encrypted, and when encrypted uses same system. The traffic is often not encrypted, and when it is
deprecated early versions of SSL/TLS. encrypted, it uses deprecated early versions of SSL/TLS.
,-----, ,--------------------,---------------------, ,-----, ,--------------------,---------------------,
| UPS |---| Attachment <-Commands Management | | UPS |---| Attachment <-Commands Management |
| |===| Daemon Responses-> Daemon | | |===| Daemon Responses-> Daemon |
/-----\ '--------------------'---------------------' /-----\ '--------------------'---------------------'
Listens on Listens on
port 3493/TCP port 3493/TCP
for localhost for localhost
Figure 6: Common single-system configuration Figure 6: Common Single-System Configuration
This situation is now changing as low cost processors become This situation is now changing as low-cost processors become
available, costing significantly less than a UPS unit. This available, costing significantly less than a UPS unit. This
evolution makes it interesting to shift to a configuration as shown evolution makes it interesting to shift to a configuration like the
in figure 7, but it also exacerbates the security weakness of figure one shown in Figure 7, but it also exacerbates the security weakness
6 since the traffic between the daemons is now over an exposed of Figure 6, since the traffic between the daemons is now over an
network. exposed network.
,-----,------------, ,--------------, ,-----,------------, ,--------------,
| UPS - Attachment | <-Commands | Management | | UPS - Attachment | <-Commands | Management |
| | Daemon | Responses-> | Daemon | | | Daemon | Responses-> | Daemon |
/-----'------------\ '--------------' /-----'------------\ '--------------'
Listens on Listens on
port 3493/TCP port 3493/TCP
Figure 7: Integration of UPS and Attachment Daemon Figure 7: Integration of UPS and Attachment Daemon
These security issues raised by UPS management are those of the power These security issues raised by UPS management are those of the power
industry in general: they are addressed in detail in IEC Technical industry in general; they are addressed in detail in IEC Technical
Specification 62351 [IEC62351-1]. In addition to equipment security, Specification 62351 [IEC62351-1]. In addition to equipment security,
cyber security is now an essential consideration. cyber security is now an essential consideration.
Quoting from IEC 62351-1[IEC62351-1], Introduction to the standard, Quoting from IEC 62351-1[IEC62351-1], Introduction to the standard,
clause 5.2.3.5: clause 5.2.3.5:
| With the computer systems for power operations presumably kept | With the computer systems for power operations presumably kept
| isolated from the Internet, many utility personnel do not see any | isolated from the Internet, many utility personnel do not see any
| reason for adding security measures to these systems. However, as | reason for adding security measures to these systems. However, as
| clearly seen from these Subclauses, this may not be true anymore | clearly seen from these Subclauses, this may not be true anymore
| as networking becomes more prevalent and additional information | as networking becomes more prevalent and additional information
| access requirements grow. | access requirements grow.
In IEC 62351-1[IEC62351-1] clause 5.3.5 lists typical security In IEC 62351-1[IEC62351-1], clause 5.3.5 lists typical security
attacks: Eavesdropping, Masquerade, Man-in-the-Middle, Replay, attacks: Eavesdropping, Masquerade, Man-in-the-Middle, Replay, and
Resource Exhaustion. RFC3552 [RFC3552] adds message insersion / Resource Exhaustion. [RFC3552] adds message insertion/deletion/
deletion / modification, and denial of service. modification and denial of service.
Let's look more closely at these requirements: Let's look more closely at these requirements:
* Eavesdropping, see Section 6.3.1 * Eavesdropping; see Section 6.3.1
* Man-in-the-Middle, see Section 6.3.2 * Man-in-the-Middle; see Section 6.3.2
* Masquerade, see Section 6.3.3 * Masquerade; see Section 6.3.3
* Message insersion, deletion, modification, see Section 6.3.4 * Message insertion, deletion, and modification; see Section 6.3.4
* Replay, see Section 6.3.5 * Replay; see Section 6.3.5
* Resource Exhaustion, Denial of Service, see Section 6.3.6 * Resource Exhaustion and Denial of Service; see Section 6.3.6
6.2. Communication Security Requirements 6.2. Communication Security Requirements
Enforcing secure communication requires tightening up the Attachment Enforcing secure communication requires tightening up the Attachment
Daemon to require the use of command STARTTLS for commands sent over Daemon to require the use of command STARTTLS for commands sent over
the global Internet. In such a situation an Attachment Daemon the global Internet. In such a situation, an Attachment Daemon
listening for traffic other than from the localhost: listening for traffic other than from localhost:
1. SHOULD require and accept command STARTTLS, 1. SHOULD require and accept command STARTTLS,
2. MUST encrypt all communication with a Management Daemon, 2. MUST encrypt all communication with a Management Daemon, and
3. SHALL refuse all non-encrypted commands except an initial 3. SHALL refuse all non-encrypted commands, except an initial
STARTTLS. STARTTLS.
Notes: Notes:
* The SHOULD rather than MUST in Section 6.2, Paragraph 2, Item 1 * The SHOULD, rather than MUST, in Section 6.2, Paragraph 2, Item 1
above allows system administrators to enforce secure communication above allows system administrators to enforce secure communication
using other techniques which do not involve the STARTTLS command. using other techniques that do not involve the STARTTLS command.
* If an Attachment Daemon requires that all commands be encrypted as * If an Attachment Daemon requires that all commands be encrypted as
required by the MUST in Section 6.2, Paragraph 2, Item 2 above, required by the MUST in Section 6.2, Paragraph 2, Item 2 above,
then automatically each Management Daemon MUST encrypt as well, then, automatically, each Management Daemon MUST encrypt as well,
since it has to do so in order to gain access. since it has to do so in order to gain access.
* The SHALL in Section 6.2, Paragraph 2, Item 3 above applies to * The SHALL in Section 6.2, Paragraph 2, Item 3 above applies to
traffic from the global Internet. An Attachment Daemon MAY accept traffic from the global Internet. An Attachment Daemon MAY accept
unencrypted commands from localhost if the local installation's unencrypted commands from localhost if the local installation's
security practices allow it, for example in a dedicated appliance. security practices allow it, for example, in a dedicated
appliance.
Firewalls SHOULD be used to restrict the communication between the Firewalls SHOULD be used to restrict the communication between the
Attachment Daemon and the accepted Management Daemons, prohibiting Attachment Daemon and the accepted Management Daemons, prohibiting
and discarding traffic from any systems that are not part of the and discarding traffic from any systems that are not part of the
envisioned power management setup. Note: See Section 6.2, Paragraph envisioned power management setup. Note: See Section 6.2, Paragraph
4, Item 1 above on the use of SHOULD. 4, Item 1 above on the use of SHOULD.
6.2.1. Certificate security 6.2.1. Certificate Security
In long-lived installations such as those found in UPS management, In long-lived installations, such as those found in UPS management,
careful certificate management is essential, whether the certificate careful certificate management is essential, whether the certificate
is provided by a Certificate Authority, or is a self-signed is provided by a Certificate Authority or is a self-signed
certificate. For example the specification of expiration times of certificate. For example, the expiration times of both the
both the certificate containing the public key and the signing certificate containing the public key and the signing certificate
certificate. should be specified.
6.3. Attacks and Defences 6.3. Attacks and Defenses
6.3.1. Eavesdropping 6.3.1. Eavesdropping
The defence against eavesdropping is encryption of the commands and The defense against eavesdropping is encryption of the commands and
responses passed between client Management Daemon and server responses passed between the client Management Daemon and server
Attachment Daemon. The protocol provides command STARTTLS, see Attachment Daemon. The protocol provides command STARTTLS, see
Section 4.2.12, which calls on the Attachment Daemon to support TLS Section 4.2.12, which calls on the Attachment Daemon to support TLS
encryption of the communication. If this command is accepted, the encryption of the communication. If this command is accepted, the
Management Daemon also encrypts. Management Daemon also encrypts.
In current NUT Project practice, the use of TLS is optional, however In current NUT Project practice, the use of TLS is optional; however,
a Management Daemon may refuse to accept unencrypted communication. a Management Daemon may refuse to accept unencrypted communication.
This is done by setting declarations FORCESSL to 1 and CERTVERIFY to This is done by setting declarations FORCESSL to 1 and CERTVERIFY to
1 in the Management Daemon configuration file. 1 in the Management Daemon configuration file.
6.3.1.1. Misplaced declarations requiring TLS 6.3.1.1. Misplaced Declarations Requiring TLS
A further weakness is that the FORCESSL and CERTVERIFY declarations A further weakness is that the FORCESSL and CERTVERIFY declarations,
which enforce use of encryption are in the client Management Daemon which enforce use of encryption, are in the client Management Daemon
configuration file and not in the Attachment Daemon. Secure practice configuration file and not in the Attachment Daemon. Secure practice
requires enforcement by the server Attachment Daemon rather than a requires enforcement by the server Attachment Daemon, rather than a
possibly rogue client Management Daemon out on the Internet. possibly rogue client Management Daemon out on the Internet.
This weakness may be mitigated with strict firewall rules which would This weakness may be mitigated with strict firewall rules that would
prevent the rogue client Management Daemon from accessing the prevent the rogue client Management Daemon from accessing the
Attachment Daemon. Attachment Daemon.
6.3.1.2. Weak protection in previous version 2.7.4 6.3.1.2. Weak Protection in Previous Version 2.7.4
Although version 2.8.0 of NUT supports TLS 1.3 [RFC8446] with X.509 Although version 2.8.0 of NUT supports TLS 1.3 [RFC8446] with X.509
v3 certificates as defined by RFC5280 [RFC5280], previous version v3 certificates as defined by [RFC5280], previous version 2.7.4 only
2.7.4 only supported earlier SSL/TLS versions. To overcome this supported earlier SSL/TLS versions. To overcome this weakness, The
weakness, The following techniques have been used: following techniques have been used:
* Shims, see Appendix D.1 * Shims; see Appendix D.1
* TLS tunnel, see Appendix D.2 * TLS tunnel; see Appendix D.2
* Virtual Private Network, VPN, see Appendix D.3 * Virtual Private Network (VPN); see Appendix D.3
* Virtual Local Area network, VLAN, see Appendix D.4 * Virtual Local Area Network (VLAN); see Appendix D.4
6.3.2. Man in the Middle 6.3.2. Man-in-the-Middle
The protocol relies on TLS encryption to prevent man-in-the-middle The protocol relies on TLS encryption to prevent man-in-the-middle
attacks. See Appendix D for defense methods used for previous NUT attacks. See Appendix D for defense methods used for previous NUT
version 2.7.4. version 2.7.4.
6.3.3. Masquerade Attack: Agent Verification 6.3.3. Masquerade Attack: Agent Verification
The protocol allows a malicious client acting as an Management Daemon The protocol allows a malicious client acting as a Management Daemon
to send command FSD to an Attachment Daemon to shut down a working to send command FSD to an Attachment Daemon to shut down a working
system and it's power supply as described in The Shutdown Story, see system and its power supply, as described in The Shutdown Story
Appendix B. Similarly, a malicious client could turn off the UPS section (see Appendix B). Similarly, a malicious client could turn
power outlets causing the system to fail. off the UPS power outlets, causing the system to fail.
The protocol provides commands USERNAME, see Section 4.2.13, and The protocol provides commands USERNAME (see Section 4.2.13) and
PASSWORD, see Section 4.2.8, which allow an administrative user in a PASSWORD (see Section 4.2.8), which allow an administrative user in a
Management Daemon to authenticate itself to the Attachment Daemon, as Management Daemon to authenticate itself to the Attachment Daemon, as
a defence against masquerade attacks. The administrative user name a defense against masquerade attacks. The administrative username
and password need protection against local malicious users. This is and password need protection against local malicious users. This is
done by restricting access to the configuration files. done by restricting access to the configuration files.
6.3.4. Message insertion, deletion, modification 6.3.4. Message Insertion, Deletion, and Modification
The protocol relies on TLS encryption to prevent message insertion, The protocol relies on TLS encryption to prevent message insertion,
deletion and modification attacks. See Appendix D for defense deletion, and modification attacks. See Appendix D for defense
methods used for previous NUT version 2.7.4. methods used for previous NUT version 2.7.4.
6.3.5. Replay 6.3.5. Replay
There are two cases: There are two cases:
1. The replay is from a system other than an approved Management 1. The replay is from a system other than an approved Management
Daemon: the protocol relies on a firewall to block the traffic. Daemon, i.e., the protocol relies on a firewall to block the
traffic.
2. The replay is from an approved Management Daemon: the protocol 2. The replay is from an approved Management Daemon. i.e., the
relies on the Management Daemon's own security to prevent protocol relies on the Management Daemon's own security to
unauthorised access. prevent unauthorized access.
6.3.6. Denial of Service 6.3.6. Denial of Service
The protocol relies on a very tightly specified firewall to prevent The protocol relies on a very tightly specified firewall to prevent
denial of service attacks. Only designated client Management Daemons denial-of-service attacks. Only designated client Management Daemons
should be able to reach the server Attachment Daemon. should be able to reach the server Attachment Daemon.
7. IANA Considerations 7. IANA Considerations
The protocol specified by this text runs over port 3493/TCP (nut) The protocol specified by this text runs over port 3493/TCP (nut),
registered by the NUT (Network UPS Tools) project. which is registered by the Network UPS Tools (NUT) Project.
This document will be added to the registration's reference field. This document has been added to the registration's Reference field in
the "Service Name and Transport Protocol Port Number Registry"
[Registry].
8. Implementation Status 8. Implementation Status
This section presents a very short summary of the status of the This section presents a very short summary of the status of the
Network UPS Tools project. Network UPS Tools project.
* May 1996: The first hack as a cron job. * May 1996: The first hack as a cron job.
* September 1997: The first server-client code. * September 1997: The first server-client code.
* March 1998: First public release. * March 1998: First public release.
* June 1999: Code rewrite with a UPS driver smartups, an Attachment * June 1999: Code rewrite with a UPS Driver smartups, an Attachment
Daemon upsd and a simple Management Daemon. Daemon upsd, and a simple Management Daemon.
* September 1999: The project became "Network UPS Tools". The * September 1999: The project became "Network UPS Tools". The
Management Daemon upsmon supported primary/secondary Management Daemon upsmon supported Primary/Secondary
configurations. configurations.
* June 2001: Common core for multiple drivers. * June 2001: Common core for multiple Drivers.
* May 2002: IANA granted port 3493/TCP (nut). August: release * May 2002: IANA granted port 3493/TCP (nut). August: release
1.0.0. November: OpenSSL support. 1.0.0. November: OpenSSL support.
* April 2003: The initial set of command and variable names was * April 2003: The initial set of command and variable names was
designed. designed.
* February 2005: Arnaud Quette took over the project lead from * February 2005: Arnaud Quette took over the project lead from
Russell Kroll. Russell Kroll.
* March 2016: Version 2.7.4 released, supported over 100 device * March 2016: Version 2.7.4 released, supported over 100 device
manufacturers and hundreds of UPS models. manufacturers and hundreds of UPS models.
* November 2020: Evgeny "Jim" Klimov took over project lead from * November 2020: Evgeny "Jim" Klimov took over project lead from
Arnaud Quette. Arnaud Quette.
* May 2022: Version 2.8.0 released, supporting protocol version 1.3. * May 2022: Version 2.8.0 released, supporting protocol version 1.3.
See [githist] and [History] for a detailed history of the NUT See [githist] and Appendix J [History] for a detailed history of the
Project. NUT Project.
8.1. Inclusion in Software Distributions 8.1. Inclusion in Software Distributions
The programs upsd, upsmon, upssched, upsc, upscmd and upsrw have been The programs upsd, upsmon, upssched, upsc, upscmd, and upsrw have
included in the package known as "nut" in the package systems of many been included in the package known as "nut" in the package systems of
distributions: all the major Linux distributions, and Unix many distributions, i.e., all the major Linux distributions and Unix
distributions such as OpenBSD and OpenSolaris. A Microsoft Windows distributions, such as OpenBSD and OpenSolaris. A Microsoft Windows
version has been developed but was not maintained. version has been developed but was not maintained.
8.2. Recommended Minimum Support 8.2. Recommended Minimum Support
The features provided by current UPS units vary widely. However The features provided by current UPS units vary widely. However,
experience shows that a minimum feature set is needed for experience shows that a minimum feature set is needed for
satisfactory use of the NUT Project software. A full list of satisfactory use of the NUT Project software. A full list of
variables is available in source code file docs/nut-names.txt variables is available in source code file docs/nut-names.txt
[gitvars] which serves as the Recording Document. [gitvars], which serves as the Recording Document.
8.2.1. Desktop PC Variables 8.2.1. Desktop PC Variables
The following variables form a minimum set suitable for Desktop PC. The following variables form a minimum set suitable for a desktop PC.
It is expected that on public power supply failure, the PC will be It is expected that, on public power supply failure, the PC will be
halted. It will not restart automatically when power returns. halted. It will not restart automatically when power returns.
* battery.charge * battery.charge
* battery.charge.low * battery.charge.low
* device.mfr * device.mfr
* device.model * device.model
* ups.status with the minimum status symbol set OL OB LB FSD, see * ups.status with the minimum status symbol set OL OB LB FSD; see
Section 5.1. Section 5.1
8.2.2. Unattended Servers, Additional Variables 8.2.2. Unattended Servers and Additional Variables
The following additional variables are needed in a minimum set The following additional variables are needed in a minimum set
suitable for an unattended server. It is expected that on public suitable for an unattended server. It is expected that, on public
power supply failure, the server will be halted. It will restart power supply failure, the server will be halted. It will restart
automatically when power returns. automatically when power returns.
* battery.date * battery.date
* device.serial * device.serial
* ups.delay.shutdown * ups.delay.shutdown
* ups.delay.start * ups.delay.start
8.2.3. Commands and other Technical Terms 8.2.3. Commands and Other Technical Terms
Satisfactory use of the NUT Project software requires support for all Satisfactory use of the NUT Project software requires support for all
the commands specified in protocol version 1.3, software version the commands specified in protocol version 1.3, software version
2.8.0. 2.8.0.
8.2.4. Support for Earlier Versions 8.2.4. Support for Earlier Versions
In order to ease migration from software version 2.7.4 which In order to ease migration from software version 2.7.4, which
supported protocol version 1.2, software version 2.8.0 also supports supported protocol version 1.2, software version 2.8.0 also supports
the technical terms used in protocol version 1.2. See Appendix C for the technical terms used in protocol version 1.2. See Appendix C for
the differences. the differences.
9. Acknowledgments 9. References
This document is based on the NUT Project documentation [devguide].
The editor acknowledges the work of Charles Lepple, Arjen de Korte,
Arnaud Quette, Jim Klimov, Russell Kroll, Manuel Wolfshant, Greg
Troxel, Mark Hansen and many others who contribute to the nut-upsuser
[nut-upsuser]. and nut-upsdev [nut-upsdev] mailing lists.
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]. Unlike
XML, SGML offers markup minimisation, and the source document takes
advantage of this. The osgmlnorm [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.
Many helpful comments were received from Eliot Lear, Bart Smit, David
Zomaya, Joyce Norris, and Ted Mittelstaedt.
10. Normative References 9.1. Normative References
[RFC0020] Cerf, V., "ASCII format for network interchange", STD 80, [RFC0020] Cerf, V., "ASCII format for network interchange", STD 80,
RFC 20, DOI 10.17487/RFC0020, October 1969, RFC 20, DOI 10.17487/RFC0020, October 1969,
<https://www.rfc-editor.org/info/rfc20>. <https://www.rfc-editor.org/info/rfc20>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
skipping to change at page 45, line 27 skipping to change at line 2067
<https://www.rfc-editor.org/info/rfc5234>. <https://www.rfc-editor.org/info/rfc5234>.
[RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF",
RFC 7405, DOI 10.17487/RFC7405, December 2014, RFC 7405, DOI 10.17487/RFC7405, December 2014,
<https://www.rfc-editor.org/info/rfc7405>. <https://www.rfc-editor.org/info/rfc7405>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>. May 2017, <https://www.rfc-editor.org/info/rfc8174>.
11. Informative References 9.2. Informative References
[devguide] "Network UPS Tools (NUT) Project Developer Guide", [C2ndEd] Kernighan, B. and D. Ritchie, "The C Programming
Language", 2nd edition, Prentice Hall Software Series,
ISBN 0-13-110362-8, 1988.
[devguide] Kroll, R., Quette, A., Lepple, C., and P. Selinger,
"Network UPS Tools Project Developer Guide",
<https://networkupstools.org/docs/developer-guide.chunked/ <https://networkupstools.org/docs/developer-guide.chunked/
ar01s09.html>. ar01s09.html>.
[Documentation] [Documentation]
"Network UPS Tools Documentation", "Network UPS Tools Documentation",
<https://networkupstools.org/documentation.html>. <https://networkupstools.org/documentation.html>.
[githist] "GitHub Network UPS Tools code repository, project [githist] "The Network UPS Tools repository, project history", July
history", 2022,
<https://github.com/networkupstools/nut/blob/master/docs/ <https://github.com/networkupstools/nut/blob/master/docs/
history.txt>. history.txt>.
[gitstats] "GitHub Network UPS Tools code repository, status names", [gitvars] "The Network UPS Tools repository, variable names", April
<https://github.com/networkupstools/nut/blob/master/ 2022,
clients/status.h>.
[gitvars] "GitHub Network UPS Tools code repository, variable
names",
<https://github.com/networkupstools/nut/blob/master/docs/ <https://github.com/networkupstools/nut/blob/master/docs/
nut-names.txt>. nut-names.txt>.
[History] "Network UPS Tools User Manual, Appendix J Project [History] Kroll, R., Quette, A., and A. de Korte, "Network UPS Tools
history", User Manual", May 2022,
<https://networkupstools.org/docs/user-manual.pdf>. <https://networkupstools.org/docs/user-manual.pdf>.
[HyTimeA] "International Standard ISO/IEC 10744 -- Hypermedia/Time- [HyTimeA] ISO/IEC, "Information technology -- Hypermedia/Time-based
based Structuring Language, Annex A, SGML Extended Structuring Language (HyTime)", ISO/IEC 10744:1997, August
Facilities", ISO/IEC JTC 1/SC 34 Document description and 1997.
processing languages, 1997.
[IEC62351-1] [IEC62351-1]
"IEC TS 62351-1 Power systems management and associated IEC, "Power systems management and associated information
information exchange -- Data and communications security. exchange -- Data and communications security. Part 1:
Part 1: Communication network and system security -- Communication network and system security -- Introduction
Introduction to security issues", IEC Technical to security issues", 35 pages, TC 57 - Power systems
Specification Reference number IEC/TS 62351-1:2007(E), 35 management and associated information exchange, IEC TS
pages, CHF 205, Technical Committee TC 57 - Power systems 62351-1:2007, May 2007, <https://nanopdf.com/download/
management and associated information exchange, 15 May technical-iec-specification-ts-62351-1_pdf>.
2007, <https://nanopdf.com/download/technical-iec-
specification-ts-62351-1_pdf>.
[Library] "GitHub Network UPS Tools, Devices Dumps Library", [Library] "Devices Dumps Library",
<https://networkupstools.org/ddl/>. <https://networkupstools.org/ddl/>.
[NUT] "Network UPS Tools (NUT) Project", [NUT] "Network UPS Tools, Devices Dumps Library",
<https://www.networkupstools.org>. <https://www.networkupstools.org>.
[nut-repository] [nut-repository]
"GitHub Repository for the Network UPS Tools (NUT) "The Network UPS Tools repository",
Project", <https://github.com/networkupstools/nut/>. <https://github.com/networkupstools/nut/>.
[nut-upsdev] [nut-upsdev]
"Network UPS Tools (NUT) Project Mailing List for NUT, "Network UPS Tools (NUT) Project Mailing List for
developers", <https://alioth-lists.debian.net/cgi- Developers", <https://alioth-lists.debian.net/cgi-
bin/mailman/listinfo/nut-upsdev>. bin/mailman/listinfo/nut-upsdev>.
[nut-upsuser] [nut-upsuser]
"Network UPS Tools (NUT) Project Mailing List for users", NUT, "Network UPS Tools (NUT) Project Mailing List for
<https://alioth-lists.debian.net/cgi-bin/mailman/listinfo/ Users", <https://alioth-lists.debian.net/cgi-
nut-upsuser>. bin/mailman/listinfo/nut-upsuser>.
[Registry] "Service Name and Transport Protocol Port Number [Registry] IANA, "Service Name and Transport Protocol Port Number
Registry", Publisher: IANA, Registry", <https://www.iana.org/assignments/service-
<https://www.iana.org/assignments/service-names-port- names-port-numbers/service-names-port-numbers.xhtml>.
numbers/service-names-port-numbers.xhtml>.
[RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC [RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC
Text on Security Considerations", BCP 72, RFC 3552, Text on Security Considerations", BCP 72, RFC 3552,
DOI 10.17487/RFC3552, July 2003, DOI 10.17487/RFC3552, July 2003,
<https://www.rfc-editor.org/info/rfc3552>. <https://www.rfc-editor.org/info/rfc3552>.
[RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S.,
Housley, R., and W. Polk, "Internet X.509 Public Key Housley, R., and W. Polk, "Internet X.509 Public Key
Infrastructure Certificate and Certificate Revocation List Infrastructure Certificate and Certificate Revocation List
(CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008,
<https://www.rfc-editor.org/info/rfc5280>. <https://www.rfc-editor.org/info/rfc5280>.
[RFC7030] Pritikin, M., Ed., Yee, P., Ed., and D. Harkins, Ed., [RFC7030] Pritikin, M., Ed., Yee, P., Ed., and D. Harkins, Ed.,
"Enrollment over Secure Transport", RFC 7030, "Enrollment over Secure Transport", RFC 7030,
DOI 10.17487/RFC7030, October 2013, DOI 10.17487/RFC7030, October 2013,
<https://www.rfc-editor.org/info/rfc7030>. <https://www.rfc-editor.org/info/rfc7030>.
[RFC7991] Hoffman, P., "The "xml2rfc" Version 3 Vocabulary", [RFC7991] Hoffman, P., "The "xml2rfc" Version 3 Vocabulary",
RFC 7991, December 2016, RFC 7991, DOI 10.17487/RFC7991, December 2016,
<https://www.rfc-editor.org/info/rfc7991>. <https://www.rfc-editor.org/info/rfc7991>.
[RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol
Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
<https://www.rfc-editor.org/info/rfc8446>. <https://www.rfc-editor.org/info/rfc8446>.
[RFC8894] Gutmann, P., "Simple Certificate Enrolment Protocol", [RFC8894] Gutmann, P., "Simple Certificate Enrolment Protocol",
RFC 8894, DOI 10.17487/RFC8894, September 2020, RFC 8894, DOI 10.17487/RFC8894, September 2020,
<https://www.rfc-editor.org/info/rfc8894>. <https://www.rfc-editor.org/info/rfc8894>.
[SGML] Goldfarb, Charles F., "The SGML Handbook", [SGML] Goldfarb, C., "The SGML Handbook", Oxford University
ISBN 0-19-853737-9, 1990. Press, ISBN-10 0-19-853737-9, 1990.
[sgmlnorm] Clark, James., "SGMLNORM An SGML System Conforming to [sgmlnorm] OpenJade Project, "OpenJade Distribution Page",
International Standard ISO 8879 -- Standard Generalized <http://openjade.sourceforge.net/>.
Markup Language", <http://www.jclark.com/sp/sgmlnorm.htm>.
[stunnel] Trojnara, Michal., "Stunnel proxy adds TLS encryption [stunnel] "Stunnel", <https://www.stunnel.org/>.
functionality to existing clients and servers",
<https://www.stunnel.org/>.
Appendix A. Variables Appendix A. Variables
The UPS variables represent the abstracted state of the UPS unit. The UPS variables represent the abstracted state of the UPS unit.
Certain variables represent not only the state of some hardware Certain variables represent not only the state of some hardware
feature, but also provide tunable values and instant commands, see feature but also provide tunable values and Instant Commands; see
Section 2.5. The full set of variables is recorded in the reference Section 2.5. The full set of variables is recorded in the reference
document for variable names [gitvars]. document for variable names [gitvars].
The number of variables used in a given deployment depends on the The number of variables used in a given deployment depends on the
sophistication of the UPS product: this annex shows a typical example sophistication of the UPS product; this annex shows a typical example
of the subset of variables used for a reasonably complete "consumer of the subset of variables used for a reasonably complete "consumer
grade" UPS. The NUT Project maintains a large library of the grade" UPS. The NUT Project maintains a large library of the
variable subsets [Library] used by different UPS models. variable subsets [Library] used by different UPS models.
Note that successive versions of a given product may add or delete Note that successive versions of a given product may add or delete
features causing a change in the subset of variables used. An features, causing a change in the subset of variables used. An
example is the removal of ups.delay.start from a "consumer grade" example is the removal of ups.delay.start from a "consumer grade"
UPS. The manufacturer reserves the feature for the "professional" UPS. The manufacturer reserves the feature for the "professional"
product. product.
An implementation of a Management Daemon acting as a utility program An implementation of a Management Daemon acting as a utility program
may provide a listing of the variables available for a given product, may provide a listing of the variables available for a given product,
for example utility program upsc as included in the NUT package, see for example, utility program upsc, as included in the NUT package;
Section 2.6, Paragraph 3. see Section 2.6, Paragraph 3.
The following sections illustrate the use of variables by taking the The following sections illustrate the use of variables by taking the
values associated with a typical product. The example is a 1600Va values associated with a typical product. The example is a 1600 Va
1000W UPS. 1000 W UPS.
A.1. Typical UPS Variables A.1. Typical UPS Variables
+===============================+============+====================+ +===============================+============+====================+
| Variable | Typical | Default | | Variable | Typical | Default |
| | value | description | | | Value | Description |
+===============================+============+====================+ +===============================+============+====================+
| battery.charge | 100 | "Battery charge | | battery.charge | 100 | "Battery charge |
| | | (percent of full)" | | | | (percent of full)" |
+-------------------------------+------------+--------------------+ +-------------------------------+------------+--------------------+
| battery.charge.low | 20 | "Remaining battery | | battery.charge.low | 20 | "Remaining battery |
| | | level when UPS | | | | level when UPS |
| | | switches to LB | | | | switches to LB |
| | | (percent)" | | | | (percent)" |
+-------------------------------+------------+--------------------+ +-------------------------------+------------+--------------------+
| battery.runtime | 1481 | "Battery runtime | | battery.runtime | 1481 | "Battery runtime |
skipping to change at page 52, line 7 skipping to change at line 2369
| | | started (seconds)" | | | | started (seconds)" |
+-------------------------------+------------+--------------------+ +-------------------------------+------------+--------------------+
| ups.vendorid | 0999 | "Vendor ID for USB | | ups.vendorid | 0999 | "Vendor ID for USB |
| | | devices" | | | | devices" |
+-------------------------------+------------+--------------------+ +-------------------------------+------------+--------------------+
Table 6: Typical UPS Variables Table 6: Typical UPS Variables
A.2. Typical UPS Readable and Writable Variables A.2. Typical UPS Readable and Writable Variables
Some of the features of a UPS are represented by variables which may Some of the features of a UPS are represented by variables that may
be tuned by the user. The following variables are typical of such be tuned by the user. The following variables are typical of such
tunable features. The precise list depends on the model of UPS. An tunable features. The precise list depends on the model of UPS. An
implementation of a Management Daemon acting as a utility program may implementation of a Management Daemon acting as a utility program may
provide a listing of the variables available, as well as acting on provide a listing of the variables available, as well as acting on
them, for example utility program upsrw as included in the NUT them, for example, utility program upsrw, as included in the NUT
package, see Section 2.6, Paragraph 3. package; see Section 2.6, Paragraph 3.
+========================+============+=========================+ +========================+============+=========================+
| Variable | Typical | Default description | | Variable | Typical | Default Description |
| | value | provided as response to | | | Value | Provided as Response to |
| | | the command GET DESC | | | | the Command GET DESC |
+========================+============+=========================+ +========================+============+=========================+
| battery.charge.low | 20 | "Remaining battery | | battery.charge.low | 20 | "Remaining battery |
| | | level when UPS switches | | | | level when UPS switches |
| | | to LB (percent)" | | | | to LB (percent)" |
+------------------------+------------+-------------------------+ +------------------------+------------+-------------------------+
| input.transfer.high | 264 | "High voltage transfer | | input.transfer.high | 264 | "High voltage transfer |
| | | point (V)" | | | | point (V)" |
+------------------------+------------+-------------------------+ +------------------------+------------+-------------------------+
| input.transfer.low | 184 | "Low voltage transfer | | input.transfer.low | 184 | "Low voltage transfer |
| | | point (V)" | | | | point (V)" |
skipping to change at page 53, line 46 skipping to change at line 2418
+------------------------+------------+-------------------------+ +------------------------+------------+-------------------------+
| ups.delay.shutdown | 20 | "Interval to wait after | | ups.delay.shutdown | 20 | "Interval to wait after |
| | | shutdown with delay | | | | shutdown with delay |
| | | command (seconds)" | | | | command (seconds)" |
+------------------------+------------+-------------------------+ +------------------------+------------+-------------------------+
| ups.delay.start | 30 | "Interval to wait | | ups.delay.start | 30 | "Interval to wait |
| | | before (re)starting the | | | | before (re)starting the |
| | | load (seconds)" | | | | load (seconds)" |
+------------------------+------------+-------------------------+ +------------------------+------------+-------------------------+
Table 7: Typical readable and writable UPS Variables Table 7: Typical Readable and Writable UPS Variables
A.3. Typical UPS Instant Commands A.3. Typical UPS Instant Commands
Some of the features of a UPS are actions known as instant commands, Some of the features of a UPS are actions known as Instant Commands
see Section 2.5, which may be ordered by the user. The following (see Section 2.5), which may be ordered by the user. The following
variables represent such instant commands. The precise list depends variables represent such Instant Commands. The precise list depends
on the model of UPS. An implementation of a Management Daemon acting on the model of UPS. An implementation of a Management Daemon acting
as a utility program may provide a listing of the variables as a utility program may provide a listing of the variables
available, as well as acting on them, for example utility program available, as well as acting on them, for example, utility program
upscmd as included in the NUT package, see Section 2.6, Paragraph 3. upscmd, as included in the NUT package; see Section 2.6, Paragraph 3.
+==================+==========================================+ +==================+==========================================+
| Command | Meaning | | Command | Meaning |
+==================+==========================================+ +==================+==========================================+
| beeper.disable | Disable the UPS beeper | | beeper.disable | Disable the UPS beeper |
+------------------+------------------------------------------+ +------------------+------------------------------------------+
| beeper.enable | Enable the UPS beeper | | beeper.enable | Enable the UPS beeper |
+------------------+------------------------------------------+ +------------------+------------------------------------------+
| beeper.mute | Temporarily mute the UPS beeper | | beeper.mute | Temporarily mute the UPS beeper |
+------------------+------------------------------------------+ +------------------+------------------------------------------+
skipping to change at page 55, line 14 skipping to change at line 2476
,------------------SERVER------------------, ,------------------SERVER------------------,
| | | | | |
,-----, | UPS <-Commands UPS | ,-----, | UPS <-Commands UPS |
| UPS |---| Attachment | Management | | UPS |---| Attachment | Management |
| |===| Daemon Responses-> Daemon | | |===| Daemon Responses-> Daemon |
/-----\ '--------------------'---------------------' /-----\ '--------------------'---------------------'
Internal Internal
loopback loopback
Figure 8: Long-running unattended server Figure 8: Long-Running Unattended Server
1. _The public power supply is on_ -- The system runs normally. 1. _The public power supply is on._ The system runs normally.
Every 5 seconds, variable ups.status reports OL. -- _Days, Every 5 seconds, variable ups.status reports OL. _Days, weeks,
weeks, months go by..._ months go by..._
2. _Winter storm. Tree falls on power lines. The public power 2. _Winter storm. Tree falls on power lines. The public power
supply fails_ -- The server remains operational running on the supply fails._ The server remains operational, running on the
UPS battery. The Management Daemon polls the Attachment Daemon, UPS battery. The Management Daemon polls the Attachment Daemon
and detects status change OL->OB. and detects status change OL->OB.
3. The Management Daemon logs warning messages. The server is 3. The Management Daemon logs warning messages. The server is
still operational running on the UPS battery. -- _Minutes go still operational, running on the UPS battery. _Minutes go
by..._ by..._
4. The battery discharges below the level specified by variable 4. The battery discharges below the level specified by variable
battery.charge.low. The server remains operational, but the UPS battery.charge.low. The server remains operational, but the UPS
battery will not last much longer. The Management Daemon polls battery will not last much longer. The Management Daemon polls
the Attachment Daemon, and detects status change OB->OB+LB. the Attachment Daemon and detects status change OB->OB+LB.
5. The Management Daemon logs the low battery event. 5. The Management Daemon logs the low battery event.
6. The Management Daemon decides to call for a system shutdown. It 6. The Management Daemon decides to call for a system shutdown. It
sets status FSD in the Attachment Daemon to call on any sets status FSD in the Attachment Daemon to call on any
secondaries to shut down and waits for command GET NUMATTACH to Secondaries to shut down and waits for command GET NUMATTACH to
report one single attachment, i.e. the Primary itself. The report one single attachment, i.e., the Primary itself. The
Management Daemon then issues the system shutdown command for Management Daemon then issues the system shutdown command for
itself. itself.
7. The operating system's shutdown process takes over. During the 7. The operating system's shutdown process takes over. During the
system shutdown, a NUT Project specific script or an equivalent system shutdown, a specific script to the NUT Project or an
systemd service unit runs the command upsdrvctl shutdown. This equivalent system service unit runs the command upsdrvctl
tells the UPS that it is to shut down N seconds later where the shutdown. This tells the UPS that it is to shut down N seconds
default is N=20. Note that the "shutdown" of a UPS removes later where the default is N=20. Note that the "shutdown" of a
power from the outlet sockets, but may not turn the UPS off UPS removes power from the outlet sockets but may not turn the
completely. A delayed shutdown is sometimes audible, and the UPS off completely. A delayed shutdown is sometimes audible,
characteristic beeping of the UPS stops. and the characteristic beeping of the UPS stops.
8. The system shuts down and powers down, hopefully before the N=20 8. The system shuts down and powers down, hopefully before the N=20
seconds have passed. seconds have passed.
9. _N seconds after item 7_ -- The UPS shuts down, i.e., it turns 9. _N seconds after item 7_ The UPS shuts down, i.e., it turns off
off its outlet sockets when N=20 seconds have passed. With some its outlet sockets when N=20 seconds have passed. With some UPS
UPS units, there is an audible "clunk". units, there is an audible "clunk".
What if the public power supply returns before the UPS shuts What if the public power supply returns before the UPS shuts
down? The UPS unit should be able to wait a configurable time down? The UPS unit should be able to wait a configurable time
with default 30 seconds. These two timers start from the moment with default 30 seconds. These two timers start from the moment
the UPS receives the upsdrvctl shutdown command. -- _Minutes, the UPS receives the upsdrvctl shutdown command. _Minutes,
hours, days go by..._ hours, days go by..._
10. _Some time later, maybe much later, the public power supply 10. _Some time later, maybe much later, the public power supply
returns_ -- The UPS reconnects it's outlets to send power to the returns._ The UPS reconnects its outlets to send power to the
protected system. protected system.
11. The system BIOS option "Restore power on AC return" or "Restore 11. The system BIOS option "Restore power on AC return" or "Restore
to previous state" has hopefully been selected and the system to previous state" has hopefully been selected and the system
powers up. The bootstrap process of the operating system powers up. The bootstrap process of the operating system
begins. begins.
12. The operating system starts the Attachment Daemon and the 12. The operating system starts the Attachment Daemon and the
Management Daemon. The Attachment Daemon starts the Driver and Management Daemon. The Attachment Daemon starts the Driver and
scans the UPS. The UPS status becomes OL+LB. scans the UPS. The UPS status becomes OL+LB.
13. After some time, the battery charges above the 13. After some time, the battery charges above the
battery.charge.low threshold and the Attachment Daemon declares battery.charge.low threshold, and the Attachment Daemon declares
the status change OL+LB->OL. We are now back in the same the status change OL+LB->OL. We are now back in the same
situation as 1 above. situation as item 1 above.
Appendix C. Technical Terms: Historical Differences Appendix C. Technical Terms: Historical Differences
This appendix lists the major differences between the technical terms This appendix lists the major differences between the technical terms
used in NUT software release 2.8.0 and documented in this text, and used in NUT software release 2.8.0 and documented in this text, as
those used in previous version 2.7.4 of the NUT Project. well as those used in previous version 2.7.4 of the NUT Project.
+===================+========================+===========+ +===================+========================+===========+
| Term in previous | Term in this document, | Reference | | Term in Previous | Term in this Document, | Reference |
| release NUT 2.7.4 | release NUT 2.8.0 | | | Release NUT 2.7.4 | Release NUT 2.8.0 | |
+===================+========================+===========+ +===================+========================+===========+
| ALREADY-LOGGED-IN | ALREADY-ATTACHED | Table 3 | | ALREADY-LOGGED-IN | ALREADY-ATTACHED | Table 3 |
+-------------------+------------------------+-----------+ +-------------------+------------------------+-----------+
| ALREADY-SSL-MODE | TLS-ALREADY-ENABLED | Table 3 | | ALREADY-SSL-MODE | TLS-ALREADY-ENABLED | Table 3 |
+-------------------+------------------------+-----------+ +-------------------+------------------------+-----------+
| LOGIN | ATTACH | Section | | LOGIN | ATTACH | Section |
| | | 4.2.1 | | | | 4.2.1 |
+-------------------+------------------------+-----------+ +-------------------+------------------------+-----------+
| LOGOUT | DETACH | Section | | LOGOUT | DETACH | Section |
| | | 4.2.2 | | | | 4.2.2 |
skipping to change at page 57, line 32 skipping to change at line 2578
| NETVER | PROTVER | Section | | NETVER | PROTVER | Section |
| | | 4.2.10 | | | | 4.2.10 |
+-------------------+------------------------+-----------+ +-------------------+------------------------+-----------+
| NUMLOGINS | NUMATTACH | Section | | NUMLOGINS | NUMATTACH | Section |
| | | 4.2.4.3 | | | | 4.2.4.3 |
+-------------------+------------------------+-----------+ +-------------------+------------------------+-----------+
| Slave | Secondary | Section | | Slave | Secondary | Section |
| | | 2.8 | | | | 2.8 |
+-------------------+------------------------+-----------+ +-------------------+------------------------+-----------+
Table 9 Table 9: Technical Terms: Historical Differences
Appendix D. Security Defences in Release 2.7.4 Appendix D. Security Defenses in Release 2.7.4
Previous NUT version 2.7.4 did not provide support for TLS 1.3 Previous NUT version 2.7.4 did not provide support for TLS 1.3
[RFC8446]. The following subsections describe mitigating techniques. [RFC8446]. The following subsections describe mitigating techniques.
D.1. Shims D.1. Shims
Previous version 2.7.4 of NUT did not support TLS 1.3 [RFC8446]. Previous version 2.7.4 of NUT did not support TLS 1.3 [RFC8446].
Where such protection is needed for version 2.7.4, a possible Where such protection is needed for version 2.7.4, a possible
technique introduces shims between the Attachment Daemon and the technique introduces shims between the Attachment Daemon and the
network, and between the network and the Management Daemon as shown network and between the network and the Management Daemon, as shown
in figure 9. These shims provide TLS 1.3 support, thus allowing the in Figure 9. These shims provide TLS 1.3 support, thus allowing the
Attachment Daemon and Management Daemon to continue temporarily Attachment Daemon and Management Daemon to continue temporarily
without native TLS. The technique has been successfully tested. without having TLS implementations themselves. The technique has
been successfully tested.
TLS shim listens TLS shim listens TLS shim listens TLS shim listens
on port TBD1/TCP on port 3493/TCP on port TBD1/TCP on port 3493/TCP
,-----,------------,----, ,----,--------------, ,-----,------------,----, ,----,--------------,
| UPS - Attachment |TLS | <-STARTTLS | TLS| Management | | UPS - Attachment |TLS | <-STARTTLS | TLS| Management |
| | Daemon |shim| OK--> |shim| Daemon | | | Daemon |shim| OK--> |shim| Daemon |
/-----'------------'----\ '----'--------------' /-----'------------'----\ '----'--------------'
Listens on Listens on
port 3493/TCP port 3493/TCP
Figure 9: Shims provide TLS support during migration Figure 9: Shims Provide TLS Support During Migration
D.1.1. Attachment Daemon Shim D.1.1. Attachment Daemon Shim
The shim in front of the Attachment Daemon listens to incoming The shim in front of the Attachment Daemon listens to incoming
traffic on port TBD1/TCP. When it receives the command STARTTLS it traffic on port TBD1/TCP. When it receives the command STARTTLS, it:
1. Returns OK to the client and sets up TLS encapsulation. 1. returns OK to the client and sets up TLS encapsulation.
2. Does not send STARTTLS to the Attachment Daemon port 3493/TCP. 2. does not send STARTTLS to the Attachment Daemon port 3493/TCP.
All other commands and responses are passed through. All other commands and responses are passed through.
Note: Port TBD1/TCP is not specified by this text. Note: Port TBD1/TCP is not specified by this text.
D.1.2. Management Daemon Shim D.1.2. Management Daemon Shim
The shim in front of the Management Daemon listens for incoming The shim in front of the Management Daemon listens for incoming
traffic on port 3493/TCP. When it receives the command STARTTLS it traffic on port 3493/TCP. When it receives the command STARTTLS, it:
1. Returns FEATURE-NOT-CONFIGURED to the client. 1. returns FEATURE-NOT-CONFIGURED to the client.
2. Sends STARTTLS to the Attachment Daemon on port TBD1/TCP. 2. sends STARTTLS to the Attachment Daemon on port TBD1/TCP.
All other commands and responses are passed through. All other commands and responses are passed through.
D.2. TLS Tunnels D.2. TLS Tunnels
Another technique is the use of TLS tunnels [RFC8446], using a Another technique is the use of TLS tunnels [RFC8446], using a
software such as stunnel [stunnel] which adds OpenSSL-based TLS software, such as stunnel [stunnel], which adds OpenSSL-based TLS
support without modifying the Attachment Daemon or Management Daemon. support without modifying the Attachment Daemon or Management Daemon.
The NUT Project has no procedure to enforce this on sites. The NUT Project has no procedure to enforce this on sites.
D.3. VPN D.3. VPN
A further option to secure communications is very similar to TLS A further option to secure communications is very similar to TLS
tunnelling [RFC8446] and consists of routing the NUT traffic through tunneling [RFC8446] and consists of routing the NUT traffic through a
a Virtual Private Network, VPN. Virtual Private Network (VPN).
D.4. VLAN D.4. VLAN
A fourth option is to isolate the UPS management traffic at the A fourth option is to isolate the UPS management traffic at the
network switching level using a Virtual LAN, VLAN technique. network switching level using a Virtual LAN (VLAN) technique.
,-------------, ,-------------, ,-------------, ,-------------,
,-----, | Attachment | | Management | ,-----, | Attachment | | Management |
| UPS |---| Daemon | | Daemon | | UPS |---| Daemon | | Daemon |
| | |-------------| UPS |-------------| | | |-------------| UPS |-------------|
| |===| | Management | UPS | | |===| | Management | UPS |
/-----\ | Protected |~~~~~~~~~~~~~~~| Management | /-----\ | Protected |~~~~~~~~~~~~~~~| Management |
| Server | VLAN | Client | | Server | VLAN | Client |
| | '-------------' | | '-------------'
'-------------' '-------------'
Production | VLAN Production | VLAN
,---|-------, ,---|-------,
,-----------,| ,-----------,|
,-----------,|' ,-----------,|'
| Clients |' | Clients |'
'-----------' '-----------'
Figure 10: UPS Management Protocol runs over its own VLAN Figure 10: UPS Management Protocol Runs over Its Own VLAN
In Figure 10 there are two VLANS: The main traffic between the In Figure 10, there are two VLANS: the main traffic between the
protected server and its clients uses the production VLAN. The UPS protected server and its clients using the production VLAN. The UPS
management traffic between the Attachment and Management Daemons uses management traffic between the Attachment and Management Daemons uses
the UPS management VLAN marked as ~~~~~~~~~~~~~. the UPS management VLAN marked as ~~~~~~~~~~~~~.
Appendix E. Administrative Security Appendix E. Administrative Security
Administrative commands such as FSD, INSTCMD and SET are powerful and Administrative commands, such as FSD, INSTCMD, and SET, are powerful
can have a deep effect on system integrity, For example, the command and can have a deep effect on system integrity. For example, the
FSD is involved in mission critical system shutdown decisions. command FSD is involved in mission-critical system shutdown
Access to them needs to be managed and restricted. This clause decisions. Access to them needs to be managed and restricted. This
presents the current practice. section presents the current practice.
E.1. Management of Administrative Users E.1. Management of Administrative Users
The Attachment Daemon maintains a file (currently upsd.users) The Attachment Daemon maintains a file (currently upsd.users) that
defining each administrative user. Note that these users are defines each administrative user. Note that these users are
independent of those recorded in file /etc/passwd. Each independent of those recorded in file /etc/passwd. Each
administrative user gets its own section in file upsd.users. The administrative user gets its own section in file upsd.users. The
declarations in that section set the parameters which define that declarations in that section set the parameters that define that
user's privileges. The section begins with the name of the user user's privileges. The section begins with the name of the user
enclosed in square brackets, OPENING BRACKET [ and CLOSING BRACKET ], enclosed in square brackets, opening bracket ([) and closing bracket
and continues until the next user name in brackets or EOF. (]), and continues until the next username in brackets or EOF.
For example the following file declares two administrative users For example, the following file declares two administrative users,
admin and pfy: admin and pfy:
[admin] [admin]
password = sekret password = sekret
upsmon master upsmon master
actions = SET actions = SET
instcmds = ALL instcmds = ALL
[pfy] [pfy]
password = sekret password = sekret
instcmds = test.panel.start instcmds = test.panel.start
instcmds = test.panel.stop instcmds = test.panel.stop
Within each section the administrative user declarations are: Within each section, the administrative user declarations are:
+=============+==========================================+ +=============+==========================================+
| Declaration | Meaning | | Declaration | Meaning |
+=============+==========================================+ +=============+==========================================+
| actions | Allow the user to do certain things in | | actions | Allow the user to do certain things in |
| | the Attachment Daemon. To specify | | | the Attachment Daemon. To specify |
| | multiple actions, use multiple instances | | | multiple actions, use multiple instances |
| | of the declaration. Valid actions are: | | | of the declaration. Valid actions are: |
| | | | | |
| | * FSD Set the "Forced Shutdown" flag | | | * FSD Set the "Forced Shutdown" flag |
| | for this UPS. See Section 4.2.3. | | | for this UPS. See Section 4.2.3. |
| | | | | |
| | * SET Change the value of a UPS | | | * SET Change the value of a UPS |
| | variable. See Section 4.2.11. | | | variable. See Section 4.2.11. |
+-------------+------------------------------------------+ +-------------+------------------------------------------+
| instcmds | Let a user initiate specific instant | | instcmds | Let a user initiate specific Instant |
| | commands. See Section 4.2.6. Use value | | | Commands. See Section 4.2.6. Use value |
| | ALL to grant all commands automatically. | | | ALL to grant all commands automatically. |
| | To specify multiple commands, use | | | To specify multiple commands, use |
| | multiple instances of the instcmds | | | multiple instances of the instcmds |
| | field. For the full list of what a | | | field. For the full list of what a |
| | given UPS supports, use client upscmd -l | | | given UPS supports, use client upscmd -l |
| | supplied by the NUT Project. The LIST | | | supplied by the NUT Project. The LIST |
| | CMD command is issued within the client | | | CMD command is issued within the client |
| | upscmd. | | | upscmd. |
+-------------+------------------------------------------+ +-------------+------------------------------------------+
| password | Set the password for this user. _Your | | password | Set the password for this user. _Your |
| | password should be more secure than the | | | password should be more secure than the |
| | examples shown._ | | | examples shown._ |
+-------------+------------------------------------------+ +-------------+------------------------------------------+
| upsmon | Add the necessary actions for a | | upsmon | Add the necessary actions for a |
| | Management Daemon to process a system | | | Management Daemon to process a system |
| | shutdown. In current practice the value | | | shutdown. In current practice, the |
| | is still master or slave. Note that | | | value is still master or slave. Note |
| | there is no EQUALS =. | | | that there is no EQUALS =. |
+-------------+------------------------------------------+ +-------------+------------------------------------------+
Table 10: Administrative user declarations Table 10: Administrative User Declarations
E.2. An Administrative User of a Client Management Daemon E.2. An Administrative User of a Client Management Daemon
The following examples show the current security practices for The following examples show the current security practices for
administrative users of a client Management Daemon They also administrative users of a client Management Daemon. They also
illustrate the command pair USERNAME and PASSWORD. See illustrate the command pair USERNAME and PASSWORD. See Sections
Section 4.2.13 and Section 4.2.8. 4.2.13 and 4.2.8.
E.2.1. An Administrative User Logs into a Short Session E.2.1. An Administrative User Logs into a Short Session
In this simple example of current practice, the system administrator In this simple example of current practice, the system administrator
sets the battery level at which an Attachment Daemon will raise the sets the battery level at which an Attachment Daemon will raise the
status LB, represented by variable battery.charge.low, to 35% of full status LB, represented by variable battery.charge.low, to 35% of full
charge. A system administrator types the following command to call charge. A system administrator types the following command to call
the client upsrw supplied by the NUT Project. the client upsrw supplied by the NUT Project.
upsrw -s battery.charge.low=35 -u admin -p sekret UPS-1@example.com upsrw -s battery.charge.low=35 -u admin -p sekret UPS-1@example.com
Option -s specifies the variable and the value, option -u specifies Option -s specifies the variable and the value, option -u specifies
the USERNAME, option -p specifies the PASSWORD, and UPS-1@example.com the USERNAME, option -p specifies the PASSWORD, and UPS-1@example.com
is the UPS. The USERNAME and PASSWORD commands are issued within the is the UPS. The USERNAME and PASSWORD commands are issued within the
client upsrw and the Session is of short duration. client upsrw, and the session is of short duration.
Note: Your password should be stronger than the example shown. Note: Your password should be stronger than the example shown.
E.2.2. An Administrative User Logs into a Long Session E.2.2. An Administrative User Logs into a Long Session
In this second example of current practice, the long-running In this second example of current practice, the long-running
Management Daemon upsmon which is responsible for initiating system Management Daemon upsmon, which is responsible for initiating system
shutdowns and which is provided by the NUT Project issues commands shutdowns and which is provided by the NUT Project, issues commands
USERNAME and PASSWORD when it starts up. The data values needed for USERNAME and PASSWORD when it starts up. The data values needed for
the USERNAME and PASSWORD commands are provided by a configuration the USERNAME and PASSWORD commands are provided by a configuration
file upsmon.conf which contains the line file upsmon.conf, which contains the line:
MONITOR UPS-1@example.com 1 admin sekret master MONITOR UPS-1@example.com 1 admin sekret master
This says that the UPS to be monitored is UPS-1@example.com, it This says that the UPS to be monitored is UPS-1@example.com. It
provides 1 single power supply, the administrative user is admin with provides 1 single power supply. The administrative user is admin
password sekret. The Management Daemon acts as a Primary, although with password sekret. The Management Daemon acts as a Primary,
current practice still uses the former term master. although current practice still uses the former term master.
The USERNAME and PASSWORD commands are contained within the client The USERNAME and PASSWORD commands are contained within the client
upsmon and the Session is of long duration. upsmon, and the session is of long duration.
Acknowledgments
This document is based on the NUT Project documentation [devguide].
The editor acknowledges the work of Charles Lepple, Arjen de Korte,
Arnaud Quette, Jim Klimov, Russell Kroll, Manuel Wolfshant, Greg
Troxel, Mark Hansen, and many others who contribute to the
nut-upsuser [nut-upsuser] and nut-upsdev [nut-upsdev] mailing lists.
Earlier draft versions of this document were prepared using an SGML
DTD [SGML] and an XML meta-DTD defined by HyTime Annex A [HyTimeA].
Unlike XML, SGML offers markup minimization, and the earlier drafts
took advantage of this. The osgmlnorm [sgmlnorm] program generated
the XML that was used as input to xml2rfc [RFC7991], which then
created the document's current source. The editor acknowledges the
help received from Carsten Bormann and Julian Reschke in the xml2rfc
mailing list.
Many helpful comments were received from Eliot Lear, Bart Smit, David
Zomaya, Joyce Norris, and Ted Mittelstaedt.
Author's Address Author's Address
Roger Price (editor) Roger Price (editor)
Network UPS Tools Project Network UPS Tools Project
France France
Email: ietf@rogerprice.org Email: ietf@rogerprice.org
 End of changes. 393 change blocks. 
864 lines changed or deleted 863 lines changed or added

This html diff was produced by rfcdiff 1.48.