RFC 9271
Uninterruptible Power Supply (UPS) Management Protocol -- Commands and Responses
RFC 9271 🦋 Part 1 of 14
Uninterruptible Power Supply (UPS) Management Protocol -- Commands and Responses
Okay bestie, the title block is giving very organised energy 💅. This is an Independent Submission by R. Price, Ed. from the Network UPS Tools Project. It's filed as Category: Informational and dated August 2022, with ISSN 2070-1721. It's RFC 9271 🎀. The title block doesn't list anything this RFC obsoletes or updates, so there's no drama there ✨.
Abstract ✨
Okay so the abstract is basically the tea ☕. This doc describes the command and response protocol people use to manage Uninterruptible Power Supply (UPS) units and other power devices. These usually live in small offices and IT setups where the public power supply is kinda erratic 😭.
The UPS talks to an Attachment Daemon on the system it protects. That daemon gets polled by a Management Daemon, which tells users and sysadmins about power supply incidents and automates shutdown decisions 🔌. The commands and responses in this doc get swapped between the UPS Attachment Daemon and the Management Daemon.
Big warning 💀: the practice that was current when this protocol was first developed risks weak security. The Security Considerations sections deal with that, so don't skip them.
Status of This Memo 📜
This doc is not an Internet Standards Track spec. It's just published for informational purposes 🌈.
It's a contribution to the RFC Series, independent of any other RFC stream. The RFC Editor chose to publish it at their discretion and makes no statement about its value for implementation or deployment. Documents approved for publication by the RFC Editor aren't candidates for any level of Internet Standard, see Section 2 of RFC 7841.
For the current status, any errata, and how to give feedback, check https://www.rfc-editor.org/info/rfc9271 🔗.
Copyright Notice ©️
Copyright (c) 2022 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication. Please read those carefully, because they spell out your rights and restrictions for this document 🧾.
Table of Contents 🗂️
1. Introduction
1.1. Current Practice
1.1.1. NUT Project
1.1.2. The Shutdown Story
1.1.3. How to Read this Document
1.2. Additional Information
1.3. Requirements Language
2. Terminology
2.1. Administrative User
2.2. Attachment Daemon
2.3. Driver
2.4. Event
2.5. Instant Command
2.6. Management Daemon
2.7. Primary
2.8. Secondary
2.9. Session
2.10. UPS Status
2.11. UPS Variable
3. Protocol Overview
4. Protocol Specification
4.1. Notation Used in this Specification
4.2. Commands
4.2.1. ATTACH
4.2.2. DETACH
4.2.3. FSD
4.2.4. GET
4.2.4.1. GET CMDDESC
4.2.4.2. GET DESC
4.2.4.3. GET NUMATTACH
4.2.4.4. GET TYPE
4.2.4.5. GET UPSDESC
4.2.4.6. GET VAR
4.2.5. HELP
4.2.6. INSTCMD
4.2.7. LIST
4.2.7.1. LIST CLIENT
4.2.7.2. LIST CMD
4.2.7.3. LIST ENUM
4.2.7.4. LIST RANGE
4.2.7.5. LIST RW
4.2.7.6. LIST UPS
4.2.7.7. LIST VAR
4.2.8. PASSWORD
4.2.9. PRIMARY
4.2.10. PROTVER
4.2.11. SET
4.2.12. STARTTLS
4.2.12.1. Key Infrastructure and Self-Signed Certificates
4.2.13. USERNAME
4.2.14. VER
4.3. Summary of Responses
4.3.1. Response When Command Succeeds
4.3.2. Error Responses
4.4. An ABNF of the Commands
4.4.1. Responses to Commands
5. Statuses and Events
5.1. Status Symbols
5.2. Events
6. Security Considerations
6.1. Current General Security Practice
6.2. Communication Security Requirements
6.2.1. Certificate Security
6.3. Attacks and Defenses
6.3.1. Eavesdropping
6.3.1.1. Misplaced Declarations Requiring TLS
6.3.1.2. Weak Protection in Previous Version 2.7.4
6.3.2. Man-in-the-Middle
6.3.3. Masquerade Attack: Agent Verification
6.3.4. Message Insertion, Deletion, and Modification
6.3.5. Replay
6.3.6. Denial of Service
7. IANA Considerations
8. Implementation Status
8.1. Inclusion in Software Distributions
8.2. Recommended Minimum Support
8.2.1. Desktop PC Variables
8.2.2. Unattended Servers and Additional Variables
8.2.3. Commands and Other Technical Terms
8.2.4. Support for Earlier Versions
9. References
9.1. Normative References
9.2. Informative References
Appendix A. Variables
A.1. Typical UPS Variables
A.2. Typical UPS Readable and Writable Variables
A.3. Typical UPS Instant Commands
Appendix B. The Shutdown Story for System and UPS
Appendix C. Technical Terms: Historical Differences
Appendix D. Security Defenses in Release 2.7.4
D.1. Shims
D.1.1. Attachment Daemon Shim
D.1.2. Management Daemon Shim
D.2. TLS Tunnels
D.3. VPN
D.4. VLAN
Appendix E. Administrative Security
E.1. Management of Administrative Users
E.2. An Administrative User of a Client Management Daemon
E.2.1. An Administrative User Logs into a Short Session
E.2.2. An Administrative User Logs into a Long Session
Acknowledgments
Author's Address1. Introduction 🌸
1.1. Current Practice
This doc describes UPS management techniques and the current UPS management practice published by the Network UPS Tools (NUT) Project. It's based on version 2.8.0 of the NUT Project software, which supports version 1.3 of the NUT protocol.
Since May 2002, the protocol in this doc has been running on IANA port 3493/TCP (nut) 🔌.
1.1.1. NUT Project
The main goal of the Network UPS Tools (NUT) Project software [NUT] is to support power devices, like UPSs ⚡. The project has been around since 1998, with a major rework in 2003. It runs through a user mailing list [nut-upsuser], a developer mailing list [nut-upsdev], a website [NUT], and a GitHub repository [nut-repository]. For the project's history, check [githist] and Appendix J of [History] 📚.
1.1.2. The Shutdown Story
The Shutdown Story section (see Appendix B) describes the current UPS management practice for doing a managed shutdown of unattended infrastructure after an unscheduled failure of the public power supply. The goal is to minimise the risk of corruption to the data this infrastructure is processing 💾.
1.1.3. How to Read this Document
To keep things simple, the term "UPS" gets used even when "Managed Power Device" would be more complete. Read the simple "UPS" as including other managed power devices too 🧚.
The statuses and events in this doc have short text-form names, and some of them are abbreviations. The full list of statuses is in Section 5.1, and the events are listed in Section 5.2.
This doc talks about the "public power supply". Other texts often say "utility power", "input source power", or even "wall power" 🙈.
1.2. Additional Information
More info about the NUT Project lives in the project documentation [Documentation] 📖. If you have questions about this protocol or related technical stuff, you can ask the mailing list [nut-upsuser] of the NUT Project 🫶.
1.3. Requirements Language
Okay, this part is important, so pay attention 👑. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here ✨.
2. Terminology 📚
The following technical terms appear in this doc. They're listed in alphabetical order 💜.
2.1. Administrative User
In current practice, the commands and other functions the Attachment Daemon offers are made available to a set of users known as Management Daemons. These Management Daemons authenticate to the Attachment Daemon with basic credentials (username and password). Even though they're called "users", administrative users aren't system users 🙅♀️. They're specific to an Attachment Daemon and are listed in a text file (currently upsd.users) that the Attachment Daemon reads. That file gives each one its password, the Instant Commands and actions it's allowed to use, and whether the Management Daemon is Primary or Secondary.
For details, see Appendix E.1. For the Primary, see Section 2.7. For the Secondary, see Section 2.8.
Typically, a high-level user will be able to send command FSD 👑, but a low-level user might only be allowed to access the test panel 🧪. The security provisions for administrative users are discussed in Appendix E 🔐.
2.2. Attachment Daemon
The Attachment Daemon retrieves the status from the UPS and sends commands to it, often through a Driver made for the specific hardware model and connection medium, e.g., USB, serial. See Section 2.3 🔌. It keeps an abstracted view of the hardware through hardware statuses. See Section 2.10. A Management Daemon may consult that abstracted view using the commands described in this doc.
See Section 8.2 for details of the recommended minimum support of variables, which calls for Attachment Daemon support of statuses OB, OL, LB, and FSD 🍓.
The NUT Project has implemented an Attachment Daemon as program upsd, plus a set of hardware-specific Drivers, all written in K&R C [C2ndEd] 🧠. The Attachment Daemon is launched as system user "root", but for better security it then drops the privilege and runs as a detached software service 🦋.
2.3. Driver
A Driver is the part of an Attachment Daemon that's specific to the UPS hardware, the connection medium, and the connection protocol, e.g., USB, serial 🌈. In current practice, the Attachment Daemon has a Driver for each hardware interface type it supports.
Although this doc considers the Driver to be part of the Attachment Daemon, current practice sees it as a separate software unit running as a daemon "in front of" the Attachment Daemon 💅. The protocol for data exchange between the Driver and the Attachment Daemon is outside the scope of this doc.
2.4. Event
A UPS event occurs in the Management Daemon when a change in the UPS status is received from the Attachment Daemon. This event is internal to the Management Daemon. See Section 5.2 ⭐.
2.5. Instant Command
An Instant Command is a command that, when sent to the Attachment Daemon, is passed to the Driver and sent to the hardware without any configured delay to perform a function 🔥. For example, INSTCMD su700 test.panel.start. See Section 4.2.6.
2.6. Management Daemon 🎀
okay so the Management Daemon is basically the boss of managing the hardware and running the system-wide stuff after a power event happens ⚡💅 It sends commands to the Attachment Daemon, keeps an eye on the status of the UPS, and figures out when UPS events happen 👀 Then it makes decisions based on those events, like calling for a system shutdown 🫶 See Appendix B for the deets.
bestie, the word "Daemon" in the name makes it sound like it has to be its own detached software service 🙈 but nothing actually requires that! It can be whatever works. The Management Daemon may also do admin stuff too, like a graphic interface so you can see the hardware activity 🌈✨
there are a few examples of a Management Daemon, and the NUT Project's upsmon is the big one 💜 It takes the system shutdown decision when the public power supply fails 💀 And if you want extra config options like timers, the helper program upssched has you covered ⏰
other programs count as Management Daemons too 🦋
upscreports the values of the variables defined for a given UPS; see Table 6.upsrwreports on and changes the values of the readable and writable configuration variables defined for a given UPS; see Appendix A.2.upscmdreports on and executes the instant action commands defined for a given UPS; see Section 4.2.6.UPSmon.pyis an experimental Python3 rewrite of upsmon and upssched that includes support for TLS 1.3 [RFC8446] 🔐🍓
2.7. Primary 👑
okay so when a power device, like a UPS unit, is powering more than one system, the computer running the Driver is called the Primary 🌸 everyone else is a Secondary 🧚 See Figure 4 for the vibe check.
common current practice for sysadmins is to treat the Management Daemon in the Primary as the Primary Management Daemon, the one in charge of shutting down every system the UPS powers ⚡ The Primary Management Daemon sets status symbol FSD to order the Secondaries to shut down 🛑
Note: Historically, the Primary was known as the "Master". 🙈
2.8. Secondary 🧚
so when a hardware device, like a UPS unit, is powering more than one system, the system that talks directly to the UPS unit (over USB, RS-232, or a network connection, e.g.) is the Primary 👑 The others are Secondaries 💖 A Secondary has no Attachment Daemon at all 🙅♀️ See Figure 4 again 🫶
common current practice for sysadmins is to treat the Management Daemon in a Secondary as a Secondary Management Daemon that reads status symbol FSD as an order to shut down 🛑
Note: Historically, the Secondary was known as the "Slave". 💀
2.9. Session 🎀
the Management Daemon may start a TCP session with a specified device, like a UPS the Attachment Daemon knows about 🦋 The session structure is there for audit and security, plus access to mission-critical UPS functions 🔐 For example, good practice is to require a password for an Instant Command that turns off a UPS outlet 🔑 Other than the commands and responses used, the details of session management are outside the scope of this document 🙈
2.10. UPS Status 🌈
the status of a hardware device, like a UPS unit, is a symbolic description of what state the unit is in ✨ It's a space-separated list of symbols from the set {ALARM BOOST BYPASS CAL CHRG COMM DISCHRG FSD LB NOCOMM OB OFF OL OVER RB TEST TRIM} 💅 The symbols TICK and TOCK are experimental additions to the statuses and are not in common current practice 🧪 See Section 5.1, which specifies each of these symbols 📖
See Section 8.2 for details of the recommended minimum support of status symbols OB, OL, LB, and FSD 💜
2.11. UPS Variable 🍓
the metrics and identifiers each UPS provides are represented by variables that give the value for that metric or identifier 📊 The UPS variable is an abstraction of the UPS hardware configuration and activity that the Attachment Daemon maintains 🧚 See Appendix A, which has examples of variables 🌸 For example, the variable battery.charge holds the current charge of the UPS battery as a percentage 🔋
Note: Some variables are constants, e.g., battery type and manufacturer. 💖
See Section 8.2 for details of the recommended minimum support of variables 🫶 A full list of possible variables is in the source code file docs/nut-names.txt [gitvars], which serves as the Recording Document 📚
3. Protocol Overview 🦋
Figure 1 shows a reference configuration where the command/response protocol applies 🔥 The UPS shown stands in for all managed power devices ⚡
"The client"
,--------------, ,--------------,
,-----, | UPS | <-Commands | UPS |
| UPS |---| Attachment |---------------| Management |
| |===| Daemon | Responses-> | Daemon |
/-----\ '--------------' '--------------'
UPS Attachment UPS Management
System Network System
Figure 1: Reference ConfigurationThe reference configuration in Figure 1 shows a single UPS unit with a power supply link (===) and a data link (---) attached to a system running an Attachment Daemon 💖 The UPS gives power supply protection to that system 🛡️
in practice, there can be more than one UPS unit, and one unit can protect more than one system 🌈 The figure also shows a single Management Daemon, but in practice there can be more than one, and any one Management Daemon can manage more than one UPS Attachment Daemon 👑
The protocol applies to connections between the Attachment Daemon and the Management Daemon, which act as the server and client, respectively 🎀 The Management Daemon sends commands over TCP to the Attachment Daemon and gets responses over TCP back from that daemon 📨
the two daemons can run on the same system or connect through a local or wide area network ✨ In simple cases, as Figure 2 shows, the Attachment Daemon and the Management Daemon live on the same system, the one protected by the UPS 🏠 The commands and responses go through an internal loopback interface 🔁
"The client"
,--------------------,---------------------,
,-----, | UPS <-Commands UPS |
| UPS |---| Attachment | Management |
| |===| Daemon Responses-> Daemon |
/-----\ '--------------------'---------------------'
Internal
Loopback
UPS Attachment and Management System
Figure 2: Simplified Single-System ConfigurationThe reference configuration doesn't require any specific design 🙌 For example, Figure 3 shows an arrangement where the Attachment Daemon is closely tied to, or even built into, the UPS system setup 🧠 This is getting more common because cheap processors can now run the Attachment Daemon, which basically creates a network-attached UPS running a published protocol 🌐🔥
"The client"
,-----,------------, ,--------------,
| | UPS | <-Commands | UPS |
| UPS - Attachment |---------------| Management |
| | Daemon | Responses-> | Daemon |
/-----'------------\ '--------------'
UPS Attachment UPS Management
System Network System
Figure 3: UPS and Attachment Daemon Integrationas processors need less power, it's getting really common to use one UPS to protect multiple systems, as Figure 4 shows 🧚 However, there's only one data line (---) from the UPS to the Primary system 🔌 The others only have power connections (===) to the UPS and are called Secondaries 💅 A Secondary doesn't run an Attachment Daemon; it connects over a network to the Attachment Daemon in the Primary 🫶 Figure 4 shows the Attachment Daemon and the Primary Management Daemon on the same system 🏠 This is common practice, but it's not a technical requirement 🙈
"The client"
,--------------------,---------------------,
,-----, | UPS <-Commands Primary |
| |---| Attachment | Management | Primary
| |===| Daemon Responses-> Daemon |
| | '--------------------'---------------------'
| UPS | ^
| | '<-Commands---Responses->,
| | v
| | ,--------------,-----------------,
| |============| | Secondary |
/-----\ | | Management | Secondary
| | Daemon |
'--------------'-----------------'
Figure 4: UPS Protects Multiple SystemsNote: Should the Primary fail or go offline, the fate of the 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 OB, the Secondary may choose to shut down as a precaution. 🚨
4. Protocol Specification 📖
this spec only covers the commands and their responses 💜 An implementation of the Attachment Daemon has an internal state machine, and some complex Management Daemon implementations have one too, for example to help with the system shutdown of a complicated installation 🧠 The Management Daemon MUST remember the previous ups.status value it received from the Attachment Daemon and compare it with the next one 👀 Other than that, the management protocol between them is effectively stateless ✨
For example, see Section 5.2, which shows a map of the new ups.status response and the previous ups.status response to an event, which is the basis for Management Daemon action 🗺️
4.1. Notation Used in this Specification 🍓
the character set for commands and responses is US-ASCII; see [RFC0020] 🔤
Multi-word elements go between quotation mark characters so they're easier to parse, e.g., "UPS on fire" 🔥 Embedded quotation marks get escaped with reverse slant (), often called backslashes 🙈 Embedded backslashes are escaped too, by writing them as \\ 💅
Commands and responses MUST NOT have leading or trailing blank space, and they MUST be terminated with a single new line character, line feed (LF) 🫶 Blank space within commands and responses MUST be reduced to one space (SP) ✨
Continuing with the next part! 💖
4.2. Commands 💅
okay so every command tells the Attachment Daemon which UPS it's talking about by using an <upsname>. Here's the shape:
<upsname> ::= <ups>[@<hostname>[:<port>]]<ups>comes from the Attachment Daemon configuration files, so that's where you'll find the name. 🎀- If you skip the
<hostname>, it defaults tolocalhost. 🏠 - The
<port>is the TCP port the Attachment Daemon is listening on, and it defaults to3493. Every current Management Daemon supports this. 🧚
For example: myups, UPS-97B@bigserver.example.com
ABNF: See variable upsname in Figure 5.
Experimental Management Daemons are a little extra and use a longer <upsname> in their config files and program parameters. 🌈
<upsname> ::= [<group>:]<ups>[@<hostname>[:<port>]]<group>is an experimental extension for grouping UPSs together. It isn't really common practice yet.<ups>still comes from the Attachment Daemon configuration files.- The
<hostname>still defaults tolocalhost.
For example: ups-1@example.com:3493, HB:heartbeat1@example.com:3493
💡 Implementation note: the current implementation doesn't care about case for command and subcommand names. SoGET VARcould be typed asGet var, but this spec always writes them in uppercase. ✨<upsname>and<varname>are case-insensitive too.UPS341 ups.idcould beups341 Ups.Id, but this spec always writes<varname>in lowercase. 🙈
4.2.1. ATTACH 🦋
Picture a setup like Figure 4, where one UPS is protecting more than one system. The Primary Management Daemon needs to know how many Secondaries are active at any moment, meaning they're getting power from the UPS, either from the public supply or from the battery. ⚡ The Attachment Daemon keeps that tally for every active system a UPS is feeding. The count starts at zero and goes up one Secondary at a time through the ATTACH command. ATTACH basically means count this Secondary as active. There are three commands for this counting game: ATTACH goes up, DETACH goes down, and a Management Daemon can check the total whenever it wants with NUMATTACH. 📊
The Primary's own Attachment Daemon also gets an ATTACH, so during normal, fully protected operation the count is 1 for the Primary plus however many Secondaries there are. 🫶 When everything shuts down, each Secondary runs DETACH on its way out, and the count drops. Once it hits 1, the Primary knows it's the only one still active, which means every Secondary is down. 💀
Command: ATTACH <upsname>
If it works, you get OK. If not, check the error responses in Section 4.3.2. 🙃
ABNF: See variable attach in Figure 5.
📜 Note: this command used to be called LOGIN. But LOGIN sounded like a user logging into a shell or program, which it wasn't, so the name got changed to avoid the confusion. 💅
4.2.2. DETACH 🌸
This is ATTACH's bestie. It lowers the count of "active" Secondaries. It means this Secondary is no longer active, and it's mostly used during system shutdown to track how many Secondaries are still active. 🍓
Command: DETACH
If it works, you get OK Goodbye. If not, check the error responses in Section 4.3.2. 👋
ABNF: See variable detach in Figure 5.
📜 Note: this command used to be called LOGOUT.
4.2.3. FSD 🔥
A Management Daemon that's Primary and has the required authority uses this command to set the status symbol FSD, which means "Forced Shutdown", in the Attachment Daemon. In current practice, the Primary uses that symbol to tell the Secondaries to shut down. 😭
Command: FSD <upsname>
If it works, you get OK FSD-SET. If not, check the error responses in Section 4.3.2. ✨
ABNF: See variable fsd in Figure 5.
Current practice is that commands like FSD are only available to a privileged admin user who's allowed to send something this mission-critical. The security rules for admin users are covered in Appendix E. 🔐
Note: FSD is also used as the name of an event. See Table 5. 🎀
4.2.4. GET 🍬
GET retrieves a single response from the Attachment Daemon. 📥
ABNF: See variable get in Figure 5.
The possible subcommands are in the sections below. 👇
4.2.4.1. GET CMDDESC 📖
This one grabs a text description of a command. 💬
Command: GET CMDDESC <upsname> <cmdname>
Response: CMDDESC <upsname> <cmdname> "<description>"
For example: send GET CMDDESC su700 load.on and you'll get back CMDDESC su700 load.on "Turn on the load immediately". ⚡
It's basically GET DESC, but for an Instant Command instead of a UPS variable. See Section 4.2.4.2. 🧚
4.2.4.2. GET DESC 🪞
This grabs a text description of a UPS variable. See Section 2.11. 🌷
Command: GET DESC <upsname> <varname>
Response: DESC <upsname> <varname> "<description>"
<description> is a short string explaining the named variable. If the file that holds this description isn't installed, the Attachment Daemon MAY return "Unavailable". 🙈
For example: send GET DESC su700 ups.status and you'll get back DESC su700 ups.status "UPS status". 💖
4.2.4.3. GET NUMATTACH 🧮
This pulls the count the Attachment Daemon keeps for all the active systems protected by this UPS. 📊
Command: GET NUMATTACH <upsname>
Response: NUMATTACH <upsname> <value>
<value> is the number of the Primary plus the Secondaries that this UPS is powering right now. 🔋
For example: send GET ATTACH su700 (yes, the example really says ATTACH) and you'll get back NUMATTACH su700 1. 🤷♀️
The Management Daemon needs this to figure out how many Secondaries are still connected during shutdown. 🫶
📜 Note: this subcommand used to be called NUMLOGINS. LOGIN wasn't a conventional user access to a shell or program, so the name got changed to avoid confusion. 💅
4.2.4.4. GET TYPE 🎀
This returns the type of a UPS variable. See Section 2.11. 🧩
Command: GET TYPE <upsname> <varname>
Response: TYPE <upsname> <varname> <type>...
<type>... can be one or more of the tokens in Table 1. You can get several types back at once. 🌈
For example: send GET TYPE su700 input.transfer.low and you'll get back 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 | 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 TypesNotes:
- ENUM, STRING:n, and RANGE are usually paired with RW, but not always. If
<type>is left out, the default is numeric, meaning either integer or float. Each Driver then has to handle values as integer or float on its own. 🧠 - Current practice is to write floating point values in decimal (base 10), English-style. Hexadecimals, exponents, and commas used as thousands separators are not allowed. So
"1200.20"is valid, but"1,200.20"and"1200,20"are not. 🙅♀️
4.2.4.5. GET UPSDESC 🏷️
This gets a text description of a whole UPS. 🏠
Command: GET UPSDESC <upsname>
Response: UPSDESC <upsname> "<description>"
<description> is set in the Attachment Daemon configuration. If it isn't set, current practice is for the Attachment Daemon to return "Unavailable". 🙈
For example: send GET UPSDESC su700 and you'll get back UPSDESC su700 "Development box". 🧸
This is great for human-friendly names so you're not stuck reading a cryptic ups@hostname string. 🫶
4.2.4.6. GET VAR 📈
This retrieves the value of a UPS variable. See Section 2.11. 💫
Command: GET VAR <upsname> <varname>
Response: VAR <upsname> <varname> "<value>"
For example: send GET VAR su700 ups.status and you'll get back VAR su700 ups.status "OB LB". 🔋
4.2.5. HELP 🆘
HELP returns a list of the commands the Attachment Daemon supports. It's made for humans as well as programs. 🧑💻
Command: HELP
For example, here's a session run on an Attachment Daemon:
netcat localhost 3493
HELP
Commands: HELP VER GET LIST SET INSTCMD ATTACH DETACH
USERNAME PASSWORD STARTTLSABNF: See variable help in Figure 5.
📜 Note: this command used to also return LOGIN and LOGOUT. Since LOGIN wasn't a conventional user access to a shell or program, the commands got renamed ATTACH and DETACH to avoid the confusion. 💅
4.2.6. INSTCMD ⚡
This sends an Instant Command to the UPS. 🚀
Command: INSTCMD <upsname> <cmdname>
<upsname> names the UPS, and <cmdname> is the Instant Command you want it to run. See Appendix A.3 for examples of Instant Commands. 🧾
If it works, you get OK. If not, check the error responses in Section 4.3.2. ✅
For example: send INSTCMD su700 test.panel.start and you'll get back OK. 🎉
ABNF: See variable instcmd in Figure 5.
4.2.7. LIST 📋
Every LIST command gives back a response in the same format. It starts with BEGIN LIST, then repeats the original query. After that comes the list, as many lines as it takes. It ends with END LIST followed by the original query again. 🧾
Yes, it's a bit repetitive, but that's the point! It makes a different kind of client possible. A client can send a LIST command and just wait. When the reply shows up, the Management Daemon doesn't need a complicated state machine to keep track of which list is which. Iconic. 👑
📜 Note: the current NUT Project version of the Attachment Daemon,upsd, sends the LIST response back as a series of messages. The Management Daemon should keep reading them until it gets the line that starts withEND LIST. 🫶
ABNF: See the variable list in Figure 5.
The possible subcommands are in the sections below. 🌸
4.2.7.1. LIST CLIENT 👯♀️
This tells the Attachment Daemon to report every current Management Daemon client for a given UPS. 💌
Command: LIST CLIENT <upsname>
Response:
BEGIN LIST CLIENT <upsname>
CLIENT <upsname> <client_IP_address>
...
END LIST CLIENT <upsname>For example: send LIST CLIENT ups1 and you'll get back:
BEGIN LIST CLIENT ups1
CLIENT ups1 ::1
CLIENT ups1 203.0.113.1
END LIST CLIENT ups14.2.7.2. LIST CMD ✨
okay so this command asks the Attachment Daemon to spill the tea on every Instant Command the Management Daemon is allowed to send it 💅 This list is basically the abstracted view of what the UPS hardware can actually do. An economical UPS will support few or no Instant Commands, but a professional model should support more 🔥
Command: LIST CMD <upsname>Response:
BEGIN LIST CMD <upsname>
CMD <upsname> <cmdname>
...
END LIST CMD <upsname><upsname> is the name of the UPS, and <cmdname> is the name of the Instant Command that may be issued to the UPS. 🎀
For example, here's LIST CMD su700 and its response 🧚
BEGIN LIST CMD su700
CMD su700 load.on
CMD su700 test.panel.start
...
END LIST CMD su7004.2.7.3. LIST ENUM 🌸
this one is giving "give me the menu" 🍓 The command calls for the Attachment Daemon to report the set of possible values of a UPS variable that has predetermined values.
Command: LIST ENUM <upsname> <varname>Response:
BEGIN LIST ENUM <upsname> <varname>
ENUM <upsname> <varname> "<value>"
...
END LIST ENUM <upsname> <varname><upsname> is the name of the UPS, <varname> is the UPS variable, and <value> is one of the possible values of that UPS variable. Note that, in current practice, the output is an unordered list. Also note that the quotation marks are part of the response. 🙈
For example, here's LIST ENUM su700 input.transfer.low and its response 💖
BEGIN LIST ENUM su700 input.transfer.low
ENUM su700 input.transfer.low "103"
ENUM su700 input.transfer.low "100"
...
END LIST ENUM su700 input.transfer.low4.2.7.4. LIST RANGE 🦋
main character energy for this one ✨ The command calls for the Attachment Daemon to report the interval in which valid values of UPS variable lie.
Command: LIST RANGE <upsname> <varname>Response:
BEGIN LIST RANGE <upsname> <varname>
RANGE <upsname> <varname> "<min>" "<max>"
...
END LIST RANGE <upsname> <varname><upsname> is the name of the UPS, <varname> is the UPS variable, and {<min>,<max>} is the interval of valid values of that UPS variable. Note that the quotation marks are part of the response. 💜
For example, here's LIST RANGE su700 input.transfer.low and its response 🌈
BEGIN LIST RANGE su700 input.transfer.low
RANGE su700 input.transfer.low "90" "105"
END LIST RANGE su700 input.transfer.low4.2.7.5. LIST RW 🎀
ngl this one is a whole vibe 🫶 The command calls for the Attachment Daemon to report a list of the UPS variables associated with a given UPS that may be read and written by the Management Daemon. These variables are the abstracted view of the UPS hardware capabilities. An economical UPS may support few variables, but a professional model should support at least the variables that are needed for an automatic shutdown and restart; see Appendix B. Also, see Section 8.2 for details of the recommended minimum support of variables. A full list of variables is available in source code file docs/nut-names.txt [gitvars], which serves as the Recording Document. 📚
Command: LIST RW <upsname>Response:
BEGIN LIST RW <upsname>
RW <upsname> <varname> "<value>"
...
END LIST RW <upsname><upsname> is the name of the UPS, <varname> is the UPS variable, and <value> is the value of that UPS variable. Note that the quotation marks are part of the response. 🍓
For example, here's LIST RW su700 and its response 🧚♀️
BEGIN LIST RW su700
RW su700 output.voltage.nominal "115"
RW su700 ups.delay.shutdown "020"
...
END LIST RW su7004.2.7.6. LIST UPS 🌷
okay this is the "who's in my squad" command 👑 The command calls for the Attachment Daemon to report a list of the UPS units to which it is attached.
Command: LIST UPSResponse:
BEGIN LIST UPS
UPS <upsname> "<description>"
...
END LIST UPS<upsname> is the name of a UPS, and <description> is the description maintained by the Attachment Daemon, if available. It is set to "Unavailable" otherwise. Note that the quotation marks are part of the response. 🦋
This command can also be used to determine what values of <upsname> are valid before calling other functions on the server. This is also a good way to handle situations where a single Attachment Daemon supports multiple UPSs. It is also useful for clients that perform a UPS discovery process. 🔍
For example, here's the response:
BEGIN LIST UPS
UPS su700 "Development box"
END LIST UPS4.2.7.7. LIST VAR 💅
the full menu, everything the UPS is tracking, and what it's currently set to 🌸 The command calls for the Attachment Daemon to report a list of all the UPS variables that it maintains for a given UPS and the values of those UPS variables.
Command: LIST VAR <upsname>Response:
BEGIN LIST VAR <upsname>
VAR <upsname> <varname> "<value>"
...
END LIST VAR <upsname><upsname> is the name of the UPS, <varname> is the UPS variable, and <value> is the value of that variable. Note that the quotation marks are part of the response. 💖
The response to this command lists the UPS variables available for this UPS and their current values. ✨
For example, here's LIST VAR su700 and its response 🫶
BEGIN LIST VAR su700
VAR su700 ups.mfr "Example Mfg"
VAR su700 ups.mfr.date "10/17/96"
...
END LIST VAR su700See Section 8.2 for details of the recommended minimum support of variables. A full list of variables is available in source code file docs/nut-names.txt [gitvars], which serves as the Recording Document. 📚
4.2.8. PASSWORD 🔐
this one is the sidekick to USERNAME, no cap 🧚 This command is a companion to USERNAME and is used by a Management Daemon to specify the password required to enter a session with the Attachment Daemon; see Section 2.9.
Command: PASSWORD <password>If the command succeeds, the response is OK; otherwise, see the error responses in Section 4.3.2.
For examples of the use of commands USERNAME and PASSWORD by administrative users, see Appendix E.2. 🎀
ABNF: See variable session-password in Figure 5.
4.2.9. PRIMARY 👑
so the Attachment Daemon keeps a note in the local file upsd.users saying that an administrative user is a Primary 📝 See Appendix E.1 for an example. When a Management Daemon starts up and opens a session with the Attachment Daemon, it lays claim to being a Primary by sending command PRIMARY to the Attachment Daemon, thus claiming that it has the required authority to perform critical actions, such as setting status symbol FSD. Iconic behaviour 😤
Command: PRIMARY <upsname><upsname> is the name of the UPS.
If the Attachment Daemon has the authority, the response is OK; otherwise, see the error responses in Section 4.3.2.
Note: Historically, this command was known as MASTER. 🙈
4.2.10. PROTVER 🌈
this command is for the humans AND the programs, bestie 🤖💖 Return the version of the command/response protocol used by the Attachment Daemon. This command is intended for human, as well as program, use.
Command: PROTVERFor example, here's the command line sequence in the Attachment Daemon:
netcat localhost 3493
PROTVER
1.3Notes:
- There are no quotation marks in the response.
- The version of the protocol returned by PROTVER is different than the implementation version of the Attachment Daemon returned by VER.
- To ease migration, NUT version 2.8.0 also supports the equivalent NETVER command used in previous releases. See Section 8.2.4.
ABNF: See variable protver in Figure 5.
4.2.11. SET 🍓
the "change the setting" command 💅 The command calls for the Attachment Daemon to set a UPS variable to a given value. Whether this has an effect on the UPS hardware is specific to the Driver and the UPS model. Some variables are read-only due to the design of the UPS or its Driver. 🔧
Command: SET VAR <upsname> <varname> "<value>"<upsname> is the name of the UPS, <varname> is the UPS variable, and <value> is the value to be assigned to that variable. Note that the quotation marks are part of the command. 🎀
If the command succeeds, the response is OK; otherwise, see the error responses in Section 4.3.2.
For example, here's SET VAR su700 ups.id "My UPS" and its response: OK 🦋
ABNF: See the variable set in Figure 5.
4.2.12. STARTTLS 🔒
the "let's go private" moment 🫣 The client tells the Attachment Daemon to switch to communication encrypted by TLS [RFC8446]. When the client receives OK, it also switches to TLS encryption.
Command: STARTTLSIf the command succeeds, the response is OK STARTTLS; otherwise, see the error responses in Section 4.3.2.
If the client does not send command STARTTLS to the Attachment Daemon, communication continues unencrypted; however, an Attachment Daemon MAY refuse unencrypted communication. 🙅♀️
NUT 2.8.0 supports the encryption of communications between the Attachment Daemon and the Management Daemon using TLS 1.3 [RFC8446] with X.509 v3 certificates, as defined by [RFC5280] and updates. See Appendix D for details of the encryption of communications in previous release 2.7.4. 🌟
ABNF: See variable starttls in Figure 5.
4.2.12.1. Key Infrastructure and Self-Signed Certificates 🔑
The very restricted nature of UPS management makes it of interest to consider self-signed certificates. 💜
okay, PKI drama time 🎭 In the World Wide Web, there are millions of servers and hundreds of millions of potential clients for each one. The servers do not know who their clients will be, so they entrust the management of a Public Key Infrastructure (PKI) to Certificate Authorities that they trust. The encryption of communications between the client and server requires that the browsers carry a list of Certificate Authorities that the clients have to trust. This is a many-to-many relationship.
The management of UPS units is not a many-to-many relationship; it is frequently one to one. In the closely restrained world of UPS management, there are a very limited number of clients for each server, rarely more than three, and unlike the World Wide Web, the server administrators know exactly who they are. These clients visit very few servers, typically one only. This situation is totally different from the World Wide Web. The use of external Certificate Authorities is a potential security weakness that must be accepted for the World Wide Web but which can be avoided for UPS management by either generating the private and public keys locally or, for larger organizations, using a PKI. 🥹
The security policies for UPS management may be subordinate to an organization's own internal IT security plans and procedures, possibly based on [RFC7030] and [RFC8894], but in simple cases, it is possible to obtain better security using self-signed certificates. 🌸
4.2.13. USERNAME 🧑💻
the Attachment Daemon is kind of picky about who gets in 😌 The Attachment Daemon limits access to clients whose credentials match those in the file upsd.users. There is no anonymous access. A Management Daemon program or script uses command USERNAME and its companion command PASSWORD to open a session with the Attachment Daemon for an administrative user. Note that this command is for program or script use and is not the familiar login command typed on a command line to gain access to a shell. 🐚
Command: USERNAME <username>If the command succeeds, the response is OK; otherwise, see the error responses in Section 4.3.2.
For examples of the use of commands USERNAME and PASSWORD by administrative users, see Appendix E.2. ✨
ABNF: See variable session-username in Figure 5.
4.2.14. VER 🧚
okay bestie, VER is the command that tells you which version of the Attachment Daemon you're running 💅 it's meant for humans AND programs, so it's giving double duty ✨
Command: VER
here's a lowkey iconic example of the whole session 🎀
netcat localhost 3493
VER
Network UPS Tools upsd 2.8.0 - http://www.networkupstools.org/Notes:
- there are no quotation marks in the response 💀 the reply comes back totally unquoted, no cap
- the implementation version the Attachment Daemon gives you from
VERis DIFFERENT from the protocol version you get fromPROTVER🙈 they're not the same thing, so don't mix them up, periodt
ABNF: see variable ver in Figure 5 🦋
4.3. Summary of Responses 🌈
4.3.1. Response When Command Succeeds 💖
okay so when a command works, the response has a command-dependent form, meaning it changes depending on which command you sent 🍓 Table 2 is the whole lineup, and it's honestly a masterpiece 👑
+==========+=====================+================+============+
| Command | Response | Reference | Note |
+==========+=====================+================+============+
| ATTACH | OK | Section 4.2.1 | Was LOGIN |
+----------+---------------------+----------------+------------+
| DETACH | OK Goodbye | Section 4.2.2 | Was LOGOUT |
+----------+---------------------+----------------+------------+
| FSD | OK FSD-SET | Section 4.2.3 | |
+----------+---------------------+----------------+------------+
| GET | Subcommand specific | Section 4.2.4 | |
+----------+---------------------+----------------+------------+
| HELP | List of commands | Section 4.2.5 | |
+----------+---------------------+----------------+------------+
| INSTCMD | OK | Section 4.2.6 | |
+----------+---------------------+----------------+------------+
| LIST | Subcommand specific | Section 4.2.7 | |
+----------+---------------------+----------------+------------+
| PASSWORD | OK | Section 4.2.8 | |
+----------+---------------------+----------------+------------+
| PRIMARY | OK | Section 4.2.9 | |
+----------+---------------------+----------------+------------+
| PROTVER | Protocol version | Section 4.2.10 | Was NETVER |
+----------+---------------------+----------------+------------+
| SET | OK | Section 4.2.11 | |
+----------+---------------------+----------------+------------+
| STARTTLS | OK STARTTLS | Section 4.2.12 | |
+----------+---------------------+----------------+------------+
| USERNAME | OK | Section 4.2.13 | |
+----------+---------------------+----------------+------------+
| VER | Program version | Section 4.2.14 | |
+----------+---------------------+----------------+------------+
Table 2: Response If Command Succeedsthe big takeaway: every command has its own success reply, so check the table before you assume 🫶
4.3.2. Error Responses ✨
okay so when something goes wrong, the Attachment Daemon replies with an error response 🙈 Every error looks like this:
ERR <error-name> [<extra>]The <error-name> is a single word token made from the 27 characters A-Z and hyphen (-). So: capital letters and dashes only, no vibes-only spelling 💅 Implementations MAY, if needed, add an additional, optional <extra>. Current practice does not make use of this possibility, so nobody's really adding one yet 🫶
Here's the whole lineup of possible <error-name> values and what each one means:
+==============================+==================================+
| The Error Name Token | Meaning |
| <error-name> | |
+==============================+==================================+
| ACCESS-DENIED | The client's host and/or |
| | authentication details supplied |
| | by USERNAME and PASSWORD are not |
| | sufficient to execute the |
| | requested command. |
+------------------------------+----------------------------------+
| ALREADY-ATTACHED | The client has already sent a |
| | successful ATTACH command for a |
| | given UPS and can't do it again. |
+------------------------------+----------------------------------+
| ALREADY-SET-PASSWORD | The client has already supplied |
| | a PASSWORD and is attempting to |
| | repeat the command in the same |
| | session. |
+------------------------------+----------------------------------+
| ALREADY-SET-USERNAME | The client has already supplied |
| | a USERNAME and is attempting to |
| | repeat the command within the |
| | same session. |
+------------------------------+----------------------------------+
| CMD-NOT-SUPPORTED | The specified UPS doesn't |
| | support the Instant Command. |
+------------------------------+----------------------------------+
| DATA-STALE | The Attachment Daemon is |
| | connected to the Driver for the |
| | UPS, but that Driver isn't |
| | providing regular updates or has |
| | specifically marked the data as |
| | stale. Current practice is for |
| | the Attachment Daemon to refuse |
| | to provide the Management Daemon |
| | with variables on stale units to |
| | avoid false readings. |
| | |
| | This generally means that the |
| | Driver is running, but it has |
| | lost communication with the |
| | hardware. Check the physical |
| | connection to the equipment. |
+------------------------------+----------------------------------+
| DRIVER-NOT-CONNECTED | The Attachment Daemon can't |
| | perform the requested command, |
| | since the Driver for that UPS is |
| | not connected. This usually |
| | means that the Driver is not |
| | running or, if it is, is |
| | misconfigured. |
+------------------------------+----------------------------------+
| FEATURE-NOT-CONFIGURED | This instance of the Attachment |
| | Daemon hasn't been configured |
| | properly to allow the requested |
| | feature to operate. In current |
| | practice, this error response is |
| | possible only for command |
| | STARTTLS. |
+------------------------------+----------------------------------+
| FEATURE-NOT-SUPPORTED | This instance of Attachment |
| | Daemon does not support the |
| | requested feature. In current |
| | practice, this error response is |
| | possible only for command |
| | STARTTLS. |
+------------------------------+----------------------------------+
| INSTCMD-FAILED | The Attachment Daemon failed to |
| | deliver the Instant Command |
| | request to the Driver. No |
| | further information is available |
| | to the client. This typically |
| | indicates a dead or broken |
| | Driver. |
+------------------------------+----------------------------------+
| INVALID-ARGUMENT | The client sent an argument to a |
| | command that is not recognized |
| | or is otherwise not valid in |
| | this context. This is typically |
| | caused by sending a valid |
| | command, such as GET, with a |
| | subcommand that is not valid. |
+------------------------------+----------------------------------+
| INVALID-PASSWORD | The client sent a nonvalid |
| | PASSWORD. |
+------------------------------+----------------------------------+
| INVALID-USERNAME | The client sent a nonvalid |
| | USERNAME. |
+------------------------------+----------------------------------+
| INVALID-VALUE | The value specified in the |
| | request is not valid. This |
| | usually applies to a SET of an |
| | ENUM type that is using a value |
| | not in the list of allowed |
| | values. See Section 4.2.7.3. |
+------------------------------+----------------------------------+
| PASSWORD-REQUIRED | The command requires a PASSWORD |
| | for authentication, but the |
| | client hasn't provided one. |
+------------------------------+----------------------------------+
| READONLY | The requested variable in a SET |
| | command is not writable. |
+------------------------------+----------------------------------+
| SET-FAILED | The Attachment Daemon failed to |
| | deliver the SET request to the |
| | Driver. This is similar to |
| | INSTCMD-FAILED. |
+------------------------------+----------------------------------+
| TLS-ALREADY-ENABLED | TLS mode is already enabled on |
| | this connection, so the |
| | Attachment Daemon can't start it |
| | again. |
| | |
| | Note: Historically, this message |
| | was ALREADY-SSL-MODE. |
+------------------------------+----------------------------------+
| TLS-NOT-ENABLED | TLS mode is required but has not |
| | yet been enabled on this |
| | connection, so the Attachment |
| | Daemon can't send commands. |
| | |
| | Note: This message is |
| | experimental and not in current |
| | common use. |
+------------------------------+----------------------------------+
| TOO-LONG | The requested value in a SET |
| | command is too long. |
+------------------------------+----------------------------------+
| UNKNOWN-COMMAND | The Attachment Daemon doesn't |
| | recognize the command. |
+------------------------------+----------------------------------+
| UNKNOWN-UPS | The UPS specified in the request |
| | is not known to the Attachment |
| | Daemon. This usually means that |
| | it didn't match anything in the |
| | Attachment Daemon configuration. |
+------------------------------+----------------------------------+
| USERNAME-REQUIRED | The command requires a USERNAME |
| | for authentication, but the |
| | client hasn't provided one. |
+------------------------------+----------------------------------+
| VAR-NOT-SUPPORTED | The specified UPS doesn't |
| | support the UPS variable in the |
| | command. |
+------------------------------+----------------------------------+Table 3: Error Responses
Note: Historically, this error response was ALREADY-LOGGED-IN.
4.4. An ABNF of the Commands ✨
Okay bestie, this section is basically the grammar cheat sheet 🎀 It repeats everything from Section 4.2, just written in Augmented Backus-Naur Form (ABNF), so it doesn't add any new features. If you want the details of each command and its response, go back to Section 4.2 💖
The commands can be written in ABNF [RFC5234] [RFC7405] and represented using US-ASCII [RFC0020].
Current practice allows mixed-case command names, but it is RECOMMENDED to use uppercase only for commands. Check out Figure 5 👑
;-------------------------------------------------------------------
; This grammar is case sensitive. Terminal keywords SHOULD be
; written in uppercase, as shown.
; The following basic rules written with uppercase names are
; taken from RFC 5234, Appendix B.1.
SP = 1*%x20 ; At least one SPACE
LF = %x0A ; Linefeed
DIGIT = %x30-39 ; Digit 0 through 9
ALPHA = %x41-5A / %x61-7A ; A-Z / a-z
DQUOTE = %x22 ; Double quote "
VCHAR = %x21-7E ; Visible (printing) characters
; Additional basic rules needed by this grammar
LC = %x61-7A ; Letter a through z
DOT = 1%x2E ; Exactly one .
COLON = 1%x3A ; Exactly one :
AT = 1%x40 ; Exactly one @
SEP = 1"-" / 1"_" / 1"." ; A single - or _ or .
JOIN = COLON / AT ; A single : or @
; Frequently used in this grammar
cmdname = 1*LC *62(DOT 1*LC) ; E.g., load.off.delay
upschar = DIGIT / ALPHA / SEP
ups = 1*ALPHA *62upschar ; E.g., Example-Mfg-999
group = ups ; E.g., HB (Not in common use)
hostname = ups ; E.g., example.com
port = 1*5DIGIT ; E.g., 3493
upsname = [group COLON] ups [AT hostname [COLON port]]
; Fully Qualified UPS name
; E.g.,
; HB:heartbeat1@example.com:3493
username = ups ; E.g., Power-Dept.6
varname = 1*LC *62( DOT 1*(DIGIT / LC) )
; E.g., outlet.1.status
;-------------------------------------------------------------------
commandLine = command LF ; LF is a single %x0A
command = attach / detach / fsd / get / help / instcmd /
list / password / primary / protver / set /
starttls / username / ver
;
attach = "ATTACH" SP upsname
;
detach = "DETACH"
;
fsd = "FSD" SP upsname
;
get = "GET" SP getsubcommnd
getsubcommand = getcmddesc / getdesc / getnumattach /
gettype / getupsdesc / getvar
;
getcmddesc = "CMDDESC" SP upsname SP cmdname
getdesc = "DESC" SP upsname SP varname
getnumattach = "NUMATTACH" SP upsname
gettype = "TYPE" SP upsname SP varname
getupsdesc = "UPSDESC" SP upsname
getvar = "VAR" SP upsname SP varname
;
help = "HELP"
;
instcmd = "INSTCMD" SP upsname SP cmdname
;
list = "LIST" listsubcommand
listsubcommand = listclient / listcmd / listenum / listrange /
listrw / listups / listvar
;
listclient = "CLIENT" SP upsname
listcmd = "CMD" SP upsname
listenum = "ENUM" SP upsname SP varname
listrange = "RANGE" SP upsname SP varname
listrw = "RW" SP upsname
listups = "UPS"
listvar = "VAR" SP upsname
;
session-password = "PASSWORD" SP *63VCHAR
; A sequence of printable characters defined
; in a server configuration file. Local
; security practices may mandate a minimum
; and maximum number of characters.
;
primary = "PRIMARY" SP upsname
;
protver = "PROTVER"
;
value = *63VCHAR ; Local practices may limit the choice of
; characters and require non-US-ASCII.
set = "SET" SP %s"VAR" SP upsname SP varname SP
DQUOTE value DQUOTE
;
starttls = "STARTTLS"
;
session-username = "USERNAME" SP username
;
ver = "VER"
;-------------------------------------------------------------------Figure 5: ABNF for the Commands
Some notes to keep in mind 🧚
- Implementation note: The ABNF uses the rules from [RFC5234] and [RFC7405], which are US-ASCII based [RFC0020]. Literally everything is built on those 💅
- The grammar is case sensitive. The terminal keywords SHOULD be written in uppercase, as specified. Caps matter here, no cap 🔥
- The repetition factor in front of an expression has the form
<min>*<max>, where<min>is the minimum number of repetitions and<max>is the maximum number. - If
<min>is omitted, its value is 0. If<max>is omitted, its value is infinity. It's giving open-ended energy 🌈 - The notation
n*n, meaning "exactly n copies", may be written asn. - Square brackets around an expression mean that the expression is optional. This could also be written as
0*1. Brackets = "maybe" vibes 🦋
4.4.1. Responses to Commands 💌
Responses to the commands are encoded in US-ASCII [RFC0020] and come in two flavours:
- Short replies to action commands. See Section 4.3 ✨
- Long replies to requests for information. These get sent as a sequence of messages. The last message will contain a line beginning
END LIST. For example, see Section 4.2.7.1 🎀
5. Statuses and Events 🌸
5.1. Status Symbols 🦋
Okay, these symbols are the abstracted view of the UPS hardware that the Attachment Daemon keeps track of. The variable ups.status holds one or more space-separated status symbols, and together they describe the UPS state at that exact moment. In current practice, the Management Daemon polls ups.status every 5 seconds with a command such as GET VAR su700 ups.status, and gets back a response such as VAR su700 ups.status "OB LB", so it can spot changes. Those changes are what signal UPS events 👀
+=========+======================================================+
| Status | Meaning |
| Symbol | |
+=========+======================================================+
| ALARM | The UPS reports that it requires intervention. |
+---------+------------------------------------------------------+
| BOOST | The UPS has determined that the voltage level of the |
| | public power supply is too low and is boosting it to |
| | the required level. The UPS continues to supply the |
| | protected system from the public power supply. |
+---------+------------------------------------------------------+
| BYPASS | The UPS is feeding current directly from the public |
| | power supply to the protected system. The backup |
| | facilities are disconnected. This state allows |
| | maintenance personnel to change the batteries |
| | without interrupting the protected system. |
+---------+------------------------------------------------------+
| CAL | The UPS is calibrating itself, for example, to |
| | determine at what charge the LB status is raised or |
| | lowered. |
+---------+------------------------------------------------------+
| CHRG | The UPS battery is charging. This usually implies |
| | that the UPS also has status OL but may not be the |
| | case if the UPS also has status OFF. |
+---------+------------------------------------------------------+
| COMM | The Attachment Daemon has effective contact with the |
| | UPS. |
+---------+------------------------------------------------------+
| DISCHRG | The UPS battery is discharging. This usually |
| | implies that the UPS also has status OB but may not |
| | be the case if the UPS also has status OFF. |
+---------+------------------------------------------------------+
| FSD | This "Forced Shutdown" status signals that the final |
| | shutdown sequence has begun. |
+---------+------------------------------------------------------+
| LB | Low Battery. The battery level of the UPS is below |
| | a chosen limit. The UPS may be in status OL or OB. |
+---------+------------------------------------------------------+
| NOCOMM | The Attachment Daemon has no effective contact with |
| | the UPS. |
+---------+------------------------------------------------------+
| OB | On Battery. The UPS is taking energy from its |
| | battery. The battery is discharging. A UPS must |
| | have status OB or OL; otherwise, it is deemed dead. |
+---------+------------------------------------------------------+
| OFF | The UPS is in state "Off". It does not react to |
| | failure in the public power supply. The exact |
| | meaning depends on the model. |
+---------+------------------------------------------------------+
| OL | Online. The UPS is online, receiving energy from |
| | the public power supply. The battery is charging. |
| | A UPS must have status OB or OL; otherwise, it is |
| | deemed dead. |
+---------+------------------------------------------------------+
| OVER | Overloaded. The UPS reports that the load on it is |
| | beyond its normal operating maximum. |
+---------+------------------------------------------------------+
| RB | Replace battery. The UPS reports that its battery |
| | or batteries should be replaced. |
+---------+------------------------------------------------------+
| TEST | Under test. The UPS is currently undergoing a test |
| | that may have been requested manually or internally. |
+---------+------------------------------------------------------+
| TICK | Heartbeat. A software UPS in the Attachment Daemon |
| | provides a regular signal monitored by the |
| | Management Daemon as a way of verifying effective |
| | end-to-end management. TICK and TOCK are |
| | companions; they are considered experimental. |
+---------+------------------------------------------------------+
| TOCK | Heartbeat. See TICK |
+---------+------------------------------------------------------+
| TRIM | The UPS has determined that the voltage level of the |
| | public power supply is too high and is reducing it |
| | to the required level. The UPS continues to supply |
| | the protected system from the public power supply. |
+---------+------------------------------------------------------+Table 4: UPS Status Symbols
5.2. Events 🦋
okay so, this is where the UPS status changes turn into actual events 💅 A Management Daemon notices something happened by comparing the UPS status it got from the Attachment Daemon over time. If the status changed, that change is the event. Iconic, honestly.
The table below shows the whole process. A status of "none" means the status symbol isn't in the variable ups.status at all ✨
The Management Daemon should grab ups.status from the Attachment Daemon at regular intervals 🔁 If it checks too often, you're wasting compute and network resources (not it 💀). If it checks too rarely, it risks missing short-lived status changes, and that's a whole mess.
A default value of 5 seconds is RECOMMENDED 🌸 Implementations MAY make it configurable if they want. So by default, the "old" status is just whatever value was retrieved 5 seconds earlier.
Current practice is for the Management Daemon to give certain events names 🏷️ Those names are in parentheses in the table.
+=======+=========+===============++=========+========+=============+
|Old | New |Event || Old | New |Event |
|Status | Status | || Status | Status | |
+=======+=========+===============++=========+========+=============+
|none | ALARM |Alarm on || ALARM | none |Alarm off |
+-------+---------+---------------++---------+--------+-------------+
|none | BOOST |Boosting || BOOST | none |Not boosting |
| | |voltage || | | |
+-------+---------+---------------++---------+--------+-------------+
|none | BYPASS |Bypass on || BYPASS | none |Bypass off |
+-------+---------+---------------++---------+--------+-------------+
|none | CAL |Calibrating || CAL | none |Not |
| | | || | |calibrating |
+-------+---------+---------------++---------+--------+-------------+
|none | CHRG |Charging || CHRG | none |Not charging |
+-------+---------+---------------++---------+--------+-------------+
|none | COMM |UPS || COMM | none |See note 4 |
| | |communicating || | | |
| | |(event COMMOK) || | | |
+-------+---------+---------------++---------+--------+-------------+
|none | DISCHRG |Discharging || DISCHRG | none |Not |
| | | || | |discharging |
+-------+---------+---------------++---------+--------+-------------+
|none | FSD |System shutdown|| FSD | none |Shutdown |
| | |(events FSD, || | |abandoned. |
| | |SHUTDOWN) || | |See note 1 |
+-------+---------+---------------++---------+--------+-------------+
|none | LB |Low battery. || LB | none |Battery not |
| | |See note 2 || | |low |
| | |(event LOWBATT)|| | | |
+-------+---------+---------------++---------+--------+-------------+
|none | NOCOMM |UPS dead? See || NOCOMM | none |See note 4 |
| | |note 4 || | | |
| | |(events || | | |
| | |COMMBAD, || | | |
| | |NOCOMM) || | | |
+-------+---------+---------------++---------+--------+-------------+
|none | OFF |UPS turned off || OFF | none |UPS not |
| | | || | |turned off |
+-------+---------+---------------++---------+--------+-------------+
|OB | OL |Receiving power|| OL | OB |Power lost |
| | |(event ONLINE) || | |(event |
| | | || | |ONBATT) |
+-------+---------+---------------++---------+--------+-------------+
|none | OVER |UPS overloaded || OVER | none |Overload gone|
+-------+---------+---------------++---------+--------+-------------+
|none | RB |Replace battery|| RB | none |Replacement |
| | |(event || | |canceled |
| | |REPLBATT) || | | |
+-------+---------+---------------++---------+--------+-------------+
|none | TEST |Test starts || TEST | none |Test finished|
+-------+---------+---------------++---------+--------+-------------+
|none | TICK |Heartbeat || TICK | none |No heartbeat.|
| | |event. See || | |See note 3 |
| | |note 3 || | | |
+-------+---------+---------------++---------+--------+-------------+
|none | TOCK |Heartbeat || TOCK | none |No heartbeat.|
| | |event. See || | |See note 3 |
| | |note 3 || | | |
+-------+---------+---------------++---------+--------+-------------+
|none | TRIM |Trimming || TRIM | none |Not trimming |
| | |voltage || | | |
+-------+---------+---------------++---------+--------+-------------+
Table 5: Event Deduction from Status ChangesNotes, because there's always a few 🙈
- Current practice does not include this event.
- If the status OB is present, current practice takes Management Daemon reception of LB as an order to perform an emergency system shutdown. 🚨
- The use of a software-defined UPS to provide a heartbeat is experimental and is not part of common current practice. 🧪
- Current practice is the following: if the UPS has not responded for 15 seconds, the Management Daemon assumes that the UPS is _dead_ (event NOCOMM), and if the last known OL/OB status was OB, a system shutdown (command FSD) is requested. 💀
6. Security Considerations 🔐
6.1. Current General Security Practice
okay so security is kind of a vibe check here 🫶 Experience over the last 20 years shows that new UPS management software releases aren't frequent, and once installed, they stay unmodified for years. That's probably because UPS management is a mature activity and part of site management. Only a limited number of system administrators get access to the UPS hardware and software, and they tend to lean on a certain "security by obscurity" since lots of installations look like Figure 6. That setup uses port 3493/TCP (nut) between the two daemons running on the same system. The traffic is often not encrypted, and when it is encrypted, it uses deprecated early versions of SSL/TLS. Not great, bestie 😭
,-----, ,--------------------,---------------------,
| UPS |---| Attachment <-Commands Management |
| |===| Daemon Responses-> Daemon |
/-----\ '--------------------'---------------------'
Listens on
port 3493/TCP
for localhost
Figure 6: Common Single-System ConfigurationThis is changing now 📈 low-cost processors are becoming available, costing a lot less than a UPS unit. That makes it interesting to shift to a setup like Figure 7, but it also makes the security weakness of Figure 6 worse, since the traffic between the daemons now goes over an exposed network. Main character energy turned into main character problems 💅
,-----,------------, ,--------------,
| UPS - Attachment | <-Commands | Management |
| | Daemon | Responses-> | Daemon |
/-----'------------\ '--------------'
Listens on
port 3493/TCP
Figure 7: Integration of UPS and Attachment DaemonThese security issues with UPS management are the same ones the power industry has in general, and they're covered in detail in IEC Technical Specification 62351 [IEC62351-1]. On top of equipment security, cyber security is now an essential consideration 🔥
Here's a quote from IEC 62351-1[IEC62351-1], the Introduction to the standard, clause 5.2.3.5:
With the computer systems for power operations presumably kept isolated from the Internet, many utility personnel do not see any reason for adding security measures to these systems. However, as clearly seen from these Subclauses, this may not be true anymore as networking becomes more prevalent and additional information access requirements grow.
In IEC 62351-1[IEC62351-1], clause 5.3.5 lists typical security attacks: Eavesdropping, Masquerade, Man-in-the-Middle, Replay, and Resource Exhaustion. [RFC3552] adds message insertion/deletion/modification and denial of service. The list is a lot, periodt 💀
Let's look at these requirements more closely 🔍
- Eavesdropping; see Section 6.3.1 👀
- Man-in-the-Middle; see Section 6.3.2 🕵️
- Masquerade; see Section 6.3.3 🎭
- Message insertion, deletion, and modification; see Section 6.3.4 ✂️
- Replay; see Section 6.3.5 🔁
- Resource Exhaustion and Denial of Service; see Section 6.3.6 🚫
6.2. Communication Security Requirements 🎀
okay so enforcing secure communication means tightening up the Attachment Daemon so it requires the use of command STARTTLS for commands sent over the global Internet. In that situation, an Attachment Daemon that's listening for traffic from anywhere other than localhost:
- SHOULD require and accept command STARTTLS, 🔒
- MUST encrypt all communication with a Management Daemon, and 🔐
- SHALL refuse all non-encrypted commands, except an initial STARTTLS. 🙅♀️
Notes, because these details matter 📝
- The SHOULD, rather than MUST, in Section 6.2, Paragraph 2, Item 1 above allows system administrators to enforce secure communication using other techniques that do not involve the STARTTLS command. 🔧
- If an Attachment Daemon requires that all commands be encrypted as required by the MUST in Section 6.2, Paragraph 2, Item 2 above, then, automatically, each Management Daemon MUST encrypt as well, since it has to do so in order to gain access. 🗝️
- The SHALL in Section 6.2, Paragraph 2, Item 3 above applies to traffic from the global Internet. An Attachment Daemon MAY accept unencrypted commands from localhost if the local installation's security practices allow it, for example, in a dedicated appliance. 🏠
Firewalls SHOULD be used to restrict communication between the Attachment Daemon and the accepted Management Daemons, prohibiting and discarding traffic from any systems that are not part of the envisioned power management setup. Note: See Section 6.2, Paragraph 4, Item 1 above on the use of SHOULD. 🧱
6.2.1. Certificate Security 📜
In long-lived installations, like the ones found in UPS management, careful certificate management is essential, whether the certificate comes from a Certificate Authority or is self-signed. For example, the expiration times of both the certificate containing the public key and the signing certificate should be specified. Future-you will thank present-you for writing those dates down 🗓️✨
6.3. Attacks and Defenses 🛡️
6.3.1. Eavesdropping 👀
okay so the defense against eavesdropping is encryption 🔐 of the commands and responses going between the client Management Daemon and the server Attachment Daemon. the protocol gives you the command STARTTLS (see Section 4.2.12 🎀), which tells the Attachment Daemon to support TLS encryption of the communication. if that command gets accepted, the Management Daemon encrypts too 💖
in current NUT Project practice, TLS is optional ✨ but a Management Daemon may refuse to accept unencrypted communication. you do that by setting the declarations FORCESSL to 1 and CERTVERIFY to 1 in the Management Daemon configuration file 🧚
6.3.1.1. Misplaced Declarations Requiring TLS 🙈
ngl this one is a lil bit of a bummer 😭 the FORCESSL and CERTVERIFY declarations, which enforce the use of encryption, live in the client Management Daemon configuration file and not in the Attachment Daemon. secure practice requires the server Attachment Daemon to do the enforcing, not a possibly rogue client Management Daemon chilling out on the Internet 👿
this weakness may be mitigated with strict firewall rules that keep the rogue client Management Daemon from reaching the Attachment Daemon 🧱
6.3.1.2. Weak Protection in Previous Version 2.7.4 🕸️
okay so version 2.8.0 of NUT supports TLS 1.3 [RFC8446] with X.509 v3 certificates as defined by [RFC5280], but previous version 2.7.4 only supported earlier SSL/TLS versions 😬 to overcome this weakness, The following techniques have been used:
- Shims; see Appendix D.1
- TLS tunnel; see Appendix D.2
- Virtual Private Network (VPN); see Appendix D.3
- Virtual Local Area Network (VLAN); see Appendix D.4
6.3.2. Man-in-the-Middle 🕵️
the protocol relies on TLS encryption to prevent man-in-the-middle attacks. see Appendix D for the defense methods used for previous NUT version 2.7.4 🌸
6.3.3. Masquerade Attack: Agent Verification 🎭
this one is giving main villain energy 😈 the protocol allows a malicious client acting as a Management Daemon to send the command FSD to an Attachment Daemon, which can shut down a working system and its power supply, as described in The Shutdown Story section (see Appendix B). a malicious client could also turn off the UPS power outlets, and then the system fails 💀
the protocol provides the commands USERNAME (see Section 4.2.13) and PASSWORD (see Section 4.2.8). these let an administrative user in a Management Daemon authenticate itself to the Attachment Daemon, which is the defense against masquerade attacks 🛡️ the administrative username and password still need protection against local malicious users, and that's done by restricting access to the configuration files 🔒
6.3.4. Message Insertion, Deletion, and Modification ✂️
the protocol relies on TLS encryption to prevent message insertion, deletion, and modification attacks. see Appendix D for the defense methods used for previous NUT version 2.7.4 🎀
6.3.5. Replay 🔁
there are two cases, bestie:
- The replay is from a system other than an approved Management Daemon, i.e., the protocol relies on a firewall to block the traffic.
- The replay is from an approved Management Daemon. i.e., the protocol relies on the Management Daemon's own security to prevent unauthorized access.
6.3.6. Denial of Service 🚫
the protocol relies on a very tightly specified firewall to prevent denial-of-service attacks. only designated client Management Daemons should be able to reach the server Attachment Daemon. the guest list is strict, periodt 🚪💅
7. IANA Considerations 🌷
the protocol specified by this text runs over port 3493/TCP (nut), which is registered by the Network UPS Tools (NUT) Project 🦋
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 ✨
this section is a very short recap of where the Network UPS Tools project has been 🕰️
- May 1996: The first hack as a cron job.
- September 1997: The first server-client code.
- March 1998: First public release.
- June 1999: Code rewrite with a UPS Driver smartups, an Attachment Daemon upsd, and a simple Management Daemon.
- September 1999: The project became "Network UPS Tools". The Management Daemon upsmon supported Primary/Secondary configurations.
- June 2001: Common core for multiple Drivers.
- May 2002: IANA granted port 3493/TCP (nut). August: release 1.0.0. November: OpenSSL support.
- April 2003: The initial set of command and variable names was designed.
- February 2005: Arnaud Quette took over the project lead from Russell Kroll.
- March 2016: Version 2.7.4 released, supported over 100 device manufacturers and hundreds of UPS models.
- November 2020: Evgeny "Jim" Klimov took over project lead from Arnaud Quette.
- May 2022: Version 2.8.0 released, supporting protocol version 1.3.
see [githist] and Appendix J [History] for a detailed history of the NUT Project 📖
8.1. Inclusion in Software Distributions
the programs upsd, upsmon, upssched, upsc, upscmd, and upsrw have been included in the package known as "nut" in the package systems of many distributions, i.e., all the major Linux distributions and Unix distributions, such as OpenBSD and OpenSolaris 🐧 a Microsoft Windows version has been developed but was not maintained 🥀
8.2. Recommended Minimum Support
the features provided by current UPS units vary wildly 🙃 but experience shows that a minimum feature set is needed for satisfactory use of the NUT Project software. a full list of variables is available in the source code file docs/nut-names.txt [gitvars], which serves as the Recording Document 📋
8.2.1. Desktop PC Variables 🖥️
the following variables form a minimum set suitable for a desktop PC. it is expected that, on public power supply failure, the PC will be halted. it will not restart automatically when power returns 🫠
battery.chargebattery.charge.lowdevice.mfrdevice.modelups.statuswith the minimum status symbol setOL OB LB FSD; see Section 5.1
8.2.2. Unattended Servers and Additional Variables 🧚
the following additional variables are needed in a minimum set suitable for an unattended server. it is expected that, on public power supply failure, the server will be halted. it will restart automatically when power returns 🌈
battery.datedevice.serialups.delay.shutdownups.delay.start
8.2.3. Commands and Other Technical Terms 💜
satisfactory use of the NUT Project software requires support for all the commands specified in protocol version 1.3, software version 2.8.0 🫶
8.2.4. Support for Earlier Versions 🍓
to ease migration from software version 2.7.4, which supported protocol version 1.2, software version 2.8.0 also supports the technical terms used in protocol version 1.2. see Appendix C for the differences 🔄
9. References 📚
9.1. Normative References
- [RFC0020] Cerf, V., "ASCII format for network interchange", STD 80, RFC 20, DOI
10.17487/RFC0020, October 1969,https://www.rfc-editor.org/info/rfc20. - [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI
10.17487/RFC2119, March 1997,https://www.rfc-editor.org/info/rfc2119. - [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, DOI
10.17487/RFC5234, January 2008,https://www.rfc-editor.org/info/rfc5234. - [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", RFC 7405, DOI
10.17487/RFC7405, December 2014,https://www.rfc-editor.org/info/rfc7405. - [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI
10.17487/RFC8174, May 2017,https://www.rfc-editor.org/info/rfc8174.
9.2. Informative References 📚
okay so this is the bibliography, the list of everything the doc points at for extra reading 🧾✨ bestie, these are the receipts and I'm obsessed with how many there are 💅
- [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/ar01s09.html. - [Documentation] "Network UPS Tools Documentation",
https://networkupstools.org/documentation.html. - [githist] "The Network UPS Tools repository, project history", July 2022,
https://github.com/networkupstools/nut/blob/master/docs/history.txt. - [gitvars] "The Network UPS Tools repository, variable names", April 2022,
https://github.com/networkupstools/nut/blob/master/docs/nut-names.txt. - [History] Kroll, R., Quette, A., and A. de Korte, "Network UPS Tools User Manual", May 2022,
https://networkupstools.org/docs/user-manual.pdf. - [HyTimeA] ISO/IEC, "Information technology -- Hypermedia/Time-based Structuring Language (HyTime)", ISO/IEC 10744:1997, August 1997.
- [IEC62351-1] IEC, "Power systems management and associated information exchange -- Data and communications security. Part 1: Communication network and system security -- Introduction to security issues", 35 pages, TC 57 - Power systems management and associated information exchange, IEC TS 62351-1:2007, May 2007,
https://nanopdf.com/download/technical-iec-specification-ts-62351-1_pdf. - [Library] "Devices Dumps Library",
https://networkupstools.org/ddl/. - [NUT] "Network UPS Tools, Devices Dumps Library",
https://www.networkupstools.org. - [nut-repository] "The Network UPS Tools repository",
https://github.com/networkupstools/nut/. - [nut-upsdev] NUT, "Network UPS Tools (NUT) Project Mailing List for Developers",
https://alioth-lists.debian.net/cgi-bin/mailman/listinfo/nut-upsdev. - [nut-upsuser] NUT, "Network UPS Tools (NUT) Project Mailing List for Users",
https://alioth-lists.debian.net/cgi-bin/mailman/listinfo/nut-upsuser. - [Registry] IANA, "Service Name and Transport Protocol Port Number Registry",
https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml. - [RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC Text on Security Considerations", BCP 72, RFC 3552, DOI 10.17487/RFC3552, July 2003,
https://www.rfc-editor.org/info/rfc3552. - [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., Housley, R., and W. Polk, "Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008,
https://www.rfc-editor.org/info/rfc5280. - [RFC7030] Pritikin, M., Ed., Yee, P., Ed., and D. Harkins, Ed., "Enrollment over Secure Transport", RFC 7030, DOI 10.17487/RFC7030, October 2013,
https://www.rfc-editor.org/info/rfc7030. - [RFC7991] Hoffman, P., "The "xml2rfc" Version 3 Vocabulary", RFC 7991, DOI 10.17487/RFC7991, December 2016,
https://www.rfc-editor.org/info/rfc7991. - [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
https://www.rfc-editor.org/info/rfc8446. - [RFC8894] Gutmann, P., "Simple Certificate Enrolment Protocol", RFC 8894, DOI 10.17487/RFC8894, September 2020,
https://www.rfc-editor.org/info/rfc8894. - [SGML] Goldfarb, C., "The SGML Handbook", Oxford University Press, ISBN-10 0-19-853737-9, 1990.
- [sgmlnorm] OpenJade Project, "OpenJade Distribution Page",
http://openjade.sourceforge.net/. - [stunnel] "Stunnel",
https://www.stunnel.org/.
Appendix A. Variables 🎀
okay the UPS variables are basically the unit's current vibe, like a snapshot of its state 🔋 some of them are also tunable values and Instant Commands too, which is giving control panel energy ✨ see Section 2.5 for that. the full list lives in the variable names reference [gitvars] 📖
how many variables you actually use depends on how fancy the UPS is 💅 this annex shows a typical example of the subset for a reasonably complete "consumer grade" UPS. the NUT Project keeps a huge library of these variable subsets [Library] for different UPS models 🌈
also, successive versions of the same product can add or drop features, so the subset can change 🦋 for example, ups.delay.start gets removed from a "consumer grade" UPS. the manufacturer keeps that feature for the "professional" product 💀
a Management Daemon acting as a utility program can give you a listing of the variables for a given product 🧚 for example, the utility program upsc, which is included in the NUT package. see Section 2.6, Paragraph 3 🫶
the next sections show how the variables work by using the values from a typical product, a 1600 Va 1000 W UPS 🔥
A.1. Typical UPS Variables ⚡🔋
okay so this is the big table of typical UPS variables, bestie 💖 each row is a variable name, a typical value, and what it's for, so you can see what a UPS reports about itself 🧚
+===============================+============+====================+
| Variable | Typical | Default |
| | Value | Description |
+===============================+============+====================+
| battery.charge | 100 | "Battery charge |
| | | (percent of full)" |
+-------------------------------+------------+--------------------+
| battery.charge.low | 20 | "Remaining battery |
| | | level when UPS |
| | | switches to LB |
| | | (percent)" |
+-------------------------------+------------+--------------------+
| battery.runtime | 1481 | "Battery runtime |
| | | (seconds)" |
+-------------------------------+------------+--------------------+
| battery.type | PbAc | "Battery |
| | | chemistry" |
+-------------------------------+------------+--------------------+
| device.mfr | Example | "" |
| | Mfg | |
+-------------------------------+------------+--------------------+
| device.model | Economy | "" |
| | 1600 | |
+-------------------------------+------------+--------------------+
| device.serial | 1234567890 | "" |
+-------------------------------+------------+--------------------+
| device.type | ups | "" |
+-------------------------------+------------+--------------------+
| driver.name | usbhid-ups | "Driver name" |
+-------------------------------+------------+--------------------+
| driver.parameter.lowbatt | 37 | "Driver parameter: |
| | | <name>" |
+-------------------------------+------------+--------------------+
| driver.parameter.offdelay | 30 | "Driver parameter: |
| | | <name>" |
+-------------------------------+------------+--------------------+
| driver.parameter.ondelay | 40 | "Driver parameter: |
| | | <name>" |
+-------------------------------+------------+--------------------+
| driver.parameter.pollfreq | 30 | "Driver parameter: |
| | | <name>" |
+-------------------------------+------------+--------------------+
| driver.parameter.pollinterval | 2 | "Driver parameter: |
| | | <name>" |
+-------------------------------+------------+--------------------+
| driver.parameter.port | auto | "Driver parameter: |
| | | <name>" |
+-------------------------------+------------+--------------------+
| driver.parameter.synchronous | no | "Driver parameter: |
| | | <name>" |
+-------------------------------+------------+--------------------+
| driver.parameter.vendorid | 0999 | "Driver parameter: |
| | | <name>" |
+-------------------------------+------------+--------------------+
| driver.version | 2.8.0 | "Driver version - |
| | | NUT release" |
+-------------------------------+------------+--------------------+
| driver.version.data | HID 1.39 | "" |
+-------------------------------+------------+--------------------+
| driver.version.internal | 0.41 | "Internal driver |
| | | version" |
+-------------------------------+------------+--------------------+
| input.transfer.high | 264 | "High voltage |
| | | transfer point |
| | | (V)" |
+-------------------------------+------------+--------------------+
| input.transfer.low | 184 | "Low voltage |
| | | transfer point |
| | | (V)" |
+-------------------------------+------------+--------------------+
| outlet.1.desc | PowerShare | "Outlet |
| | Outlet 1 | description" |
+-------------------------------+------------+--------------------+
| outlet.1.id | 2 | "Outlet system |
| | | identifier" |
+-------------------------------+------------+--------------------+
| outlet.1.status | on | "Outlet switch |
| | | status" |
+-------------------------------+------------+--------------------+
| outlet.1.switchable | no | "Outlet switch |
| | | ability" |
+-------------------------------+------------+--------------------+
| outlet.2.desc | PowerShare | "Outlet |
| | Outlet 2 | description" |
+-------------------------------+------------+--------------------+
| outlet.2.id | 3 | "Outlet system |
| | | identifier" |
+-------------------------------+------------+--------------------+
| outlet.2.status | on | "Outlet switch |
| | | status" |
+-------------------------------+------------+--------------------+
| outlet.2.switchable | no | "Outlet switch |
| | | ability" |
+-------------------------------+------------+--------------------+
| outlet.desc | Main | "Outlet |
| | Outlet | description" |
+-------------------------------+------------+--------------------+
| outlet.id | 1 | "Outlet system |
| | | identifier" |
+-------------------------------+------------+--------------------+
| outlet.power | 25 | "" |
+-------------------------------+------------+--------------------+
| outlet.switchable | no | "Outlet switch |
| | | ability" |
+-------------------------------+------------+--------------------+
| output.frequency.nominal | 50 | "Nominal output |
| | | frequency (Hz)" |
+-------------------------------+------------+--------------------+
| output.voltage | 230.0 | "Output voltage |
| | | (V)" |
+-------------------------------+------------+--------------------+
| output.voltage.nominal | 230 | "Nominal output |
| | | voltage (V)" |
+-------------------------------+------------+--------------------+
| ups.beeper.status | enabled | "UPS beeper |
| | | status" |
+-------------------------------+------------+--------------------+
| ups.delay.shutdown | 20 | "Interval to wait |
| | | after shutdown |
| | | with delay command |
| | | (seconds)" |
+-------------------------------+------------+--------------------+
| ups.delay.start | 30 | "Interval to wait |
| | | before |
| | | (re)starting the |
| | | load (seconds)" |
+-------------------------------+------------+--------------------+
| ups.firmware | 02 | "UPS firmware" |
+-------------------------------+------------+--------------------+
| ups.load | 20 | "Load on UPS |
| | | (percent of full)" |
+-------------------------------+------------+--------------------+
| ups.mfr | Example | "UPS manufacturer" |
| | Mfg | |
+-------------------------------+------------+--------------------+
| ups.model | Economy | "UPS model" |
| | 1600 | |
+-------------------------------+------------+--------------------+
| ups.power.nominal | 1600 | "UPS power rating |
| | | (VA)" |
+-------------------------------+------------+--------------------+
| ups.productid | ffff | "Product ID for |
| | | USB devices" |
+-------------------------------+------------+--------------------+
| ups.serial | 000000000 | "UPS serial |
| | | number" |
+-------------------------------+------------+--------------------+
| ups.status | OL | "UPS status" |
+-------------------------------+------------+--------------------+
| ups.temperature | 27 | "UPS temperature |
| | | (C)" |
+-------------------------------+------------+--------------------+
| ups.timer.shutdown | 0 | "Time before the |
| | | load will be |
| | | shutdown |
| | | (seconds)" |
+-------------------------------+------------+--------------------+
| ups.timer.start | 0 | "Time before the |
| | | load will be |
| | | started (seconds)" |
+-------------------------------+------------+--------------------+
| ups.vendorid | 0999 | "Vendor ID for USB |
| | | devices" |
+-------------------------------+------------+--------------------+
Table 6: Typical UPS VariablesA.2. Typical UPS Readable and Writable Variables
Okay so this is the part where the UPS shows you its settings, bestie 🔧✨ Some features are variables you're allowed to tune. The exact list depends on which UPS model you've got, so don't be surprised if yours looks different 💅. A Management Daemon acting as a utility program can list the variables it has and act on them too, like the utility program upsrw from the NUT package. Check Section 2.6, Paragraph 3 for that bit 🦋.
+========================+============+=========================+
| Variable | Typical | Default Description |
| | Value | Provided as Response to |
| | | the Command GET DESC |
+========================+============+=========================+
| battery.charge.low | 20 | "Remaining battery |
| | | level when UPS switches |
| | | to LB (percent)" |
+------------------------+------------+-------------------------+
| input.transfer.high | 264 | "High voltage transfer |
| | | point (V)" |
+------------------------+------------+-------------------------+
| input.transfer.low | 184 | "Low voltage transfer |
| | | point (V)" |
+------------------------+------------+-------------------------+
| outlet.1.desc | PowerShare | "Outlet description" |
| | Outlet 1 | |
+------------------------+------------+-------------------------+
| outlet.2.desc | PowerShare | "Outlet description" |
| | Outlet 2 | |
+------------------------+------------+-------------------------+
| outlet.2.switchable | no | "Outlet switch ability" |
+------------------------+------------+-------------------------+
| outlet.desc | Main | "Outlet description" |
| | Outlet | |
+------------------------+------------+-------------------------+
| outlet.power | 25 | "Description |
| | | unavailable" |
+------------------------+------------+-------------------------+
| output.voltage.nominal | 230 | "Nominal output voltage |
| | | (V)" |
+------------------------+------------+-------------------------+
| ups.delay.shutdown | 20 | "Interval to wait after |
| | | shutdown with delay |
| | | command (seconds)" |
+------------------------+------------+-------------------------+
| ups.delay.start | 30 | "Interval to wait |
| | | before (re)starting the |
| | | load (seconds)" |
+------------------------+------------+-------------------------+
Table 7: Typical Readable and Writable UPS VariablesA.3. Typical UPS Instant Commands
Some features of a UPS are actions called Instant Commands (see Section 2.5), and the user can order them around 🎀. These are the commands that stand for those actions. Again, the exact list depends on the UPS model 💖. A Management Daemon acting as a utility program may list what's available and act on it, like the utility program upscmd from the NUT package. Section 2.6, Paragraph 3 has the details 🌸.
+==================+==========================================+
| Command | Meaning |
+==================+==========================================+
| beeper.disable | Disable the UPS beeper |
+------------------+------------------------------------------+
| beeper.enable | Enable the UPS beeper |
+------------------+------------------------------------------+
| beeper.mute | Temporarily mute the UPS beeper |
+------------------+------------------------------------------+
| load.off | Turn off the load immediately |
+------------------+------------------------------------------+
| load.off.delay | Turn off the load with a delay (seconds) |
+------------------+------------------------------------------+
| load.on | Turn on the load immediately |
+------------------+------------------------------------------+
| load.on.delay | Turn on the load with a delay (seconds) |
+------------------+------------------------------------------+
| shutdown.return | Turn off the load and return when power |
| | is back |
+------------------+------------------------------------------+
| shutdown.stayoff | Turn off the load and remain off |
+------------------+------------------------------------------+
| shutdown.stop | Stop a shutdown in progress |
+------------------+------------------------------------------+
Table 8: Typical Instant CommandsAppendix B. The Shutdown Story for System and UPS
This appendix is the backstory 📖🌈. It helps you get how the system and the UPS vibe together, but it does not define any feature of the command-response protocol, so don't go looking for rules here 🙈.
We're following the shutdown and restart of a long-running unattended server that's protected by one UPS 🖥️💜. The Management Daemon lives inside the server, as shown in Figure 8.
,------------------SERVER------------------,
| | |
,-----, | UPS <-Commands UPS |
| UPS |---| Attachment | Management |
| |===| Daemon Responses-> Daemon |
/-----\ '--------------------'---------------------'
Internal
loopback
Figure 8: Long-Running Unattended Server- _The public power supply is on._ The system runs normally. Every 5 seconds, variable ups.status reports OL. _Days, weeks, months go by..._ 🌞
- _Winter storm. Tree falls on power lines. The public power supply fails._ The server stays up, running on the UPS battery. The Management Daemon polls the Attachment Daemon and notices the status change OL->OB. 🌩️😭
- The Management Daemon logs warning messages. The server is still running on the UPS battery. _Minutes go by..._ 📝
- The battery drains below the level set by variable battery.charge.low. The server is still running, but the UPS battery won't last much longer 🪫. The Management Daemon polls the Attachment Daemon and notices the status change OB->OB+LB.
- The Management Daemon logs the low battery event 📋.
- The Management Daemon decides it's time for a system shutdown 🛑. It sets status FSD in the Attachment Daemon so any Secondaries get the call to shut down too, then waits for command GET NUMATTACH to report one single attachment, i.e., the Primary itself. After that, the Management Daemon issues the system shutdown command for itself 👑.
- The operating system's shutdown process takes over. During the system shutdown, a specific script from the NUT Project, or an equivalent system service unit, runs the command upsdrvctl shutdown. This tells the UPS to shut down N seconds later, where the default is N=20 ⏳. Note that the "shutdown" of a UPS removes power from the outlet sockets but may not turn the UPS off completely. A delayed shutdown is sometimes audible, and the characteristic beeping of the UPS stops 🔕.
- The system shuts down and powers off, hopefully before the N=20 seconds have passed 🌙.
- _N seconds after item 7_ The UPS shuts down, meaning it turns off its outlet sockets once N=20 seconds have passed. With some UPS units, there's an audible "clunk" 💥.
What if the public power supply comes back before the UPS shuts down? The UPS unit should be able to wait a configurable time, with a default of 30 seconds. Both timers start from the moment the UPS receives the upsdrvctl shutdown command. _Minutes, hours, days go by..._ ⏰💀
- _Some time later, maybe much later, the public power supply returns._ The UPS reconnects its outlets to send power to the protected system 💡.
- The system BIOS option "Restore power on AC return" or "Restore to previous state" has hopefully been selected, and the system powers up. The bootstrap process of the operating system begins 🥾.
- The operating system starts the Attachment Daemon and the Management Daemon. The Attachment Daemon starts the Driver and scans the UPS. The UPS status becomes OL+LB 🔋.
- After some time, the battery charges above the battery.charge.low threshold, and the Attachment Daemon declares the status change OL+LB->OL. We are now back in the same situation as item 1 above 🔁✨.
Appendix C. Technical Terms: Historical Differences 🎀
okay bestie, this appendix is the cheat sheet for when NUT renamed some terms between 2.7.4 and 2.8.0 🧚 It lists the major differences between the terms in previous version 2.7.4 and the ones used in this text for release 2.8.0 💅
+===================+========================+===========+
| Term in Previous | Term in this Document, | Reference |
| Release NUT 2.7.4 | Release NUT 2.8.0 | |
+===================+========================+===========+
| ALREADY-LOGGED-IN | ALREADY-ATTACHED | Table 3 |
+-------------------+------------------------+-----------+
| ALREADY-SSL-MODE | TLS-ALREADY-ENABLED | Table 3 |
+-------------------+------------------------+-----------+
| LOGIN | ATTACH | Section |
| | | 4.2.1 |
+-------------------+------------------------+-----------+
| LOGOUT | DETACH | Section |
| | | 4.2.2 |
+-------------------+------------------------+-----------+
| Master | Primary | Section |
| | | 2.7 |
+-------------------+------------------------+-----------+
| NETVER | PROTVER | Section |
| | | 4.2.10 |
+-------------------+------------------------+-----------+
| NUMLOGINS | NUMATTACH | Section |
| | | 4.2.4.3 |
+-------------------+------------------------+-----------+
| Slave | Secondary | Section |
| | | 2.8 |
+-------------------+------------------------+-----------+
Table 9: Technical Terms: Historical DifferencesAppendix D. Security Defenses in Release 2.7.4 🛡️
ngl, 2.7.4 couldn't do TLS 1.3 [RFC8446] 😭 so this appendix covers the mitigating techniques people used to cover that gap 🔐
D.1. Shims 🧩
Previous version 2.7.4 of NUT did not support TLS 1.3 [RFC8446]. Where that protection is needed for 2.7.4, a possible technique is to put shims between the Attachment Daemon and the network, and between the network and the Management Daemon, as shown in Figure 9 ✨ The shims give you TLS 1.3 support, so the Attachment Daemon and Management Daemon can keep going for a while without having TLS implementations of their own 💖 The technique has been successfully tested 🙌
TLS shim listens TLS shim listens
on port TBD1/TCP on port 3493/TCP
,-----,------------,----, ,----,--------------,
| UPS - Attachment |TLS | <-STARTTLS | TLS| Management |
| | Daemon |shim| OK--> |shim| Daemon |
/-----'------------'----\ '----'--------------'
Listens on
port 3493/TCP
Figure 9: Shims Provide TLS Support During MigrationD.1.1. Attachment Daemon Shim 🦋
The shim in front of the Attachment Daemon listens to incoming traffic on port TBD1/TCP. When it receives the command STARTTLS, it:
- returns
OKto the client and sets up TLS encapsulation. - does not send
STARTTLSto the Attachment Daemon port 3493/TCP.
All other commands and responses are passed through.
Note: Port TBD1/TCP is not specified by this text.
D.1.2. Management Daemon Shim 🌸
The shim in front of the Management Daemon listens for incoming traffic on port 3493/TCP. When it receives the command STARTTLS, it:
- returns
FEATURE-NOT-CONFIGUREDto the client. - sends
STARTTLSto the Attachment Daemon on port TBD1/TCP.
All other commands and responses are passed through.
D.2. TLS Tunnels 🚇
Another technique is to use TLS tunnels [RFC8446], with a software such as stunnel [stunnel], which adds OpenSSL-based TLS support without modifying the Attachment Daemon or Management Daemon. The NUT Project has no procedure to enforce this on sites 🙈
D.3. VPN 🔒
A further option to secure communications is very similar to TLS tunneling [RFC8446]. It consists of routing the NUT traffic through a Virtual Private Network (VPN) 🌈
D.4. VLAN 🌐
A fourth option is to isolate the UPS management traffic at the network switching level using a Virtual LAN (VLAN) technique 💜
,-------------, ,-------------,
,-----, | Attachment | | Management |
| UPS |---| Daemon | | Daemon |
| | |-------------| UPS |-------------|
| |===| | Management | UPS |
/-----\ | Protected |~~~~~~~~~~~~~~~| Management |
| Server | VLAN | Client |
| | '-------------'
'-------------'
Production | VLAN
,---|-------,
,-----------,|
,-----------,|'
| Clients |'
'-----------'
Figure 10: UPS Management Protocol Runs over Its Own VLANIn Figure 10, there are two VLANs. The main traffic between the protected server and its clients uses the production VLAN. The UPS management traffic between the Attachment and Management Daemons uses the UPS management VLAN, marked as ~~~~~~~~~~~~~.
Appendix E. Administrative Security 👑
Administrative commands, such as FSD, INSTCMD, and SET, are powerful and can have a deep effect on system integrity 😭 For example, FSD is involved in mission-critical system shutdown decisions. Access to them needs to be managed and restricted, so this section presents the current practice 💅
E.1. Management of Administrative Users 🧑💻
The Attachment Daemon maintains a file (currently upsd.users) that defines each administrative user. Note that these users are independent of those recorded in file /etc/passwd. Each administrative user gets its own section in upsd.users. The declarations in that section set the parameters that define that user's privileges. The section begins with the name of the user enclosed in square brackets, opening bracket ([) and closing bracket (]), and continues until the next username in brackets or EOF.
For example, the following file declares two administrative users, admin and pfy:
[admin]
password = sekret
upsmon master
actions = SET
instcmds = ALL
[pfy]
password = sekret
instcmds = test.panel.start
instcmds = test.panel.stopWithin each section, the administrative user declarations are:
+=============+==========================================+
| Declaration | Meaning |
+=============+==========================================+
| actions | Allow the user to do certain things in |
| | the Attachment Daemon. To specify |
| | multiple actions, use multiple instances |
| | of the declaration. Valid actions are: |
| | |
| | * FSD Set the "Forced Shutdown" flag |
| | for this UPS. See Section 4.2.3. |
| | |
| | * SET Change the value of a UPS |
| | variable. See Section 4.2.11. |
+-------------+------------------------------------------+
| instcmds | Let a user initiate specific Instant |
| | Commands. See Section 4.2.6. Use value |
| | ALL to grant all commands automatically. |
| | To specify multiple commands, use |
| | multiple instances of the instcmds |
| | field. For the full list of what a |
| | given UPS supports, use client upscmd -l |
| | supplied by the NUT Project. The LIST |
| | CMD command is issued within the client |
| | upscmd. |
+-------------+------------------------------------------+
| password | Set the password for this user. _Your |
| | password should be more secure than the |
| | examples shown._ |
+-------------+------------------------------------------+
| upsmon | Add the necessary actions for a |
| | Management Daemon to process a system |
| | shutdown. In current practice, the |
| | value is still master or slave. Note |
| | that there is no EQUALS =. |
+-------------+------------------------------------------+
Table 10: Administrative User DeclarationsE.2. An Administrative User of a Client Management Daemon 🎀
The following examples show the current security practices for administrative users of a client Management Daemon. They also illustrate the command pair USERNAME and PASSWORD. See Sections 4.2.13 and 4.2.8 ✨
E.2.1. An Administrative User Logs into a Short Session ⏱️
In this simple example of current practice, the system administrator sets the battery level at which an Attachment Daemon will raise the status LB, represented by variable battery.charge.low, to 35% of full charge. The system administrator types the following command to call the client upsrw, supplied by the NUT Project:
upsrw -s battery.charge.low=35 -u admin -p sekret UPS-1@example.comOption -s specifies the variable and the value, option -u specifies the USERNAME, option -p specifies the PASSWORD, and UPS-1@example.com is the UPS. The USERNAME and PASSWORD commands are issued within the client upsrw, and the session is of short duration.
Note: Your password should be stronger than the example shown.
E.2.2. An Administrative User Logs into a Long Session 🕰️
In this second example of current practice, the long-running Management Daemon upsmon, which is responsible for initiating system shutdowns and is provided by the NUT Project, issues the commands USERNAME and PASSWORD when it starts up. The data values needed for the USERNAME and PASSWORD commands come from a configuration file, upsmon.conf, which contains the line:
MONITOR UPS-1@example.com 1 admin sekret masterThis says that the UPS to be monitored is UPS-1@example.com. It provides 1 single power supply. The administrative user is admin, with password sekret. The Management Daemon acts as a Primary, although current practice still uses the former term master 🌟
The USERNAME and PASSWORD commands are contained within the client upsmon, and the session is of long duration 🫶
Acknowledgments ✨
okay bestie, this whole doc is based on the NUT Project documentation [devguide] 🫶 huge shoutout to Charles Lepple, Arjen de Korte, Arnaud Quette, Jim Klimov, Russell Kroll, Manuel Wolfshant, Greg Troxel, Mark Hansen, and so many other people who chat on the nut-upsuser [nut-upsuser] and nut-upsdev [nut-upsdev] mailing lists 💜 the editor is so grateful 💖
Earlier drafts were written with an SGML DTD [SGML] and an XML meta-DTD defined by HyTime Annex A [HyTimeA] 🤓 ngl that's a LOT of acronyms. Here's the tea: unlike XML, SGML offers markup minimization, and the earlier drafts totally took advantage of it 🙈 The osgmlnorm [sgmlnorm] program generated the XML that went into xml2rfc [RFC7991], which then created the document's current source 🎀 The editor also gives a big thank you to Carsten Bormann and Julian Reschke for helping out on the xml2rfc mailing list 🌸
Many helpful comments came in from Eliot Lear, Bart Smit, David Zomaya, Joyce Norris, and Ted Mittelstaedt 💅✨
Author's Address 🦋
Roger Price (editor)
Network UPS Tools Project
France
Email: ietf@rogerprice.org📦 where this page comes from
- ietf: rfc9271 2022-08
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms