Uninterruptible Power Supply (UPS) Management Protocol -- Commands and Responses Network UPS Tools Project
France ietf@rogerprice.org
General IETF Uninterruptible Power Supply UPS NUT This document describes the command/response protocol currently used in the management of Uninterruptible Power Supply (UPS) units and other power devices often deployed in small offices, and in IT installations subject to an erratic public power supply. The UPS units typically interface to an Attachment Daemon in the system they protect. This Daemon is in turn polled by a Management Daemon which notifies users and system administrators of power supply incidents, and automates system shutdown decisions. The commands and responses described by this document are exchanged between the UPS Attachment Daemon and the Management Daemon. Current practice when this text was written risks weak security and this is addressed in the Security Considerations sections of this document.
Introduction
Current Practice This document describes UPS management techniques and current UPS management practice published by the NUT Project. The document is based on version 2.8.0 of the NUT Project software which supports version 1.3 of the NUT protocol. Since May 2002, the protocol described by this document has been operating on IANA port nut/3493 running over TCP.
NUT Software Project The primary goal of the NUT (Network UPS Tools) Software Project is to provide support for Power Devices, such as Uninterruptible Power Supplies. The Project has been in operation since 1998 with a major rework in 2003. It operates through a user mailing list, a developer mailing list, a web site and a GitHub repository. See and for a history of the project.
The "Shutdown Story" Appendix "The Shutdown Story" describes the current UPS management practice for performing a managed shutdown of unattended infrastructure after an unscheduled failure of the public power supply in order to minimise the risk of corruption to data processed by this infrastructure. See .
How to Read this Document To lighten the text, the term "UPS" is used when "Managed Power Device" would be more complete. The reader should understand the simple "UPS" to include other managed power devices. The statuses and events appearing in this document are named with short text-form names, some of which are abbreviations. A full list of the statuses can be found in while the events are listed in . This document refers to the "public power supply". Other texts frequently refer to "utility power", "input source power" or even "wall power".
Requirements Language 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 when, and only when, they appear in all capitals, as shown here.
Additional Information Additional information about the NUT Project is available in the project documentation. Requests for further information about this protocol and related technical matters may be addressed to the mailing list of the NUT Project.
Terminology The following technical terms appear in this document. They are listed in alphabetical order.
Attachment Daemon The Attachment Daemon retrieves status from the UPS and sends commands to it often through a Driver specific to the hardware model and the connection medium, e.g., USB, serial. See . It maintains an abstracted view of the hardware through the use of hardware statuses. See . A Management Daemon may consult the abstracted view using the commands described in this document. See 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 implemented an Attachment Daemon as program upsd and a set of hardware specific drivers, all written in K&R C. The Attachment Daemon is launched as system user "root", but for better security, then drops privilege to run as a detached software service.
Administrative User In current practice, the commands and other functions offered by the Attachment Daemon to each Management Daemon are made available to a set of Management Daemon users which authenticate to the Attachment Daemon with basic credentials (username and password). These users are not system users, they are specific to an Attachment Daemon and are listed in a text file (currently upsd.users) which is read by the Attachment Daemon and which assigns to each of them the password, Instant Commands and actions which are allowed, together with the Primary or Secondary status of the Management Daemon. For details, see . For details of Primary see , and for details of Secondary see . 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 .
Driver A Driver is that part of an Attachment Daemon which is specific to the UPS hardware, the connection medium and the connection protocol, e.g., USB, serial. In current practice the Attachment Daemon has a driver for each hardware interface type it supports. Although this document considers the driver to be part of the Attachment Daemon, current practice is to see it as a separate software unit running as a Daemon "in front of" the Attachment Daemon. The protocol for data exchange between the Driver and the Attachment Daemon is outside the scope of this document.
Event A UPS Event occurs in the Management Daemon when a change in UPS status is received from the Attachment Daemon. This event is internal to the Management Daemon. See .
Instant Command A command which 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 .
Management Daemon The Management Daemon is primarily responsible for managing the hardware and orchestrating system-wide actions after a power event. Using commands sent to the Attachment Daemon it follows the status of the UPS and determines when UPS events occur. It takes decisions based on the events, such as calling for a system shutdown. See . Although the term includes the word "Daemon" nothing requires that it be implemented as a detached software service. The Management Daemon may also provide administrative functions such as a graphic interface to view the hardware activity. There are several examples of a Management Daemon: the NUT Project provides upsmon which takes the system shutdown decision when the public power supply fails. Further configuration options such as timers were provided by helper program upssched. Other programs represent the Management Daemon:
  • upsc reports the values of the variables defined for a given UPS, see .
  • upsrw reports on and changes the values of the readable and writable configuration variables defined for a given UPS, see .
  • upscmd reports on and executes the instant action commands defined for a given UPS, see .
  • UPSmon.py is an experimental Python3 rewrite of upsmon and upssched which includes support for TLS 1.3.
Primary When a power device such as a UPS unit supplies power to more than one system, the computer running the driver is known as the Primary. The others are Secondaries. See figure . Common current practice for system administrators is to consider the Management Daemon in the Primary to be the Primary Management Daemon which is in charge of the shutdown of all the systems powered by the UPS. The Primary Management Daemon sets status symbol FSD to order the secondaries to shut down. Note: Historically, the Primary was known as the "Master".
Secondary When a hardware device such as a UPS unit supplies power to more than one system, the system which communicates directly with the UPS unit e.g. using a USB, RS232, or network connection, is known as the Primariy. The other are Secondaries. There is no Attachment Daemon in a Secondary. See figure . Common current practice for system administrators is to consider the Management Daemon in a Secondary to be a Secondary Management Daemon which understands status symbol FSD as an order to shut down. Note: Historically, the Secondary was known as the "Slave".
Session The Management Daemon may initiate a TCP session with a specified device such as a UPS known to the Attachment Daemon. The session structure provides for audit and security as well as access to mission critical UPS functions. For example good practice requires a password protection for an Instant Command which turns off a UPS outlet. Other than the commands and responses used, the details of session management are outside the scope of this document.
UPS Status The status of a hardware device such as a UPS unit is a symbolic description of the state of the unit. It consists of a space separated list of symbols from the set {ALARM BOOST BYPASS CAL CHRG COMM DISCHRG FSD LB NOCOMM OB OFF OL OVER RB TEST TRIM}. The symbols TICK and TOCK are experimental additions to the statuses and are not in common current practice. See which specifies each of these symbols. See for details of the recommended minimum support of status symbols OB, OL, LB and FSD.
UPS Variable The metrics and identifiers provided by each UPS are represented by variables giving the value representing that metric or identifier, The UPS variable is an abstraction of the UPS hardware configuration and activity maintained by the Attachment Daemon. See which provides examples of variables. For example the variable battery.charge contains the current charge of the UPS battery as a percentage value. Note: Some variables are constants, e.g. battery type, manufacturer. See for details of the recommended minimum support of variables. A full list of possible variables is available in source code file docs/nut-names.txt which serves as the Recording Document.
Protocol Overview Figure shows a reference configuration in which the command/response protocol applies. The UPS shown is representative of all managed power devices,
Reference Configuration "The client" ,--------------, ,--------------, ,-----, | UPS | <-Commands | UPS | | UPS |---| Attachment |---------------| Management | | |===| Daemon | Responses-> | Daemon | /-----\ '--------------' '--------------' UPS Attachment UPS Management System Network System
The reference configuration in figure shows a single UPS unit which has a power supply link (===) and a data link (---) attached to a system running an Attachment Daemon. The UPS provides power supply protection to the system running the Attachment Daemon. In practice there may be more than one UPS unit, and a unit may provide power protection to more than one system. The figure also shows a single Management Daemon. In practice there may be more than one Management Daemon, and any one Management Daemon may manage more than one UPS Attachment Daemon. The protocol applies to connections between the Attachment Daemon and the Management Daemon which act as server and client respectively. The Management Daemon sends commands over TCP to the Attachment Daemon and receives responses over TCP from that Daemon. The two Daemons may run in the same system, or may be connected through a local or wide area network. In simple cases, as shown in figure , the Attachment Daemon and the Management Daemon are in the same system, the one protected by the UPS. The commands and responses are exchanged through an internal loopback interface.
Simplified single-system configuration "The client" ,--------------------,---------------------, ,-----, | UPS <-Commands UPS | | UPS |---| Attachment | Management | | |===| Daemon Responses-> Daemon | /-----\ '--------------------'---------------------' Internal loopback UPS Attachment and Management System
The reference configuration does not require any specific design. For example figure shows an arrangement in which the Attachment Daemon is closely associated with, or even included in the UPS system setup. This is becoming more prevalent with the availability of low cost processors able to run the Attachment Daemon thereby effectively creating a network attached UPS running a published protocol.
UPS and Attachment Daemon integration "The client" ,-----,------------, ,--------------, | | UPS | <-Commands | UPS | | UPS - Attachment |---------------| Management | | | Daemon | Responses-> | Daemon | /-----'------------\ '--------------' UPS Attachment UPS Management System Network System
As the power requirements for processors decrease, it is becoming increasingly common to use a single UPS to protect multiple systems as shown in figure . However there is only one data line (---) from the UPS to the Primary system. The others have only power connections (===) to the UPS, and are known as Secondaries. A Secondary does not run an Attachment Daemon, it connects over a network to the Attachment Daemon in the Primary. Figure shows the Attachment Daemon and the Primary Management Daemon in the same system. This is common practice but it is not a technical requirement.
UPS protects multiple systems "The client" ,--------------------,---------------------, ,-----, | UPS <-Commands Primary | | |---| Attachment | Management | Primary | |===| Daemon Responses-> Daemon | | | '--------------------'---------------------' | UPS | ^ | | '<-Commands---Responses->, | | v | | ,--------------,-----------------, | |============| | Secondary | /-----\ | | Management | Secondary | | Daemon | '--------------'-----------------'
Protocol Specification This specification includes only the commands and their responses. An implementation of the Attachment Daemon has an internal state machine, and some complex implementations of the Management Daemon include an internal state machine; for example to assist the system shutdown of a complex installation. The Management Daemon is required to remember the previous ups.status value it received from the Attachment Daemon and compare it with the next. Other than that the management protocol used between them is effectively stateless. See for example which shows a map of the new ups.status response and the previous ups.status response to an Event which is taken as the basis for Management Daemon action.
Notation Used in this Specification The character set used for commands and responses is UTF-8 but current practice is to limit the character set used to the single byte UTF-8 characters 0-127. Multi-word elements are contained within U+0022 QUOTATION MARK characters for easier parsing. E.g., "UPS on fire". Embedded quotation marks are escaped with U+005C REVERSE SOLIDUS \ often known as backslashes. Embedded backslashes are also escaped by representing them as \\. Commands and responses have no leading or trailing whitespace, and are terminated with a single new line character U+000A LINE FEED (LF). White space within commands and responses is reduced to one U+0020 SPACE (SP).
Commands The commands address the UPS to which they apply by <upsname> where
  • <upsname> ::= <ups>[@<hostname>[:<port>]]
  • <ups> is defined by the Attachment Daemon configuration files.
  • The default <hostname> is localhost
  • The <port> is the number of the TCP port on which the Attachment Daemon is listening. The default is 3493. This is supported by all current Management Daemons.
Examples: myups, UPS-97B@bigserver.example.com Note: Experimental Management Daemons use an extended form of <upsname> in configuration files and in program parameters, where
  • <upsname> ::= [<group>:]<ups>[@<hostname>[:<port>]]
  • <group> is an experimental extension to provide for groups of UPSs. It is not in common current practice.
  • <ups> is defined by the Attachment Daemon configuration files.
  • The default <hostname> is localhost
Examples: ups-1@example.com:3493, HB:heartbeat1@example.com:3493 In the current implementation, the names of commands and subcommands are not case sensitive. For example GET VAR may be written as Get var, but in this specification they are always written in upper case. Similarly, <upsname> and <varname> are not case sensitive. For example UPS341 ups.id may be written as ups341 Ups.Id, but in this specification <varname> is always written in lower case.
ATTACH In a configuration such as that shown in in which a UPS protects more than one system, the Primary Management Daemon needs to know how many Secondaries are currently "active", i.e., powered by the UPS, either from the public power supply or from battery power. The Attachment Daemon supports this by keeping a count of all the "active" systems powered by a UPS. The count is initialised, one Secondary at a time by the ATTACH command, which should be understood as "count this Secondary as active". ATTACH is one of three commands for Secondary counting: command DETACH decrements the count and a Management Daemon may read the count at any time using command NUMATTACH. The ATTACH command is also sent to the Attachment Daemon for the Primary so during normal, fully protected operation, the count is 1 for the Primary + the number of secondaries. During a full system shutdown, the count drops as each Secondary Management Daemon executes command DETACH during its own shutdown. When the count drops to 1, only the Primary is "active" and it knows that all the secondaries have shut down. Command: ATTACH <upsname> If the command succeeds, the response is OK, otherwise see the error responses in . Note: Historically, this command was known as LOGIN. Since that LOGIN was not the conventional user access to a shell or program the name was changed to avoid confusion.
DETACH This companion command to ATTACH reduces the count of "active" Secondaries. It should be understood as "this Secondary is no longer active", and is usually used during system shutdown to decrement a count of how many Secondaries are still "active". Command: DETACH If the command succeeds, the response is OK Goodbye, otherwise see the error responses in . Note: Historically, this command was known as LOGOUT.
FSD A Management Daemon which is Primary and has the required authority, uses this command to set status symbol FSD meaning "Forced Shutdown" in the Attachment Daemon. In current practice the Primary Management Daemon uses the symbol to tell the Secondaries to shut down. Command: FSD <upsname> If the command succeeds, the response is OK FSD-SET, otherwise see the error responses in . In current practice, commands such as FSD are made available only to a privileged administrative user authorized to send such a mission critical command. The security provisions for administrative users are discussed in . Note: The symbol "FSD" is also used for an Event. See .
GET Retrieve a single response from the Attachment Daemon. The possible sub-commands are:
GET CMDDESC Retrieve a text description of a command. Command: GET CMDDESC <upsname> <cmdname> Response: CMDDESC <upsname> <cmdname> "<description>" For example: GET CMDDESC su700 load.on and response CMDDESC su700 load.on "Turn on the load immediately" This is like GET DESC, but it applies to an Instant Command;. See .
GET DESC Retrieve a text description of a UPS variable. See . Command: GET DESC <upsname> <varname> Response: DESC <upsname> <varname> "<description>" where <description> is a string that gives a brief explanation of the named variable. The Attachment Daemon MAY return "Unavailable" if the file which provides this description is not installed. For example command GET DESC su700 ups.status and response DESC su700 ups.status "UPS status"
GET NUMATTACH Retrieve the count kept by the Attachment Daemon of all the "active" systems protected by this UPS. Command: GET NUMATTACH <upsname> Response: NUMATTACH <upsname> <value> where <value> is a count of the Primary and the number of Secondaries currently powered by this UPS. For example command GET ATTACH su700 and response NUMATTACH su700 1 This information is needed by the Management Daemon to determine how many Secondaries are still connected during the system shutdown process. Note: Historically, this sub-command was known as NUMLOGINS. Since LOGIN was not the conventional user access to a shell or program the name was changed to avoid confusion.
GET TYPE Retrieve the type of a UPS variable. See . Command: GET TYPE <upsname> <varname> Response: TYPE <upsname> <varname> <type>... where <type> can be one or more of the following tokens. Multiple types may be returned. For example command GET TYPE su700 input.transfer.low and response TYPE su700 input.transfer.low ENUM Variable Types
    Type     Meaning
RW This is a read/write variable. It may be read with command GET VAR, see , and set to a different value with command SET, see .
ENUM An enumerated type, which supports specific predetermined values.
STRING:n This is a string of maximum length n.
RANGE This is a number, either integer or float, comprised in the range which may be seen with the command LIST RANGE, see .
NUMBER This is a single numeric value, either integer or float.
Notes:
  • ENUM, STRING:n and RANGE are usually associated with RW, but not always. The default <type>, when omitted, is numeric, so either integer or float. Each Driver is then responsible for handling values as either integer or float.
  • Current practice is to represent floating point values using locale C.utf8 which is a decimal (base 10) US English-based representation. Hexadecimal, exponents, and comma for thousands separator are not allowed. For example: "1200.20" is valid, while "1,200.20" and "1200,20" are not valid.
GET UPSDESC Retrieve a text description of a UPS. Command: GET UPSDESC <upsname> Response: UPSDESC <upsname> "<description>" where <description> is defined by the Attachment Daemon configuration. If it is not set, current practice is for the Attachment Daemon to return "Unavailable". For example command GET UPSDESC su700 and response UPSDESC su700 "Development box" This can be used to provide human-readable descriptions instead of a cryptic ups@hostname string.
GET VAR Retrieve the value of a UPS variable. See . Command: GET VAR <upsname> <varname> Response: VAR <upsname> <varname> "<value>" For example command GET VAR su700 ups.status and response VAR su700 ups.status "OB LB"
HELP Return a list of the commands supported by the Attachment Daemon. This command is intended for human as well as program use. Command HELP For example, the following command line sequence executed on an Attachment Daemon: netcat localhost 3493 HELP Commands: HELP VER GET LIST SET INSTCMD ATTACH DETACH USERNAME PASSWORD STARTTLS Note: Historically, this command also returned LOGIN and LOGOUT. Since LOGIN was not the conventional user access to a shell or program, the command names were changed to ATTACH and DETACH to avoid confusion.
INSTCMD Send an Instant Command to the UPS. Command: INSTCMD <upsname> <cmdname> where <upsname> is the name of the UPS and <cmdname> is the Instant Command to be issued to that UPS. See for examples of instant commands. If the command succeeds, the response is OK, otherwise see the error responses, . For example the command: INSTCMD su700 test.panel.start and the response OK
LIST All the LIST commands produce a response with a common format. The response will begin with BEGIN LIST and then repeat the initial query. A list then follows, with as many lines as are necessary. The response ends with END LIST followed by the initial query. The formatting may seem a bit redundant, but it makes a different form of client possible. A client can send a LIST command and then wait for the response. When it arrives, the Management Daemon doesn't need a complicated state machine to remember which list is which. Note: The current NUT Project implementation of the Attachment Daemon, upsd, sends back the response to the LIST command as a sequence of messages. The Management Daemon should continue reading these messages until it receives the line beginning END LIST. The possible subcommands are:
LIST CLIENT The command calls for the Attachment Daemon to report all the current Management Daemon clients of a given UPS. Command: LIST CLIENT <upsname> The response is BEGIN LIST CLIENT <upsname> CLIENT <upsname> <client_IP_address> ... END LIST CLIENT <upsname> For example, the command LIST CLIENT ups1 and the response: BEGIN LIST CLIENT ups1 CLIENT ups1 ::1 CLIENT ups1 203.0.113.1 END LIST CLIENT ups1
LIST CMD The command calls for the Attachment Daemon to report a list of the Instant Commands which the Management Daemon may send to the Attachment Daemon. This Instant Command list is the abstracted view of the UPS hardware capabilities. An economical UPS will support few or no Instant Commands but a professional model should support more. Command: LIST CMD <upsname> The response is: BEGIN LIST CMD <upsname> CMD <upsname> <cmdname> ... END LIST CMD <upsname> where <upsname> is the name of the UPS, and <cmdname> is the name of the Instant Command which may be issued to the UPS. For example the command: LIST CMD su700 and the response: BEGIN LIST CMD su700 CMD su700 load.on CMD su700 test.panel.start ... END LIST CMD su700
LIST ENUM The command calls for the Attachment Daemon to report the set of possible values of a UPS variable which has predetermined values. Command: LIST ENUM <upsname> <varname> The response is: BEGIN LIST ENUM <upsname> <varname> ENUM <upsname> <varname> "<value>" ... END LIST ENUM <upsname> <varname> where <upsname> is the name of the UPS, <varname> is the UPS variable and <value> is one of the possible values of that UPS variable. Note that in current practice the output is an unordered list. Note also that the U+0022 QUOTATION MARK characters are part of the response. For example the command: LIST ENUM su700 input.transfer.low and the response: BEGIN LIST ENUM su700 input.transfer.low ENUM su700 input.transfer.low "103" ENUM su700 input.transfer.low "100" ... END LIST ENUM su700 input.transfer.low
LIST RANGE The command calls for the Attachment Daemon to report the interval in which valid values of UPS variable lie. Command: LIST RANGE <upsname> <varname> The response is: BEGIN LIST RANGE <upsname> <varname> RANGE <upsname> <varname> "<min>" "<max>" ... END LIST RANGE <upsname> <varname> where <upsname> is the name of the UPS, <varname> is the UPS variable and {<min>,<max>} is the interval of valid values of that UPS variable. Note that the U+0022 QUOTATION MARK characters are part of the response. For example, the command LIST RANGE su700 input.transfer.low and the response: BEGIN LIST RANGE su700 input.transfer.low RANGE su700 input.transfer.low "90" "105" END LIST RANGE su700 input.transfer.low
LIST RW The command calls for the Attachment Daemon to report a list of the UPS variables associated with a given UPS which may be read and 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 which are needed for an automatic shutdown and restart, see . See also for details of the recommended minimum support of variables. A full list of variables is available in source code file docs/nut-names.txt which serves as the Recording Document. Command: LIST RW <upsname> The response is: BEGIN LIST RW <upsname> RW <upsname> <varname> "<value>" ... END LIST RW <upsname> where <upsname> is the name of the UPS, <varname> is the UPS variable and <value> is the value of that UPS variable. Note that the U+0022 QUOTATION MARK characters are part of the response. For example the command: LIST RW su700 and the response: BEGIN LIST RW su700 RW su700 output.voltage.nominal "115" RW su700 ups.delay.shutdown "020" ... END LIST RW su700
LIST UPS The command calls for the Attachment Daemon to report a list of the UPS units to which it is attached. Command: LIST UPS The response is: BEGIN LIST UPS UPS <upsname> "<description>" ... END LIST UPS where <upsname> is the name of a UPS, and <description> is the description maintained by the Attachment Daemon if available. It is set to "Unavailable" otherwise. Note that the U+0022 QUOTATION MARK characters are part of the response. This command can also be used to determine what values of <upsname> are valid before calling other functions on the server. This is also a good way to handle situations where a single Attachment Daemon supports multiple UPS's. It is also useful for clients which perform a UPS discovery process. For example, the response: BEGIN LIST UPS UPS su700 "Development box" END LIST UPS
LIST VAR The command calls for the Attachment Daemon to report a list of all the UPS variables which it maintains for a given UPS, and the values of those UPS variables. Command: LIST VAR <upsname> The response is: BEGIN LIST VAR <upsname> VAR <upsname> <varname> "<value>" ... END LIST VAR <upsname> where <upsname> is the name of the UPS, <varname> is the UPS variable and <value> is the value of that variable. Note that the U+0022 QUOTATION MARK characters are part of the response. The response to this command lists the UPS variables available for this UPS and their current values. For example the command LIST VAR su700 and the response: BEGIN LIST VAR su700 VAR su700 ups.mfr "Example Mfg" VAR su700 ups.mfr.date "10/17/96" ... END LIST VAR su700 See for details of the recommended minimum support of variables. A full list of variables is available in source code file docs/nut-names.txt which serves as the Recording Document.
PASSWORD 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 . Command: PASSWORD <password> If the command succeeds, the response is OK, otherwise see the error responses, . For examples of the use of commands USERNAME and PASSWORD by administrative users, see .
PRIMARY In current practice, the Attachment Daemon records in local file upsd.users that an administrative user is a Primary. See 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 such critical actions as setting status symbol FSD. Command: PRIMARY <upsname> where <upsname> is the name of the UPS. If the Attachment Daemon has the authority, the response is OK, otherwise see the error responses in . Note: Historically, this command was known as MASTER.
PROTVER Return the implementation version of the command/response protocol used by the Attachment Daemon. This command is intended for human as well as program use. Command PROTVER For example, the following command line sequence in the Attachment Daemon: netcat localhost 3493 PROTVER 1.3 Notes:
  1. There are no U+0022 QUOTATION MARK characters in the response.
  2. Historically, this command was known as NETVER and current practice is to use NETVER instead of PROTVER.
  3. The implementation version of the protocol returned by PROTVER is different to the implementation version of the Attachment Daemon returned by VER.
  4. The protocol version 1.3 requires support of the commands used in previous protocol version 1.2 aliases.
SET 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>" where <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 U+0022 QUOTATION MARK characters are part of the command. If the command succeeds, the response is OK, otherwise see the error responses in . For example the command: SET VAR su700 ups.id "My UPS" and the response OK
STARTTLS The client tells the Attachment Daemon to switch to TLS encrypted communication. When the client receives OK it also switches to TLS encryption. Command: STARTTLS If the command succeeds, the response is OK STARTTLS, otherwise see the error responses in . If the client does not send command STARTTLS to the Attachment Daemon communication continues unencrypted, however an Attachment Daemon MAY refuse unencrypted communication. Notes:
  1. NUT 2.8.0 supports the encryption of communications between the Attachment Daemon and the Management Daemon using TLS 1.3 with X.509 v3 certificates as defined by RFC5280 and updates.
  2. In the closely restrained world of UPS management, it may be possible to obtain better security usig self-signed certificates.
USERNAME 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 . For examples of the use of commands USERNAME and PASSWORD by administrative users, see .
VER Return the implementation version of the Attachment Daemon. This command is intended for human as well as program use. Command VER For example, the following command line sequence: netcat localhost 3493 VER Network UPS Tools upsd 2.8.0 - http://www.networkupstools.org/ Notes:
  1. There are no U+0022 QUOTATION MARK characters in the response.
  2. The implementation version of the Attachment Daemon returned by VER is different to the protocol version returned by PROTVER.
  3. NUT version 2.8.0 supports the commands used in previous version 2.7.4 as aliases.
Summary of Responses
Response when Command Succeeds If the command succeeds, the response has the following command-dependent form: Response if command succeeds
Command Response Note Reference
ATTACH OK Was LOGIN
DETACH OK Goodbye Was LOGOUT
FSD OK FSD-SET
GET Sub command specific
HELP List of commands
INSTCMD OK
LIST Sub command specific
PASSWORD OK
PRIMARY OK
PROTVER Protocol version Was NETVER
SET OK
STARTTLS OK STARTTLS
USERNAME OK
VER Program version
Error Responses Error responses have the following format: ERR <error-name> [<extra>] where <error-name> is a single word token taken from the 27 characters A-Z and U+002D HYPHEN-MINUS. Implementations MAY if needed add an additional optional <extra>. Current practice does not make use of this possibility. The <error-name> may have one of the following values: Error responses
    The error name token    
<error-name> 		Meaning
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. Note: Historically, this error response was ALREADY-LOGGED-IN.
ALREADY-SET-PASSWORD The client has already supplied a PASSWORD and is attempting to repeat the command in the same Session.
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 which 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 which is not valid.
INVALID-PASSWORD The client sent a non valid PASSWORD.
INVALID-USERNAME The client sent an non valid USERNAME.
INVALID-VALUE The value specified in the request is not valid. This usually applies to a SET of an ENUM type which is using a value not in the list of allowed values. See .
PASSWORD-REQUIRED The command requires a previous 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.
An ABNF of the Commands This section repeats the syntax of , but in Augmented Bachus-Naur Form (ABNF). It does not define any additional feature. For further details of each command and the response, see . The commands may be presented in ABNF , , and represented using Unicode and encoded in UTF-8 , a transformation format of ISO 10646. In this ABNF, non-terminals are written in lower case letters, terminals are written in upper case letters. User supplied values are written in lower case letters and are enclosed between Less-Than Sign U+003C and Grater-Than Sign U+003E: <cmdname> is defined in , <value> is defined in , <varname> is defined in , <upsname> is defined in and <username> is defined in . Current practice tolerates mixed case command names, but it is RECOMMENDED to use upper case only for commands. See .
ABNF for the Commands command = attach / detach / fsd / %s"GET" getsubcommand / help / instcmd / %s"LIST" listsubcommand / password / primary / protver / set / starttls / username / ver attach = %s"ATTACH" <upsname> detach = %s"DETACH" fsd = %s"FSD" <upsname> getsubcommand = getcmddesc / getdesc / getnumattach / gettype / getupsdesc / getvar getcmddesc = %s"CMDDESC" <upsname> <cmdname> getdesc = %s"DESC" <upsname> <varname> getnumattach = %s"NUMATTACH" <upsname> gettype = %s"TYPE" <upsname> <varname> getupsdesc = %s"UPSDESC" <upsname> getvar = %s"VAR" <upsname> <varname> help = %s"HELP" instcmd = %s"INSTCMD" <upsname> <cmdname> listsubcommand = listclient / listcmd / listenum / listrange / listrw / listups / listvar listclient = %s"CLIENT" <upsname> listcmd = %s"CMD" <upsname> listenum = %s"ENUM" <upsname> <varname> listrange = %s"RANGE" <upsname> <varname> listrw = %s"RW" <upsname> listups = %s"UPS" listvar = %s"VAR" <upsname> password = %s"PASSWORD" <password> primary = %s"PRIMARY" <upsname> protver = %s"PROTVER" set = %s"SET" %s"VAR" <upsname> <varname> U+0022<value>U+0022 starttls = %s"STARTTLS" username = %s"USERNAME" <username> ver = %s"VER"
Statuses and Events
Status Symbols These symbols resume the abstracted view of the UPS hardware maintained by the Attachment Daemon. The variable ups.status contains one or more space-separated status symbols which together describe the UPS state at that instant. In current practice the Management Daemon will poll variable ups.status every 5 seconds with a command such as GET VAR su700 ups.status and response VAR su700 ups.status "OB LB" to discover changes in the UPS status. These changes will indicate UPS events. UPS Status Symbols
Status Symbol Meaning
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 it's battery. The battery is discharging. A UPS must have status OB or OL, otherwise it is deemed dead.
OFF The UPS is in state "Off". It does not react to failure in the 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 it's normal operating maximum.
RB Replace battery. The UPS reports that it's battery/batteries should be replaced.
TEST Under test. The UPS is currently undergoing a test, which may have been called for manually or internally.
TICK Heartbeat. A software UPS in the Attachment Daemon 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.
Events A Management Daemon detects the occurrence of a UPS Event from a change in the UPS status received from the Attachment Daemon. The following table summarizes the process. A status of "none" means that the status symbol is not present in the variable ups.status. The Management Daemon should retrieve the variable ups.status from the Attachment Daemon at regular intervals. If the interval is too short, compute and network resources will be wasted, but if the interval is too large, the Management Daemon risks missing short-lived changes in the UPS status. A default value of 5 seconds is RECOMMENDED, but an implementation MAY make this value configurable. By default the "old" status is therefore the previous value retrieved 5 seconds ago. Current practice is for the Management Daemon to assign names to certain events. These is shown in the table in parentheses. Event deduction from status changes
Old status New status Event      Old status New status Event
none ALARM Alarm on      ALARM none Alarm off
none BOOST Boosting voltage      BOOST none Not boosting
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 communicating
(Event COMMOK) 		     COMM none See note
none DISCHRG Discharging      DISCHRG none Not discharging
none FSD System shutdown
(Events FSD, SHUTDOWN) 		     FSD none Shutdown abandoned. See note
none LB Low battery. See note (Event LOWBATT)      LB none Battery not low
none NOCOMM UPS dead? See note
(Events COMMBAD, NOCOMM) 		     NOCOMM none See note
none OFF UPS turned off      OFF none UPS not turned off
OB OL Receiving power
(Event ONLINE) 		     OL OB Power lost
(Event ONBATT)
none OVER UPS overloaded      OVER none Overload gone
none RB Replace battery
(Event REPLBATT) 		     RB none Replacement canceled
none TEST Test starts      TEST none Test finished
none TICK Heartbeat event. See note      TICK none No heartbeat. See note
none TOCK Heartbeat event. See note      TOCK none No heartbeat. See note
none TRIM Trimming voltage      TRIM none Not trimming
Notes
  1. Current practice does not include this event.
  2. If the status OB is present, current practice takes Management Daemon reception of LB as an order to perform an emergency system shutdown.
  3. The use of a software defined UPS to provide a heartbeat is experimental and is not part of common current practice.
  4. Current practice is: if the UPS has not responded for 15 seconds, 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 called for.
Security Considerations
Current General Security Practice Experience over the last 20 years shows that new UPS management software releases are not frequent, and when installed, stay unmodified for some years. This is probably because UPS management is a mature hardware dependent activity. A limited number of system administrators have access to the UPS hardware and software and tend to assume a certain "security by obscurity" since many installations have a configuration as shown in figure which uses port nut/3493 between the two Daemons running in the same system. The traffic is often not encrypted, and when encrypted uses deprecated early versions of SSL/TLS.
Common single-system configuration ,-----, ,--------------------,---------------------, | UPS |---| Attachment <-Commands Management | | |===| Daemon Responses-> Daemon | /-----\ '--------------------'---------------------' Listens on port nut/3493 for localhost
This situation is now changing as low cost processors become available, costing significantly less than a UPS unit. This evolution makes it interesting to shift to a configuration as shown in figure , but it also exacerbates the security weakness of figure since the traffic between the Daemons is now over an exposed network.
Integration of UPS and Attachment Daemon ,-----,------------, ,--------------, | UPS - Attachment | <-Commands | Management | | | Daemon | Responses-> | Daemon | /-----'------------\ '--------------' Listens on port nut/3493
These security issues raised by UPS management are those of the power industry in general: they are addressed in detail in Technical Specification IEC 62351-1. In addition to equipment security, cyber security is now an essential consideration. Quoting from IEC 62351-1 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.
Clause 5.3.5 lists typical security attacks: Eavesdropping, Masquerade, Man-in-the-Middle, Replay, Resource Exhaustion. RFC3552 adds message insersion / deletion / modification, and denial of service. Let's look more closely at these requirements:
  • Eavesdropping, see
  • Man-in-the-Middle, see
  • Masquerade, see
  • Message insersion, deletion, modification, see
  • Replay, see
  • Resource Exhaustion, Denial of Service, see
Communication Security Requirements Enforcing secure communication requires tightening up the Attachment Daemon to require the use of command STARTTLS for commands sent over the global Internet. In such a situation an Attachment Daemon listening for traffic other than from the localhost:
  1. SHOULD require and accept command STARTTLS,
  2. MUST encrypt all communication with a Management Daemon,
  3. SHALL refuse all non-encrypted commands except an initial STARTTLS.
Notes:
  • The SHOULD rather than MUST in above allows system administrators to enforce secure communication using other techniques which do not involve the STARTTLS command.
  • If an Attachment Daemon requires that all commands be encrypted as required by the MUST in above, then automatically each Management Daemon MUST encrypt as well, since it has to do so in order to gain access.
  • The SHALL in 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.
  • Note that the separate management of strongly secure traffic from the global Internet and weakly secure traffic from localhost can be achieved by using two ports: nut/3493 for the current weakly secure traffic from localhost, and some other port, perhaps ups/TBD1, for enforced secure communication, much in the manner of http and https.
Firewalls SHOULD be used to restrict the communication between the Attachment Daemon and the accepted Management Daemons, prohibiting and discarding traffic from any systems that are not part of the envisioned power management setup. Note: See above on the use of SHOULD.
Attacks and Defences
Eavesdropping The defence against eavesdropping is encryption of the commands and responses passed between client Management Daemon and server Attachment Daemon. The protocol provides command STARTTLS, see , which calls on the Attachment Daemon to support TLS encryption of the communication. If this command is accepted, the Management Daemon also encrypts. In current NUT Project practice, the use of TLS is optional, however a Management Daemon may refuse to accept unencrypted communication. This is done by setting declarations FORCESSL to 1 and CERTVERIFY to 1 in the Management Daemon configuration file.
Misplaced declarations requiring TLS A further weakness is that the FORCESSL and CERTVERIFY declarations which enforce use of encryption are in the client Management Daemon configuration file and not in the Attachment Daemon. Secure practice requires enforcement by the server Attachment Daemon rather than a possibly rogue client Management Daemon out on the Internet. This weakness may be mitigated with strict firewall rules which would prevent the rogue client Management Daemon from accessing the Attachment Daemon.
Weak protection in previous version 2.7.4 Although version 2.8.0 of NUT supports TLS v.3 with X.509 v3 certificates as defined by RFC5280 , previous version 2.7.4 only supported earlier SSL/TLS versions. To overcome this weakness, The following techniques have been used:
  • Shims, see
  • TLS tunnel, see
  • Virtual Private Network, VPN, see
  • Virtual Local Area network, VLAN, see
Man in the Middle The protocol relies on TLS encryption to prevent man-in-the-middle attacks. See for defense methods used for previous NUT version 2.7.4.
Masquerade Attack: Agent Verification The protocol allows a Management Daemon to send command FSD to an Attachment Daemon to shut down a working system and it's power supply as described in The Shutdown Story, see . A malicious client acting as a Management Daemon could turn off the UPS power outlets causing the system to fail. The protocol provides commands USERNAME, see , and PASSWORD, see , which allow an administrative user in a Management Daemon to authenticate itself to the Attachment Daemon, as a defence against masquerade attacks. The administrative user name and password need protection against local malicious users. This is done by restricting access to the configuration files.
Message insertion, deletion, modification The protocol relies on TLS encryption to prevent message insertion, deletion and modification attacks. See for defense methods used for previous NUT version 2.7.4.
Replay There are two cases:
  1. The replay is from a system other than an approved Management Daemon: the protocol relies on a firewall to block the traffic.
  2. The replay is from an approved Management Daemon: the protocol relies on the Management Daemon's own security to prevent unauthorised access.
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.
Codepoint Management This document raises five matters of codepoint management:
  1. The namespaces occupied by the protocol commands described in this document, see .
  2. The namespaces occupied by the protocol responses described in this document, see .
  3. The namespace occupied by UPS status names,
  4. The namespace occupied by UPS variable names,
  5. The port name and port number used to manage UPS units.
Namespaces used by Commands, Responses, Statuses and Variables Current NUT Project experience after more than 20 years is that the UPS management area advances slowly, and that there are few requests to modify or extend the Commands, Responses, Statuses and Variables. When this does occur, the NUT Project has been able to settle the matter without difficulty in the project mailing list. It is therefore proposed to not burden IANA with this namespace management and to continue with the current process in which the project in its mailing list acts as a Working Group. The Commands, Responses, Statuses and Variables are currently recorded as follows: Project records of namespace allocation
Namespace Recording document Reference
Commands and Responses This document Commands, see , Responses, see
(Idem, historical record) Project Developer Guide Ch 9 Developer Guide
Statuses This document
(Idem, historical record) Source code clients/status.h GitHub repository
Variables Source code file docs/nut-names.txt GitHub repository
Port Name and Number used to Manage UPS Units See the IANA Registry for the latest situation.
Port nut/3493 In 2002 IANA assigned port nut/3493 to project lead Russell Kroll, and updated the assignment to the NUT Project itself in 2020.
Port ups/401 In 2008 IANA assigned ups/401 "Uninterruptible Power Supply" to Mr. Charles Bennett as both assignee and contact. We have been unable to find any protocol document or other published activity report for this port other than the One Windows Trojan. Mr. Bennett himself died in 2015, see obituary. Since his email address was registered by IANA as bennettc@ohio.edu it is possible that the University of Ohio is a successor in interest. The editor tried to contact the IT support department of the university by email and telephone but was rejected. Ed: My non-contact was Mr. Keith Brock, IT Support Senior Specialist, brock@ohio.edu +1 740 597 2136
NUT Project Requirement The NUT Project needs to address the the current weak security, see , of UPS management deployments, for example
  • by implementing the "shim" technique of described in for providing secure access to the Attachment Daemon,
  • or by providing a choice of ports through which an Attachment Daemon may receive commands: one for "legacy" traffic, the other for fully secured traffic.
The project needs a second registered port. Since ports are a limited resource, it would be better to re-use an existing port rather than request a new one, and the project is interested in using existing port ups/TBD1. Let's look more closely at this:
  • The port name "ups" satisfies the Principle of Least Surprise. It is not surprising for a port called "ups" to be used to manage UPSs. It is unlikely to be used for anything else.
  • There are no other known users of this port and no other published protocols or usage reports.
  • The currently assigned port number 401 is for a system port. The project has no imperative need for such a port; a user port, TBD1, would be sufficient. The Attachment Daemon is a system activity, but it can be launched by root and dropped to a non-privileged user perfectly well on a user port. Note: In Unix-like systems a port with a number below 1024 is privileged and requires elevated permissions to manage.
  • System ports are more likely to attract malicious scans than user ports.
  • The project does not need to be assigned this port. The need is to be able to use port "ups".
IANA Considerations
Port Name ups: Reference to this Document The NUT Project has a requirement to use a second port, see "NUT Project Requirement" , and would like to use port name ups as well as port nut. The project requests that IANA authorise such use, perhaps by updating the Service Name and Transport Protocol Port Number Registry for ports ups and nut/3493 to include a reference to this document. UPS management does not need a system port. If port number 401 were freed and the name ups assigned to user port TBD1, that would be equally effective. The document shepherd is requested to replace the port number TBD1 by any number that IANA assigns to port name ups.
Change of Registrant The NUT Project advises IANA that port ups/401 has no effective registrant, see . The project does not have an imperative need to be the registrant but will accept to become the registrant if IANA deems such change desirable. Such a change in registrant could be accompanied by an allocation of a user port number TBD1.
Implementation Status This section presents a very short summary of the status of the Network UPS Tools project
  • May 1996: The first hack as a cron job.
  • September 1997: The first server-client code.
  • March 1998: First public release.
  • June 1999: Code rewrite with a UPS driver smartups, an Attachment Daemon 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 nut/3493. 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.
  • March 2022: Version 2.8.0 released, supporting protocol version 1.3.
See and for a detailed history of the NUT Project.
Inclusion in Software Distributions The programs upsd, upsmon, upssched, upsc, upscmd and upsrw have been included in the package known as "nut" in the package systems of many distributions: all the major Linux distributions, and Unix distributions such as OpenBSD and OpenSolaris. A Microsoft Windows version has been developed but was not maintained.
Recommended Minimum Support The features provided by current UPS units vary widely. However experience shows that a minimum feature set is needed for satisfactory use of the NUT Project software. A full list of variables is available in source code file docs/nut-names.txt which serves as the Recording Document.
Desktop PC Variables The following variables form a minimum set suitable for 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.charge
  • battery.charge.low
  • device.mfr
  • device.model
  • ups.status with the minimum status symbol set OL OB LB FSD, see .
Unattended Servers, 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.date
  • device.serial
  • ups.delay.shutdown
  • ups.delay.start
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. The software should also support the technical terms used in protocol version 1.2, software version 2.7.4. See for the differences.
Acknowledgments This document is based on the NUT Project documentation. The editor acknowledges the work of Charles Lepple, Arjen de Korte, Arnaud Quette, Jim Klimov, Russell Kroll, Manuel Wolfshant, Greg Troxel, Mark Hansen and many others who contribute to the nut-upsuser. and nut-upsdev mailing lists. The source for this document is marked up using an SGML DTD and an XML meta-DTD as defined by HyTime Annex A. Unlike XML, SGML offers markup minimisation, and the source document takes advantage of this. The osgmlnorm program generates XML which program xml2rfc uses to prepare the HTML and text renderings. The editor acknowledges the help received from Carsten Bormann and Julian Reschke in the xml2rfc mailing list. The editor thanks the Independent Submissions Editors Adrian Farrel and Eliot Lear for advice received during the preparation of this document. Many helpful comments were received from Bart Smit, David Zomaya, Joyce Norris, Ted Mittelstaedt and Manuel Wolfshant.
Normative References Key words for use in RFCs to Indicate Requirement Levels In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. Unicode Format for Network Interchange The Internet today is in need of a standardized form for the transmission of internationalized "text" information, paralleling the specifications for the use of ASCII that date from the early days of the ARPANET. This document specifies that format, using UTF-8 with normalization and specific line-ending sequences. [STANDARDS-TRACK] Augmented BNF for Syntax Specifications: ABNF Internet technical specifications often need to define a formal syntax. Over the years, a modified version of Backus-Naur Form (BNF), called Augmented BNF (ABNF), has been popular among many Internet specifications. The current specification documents ABNF. It balances compactness and simplicity with reasonable representational power. The differences between standard BNF and ABNF involve naming rules, repetition, alternatives, order-independence, and value ranges. This specification also supplies additional rule definitions and encoding for a core lexical analyzer of the type common to several Internet specifications. [STANDARDS-TRACK] Case-Sensitive String Support in ABNF This document extends the base definition of ABNF (Augmented Backus-Naur Form) to include a way to specify US-ASCII string literals that are matched in a case-sensitive manner. Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. ISO/IEC 10646:2020 Information technology - Universal coded character set (UCS) Informative References Guidelines for Writing RFC Text on Security Considerations All RFCs are required to have a Security Considerations section. Historically, such sections have been relatively weak. This document provides guidelines to RFC authors on how to write a good Security Considerations section. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. The "xml2rfc" Version 3 Vocabulary Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile This memo profiles the X.509 v3 certificate and X.509 v2 certificate revocation list (CRL) for use in the Internet. An overview of this approach and model is provided as an introduction. The X.509 v3 certificate format is described in detail, with additional information regarding the format and semantics of Internet name forms. Standard certificate extensions are described and two Internet-specific extensions are defined. A set of required certificate extensions is specified. The X.509 v2 CRL format is described in detail along with standard and Internet-specific extensions. An algorithm for X.509 certification path validation is described. An ASN.1 module and examples are provided in the appendices. [STANDARDS-TRACK] Improving Awareness of Running Code: The Implementation Status Section This document describes a simple process that allows authors of Internet-Drafts to record the status of known implementations by including an Implementation Status section. This will allow reviewers and working groups to assign due consideration to documents that have the benefit of running code, which may serve as evidence of valuable experimentation and feedback that have made the implemented protocols more mature. This process is not mandatory. Authors of Internet-Drafts are encouraged to consider using the process for their documents, and working groups are invited to think about applying the process to all of their protocol specifications. This document obsoletes RFC 6982, advancing it to a Best Current Practice. The Transport Layer Security (TLS) Protocol Version 1.3 This document specifies version 1.3 of the Transport Layer Security (TLS) protocol. TLS allows client/server applications to communicate over the Internet in a way that is designed to prevent eavesdropping, tampering, and message forgery. This document updates RFCs 5705 and 6066, and obsoletes RFCs 5077, 5246, and 6961. This document also specifies new requirements for TLS 1.2 implementations. IEC TS 62351-1 Power systems management and associated information exchange -- Data and communications security. Part 1: Communication network and system security -- Introduction to security issues Provides an introduction to the remaining parts of the IEC 62351 series, primarily to introduce the reader to various aspects of information security as applied to power system operations. Network UPS Tools (NUT) Project Network UPS Tools (NUT) Project Mailing List for users Network UPS Tools (NUT) Project Mailing List for developers GitHub Repository for the Network UPS Tools (NUT) Project Network UPS Tools (NUT) Project Developer Guide The SGML Handbook Oxford University Press International Standard ISO/IEC 10744 -- Hypermedia/Time-based Structuring Language, Annex A, SGML Extended Facilities SGMLNORM An SGML System Conforming to International Standard ISO 8879 -- Standard Generalized Markup Language Service Name and Transport Protocol Port Number Registry Charles Bennett Obituary GitHub Network UPS Tools, Devices Dumps Library Network UPS Tools User Manual, Appendix J Project history Network UPS Tools Documentation GitHub Network UPS Tools code repository, variable names GitHub Network UPS Tools code repository, status names GitHub Network UPS Tools code repository, project history Stunnel proxy adds TLS encryption functionality to existing clients and servers
Variables The UPS variables represent the abstracted state of the UPS unit. Certain variables represent not only the state of some hardware feature, but also provide tunable values and instant commands, see . The full set of variables is recorded in the reference document for variable names. The number of variables used in a given deployment depends on the sophistication of the UPS product: this annex shows a typical example of the subset of variables used for a reasonably complete "consumer grade" UPS. The NUT Project maintains a large library of the variable subsets used by different UPS models. Note that successive versions of a given product may add or delete features causing a change in the subset of variables used. An example is the removal of ups.delay.start from a "consumer grade" UPS. The manufacturer reserves the feature for the "professional" product. An implementation of a Management Daemon acting as a utility program may provide a listing of the variables available for a given product, for example utility program upsc as included in the NUT package, see . The following sections illustrate the use of variables by taking the values associated with a typical product example of a 1600Va 1000W UPS.
Typical UPS Variables Typical UPS Variables
Variable Typical value Default 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 1 "Outlet 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 2 "Outlet 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 Mfg "UPS manufacturer"
ups.model Economy 1600 "UPS model"
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"
Typical UPS Readable and Writable Variables Some of the features of a UPS are represented by variables which may be tuned by the user. The following variables are typical of such tunable features. The precise list depends on the model of UPS. An implementation of a Management Daemon acting as a utility program may provide a listing of the variables available, as well as acting on them, for example utility program upsrw as included in the NUT package, see . Typical readable and writable UPS Variables
Variable Typical value Default description 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 1 "Outlet description"
outlet.2.desc PowerShare Outlet 2 "Outlet description"
outlet.2.switchable no "Outlet switch ability"
outlet.desc Main Outlet "Outlet description"
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)"
Typical UPS Instant Commands Some of the features of a UPS are actions known as instant commands, see , which may be ordered by the user. The following variables represent such instant commands. The precise list depends on the model of UPS. An implementation of a Management Daemon acting as a utility program may provide a listing of the variables available, as well as acting on them, for example utility program upscmd as included in the NUT package, see . Typical Instant Commands
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
The Shutdown Story for System and UPS This appendix provides background material helpful for a general understanding of the relation between system and UPS. It does not define any feature of the command-response protocol. We consider the steps involved in the shutdown and restart of a long-running unattended server protected by a single UPS. The Management Daemon runs in the server as shown in .
Long-running unattended server ,------------------SERVER------------------, | | | ,-----, | UPS <-Commands UPS | | UPS |---| Attachment | Management | | |===| Daemon Responses-> Daemon | /-----\ '--------------------'---------------------' Internal loopback
  1. The public power supply is on -- The system runs normally. Every 5 seconds, variable ups.status reports OL. -- Days, weeks, months go by...
  2. Winter storm. Tree falls on power lines. The public power supply fails -- The server remains operational running on the UPS battery. The Management Daemon polls the Attachment Daemon, and detects status change OL->OB.
  3. The Management Daemon logs warning messages. The server is still operational running on the UPS battery. -- Minutes go by...
  4. The battery discharges below the level specified by variable battery.charge.low. The server remains operational, but the UPS battery will not last much longer. The Management Daemon polls the Attachment Daemon, and detects status change OB->OB+LB.
  5. The Management Daemon logs the low battery event.
  6. The Management Daemon decides to call for a system shutdown. It sets status FSD in the Attachment Daemon to call on any secondaries to shut down and waits for command GET NUMATTACH to report one single attachment, i.e. the Primary itself. The Management Daemon then issues the system shutdown command for itself.
  7. The operating system's shutdown process takes over. During the system shutdown, a NUT Project specific script or an equivalent systemd service unit runs the command upsdrvctl shutdown. This tells the UPS that it is to shut down N seconds later where the default is N=20. Note that the "shutdown" of a UPS removes power from the outlet sockets, but may not turn the UPS off completely. A delayed shutdown is sometimes audible, and the characteristic beeping of the UPS stops.
  8. The system shuts down and powers down, hopefully before the N=20 seconds have passed.
  9. N seconds after item -- The UPS shuts down, i.e., it turns off its outlet sockets when N=20 seconds have passed. With some UPS units, there is an audible "clunk". What if the public power supply returns before the UPS shuts down? The UPS unit should be able to wait a configurable time with default 30 seconds. These two timers start from the moment the UPS receives the upsdrvctl shutdown command. -- Minutes, hours, days go by...
  10. Some time later, maybe much later, the public power supply returns -- The UPS reconnects it's outlets to send power to the protected system.
  11. 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.
  12. 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.
  13. 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 above.
Technical Terms: Historical Differences This appendix lists the major differences between the technical terms used in NUT software release 2.8.0 and documented in this text, and those used in previous version 2.7.4 of the NUT Project.
Term in previous
release NUT 2.7.4 		Term in this document,
release NUT 2.8.0 		Reference
ALREADY-LOGGED-IN ALREADY-ATTACHED
ALREADY-SSL-MODE TLS-ALREADY-ENABLED
LOGIN ATTACH
LOGOUT DETACH
Master Primary
NETVER PROTVER
NUMLOGINS NUMATTACH
Slave Secondary
Security Defences in Release 2.7.4 Previous NUT version 2.7.4 did not provide support for TLS v.3 . The following subsections describe mitigating techniques.
Shims Previous version 2.7.4 of NUT did not support TLS v.3 . Where such protection is needed for version 2.7.4, a possible technique introduces shims between the Attachment Daemon and the network, and between the network and the Management Daemon as shown in figure . These shims provide TLS v.3 support, thus allowing the Attachment Daemon and Management Daemon to continue temporarily without native TLS. The technique has been successfully tested, but the principal difficulty is that the shims make use of a second port which is not currently available.
Shims provide TLS support during migration TLS shim listens TLS shim listens on port TBD1 on port 3493 ,-----,------------,----, ,----,--------------, | UPS - Attachment |TLS | <-STARTTLS | TLS| Management | | | Daemon |shim| OK--> |shim| Daemon | /-----'------------'----\ '----'--------------' Listens on port nut/3493
Attachment Daemon Shim The shim in front of the Attachment Daemon listens to incoming traffic on a port to be specified. When it receives the command STARTTLS it
  1. Returns OK to the client and sets up TLS encapsulation.
  2. Does not send STARTTLS to the Attachment Daemon port nut/3493.
All other commands and responses are passed through.
Management Daemon Shim The shim in front of the Management Daemon listens for incoming traffic on port nut/3493. When it receives the command STARTTLS it
  1. Returns FEATURE-NOT-CONFIGURED to the client.
  2. Sends STARTTLS to the Attachment Daemon on a port to be specified.
All other commands and responses are passed through.
TLS Tunnels Another technique is the use of TLS tunnels, using a software such as 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.
VPN A further option to secure communications is very similar to TLS tunnelling and consists of routing the NUT traffic through a Virtual Private Network, VPN.
VLAN A fourth option is to isolate the UPS management traffic at the network switching level using a Virtual LAN, VLAN technique.
UPS Management Protocol runs over its own VLAN ,-------------, ,-------------, ,-----, | Attachment | | Management | | UPS |---| Daemon | | Daemon | | | |-------------| UPS |-------------| | |===| | Management | UPS | /-----\ | Protected |~~~~~~~~~~~~~~~| Management | | Server | VLAN | Client | | | '-------------' '-------------' Production | VLAN ,---|-------, ,-----------,| ,-----------,|' | Clients |' '-----------'
In 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 ~~~~~~~~~~~~~.
Administrative Security Administrative commands such as FSD, INSTCMD and SET are powerful and can have a deep effect on system integrity, For example, the command FSD is involved in mission critical system shutdown decisions. Access to them needs to be managed and restricted. This clause presents the current practice.
Management of Administrative Users The Attachment Daemon maintains a file (currently upsd.users) defining each administrative user. Note that these users are independent of those recorded in file /etc/passwd. Each administrative user gets its own section in file upsd.users. The declarations in that section set the parameters which define that user's privileges. The section begins with the name of the user enclosed in square brackets, U+005B LEFT SQUARE BRACKET [ and U+005D RIGHT SQUARE BRACKET ], and continues until the next user name in brackets or EOF. For example the following file declares two administrative users admin and pfy: [admin] password = sekret upsmon master actions = SET instcmds = ALL [pfy] password = sekret instcmds = test.panel.start instcmds = test.panel.stop Within each section the administrative user declarations are: Administrative user declarations
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 .
  • SET Change the value of a UPS variable. See .
instcmds Let a user initiate specific instant commands. See . 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 U+003D EQUALS SIGN =.
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 and .
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. A 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.com The USERNAME and PASSWORD commands are issued within the client upsrw and the Session is of short duration.
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 which is provided by the NUT Project issues commands USERNAME and PASSWORD when it starts up. The data values needed for the USERNAME and PASSWORD commands are provided by a configuration file upsmon.conf which contains the line MONITOR UPS-1@example.com 1 admin sekret master This says that the UPS to be monitored is UPS-1@example.com, it provides 1 single power supply, the administrative user is admin with password sekret. The Management Daemon acts as a Primary, although current practice uses the term master. The USERNAME and PASSWORD commands are contained within the client upsmon and the Session is of long duration.
Change Log Ed: To be removed on publication.
Changes in Version 01
  1. There is exactly one newline at the end of commands and responses.
  2. Added descriptions to variables in Annex.
  3. Added clause Events.
Changes in Version 02
  1. Extended acknowledgments.
  2. Added reference to possible use of RFC1628 between driver and Attachment Daemon.
  3. Clarified response to command LIST CLIENT.
Changes in Version 03
  1. Clarified description of Attachment Daemon.
  2. Added Implementation status section as recommended by RFC 7942.
  3. Rewrote .
  4. Clarified as being merely an example of variables used for a specific UPS product.
  5. Added definition of <upsname> in .
Changes in Version 04 There are many changes in this version following the ISE review. See reply to ISE review: http://rogerprice.org/NUT/ISE-comments-2021-06-14.reply.html Among other changes are:
  1. Section becomes "Codepoint Management".
  2. Editorial cleanup. All <aside> elements labelled as notes.
  3. Added implementation note to .
  4. Error message ALREADY-SSL-MODE becomes ALREADY-TSL-ENABLED.
  5. Added error message TSL-NOT-ENABLED.
  6. Typo in clause UPS status.
  7. Removed all reference to use of RFC1628 between driver and Attachment Daemon.
  8. In field [:<port>] is always available in <upsname>
  9. Added technical term administrative user.
  10. Added appendix Technical terms: Historical differences
  11. Added table of "successful" responses: Response when command succeeds
  12. Three commands change name LOGIN -> ATTACH, LOGOUT -> DETACH and NUMLOGINS -> NUMATTACH.
  13. Error message ALREADY-LOGGED-IN becomes ALREADY-ATTACHED.
Changes in Version 05 This version includes changes made following comments by the reviewers.
  1. Abstract: Change "takes" -> "automates".
  2. Abstract: Change "Current practice" -> "Current practice when this text was written".
  3. Abstract: Change "leads to" -> "risks".
  4. Section, Added sentence on use of "public power supply".
  5. Section, Change "shutting down..." -> "performing a managed shutdown of unattended..."
  6. Section added link to NUT documentation.
  7. Section added "They are listed in alphabetical order."
  8. Section Change "talks to the UPS" -> "retrieves status from the UPS and sends commands to it".
  9. Section Change "... launched as system user root and drops privilege ..." -> "... launched as system user root to allow direct access to the hardware (e.g. /proc, /dev). For better security, the daemon then drops privilege ..."
  10. Section Change "Management Daemon users." -> "Management Daemon users which authenticate to the attachment daemon with basic credentials (username and password)."
  11. Section Change "... and are defined by a file in the ..." -> "... and are listed in a text file which is read by the ...".
  12. Section Added link to .
  13. Section Change "specific to the hardware" -> "specific to the UPS hardware"
  14. Section Change "causes the hardware" -> "is passed to the driver and sent to the hardware".
  15. Section Change "to immediately" -> "without any configured delay to".
  16. Section Change "the system reaction to power loss." -> "orchestrating system-wide actions after a power event."
  17. Section Title "NUT Project" -> "NUT Software Project".
  18. Section Change "the system to which the data lead is connected" -> "the computer running the driver".
  19. Section Replaced and clarified "data lead" not present with secondaries.
  20. Section Change "may open a session" -> "may initiate a TCP session".
  21. Section Change "are considered fundamental and are" -> "MUST be".
  22. Section Change "other statuses depend" -> "other statuses are OPTIONAL and depend".
  23. Section Change "The features" -> "The metrics and identifiers".
  24. Section Change "current value attached to that feature" -> "value representing that metric or identifier".
  25. Section Added a note: "Note: Some variables are constants, e.g. battery type, manufacturer."
  26. Section Rewrote paragraph to clarify "the Attachment Daemon and the Management daemon which act as server and client respectively."
  27. Section Change "run the Attachment Daemon (2.1)." -> "run the Attachment Daemon (2.1), thereby effectively creating a network attached UPS running a standard protocol."
  28. Figure In the note: replaced "but if the UPS had status OB the Secondary shuts down." by "but if the UPS had status OB the Secondary may choose to shut down as a precaution."
  29. Section Added scholarly historical note.
  30. Section Change "of the port" -> "of the TCP port".
  31. Section Change "the count is 1 (the Primary (2.8)) + the number of Secondaries (2.9)" -> "the count is 1 for the primary + the number of secondaries". Change "a trio of" to "three".
  32. Section Clarify that "FSD" means "Forced Shutdown".
  33. Section Change "only to a high-level" -> "only to a privileged".
  34. Section Added prefix GET to all the subcommands.
  35. Section Added prefix LIST to all the subcommands.
  36. Section Change "common container" -> "common".
  37. Section Change "then go off and wait for the response" to "wait".
  38. Section Added note differentiating and .
  39. Section Changed "and the UPS model." -> "and the UPS model. Some variables are read-only due to the design of the UPS or its driver."
  40. Section Changed "The choice of TLS version is a matter for site security policy and is not specified in this document." -> "The parameters and versions of cryptographic libraries are those of the Attachment Daemon's underlying OS and are outside the scope of this document."
  41. Section Change "provides facilities to limit access to the UPS unit(s) to which it is attached." -> "limits access to clients whose credentials match those in the file upsd.users. There is no anonymous access."
  42. Section Added note differentiating and .
  43. Section Change "public supply", "wall power" and "input supply" -> "input power supply", nine places.
  44. Section Remove notes from CHRG and DISCHARG.
  45. Section OB: Removed "offline".
  46. Section Change "deduces" -> "detects".
  47. Section Change "valuable resources" -> "compute and network resources" .
  48. Section Change "will not have up-to-date information about the UPS status" -> "risks missing short-lived changes in the UPS status"
  49. Section After "imposed by a wave of the hand" added "it cannot be implemented quickly and without impact to many deployed systems".
  50. Section Added section.
  51. Section Added section with figure.
  52. Section Added "Note: In Unix-like systems a port with a number below 1024 is privileged and requires elevated permissions to manage."
  53. Section Change "but accepts" -> "but will accept".
  54. Appendix Change "domestic" -> "consumer grade".
  55. Appendix item Change Note that the "shut down" of a UPS does not turn the UPS off completely. It disconnects the outlet sockets. Such a delayed shutdown is audible since the characteristic beeping of a UPS stops. -> Note that the "shutdown" of a UPS removes power from the outlet sockets, but may not turn the UPS off completely. A delayed shutdown is sometimes audible, and the characteristic beeping of the UPS stops.
Changes in Version 06 This version includes changes made following comments by the reviewers.
  1. Section Added sentence to permit unencrypted communication.
  2. Added Section Recommended Minimum Support
  3. Changed "long-running Attachment Daemon upsmon" -> "long-running Management Daemon upsmon". Text now moved to appendix.
  4. Appendix item. Added clarification of the use of status symbol FSD and command NUMATTACH.
  5. Section Changed "a standard protocol" -> "a published protocol".
Changes in Version 07 This version includes changes made following comments by reviewers at the request of the IETF's Independent Submissions Editor.
  1. Section Cosmetic change.
  2. Section Added reference to GitHub repository.
  3. Section Added paragraph to explain that NUT is not case sensitive.
  4. Section Rewrote first sentence: "All the LIST commands..."
  5. Section Rewrote 2nd sentence as follows: The administrative user name and password need protection from sniffing and local malicious users. This is done by encrypting the traffic and properly restricting access to the configuration files. (Text has since been thoroughly reworked.)
  6. Section Replace SSL by TLS.
  7. Section Replace SSH by TLS. Remove <aside>.
  8. Appendix table Added ups.temperature
  9. Appendix The Shutdown Story, BIOS options. I removed wording from and completed the wording in .
Changes in Version 08 This version includes further changes made following comments by reviewers at the request of the IETF's Independent Submissions Editor.
Technical changes
  1. . Arnaud took over in 2005, not 2001. Added reference to project history on GitHub.
Editorial changes following initial ISE comments
  1. Removed counter attribute from <xref> to prevent ()s.
  2. Removed most content from <xref>.
  3. References become more literary and less "hypertext".
  4. Most keywords and symbols are no longer clickable.