| RFC 9271 | UPS Management Protocol | August 2022 |
| Price | Informational | [Page] |
This document describes the command/response protocol currentlyused in the management of Uninterruptible Power Supply (UPS) units andother power devices often deployed in small offices and in ITinstallations subject to an erratic public power supply. The UPS units typicallyinterface to an Attachment Daemon in the system they protect. Thisdaemon is in turn polled by a Management Daemon that notifies usersand system administrators of power supply incidents and automatessystem shutdown decisions. The commands and responses described bythis document are exchanged between the UPS Attachment Daemon and theManagement Daemon. The practice current when this protocol was firstdeveloped risks weak security, and this is addressed in the SecurityConsiderations sections of this document.¶
This document is not an Internet Standards Track specification; it is published for informational purposes.¶
This is a contribution to the RFC Series, independently of any other RFC stream. The RFC Editor has chosen to publish this document at its discretion and makes no statement about its value for implementation or deployment. Documents approved for publication by the RFC Editor are not candidates for any level of Internet Standard; see Section 2 of RFC 7841.¶
Information about the current status of this document, any errata, and how to provide feedback on it may be obtained athttps://www.rfc-editor.org/info/rfc9271.¶
Copyright (c) 2022 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document.¶
This document describes UPS management techniques and current UPSmanagement practice published by the Network UPS Tools (NUT) Project.The document is based on version 2.8.0 of the NUT Project software,which supports version 1.3 of the NUT protocol.¶
Since May 2002, the protocol described by this document has beenoperating on IANA port 3493/TCP (nut).¶
The primary goal of the Network UPS Tools (NUT)Project software[NUT] is to provide support for powerdevices, such as UPSs. The project has beenin operation since 1998, with a major rework in 2003. It operatesthrough a usermailing list [nut-upsuser], adevelopermailing list [nut-upsdev],awebsite [NUT], andaGitHub repository [nut-repository]. See[githist] and Appendix J of[History] fora history of the project.¶
The Shutdown Story section (seeAppendix B)describes the current UPS management practice for performing a managedshutdown of unattended infrastructure after an unscheduled failure ofthe public power supply in order to minimize the risk of corruption to dataprocessed by this infrastructure.¶
As a simplification to ease reading, the term "UPS" is used when"Managed Power Device" would be more complete. The reader shouldunderstand the simple "UPS" to include other managed power devices.¶
The statuses and events appearing in this document are named withshort text-form names, some of which are abbreviations. A full listof the statuses can be found inSection 5.1, whilethe events are listed inSection 5.2.¶
This document refers to the "public power supply". Other textsfrequently refer to "utility power", "input source power", or even"wall power".¶
Additional information about the NUT Project is available intheproject documentation [Documentation].Requests for further information about this protocol and relatedtechnical matters may be addressed tothemailing list [nut-upsuser] of the NUT Project.¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED","MAY", and "OPTIONAL" in this document are to be interpreted asdescribed in BCP 14[RFC2119][RFC8174] when, and only when, they appear in all capitals, as shown here.¶
The following technical terms appear in this document. They arelisted in alphabetical order.¶
In current practice, the commands and other functions offered bythe Attachment Daemon are made available to a set of users known as Management Daemons. TheseManagement Daemons authenticate to the Attachment Daemon with basic credentials (username andpassword). Although called "users", the administrative users are notsystem users; they are specific to an Attachment Daemon and are listed in a textfile (currentlyupsd.users) that is read by the Attachment Daemon andthat assigns to each of them the password, Instant Commands, andactions that are allowed, together with the Primary or Secondarystatus of the Management Daemon. For details,seeAppendix E.1. For details of the Primary, seeSection 2.7; for details of the Secondary, seeSection 2.8. Typically, ahigh-level user will be able to send commandFSD, but alow-level user might only be allowed to access the test panel. Thesecurity provisions for administrative users are discussed inAppendix E.¶
The Attachment Daemon retrieves the status from the UPS and sendscommands to it often through a Driver specific to the hardware modeland the connection medium, e.g., USB, serial. SeeSection 2.3. Itmaintains an abstracted view of the hardware through the use ofhardware statuses. SeeSection 2.10. A Management Daemon mayconsult the abstracted view using the commands described in thisdocument.¶
SeeSection 8.2 for details of the recommendedminimum support of variables, which calls for Attachment Daemon supportof statusesOB,OL,LB, andFSD.¶
The NUT Project has implemented an Attachment Daemon as programupsdand a set of hardware-specific Drivers, all written in K&R C[C2ndEd]. TheAttachment Daemon is launched as system user "root" but for better security; then, itdrops the privilege to run as a detached software service.¶
A Driver is that part of an Attachment Daemon that is specific tothe UPS hardware, the connection medium, and the connection protocol,e.g., USB, serial. In current practice, the Attachment Daemon has aDriver for each hardware interface type it supports. Although thisdocument considers the Driver to be part of the Attachment Daemon,current practice is to see it as a separate software unit running as adaemon "in front of" the Attachment Daemon. The protocol for dataexchange between the Driver and the Attachment Daemon is outside thescope of this document.¶
A UPS event occurs in the Management Daemon when a change in the UPS status isreceived from the Attachment Daemon. This event is internal to the Management Daemon.SeeSection 5.2.¶
An Instant Command is a command that, when sent to the Attachment Daemon,is passed to the Driver andsent to the hardware without any configured delay to perform afunction. For example,INSTCMD su700 test.panel.start.SeeSection 4.2.6.¶
The Management Daemon is primarily responsible for managing thehardware and orchestrating system-wide actions after a power event.Using commands sent to the Attachment Daemon, it follows the status of the UPS anddetermines when UPS events occur. It takes decisions based on theevents, such as calling for a system shutdown. SeeAppendix B. Although the term includes theword "Daemon", nothing requires that it be implemented as a detachedsoftware service. The Management Daemon may also provideadministrative functions, such as a graphic interface to view thehardware activity.¶
There are several examples of a Management Daemon: the NUT Projectprovidesupsmon, which takes the system shutdown decision whenthe public power supply fails. Further configuration options, such as timers, areprovided by the helper programupssched.¶
Other programs represent the Management Daemon:¶
upsc reports the values of the variables defined for agiven UPS; seeTable 6.¶upsrw reports on and changes the values of the readableand writable configuration variables defined for a given UPS;seeAppendix A.2.¶upscmd reports on and executes the instant actioncommands defined for a given UPS; seeSection 4.2.6.¶UPSmon.py is an experimental Python3 rewriteofupsmon andupssched that includes supportforTLS 1.3 [RFC8446].¶When a power device, such as a UPS unit, supplies power to more thanone system, the computer running the Driver is known as the Primary.The others are Secondaries. SeeFigure 4. Common current practice for system administrators isto consider the Management Daemon in the Primary to be the Primary ManagementDaemon that is in charge of the shutdown of all the systems poweredby the UPS. The Primary Management Daemon sets statussymbolFSD to order the Secondaries to shut down.¶
Note: Historically, the Primary was known as the "Master".¶
When a hardware device, such as a UPS unit, supplies power to morethan one system, the system that communicates directly with the UPSunit, e.g., using a USB, RS-232, or a network connection, is known as thePrimary. The others are Secondaries. There is no Attachment Daemon in aSecondary. SeeFigure 4.Common current practice for system administrators is to consider theManagement Daemon in a Secondary to be a Secondary Management Daemon thatunderstands status symbolFSD as an order to shut down.¶
Note: Historically, the Secondary was known as the "Slave".¶
The Management Daemon may initiate a TCP session with a specified device, suchas a UPS known to the Attachment Daemon. The session structure provides for auditand security, as well as access to mission-critical UPS functions. Forexample, good practice requires password protection for an InstantCommand that turns off a UPS outlet. Other than the commands andresponses used, the details of session management are outside thescope of this document.¶
The status of a hardware device, such as a UPS unit, is a symbolicdescription of the state of the unit. It consists of a space-separatedlist of symbols from the set {ALARMBOOSTBYPASSCALCHRGCOMMDISCHRGFSDLBNOCOMMOBOFFOLOVERRBTESTTRIM}. The symbolsTICK andTOCK are experimental additions to the statuses and are not incommon current practice. SeeSection 5.1, whichspecifies each of these symbols.¶
SeeSection 8.2 for details of the recommendedminimum support of status symbolsOB,OL,LB,andFSD.¶
The metrics and identifiers provided by each UPS are represented byvariables giving the value representing that metric or identifier. TheUPS variable is an abstraction of the UPS hardware configuration andactivity maintained by the Attachment Daemon. SeeAppendix A,which provides examples of variables. For example, thevariablebattery.charge contains the current charge of theUPS battery as a percentage value.¶
Note: Some variables are constants, e.g., battery type andmanufacturer.¶
SeeSection 8.2 for details of therecommended minimum support of variables. A full list of possiblevariables is available insource code filedocs/nut-names.txt [gitvars], which serves as the Recording Document.¶
Figure 1 shows a referenceconfiguration in which the command/response protocol applies. The UPSshown is representative of all managed power devices.¶
"The client" ,--------------, ,--------------, ,-----, | UPS | <-Commands | UPS | | UPS |---| Attachment |---------------| Management | | |===| Daemon | Responses-> | Daemon | /-----\ '--------------' '--------------' UPS Attachment UPS Management System Network System
The reference configuration inFigure 1 shows a single UPS unit thathas a power supply link(===) and a data link (---) attached to a systemrunning an Attachment Daemon. The UPS provides power supply protection to thesystem running the Attachment Daemon.¶
In practice, there may be more than one UPS unit, and a unit mayprovide power protection to more than one system. The figure alsoshows a single Management Daemon. In practice, there may be more than oneManagement Daemon, and any one Management Daemon may manage more thanone UPS Attachment Daemon.¶
The protocol applies to connections between the Attachment Daemonand the Management Daemon, which act as theserverandclient, respectively. The Management Daemon sendscommands over TCP to the Attachment Daemon and receives responses overTCP from that daemon.¶
The two daemons may run in the same system or may be connectedthrough a local or wide area network. In simple cases, as shown inFigure 2, the Attachment Daemonand the Management Daemon are in the same system, the one protected by the UPS.The commands and responses are exchanged through an internal loopbackinterface.¶
"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 specificdesign. For example,Figure 3shows an arrangement in which the Attachment Daemon is closely associated with, oreven included in, the UPS system setup. This is becoming moreprevalent with the availability of low-cost processors able to run theAttachment Daemon, thereby effectively creating a network-attached UPS running apublished protocol.¶
"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 becomingincreasingly common to use a single UPS to protect multiple systems, asshown inFigure 4. However,there is only one data line (---) from the UPS to the Primarysystem. The others have only power connections (===) to theUPS and are known as Secondaries. A Secondary does not run an Attachment Daemon;it connects over a network to the Attachment Daemon in thePrimary.Figure 4 shows theAttachment Daemon and the Primary Management Daemon in the same system. This is commonpractice, but it is not a technical requirement.¶
"The client" ,--------------------,---------------------, ,-----, | UPS <-Commands Primary | | |---| Attachment | Management | Primary | |===| Daemon Responses-> Daemon | | | '--------------------'---------------------' | UPS | ^ | | '<-Commands---Responses->, | | v | | ,--------------,-----------------, | |============| | Secondary | /-----\ | | Management | Secondary | | Daemon | '--------------'-----------------'
Note: Should the Primary fail or go offline, the fate ofthe Secondaries depends on the UPS status when the Primary failed. Ifthe UPS had statusOL, the Secondary continues operation, but if theUPS had statusOB, the Secondary may choose to shut down as a precaution.¶
This specification includes only the commands and their responses.An implementation of the Attachment Daemon has an internal state machine, and somecomplex implementations of the Management Daemon include an internal statemachine, for example, to assist the system shutdown of a complexinstallation. The Management Daemon is required to remember thepreviousups.status value it received from the Attachment Daemon andcompare it with the next. Other than that, the management protocolused between them is effectively stateless.¶
For example, seeSection 5.2, which shows a map of thenewups.status response and the previousups.statusresponse to an event, which is taken as the basis for Management Daemon action.¶
The character set used for commandsand responses is US-ASCII; see[RFC0020].¶
Multi-word elements are contained betweenquotation mark characters for easier parsing, e.g., "UPS onfire". Embedded quotation marks are escaped with reverse slant (\), often known as backslashes. Embeddedbackslashes are also escaped by representing them as \\.¶
Commands and responses have no leading ortrailing blank space and are terminated with a single newline character line feed (LF).¶
Blank space within commands and responses is reduced toone space (SP).¶
The commands address the UPS to which they applyby<upsname>, where¶
<upsname>::=<ups>[@<hostname>[:<port>]]¶<ups> is defined by the Attachment Daemon configuration files.¶<hostname> islocalhost.¶<port> is the number of the TCP port on whichthe Attachment Daemon is listening. The default is 3493. This is supported byall current Management Daemons.¶Examples:myups,UPS-97B@bigserver.example.com¶
ABNF: See variableupsname inFigure 5.¶
Note: Experimental Management Daemons use an extended formof<upsname> in configuration files and in programparameters, 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.¶<hostname> islocalhost.¶Examples:ups-1@example.com:3493,HB:heartbeat1@example.com:3493¶
Implementation note: In the current implementation,the names of commands and subcommands are not case sensitive. Forexample,GET VAR may be written asGet var, but inthis specification, they are always written in uppercase.Similarly,<upsname> and<varname> arenot case sensitive. For example,UPS341 ups.id may be writtenasups341 Ups.Id, but in thisspecification,<varname> is always written in lowercase.¶
ATTACHIn a configuration like the one showninFigure 4, in which a UPS protects more thanone system, the Primary Management Daemon needs to know how many Secondaries arecurrentlyactive, i.e., powered by the UPS, either from thepublic power supply or from battery power. The Attachment Daemon supports this by keeping acount of all theactive systems powered by a UPS. Thecount is initialized, one Secondary at a time by theATTACHcommand, which should be understood ascount this Secondary asactive.ATTACH is one of three commands for Secondarycounting. Additionally, commandDETACH decrements the count, and a Management Daemon mayread the count at any time using the commandNUMATTACH.¶
TheATTACH command is also sent to the Attachment Daemon for thePrimary, so during normal, fully protected operation, the count is 1for the Primary + the number of Secondaries. During a full systemshutdown, the count drops as each Secondary Management Daemon executes commandDETACH during its own shutdown. When the count drops to 1, onlythe Primary isactive, and it knows that all the Secondarieshave shut down.¶
Command:ATTACH <upsname>¶
If the command succeeds, the response isOK; otherwise,see the error responses inSection 4.3.2.¶
ABNF: See variableattach inFigure 5.¶
Note: Historically, this command was known asLOGIN.However, becauseLOGIN was not the conventional user access to ashell or program, the name was changed to avoid confusion.¶
DETACHThis companion command toATTACH reduces the count of"active" Secondaries. It should be understood asthis Secondaryis no longer active and is usually used during system shutdownto decrement a count of how many Secondaries are stillactive.¶
Command:DETACH¶
If the command succeeds, the response isOK Goodbye;otherwise, see the error responsesinSection 4.3.2.¶
ABNF: See variabledetach inFigure 5.¶
Note: Historically, this command was known asLOGOUT.¶
FSDA Management Daemon that is Primary and has the required authority uses thiscommand to set status symbolFSD, meaning "Forced Shutdown", inthe Attachment Daemon. In current practice, the Primary Management Daemon uses the symbol totell the Secondaries to shut down.¶
Command:FSD <upsname>¶
If the command succeeds, the response isOK FSD-SET;otherwise, see the error responses inSection 4.3.2.¶
ABNF: See variablefsd inFigure 5.¶
In current practice, commands such asFSD are madeavailable only to a privileged administrative user authorized to sendsuch a mission-critical command. The security provisions foradministrative users are discussed inAppendix E.¶
GETRetrieve a single response from the Attachment Daemon.¶
ABNF: See variableget inFigure 5.¶
The possible subcommands are listed in the sections below.¶
GET CMDDESCRetrieve a text description of a command.¶
Command:GET CMDDESC <upsname> <cmdname>¶
Response:CMDDESC <upsname> <cmdname> "<description>"¶
For example: commandGET CMDDESC su700 load.on andresponseCMDDESC su700 load.on "Turn on the load immediately"¶
This is likeGET DESC, but it applies to an Instant Command.SeeSection 4.2.4.2.¶
GET DESCRetrieve a text description of a UPS variable. SeeSection 2.11.¶
Command:GET DESC <upsname> <varname>¶
Response:DESC <upsname> <varname> "<description>"¶
<description> is a string that gives a briefexplanation of the named variable. The Attachment DaemonMAY return"Unavailable" if the file that provides this description is notinstalled.¶
For example: commandGET DESC su700 ups.status andresponseDESC su700 ups.status "UPS status"¶
GET NUMATTACHRetrieve the count kept by the Attachment Daemon of all theactivesystems protected by this UPS.¶
Command:GET NUMATTACH <upsname>¶
Response:NUMATTACH <upsname> <value>¶
<value> is a count of the Primary and thenumber of Secondaries currently powered by this UPS.¶
For example: commandGET ATTACH su700 andresponseNUMATTACH su700 1¶
This information is needed by the Management Daemon to determine how manySecondaries are still connected during the system shutdown process.¶
Note: Historically, this subcommand was knownasNUMLOGINS. SinceLOGIN was not the conventionaluser access to a shell or program, the name was changed to avoidconfusion.¶
GET TYPERetrieve the type of a UPS variable. SeeSection 2.11.¶
Command:GET TYPE <upsname> <varname>¶
Response:TYPE <upsname> <varname> <type>...¶
<type>... can be one or more of the followingtokens. Multiple types may be returned.¶
For example: commandGET TYPE su700 input.transfer.low andresponseTYPE su700 input.transfer.low ENUM¶
| Type | Meaning |
|---|---|
| RW | This is a read/write variable. It may be read withcommandGET VAR (seeSection 4.2.4.6) and set to a different valuewith commandSET (seeSection 4.2.11). |
| ENUM | This is an enumerated type, which supports specificpredetermined values. |
| STRING:n | This is a string of maximumlengthn. |
| RANGE | This is a number, either integer or float,comprised in the range that may be seen with the command |
| NUMBER | This is a single numeric value, eitherinteger or float. |
Notes:¶
GET UPSDESCRetrieve a text description of a UPS.¶
Command:GET UPSDESC <upsname>¶
Response:UPSDESC <upsname> "<description>"¶
<description> is defined by the Attachment Daemon configuration. Ifit is not set, current practice is for the Attachment Daemon to return"Unavailable".¶
For example: commandGET UPSDESC su700 and responseUPSDESC su700 "Development box"¶
This can be used to provide human-readable descriptions, instead ofa crypticups@hostname string.¶
HELPReturn a list of the commands supported by the Attachment Daemon. This commandis intended for human, as well as program, use.¶
Command:HELP¶
For example: the following command line sequence executed on anAttachment Daemon¶
netcat localhost 3493HELPCommands: HELP VER GET LIST SET INSTCMD ATTACH DETACH USERNAME PASSWORD STARTTLS¶
ABNF: See variablehelp inFigure 5.¶
Note: Historically, this command also returnedLOGINandLOGOUT. BecauseLOGIN was not the conventionaluser access to a shell or program, the command names were changedtoATTACH andDETACH to avoid confusion.¶
INSTCMDSend an Instant Command to the UPS.¶
Command:INSTCMD <upsname> <cmdname>¶
<upsname> is the name of the UPS,and<cmdname> is the Instant Command to be issued tothat UPS. SeeAppendix A.3 for examples ofInstant Commands.¶
If the command succeeds, the response isOK; otherwise,see the error responses inSection 4.3.2.¶
For example: commandINSTCMD su700 test.panel.startand responseOK¶
LISTAll theLIST commands produce a response with a commonformat. The response begins withBEGIN LIST and thenrepeats the initial query. A list then follows, with as many lines asare necessary. The response ends withEND LIST, followed bythe initial query.¶
The formatting may seem a bit redundant, but it makes a differentform of client possible. A client can send aLIST commandand then wait for the response. When it arrives, the Management Daemon doesn'tneed a complicated state machine to remember which list is which.¶
Note: The current NUT Project implementation of theAttachment Daemon,upsd, sends back the response to theLISTcommand as a sequence of messages. The Management Daemon should continue readingthese messages until it receives the line beginningEND LIST.¶
ABNF: See the variablelist inFigure 5.¶
The possible subcommands are listed in the sections below.¶
LIST CLIENTThe command calls for the Attachment Daemon to report all the current Management Daemonclients of a given UPS.¶
Command:LIST CLIENT <upsname>¶
Response:¶
BEGIN LIST CLIENT <upsname>CLIENT <upsname> <client_IP_address>...END LIST CLIENT <upsname>¶
For example: commandLIST CLIENT ups1 and response¶
BEGIN LIST CLIENT ups1CLIENT ups1 ::1CLIENT ups1 203.0.113.1END LIST CLIENT ups1¶
LIST CMDThe command calls for the Attachment Daemon to report a list of the InstantCommands that the Management Daemon may send to the Attachment Daemon. This Instant Commandlist is the abstracted view of the UPS hardware capabilities. Aneconomical UPS will support few or no Instant Commands, but aprofessional model should support more.¶
Command:LIST CMD <upsname>¶
Response:¶
BEGIN LIST CMD <upsname>CMD <upsname> <cmdname>...END LIST CMD <upsname>¶
<upsname> is the name of the UPS,and<cmdname> is the name of the Instant Command thatmay be issued to the UPS.¶
For example: commandLIST CMD su700 and response¶
BEGIN LIST CMD su700CMD su700 load.onCMD su700 test.panel.start...END LIST CMD su700¶
LIST ENUMThe command calls for the Attachment Daemon to report the set of possiblevalues of a UPS variable that has predetermined values.¶
Command:LIST ENUM <upsname> <varname>¶
Response:¶
BEGIN LIST ENUM <upsname> <varname>ENUM <upsname> <varname> "<value>"...END LIST ENUM <upsname> <varname>¶
<upsname> is the name of the UPS,<varname> is the UPS variable,and<value> is one of the possible values of that UPSvariable. Note that, in current practice, the output is an unorderedlist. Also note that the quotation marks are part ofthe response.¶
For example: commandLIST ENUM su700 input.transfer.lowand response¶
BEGIN LIST ENUM su700 input.transfer.lowENUM su700 input.transfer.low "103"ENUM su700 input.transfer.low "100"...END LIST ENUM su700 input.transfer.low¶
LIST RANGEThe command calls for the Attachment Daemon to report the interval in whichvalid values of UPS variable lie.¶
Command:LIST RANGE <upsname> <varname>¶
Response:¶
BEGIN LIST RANGE <upsname> <varname>RANGE <upsname> <varname> "<min>" "<max>"...END LIST RANGE <upsname> <varname>¶
<upsname> is the name of the UPS,<varname> is the UPS variable, and{<min>,<max>} is the interval of validvalues of that UPS variable. Note that the quotationmarks are part of the response.¶
For example: commandLIST RANGE su700input.transfer.low and response¶
BEGIN LIST RANGE su700 input.transfer.lowRANGE su700 input.transfer.low "90" "105"END LIST RANGE su700 input.transfer.low¶
LIST RWThe command calls for the Attachment Daemon to report a list of the UPSvariables associated with a given UPS that may be read and written bythe Management Daemon. These variables are the abstracted view of the UPShardware capabilities. An economical UPS may support few variables,but a professional model should support at least the variables thatare needed for an automatic shutdown and restart;seeAppendix B. Also,seeSection 8.2 for details of the recommendedminimum support of variables. A full list of variables is availableinsource code file docs/nut-names.txt [gitvars],which serves as the Recording Document.¶
Command:LIST RW <upsname>¶
Response:¶
BEGIN LIST RW <upsname>RW <upsname> <varname> "<value>"...END LIST RW <upsname>¶
<upsname> is the name of the UPS,<varname> is the UPS variable, and<value> is the value of that UPS variable. Note thatthe quotation marks are part of the response.¶
For example: commandLIST RW su700 and response¶
BEGIN LIST RW su700RW su700 output.voltage.nominal "115"RW su700 ups.delay.shutdown "020"...END LIST RW su700¶
LIST UPSThe command calls for the Attachment Daemon to report a list of the UPS unitsto which it is attached.¶
Command:LIST UPS¶
Response:¶
BEGIN LIST UPSUPS <upsname> "<description>"...END LIST UPS¶
<upsname> is the name of a UPS, and<description> is the description maintained by theAttachment Daemon, if available. It is set to "Unavailable" otherwise. Note thatthe quotation marks are part of the response.¶
This command can also be used to determine what values of<upsname> are valid before calling other functions onthe server. This is also a good way to handle situations where asingle Attachment Daemon supports multiple UPSs. It is also useful for clientsthat perform a UPS discovery process.¶
For example: response¶
BEGIN LIST UPSUPS su700 "Development box"END LIST UPS¶
LIST VARThe command calls for the Attachment Daemon to report a list of all the UPSvariables that it maintains for a given UPS and the values of thoseUPS variables.¶
Command:LIST VAR <upsname>¶
Response:¶
BEGIN LIST VAR <upsname>VAR <upsname> <varname> "<value>"...END LIST VAR <upsname>¶
<upsname> is the name of the UPS,<varname> is the UPS variable, and<value> is the value of that variable. Note thatthe quotation marks are part of the response.¶
The response to this command lists the UPS variables available forthis UPS and their current values.¶
For example: commandLIST VAR su700 and response¶
BEGIN LIST VAR su700VAR su700 ups.mfr "Example Mfg"VAR su700 ups.mfr.date "10/17/96"...END LIST VAR su700¶
SeeSection 8.2 for details of the recommended minimumsupport of variables. A full list of variables is availableinsource code file docs/nut-names.txt [gitvars],which serves as the Recording Document.¶
PASSWORDThis command is a companion toUSERNAME and is used by aManagement Daemon to specify the password required to enter a session with theAttachment Daemon; seeSection 2.9.¶
Command:PASSWORD <password>¶
If the command succeeds, the response isOK; otherwise, seethe error responses inSection 4.3.2.¶
For examples of the use of commandsUSERNAMEandPASSWORD by administrative users,seeAppendix E.2.¶
PRIMARYIn current practice, the Attachment Daemon records in localfileupsd.users that an administrative user is a Primary.SeeAppendix E.1 for an example. When a Management Daemonstarts up and opens a session with the Attachment Daemon, it lays claim to being aPrimary by sending commandPRIMARY to the Attachment Daemon, thusclaiming that it has the required authority to perform criticalactions, such as setting status symbolFSD.¶
Command:PRIMARY <upsname>¶
<upsname> is the name of the UPS.¶
If the Attachment Daemon has the authority, the response isOK;otherwise, see the errorresponses inSection 4.3.2.¶
Note: Historically, this command was known asMASTER.¶
PROTVERReturn the version of the command/response protocolused by the Attachment Daemon. This command is intended for human, as well asprogram, use.¶
Command:PROTVER¶
For example: the following command line sequence in the Attachment Daemon¶
netcat localhost 3493PROTVER1.3¶
Notes:¶
PROTVER isdifferent than the implementation version of the Attachment Daemon returnedbyVER.¶NETVER command used in previousreleases. SeeSection 8.2.4.¶SETThe command calls for the Attachment Daemon to set a UPS variable to a givenvalue. Whether this has an effect on the UPS hardware is specific tothe Driver and the UPS model. Some variables are read-only due to thedesign of the UPS or its Driver.¶
Command:SET VAR <upsname> <varname>"<value>"¶
<upsname> is the name of the UPS,<varname> is the UPS variable, and<value> is the value to be assigned to that variable.Note that the quotation marks are part of the command.¶
If the command succeeds, the response isOK; otherwise, seethe error responses inSection 4.3.2.¶
For example: commandSET VAR su700 ups.id "My UPS" andresponseOK¶
STARTTLSThe client tells the Attachment Daemon to switch to communication encrypted byTLS[RFC8446]. When theclient receivesOK, it also switches to TLS encryption.¶
Command:STARTTLS¶
If the command succeeds, the response isOK STARTTLS;otherwise, see the error responsesinSection 4.3.2.¶
If the client does not send command STARTTLS to the Attachment Daemon,communication continues unencrypted; however, an Attachment DaemonMAY refuseunencrypted communication.¶
NUT 2.8.0 supports the encryption of communications between theAttachment Daemon and the Management Daemon using TLS1.3[RFC8446] with X.509 v3 certificates, asdefined by[RFC5280] and updates.SeeAppendix D for details of theencryption of communications in previous release 2.7.4.¶
ABNF: See variablestarttls inFigure 5.¶
The very restricted nature of UPS management makes it ofinterest to consider self-signed certificates.¶
In the World Wide Web, there are millions of servers and hundredsof millions of potential clients for each one. The servers do notknow who their clients will be, so they entrust the management of aPublic Key Infrastructure (PKI) to Certificate Authorities that theytrust. The encryption of communicationsbetween the client and server requires that the browsers carry a list ofCertificate Authorities that the clients have to trust.This isa many-to-many relationship.¶
The management of UPS units is not a many-to-many relationship; itis frequently one to one. In the closely restrained world of UPSmanagement, there are a very limited number of clients for eachserver, rarely more than three, and unlike the World Wide Web, theserver administrators know exactly who they are. These clients visitvery few servers, typically one only. This situation is totallydifferent from the World Wide Web. The use of external CertificateAuthorities is a potential security weakness that must be accepted forthe World Wide Web but which can be avoided for UPS management byeither generating the private and public keys locally or, for largerorganizations, using a PKI.¶
The security policies for UPS management may be subordinate to anorganization's own internal IT security plans and procedures, possiblybased on[RFC7030]and[RFC8894], but in simple cases, it is possibleto obtain better security using self-signed certificates.¶
USERNAMEThe Attachment Daemon limits access to clients whose credentials match those inthe fileupsd.users. There is no anonymous access. A Management Daemonprogram or script uses commandUSERNAME and its companioncommandPASSWORD to open a session with the Attachment Daemon for anadministrative user. Note that this command is for program or scriptuse and is not the familiar login command typed on a command line togain access to a shell.¶
Command:USERNAME <username>¶
If the command succeeds, the response isOK; otherwise, seethe error responses inSection 4.3.2.¶
For examples of the use of commandsUSERNAME andPASSWORD by administrative users,seeAppendix E.2.¶
VERReturn the implementation version of the Attachment Daemon. This command isintended for human, as well as program, use.¶
Command:VER¶
For example: the following command line sequence¶
netcat localhost 3493VERNetwork UPS Tools upsd 2.8.0 - http://www.networkupstools.org/¶
Notes:¶
If the command succeeds, the response has the followingcommand-dependent form:¶
| Command | Response | Reference | Note |
|---|---|---|---|
ATTACH | OK | Section 4.2.1 | Was LOGIN |
DETACH | OK Goodbye | Section 4.2.2 | Was LOGOUT |
FSD | OK FSD-SET | Section 4.2.3 | |
GET | Subcommand specific | Section 4.2.4 | |
HELP | List of commands | Section 4.2.5 | |
INSTCMD | OK | Section 4.2.6 | |
LIST | Subcommand specific | Section 4.2.7 | |
PASSWORD | OK | Section 4.2.8 | |
PRIMARY | OK | Section 4.2.9 | |
PROTVER | Protocol version | Section 4.2.10 | Was NETVER |
SET | OK | Section 4.2.11 | |
STARTTLS | OK STARTTLS | Section 4.2.12 | |
USERNAME | OK | Section 4.2.13 | |
VER | Program version | Section 4.2.14 |
Error responses have the following format:¶
ERR <error-name> [<extra>]¶
<error-name> is a single word token taken fromthe 27 characters A-Z and hyphen(-). ImplementationsMAY, if needed, add an additional,optional<extra>. Current practice does not make useof this possibility.¶
The<error-name> may have one of the followingvalues:¶
The Error Name Token <error-name> | Meaning |
|---|---|
ACCESS-DENIED | The client's host and/orauthentication details supplied byUSERNAMEandPASSWORD are not sufficient to execute the requestedcommand. |
ALREADY-ATTACHED | The client has already sent asuccessful |
ALREADY-SET-PASSWORD | The client has alreadysupplied aPASSWORD and is attempting to repeat the commandin the same session. |
ALREADY-SET-USERNAME | The client has alreadysupplied aUSERNAME and is attempting to repeat the commandwithin the same session. |
CMD-NOT-SUPPORTED | The specified UPS doesn'tsupport the Instant Command. |
DATA-STALE | The Attachment Daemon is connected to theDriver for the UPS, but that Driver isn't providing regular updatesor has specifically marked the data as stale. Current practice is forthe Attachment Daemon to refuse to provide the Management Daemon with variables on stale unitsto avoid false readings.¶ This generally means that the Driver is running, but it has lostcommunication with the hardware. Check the physical connection to theequipment.¶ |
DRIVER-NOT-CONNECTED | The Attachment Daemon can't perform therequested command, since the Driver for that UPS is notconnected. This usually means that the Driver is not running or, if itis, is misconfigured. |
FEATURE-NOT-CONFIGURED | This instance of the Attachment Daemonhasn't been configured properly to allow the requested feature tooperate. In current practice, this error response is possible only forcommandSTARTTLS. |
FEATURE-NOT-SUPPORTED | This instance of Attachment Daemon doesnot support the requested feature. In current practice, this errorresponse is possible only for commandSTARTTLS. |
INSTCMD-FAILED | The Attachment Daemon failed to deliver theInstant Command request to the Driver. No further information isavailable to the client. This typically indicates a dead or brokenDriver. |
INVALID-ARGUMENT | The client sent an argument to acommand that is not recognized or is otherwise not valid in thiscontext. This is typically caused by sending a valid command, such asGET, with a subcommand that is not valid. |
INVALID-PASSWORD | The client sent a nonvalidPASSWORD. |
INVALID-USERNAME | The client sent a nonvalidUSERNAME. |
INVALID-VALUE | The value specified in the requestis not valid. This usually applies to aSET ofanENUM type that is using a value not in the list ofallowed values. SeeSection 4.2.7.3. |
PASSWORD-REQUIRED | The command requiresaPASSWORD for authentication, but the client hasn't providedone. |
READONLY | The requested variable in aSETcommand is not writable. |
SET-FAILED | The Attachment Daemon failed to delivertheSET request to the Driver. This is similartoINSTCMD-FAILED. |
TLS-ALREADY-ENABLED | TLS mode is already enabledon this connection, so the Attachment Daemon can't start it again.¶ Note: Historically, this message was |
TLS-NOT-ENABLED | TLS mode is required but hasnot yet been enabled on this connection, so the Attachment Daemon can't sendcommands.¶ Note: This message is experimental and not in current commonuse.¶ |
TOO-LONG | The requested value in aSETcommand is too long. |
UNKNOWN-COMMAND | The Attachment Daemon doesn't recognize thecommand. |
UNKNOWN-UPS | The UPS specified in the request isnot known to the Attachment Daemon. This usually means that it didn't matchanything in the Attachment Daemon configuration. |
USERNAME-REQUIRED | The command requiresaUSERNAME for authentication, but the client hasn't providedone. |
VAR-NOT-SUPPORTED | The specified UPS doesn'tsupport the UPS variable in the command. |
Note: Historically, this error response wasALREADY-LOGGED-IN.¶
This section repeats the syntax ofSection 4.2but in Augmented Backus-Naur Form (ABNF). It does not define anyadditional features. For further details of each command and theresponse, seeSection 4.2.¶
The commands may be presented in ABNF[RFC5234][RFC7405] andrepresented using US-ASCII[RFC0020].¶
Current practice tolerates mixed-case command names, but it isRECOMMENDED to use uppercase only for commands.SeeFigure 5.¶
;-------------------------------------------------------------------; This grammar is case sensitive. Terminal keywords SHOULD be; written in uppercase, as shown.; The following basic rules written with uppercase names are; taken from RFC 5234, Appendix B.1. SP = 1*%x20 ; At least one SPACE LF = %x0A ; Linefeed DIGIT = %x30-39 ; Digit 0 through 9 ALPHA = %x41-5A / %x61-7A ; A-Z / a-z DQUOTE = %x22 ; Double quote " VCHAR = %x21-7E ; Visible (printing) characters; Additional basic rules needed by this grammar LC = %x61-7A ; Letter a through z DOT = 1%x2E ; Exactly one . COLON = 1%x3A ; Exactly one : AT = 1%x40 ; Exactly one @ SEP = 1"-" / 1"_" / 1"." ; A single - or _ or . JOIN = COLON / AT ; A single : or @; Frequently used in this grammar cmdname = 1*LC *62(DOT 1*LC) ; E.g., load.off.delay upschar = DIGIT / ALPHA / SEP ups = 1*ALPHA *62upschar ; E.g., Example-Mfg-999 group = ups ; E.g., HB (Not in common use) hostname = ups ; E.g., example.com port = 1*5DIGIT ; E.g., 3493 upsname = [group COLON] ups [AT hostname [COLON port]] ; Fully Qualified UPS name ; E.g., ; HB:heartbeat1@example.com:3493 username = ups ; E.g., Power-Dept.6 varname = 1*LC *62( DOT 1*(DIGIT / LC) ) ; E.g., outlet.1.status;------------------------------------------------------------------- commandLine = command LF ; LF is a single %x0A command = attach / detach / fsd / get / help / instcmd / list / password / primary / protver / set / starttls / username / ver; attach = "ATTACH" SP upsname; detach = "DETACH"; fsd = "FSD" SP upsname; get = "GET" SP getsubcommnd getsubcommand = getcmddesc / getdesc / getnumattach / gettype / getupsdesc / getvar; getcmddesc = "CMDDESC" SP upsname SP cmdname getdesc = "DESC" SP upsname SP varname getnumattach = "NUMATTACH" SP upsname gettype = "TYPE" SP upsname SP varname getupsdesc = "UPSDESC" SP upsname getvar = "VAR" SP upsname SP varname; help = "HELP"; instcmd = "INSTCMD" SP upsname SP cmdname; list = "LIST" listsubcommand listsubcommand = listclient / listcmd / listenum / listrange / listrw / listups / listvar; listclient = "CLIENT" SP upsname listcmd = "CMD" SP upsname listenum = "ENUM" SP upsname SP varname listrange = "RANGE" SP upsname SP varname listrw = "RW" SP upsname listups = "UPS" listvar = "VAR" SP upsname; session-password = "PASSWORD" SP *63VCHAR ; A sequence of printable characters defined ; in a server configuration file. Local ; security practices may mandate a minimum ; and maximum number of characters.; primary = "PRIMARY" SP upsname; protver = "PROTVER"; value = *63VCHAR ; Local practices may limit the choice of ; characters and require non-US-ASCII. set = "SET" SP %s"VAR" SP upsname SP varname SP DQUOTE value DQUOTE; starttls = "STARTTLS"; session-username = "USERNAME" SP username; ver = "VER";-------------------------------------------------------------------
Notes:¶
n*n, meaning "exactly n copies", may bewritten asn.¶0*1.¶The responses to the commands are encodedinUS-ASCII [RFC0020] and fall into two groups:¶
END LIST . Forexample, seeSection 4.2.7.1.¶These symbols resume the abstracted view of the UPS hardwaremaintained by the Attachment Daemon. The variableups.status containsone or more space-separated status symbols, which together describe theUPS state at that instant. In current practice, the Management Daemon will pollvariableups.status every 5 seconds with a command, suchasGET VAR su700 ups.status, and a response, such asVARsu700 ups.status "OB LB", to discover changes in the UPS status.These changes will indicate UPS events.¶
| 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 istoo low and is boosting it to the required level. The UPS continuesto supply the protected system from the public power supply. |
BYPASS | The UPS is feeding current directly from the public power supply to theprotected system. The backup facilities are disconnected. This stateallows maintenance personnel to change the batteries withoutinterrupting the protected system. |
CAL | The UPS is calibrating itself, for example, to determine at whatcharge theLB status is raised or lowered. |
CHRG | The UPS battery is charging. This usually implies that the UPSalso has status |
COMM | The Attachment Daemon has effective contact with the UPS. |
DISCHRG | The UPS battery is discharging. This usually implies that the UPSalso has status |
FSD | This "Forced Shutdown" status signals that the final shutdownsequence has begun. |
LB | Low Battery. The battery level of the UPS is below a chosen limit.The UPS may be in statusOL orOB. |
NOCOMM | The Attachment Daemon has no effective contact with the UPS. |
OB | On Battery. The UPS is taking energy from its battery.The battery is discharging. A UPS must have statusOB orOL;otherwise, it is deemed dead. |
OFF | The UPS is in state "Off". It does not react to failure in thepublic power supply. The exact meaning depends on the model. |
OL | Online. The UPS is online, receiving energy from the public power supply. Thebattery is charging. A UPS must have statusOB orOL; otherwise,it is deemed dead. |
OVER | Overloaded. The UPS reports that the load on it is beyond itsnormal operating maximum. |
RB | Replace battery. The UPS reports that its battery or batteries shouldbe replaced. |
TEST | Under test. The UPS is currently undergoing a test that may havebeen requested manually or internally. |
TICK | Heartbeat. A software UPS in the Attachment Daemon provides a regular signalmonitored by the Management Daemon as a way of verifying effective end-to-endmanagement.TICK andTOCK are companions; they are consideredexperimental. |
TOCK | Heartbeat. SeeTICK |
TRIM | The UPS has determined that the voltage level of the public power supply istoo high and is reducing it to the required level. The UPS continuesto supply the protected system from the public power supply. |
A Management Daemon detects the occurrence of a UPS event from a change in theUPS status received from the Attachment Daemon. The following table summarizesthe process. A status of "none" means that the status symbol is notpresent in the variableups.status.¶
The Management Daemon should retrieve the variableups.status from theAttachment Daemon at regular intervals. If the interval is too short, compute andnetwork 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 isRECOMMENDED, but an implementationMAY make this value configurable. By default, the "old" status istherefore the previous value retrieved 5 seconds ago.¶
Current practice is for the Management Daemon to assign names to certainevents. These are shown in the table in parentheses.¶
| 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 note4 | |
| none | DISCHRG | Discharging | DISCHRG | none | Not discharging | |
| none | FSD | System shutdown (events FSD,SHUTDOWN) | FSD | none | Shutdown abandoned. See note1 | |
| none | LB | Low battery. See note2 (eventLOWBATT) | LB | none | Battery not low | |
| none | NOCOMM | UPS dead? See note4 (events COMMBAD,NOCOMM) | NOCOMM | none | See note4 | |
| 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 note3 | TICK | none | No heartbeat. See note3 | |
| none | TOCK | Heartbeat event. See note3 | TOCK | none | No heartbeat. See note3 | |
| none | TRIM | Trimming voltage | TRIM | none | Not trimming |
OB is present, current practicetakes Management Daemon reception ofLB as an order to perform an emergencysystem shutdown.¶NOCOMM), and if the last knownOL/OB status wasOB, asystem shutdown (commandFSD) is requested.¶Experience over the last 20 years shows that new UPS managementsoftware releases are not frequent and, when installed, stayunmodified for some years. This is probably because UPS management isa mature activity, part of site management. A limited number ofsystem administrators have access to the UPS hardware and software andtend to assume a certain "security by obscurity" since manyinstallations have a configuration like the one shown inFigure 6, which uses port3493/TCP (nut) between the two daemons running in the same system.The traffic is often not encrypted, and when it is encrypted, it uses deprecatedearly versions of SSL/TLS.¶
,-----, ,--------------------,---------------------, | UPS |---| Attachment <-Commands Management | | |===| Daemon Responses-> Daemon | /-----\ '--------------------'---------------------' Listens on port 3493/TCP for localhost
This situation is now changing as low-cost processors becomeavailable, costing significantly less than a UPS unit. This evolutionmakes it interesting to shift to a configuration like the one shown inFigure 7, but it alsoexacerbates the security weakness ofFigure 6, since the traffic between the daemons is now over anexposed network.¶
,-----,------------, ,--------------, | UPS - Attachment | <-Commands | Management | | | Daemon | Responses-> | Daemon | /-----'------------\ '--------------' Listens on port 3493/TCP
These security issues raised by UPS management are those of thepower industry in general; they are addressed in detail inIEC Technical Specification 62351 [IEC62351-1].In addition to equipment security, cyber security is now an essentialconsideration.¶
Quoting from IEC 62351-1[IEC62351-1],Introduction to the standard, clause 5.2.3.5:¶
With the computer systems for power operations presumablykept isolated from the Internet, many utility personnel do not see anyreason for adding security measures to these systems. However, asclearly seen from these Subclauses, this may not be true anymore asnetworking becomes more prevalent and additional information accessrequirements grow.¶
In IEC 62351-1[IEC62351-1], clause 5.3.5 liststypical security attacks: Eavesdropping, Masquerade,Man-in-the-Middle, Replay, and Resource Exhaustion.[RFC3552] adds message insertion/deletion/modificationand denial of service.¶
Let's look more closely at these requirements:¶
Enforcing secure communication requires tightening up the Attachment Daemon torequire the use of commandSTARTTLS for commands sent over the global Internet. In such asituation, an Attachment Daemon listening for traffic other than fromlocalhost:¶
Notes:¶
STARTTLS command.¶localhost if the local installation's securitypractices allow it, for example, in a dedicated appliance.¶FirewallsSHOULD be used to restrict the communication betweenthe Attachment Daemon and the accepted Management Daemons, prohibiting and discarding trafficfrom any systems that are not part of the envisioned power managementsetup. Note: SeeSection 6.2, Paragraph 4, Item 1 above on the useofSHOULD.¶
In long-lived installations, such as those found in UPS management,careful certificate management is essential, whether the certificateis provided by a Certificate Authority or is a self-signedcertificate. For example, the expiration times of both the certificate containing the public key and the signing certificateshould be specified.¶
The defense against eavesdropping is encryption of the commands andresponses passed between the client Management Daemon and server Attachment Daemon. The protocolprovides commandSTARTTLS, seeSection 4.2.12, which calls onthe Attachment Daemon to support TLS encryption of the communication. If thiscommand 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. Thisis done by setting declarationsFORCESSL to 1andCERTVERIFY to 1 in the Management Daemon configuration file.¶
A further weakness is that theFORCESSLandCERTVERIFY 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 apossibly rogue client Management Daemon out on the Internet.¶
This weakness may be mitigated with strict firewall rules thatwould prevent the rogue client Management Daemon from accessing the Attachment Daemon.¶
Although version 2.8.0 of NUT supports TLS1.3[RFC8446] with X.509 v3 certificates asdefined by[RFC5280], previous version2.7.4 only supported earlier SSL/TLS versions. To overcome thisweakness, The following techniques have been used:¶
The protocol relies on TLS encryption to prevent man-in-the-middleattacks. SeeAppendix D for defensemethods used for previous NUT version 2.7.4.¶
The protocol allows a malicious client actingas a Management Daemon to send commandFSD to an Attachment Daemon to shut down aworking system and its power supply, as described in The ShutdownStory section (seeAppendix B). Similarly, amalicious client could turn off the UPS power outlets, causing thesystem to fail.¶
The protocol provides commandsUSERNAME (seeSection 4.2.13)andPASSWORD (seeSection 4.2.8), which allow an administrativeuser in a Management Daemon to authenticate itself to the Attachment Daemon, as a defenseagainst masquerade attacks. The administrative username and passwordneed protection against local malicious users. This is done byrestricting access to the configuration files.¶
The protocol relies on TLS encryption to prevent message insertion,deletion, and modification attacks.SeeAppendix D for defense methodsused for previous NUT version 2.7.4.¶
The protocol relies on a very tightly specified firewall to preventdenial-of-service attacks. Only designated client Management Daemons should beable to reach the server Attachment Daemon.¶
The protocol specified by this text runs over port 3493/TCP (nut), which isregistered by the Network UPS Tools (NUT) Project.¶
This document has been added to the registration's Reference field in the "Service Name and Transport Protocol Port Number Registry"[Registry].¶
This section presents a very short summary of the status of the Network UPS Tools project.¶
smartups, an Attachment Daemonupsd, and a simple Management Daemon.¶upsmon supported Primary/Secondary configurations.¶See[githist] and Appendix J[History] for a detailed history of the NUT Project.¶
The programsupsd,upsmon,upssched,upsc,upscmd, andupsrw have been included in the package known as "nut" in the package systems of many distributions, i.e., all the major Linux distributions and Unix distributions, such as OpenBSD and OpenSolaris. A Microsoft Windowsversion has been developed but was not maintained.¶
The features provided by current UPS units vary widely. However, experience shows that a minimum feature set is needed for satisfactory use of the NUT Project software. A full list of variables is available insource code file docs/nut-names.txt [gitvars], which serves as the Recording Document.¶
The following variables form a minimum set suitable for a desktop PC. It is expected that, on public power supply failure, the PC will be halted. It will not restart automatically when power returns.¶
The following additional variables are needed in a minimum set suitable for an unattended server. It is expected that, on public power supply failure, the server will be halted. It will restart automatically when power returns.¶
Satisfactory use of the NUT Project software requires support for all the commands specified in protocol version 1.3, software version 2.8.0.¶
In order to ease migration from software version 2.7.4, which supported protocol version 1.2, software version 2.8.0 also supports the technical terms used in protocol version 1.2. SeeAppendix C for the differences.¶
The UPS variables represent the abstracted state of the UPS unit.Certain variables represent not only the state of some hardwarefeature but also provide tunable values and Instant Commands;seeSection 2.5. The full set of variables is recordedin thereference document for variablenames [gitvars].¶
The number of variables used in a given deployment depends on thesophistication of the UPS product; this annex shows a typical exampleof the subset of variables used for a reasonably complete "consumergrade" UPS. The NUT Project maintains alargelibrary of the variable subsets [Library] used by different UPS models.¶
Note that successive versions of a given product may add or deletefeatures, causing a change in the subset of variables used. An exampleis the removal ofups.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 mayprovide a listing of the variables available for a given product, forexample, utility programupsc, as included in the NUT package;seeSection 2.6, Paragraph 3.¶
The following sections illustrate the use of variables by takingthe values associated with a typical product. The example is a 1600 Va1000 W UPS.¶
| 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" |
Some of the features of a UPS are represented by variables thatmay be tuned by the user. The following variables are typical of suchtunable features. The precise list depends on the model of UPS. Animplementation of a Management Daemon acting as a utility program may provide alisting of the variables available, as well as acting on them, forexample, utility programupsrw, as included in the NUT package;seeSection 2.6, Paragraph 3.¶
| Variable | Typical Value | Default Description Provided as Response to the CommandGET 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)" |
Some of the features of a UPS are actions known as InstantCommands (seeSection 2.5), which may be ordered by theuser. The following variables represent such Instant Commands. Theprecise list depends on the model of UPS. An implementation of aManagement Daemon acting as a utility program may provide a listing of thevariables available, as well as acting on them, for example, utilityprogramupscmd, as included in the NUT package;seeSection 2.6, Paragraph 3.¶
| 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 |
This appendix provides background material helpful for a generalunderstanding of the relation between system and UPS. It does notdefine any feature of the command-response protocol.¶
We consider the steps involved in the shutdown and restart of along-running unattended server protected by a single UPS. The Management Daemonruns in the server as shown inFigure 8.¶
,------------------SERVER------------------, | | | ,-----, | UPS <-Commands UPS | | UPS |---| Attachment | Management | | |===| Daemon Responses-> Daemon | /-----\ '--------------------'---------------------' Internal loopback
ups.status reportsOL.Days, weeks, months go by...¶OL->OB.¶battery.charge.low. The server remains operational, but theUPS battery will not last much longer. The Management Daemon polls the Attachment Daemon anddetects status changeOB->OB+LB.¶FSD in the Attachment Daemon to call on any Secondaries toshut down and waits for commandGET NUMATTACH to report onesingle attachment, i.e., the Primary itself. The Management Daemon then issues thesystem shutdown command for itself.¶upsdrvctlshutdown. This tells the UPS that it is to shut down N secondslater where the default is N=20.Note that the "shutdown" of a UPS removes powerfrom the outlet sockets but may not turn the UPS off completely.A delayed shutdown is sometimes audible, and the characteristicbeeping of the UPS stops.¶N seconds afteritem7 The UPS shutsdown, i.e., it turns off its outlet sockets when N=20 seconds havepassed. With some UPS units, there is an audible "clunk".¶
What if the public power supply returns before the UPS shuts down? The UPS unitshould be able to wait a configurable time with default 30 seconds.These two timers start from the moment the UPS receives theupsdrvctl shutdown command.Minutes, hours, days goby...¶
OL+LB.¶battery.charge.low threshold, and the Attachment Daemon declares thestatus changeOL+LB->OL. We are now back in the samesituation as item1 above.¶This appendix lists the major differences between the technicalterms used in NUT software release 2.8.0 and documented in this text,as well as those used in previous version 2.7.4 of the NUT Project.¶
| Term in Previous Release NUT 2.7.4 | Term in this Document, Release NUT 2.8.0 | Reference |
|---|---|---|
| ALREADY-LOGGED-IN | ALREADY-ATTACHED | Table 3 |
| ALREADY-SSL-MODE | TLS-ALREADY-ENABLED | Table 3 |
LOGIN | ATTACH | Section 4.2.1 |
LOGOUT | DETACH | Section 4.2.2 |
| Master | Primary | Section 2.7 |
NETVER | PROTVER | Section 4.2.10 |
NUMLOGINS | NUMATTACH | Section 4.2.4.3 |
| Slave | Secondary | Section 2.8 |
Previous NUT version 2.7.4 did not provide support for TLS1.3[RFC8446]. The following subsectionsdescribe mitigating techniques.¶
Previous version 2.7.4 of NUT did not support TLS1.3[RFC8446]. Where such protection is neededfor version 2.7.4, a possible technique introduces shims between theAttachment Daemon and the network and between the network and the Management Daemon, as showninFigure 9. These shimsprovide TLS 1.3 support, thus allowing the Attachment Daemon and Management Daemon to continuetemporarily without having TLS implementations themselves. The technique has been successfullytested.¶
TLS shim listens TLS shim listens on port TBD1/TCP on port 3493/TCP ,-----,------------,----, ,----,--------------, | UPS - Attachment |TLS | <-STARTTLS | TLS| Management | | | Daemon |shim| OK--> |shim| Daemon | /-----'------------'----\ '----'--------------' Listens on port 3493/TCP
The shim in front of the Attachment Daemon listens to incoming traffic on portTBD1/TCP. When it receives the commandSTARTTLS, it:¶
OK to the client and sets up TLS encapsulation.¶STARTTLS to the Attachment Daemon port 3493/TCP.¶All other commands and responses are passed through.¶
Note: Port TBD1/TCP is not specified by this text.¶
The shim in front of the Management Daemon listens for incoming traffic on port3493/TCP. When it receives the commandSTARTTLS, it:¶
FEATURE-NOT-CONFIGURED to the client.¶STARTTLS to the Attachment Daemon on port TBD1/TCP.¶All other commands and responses are passed through.¶
Another technique is the use ofTLStunnels [RFC8446], using a software, such asstunnel[stunnel], which adds OpenSSL-based TLSsupport without modifying the Attachment Daemon or Management Daemon. The NUT Project has noprocedure to enforce this on sites.¶
A further option to secure communications is very similartoTLS tunneling [RFC8446] and consists ofrouting the NUT traffic through a Virtual Private Network (VPN).¶
A fourth option is to isolate the UPS management traffic at thenetwork switching level using a Virtual LAN (VLAN) technique.¶
,-------------, ,-------------,,-----, | Attachment | | Management || UPS |---| Daemon | | Daemon || | |-------------| UPS |-------------|| |===| | Management | UPS |/-----\ | Protected |~~~~~~~~~~~~~~~| Management | | Server | VLAN | Client | | | '-------------' '-------------' Production | VLAN ,---|-------, ,-----------,| ,-----------,|' | Clients |' '-----------'
InFigure 10, there are two VLANS: the maintraffic between the protected server and its clients using theproduction VLAN. The UPS management traffic between the Attachment andManagement Daemons uses the UPS management VLAN marked as~~~~~~~~~~~~~.¶
Administrative commands, such asFSD,INSTCMD,andSET, are powerful and can have a deep effect on systemintegrity. For example, the commandFSD is involved inmission-critical system shutdown decisions. Access to them needs tobe managed and restricted. This section presents the current practice.¶
The Attachment Daemon maintains a file (currentlyupsd.users) that defineseach administrative user. Note that these users are independent ofthose recorded in file/etc/passwd. Each administrative usergets its own section in fileupsd.users. The declarations inthat section set the parameters that define that user'sprivileges. The section begins with the name of the user enclosed insquare brackets, opening bracket ([)and closing bracket (]), and continues untilthe next username in brackets or EOF.¶
For example, the following file declares two administrative users,admin andpfy:¶
[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:¶
| 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:¶
|
instcmds | Let a user initiate specific Instant Commands. SeeSection 4.2.6. Use valueALL 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 clientupscmd -l supplied by the NUT Project. TheLIST CMD command is issued within the clientupscmd. |
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 stillmaster orslave. Note that there is no EQUALS =. |
The following examples show the current security practices foradministrative users of a client Management Daemon. They also illustrate thecommand pairUSERNAME andPASSWORD. See Sections4.2.13and4.2.8.¶
In this simple example of current practice, the systemadministrator sets the battery level at which an Attachment Daemon will raise thestatusLB, represented by variablebattery.charge.low, to35% of full charge. A system administrator types the following commandto call the clientupsrw supplied by theNUT Project.¶
upsrw -s battery.charge.low=35 -u admin -p sekret UPS-1@example.com¶
Option-s specifies the variable and the value,option-u specifies theUSERNAME, option-pspecifies thePASSWORD, andUPS-1@example.com is theUPS. TheUSERNAME andPASSWORD commands are issuedwithin the clientupsrw, and the session is of short duration.¶
Note: Your password should be stronger than the example shown.¶
In this second example of current practice, the long-runningManagement Daemonupsmon, which is responsible for initiating systemshutdowns and which is provided by the NUT Project, issues commandsUSERNAME andPASSWORD when it starts up. The datavalues needed for theUSERNAME andPASSWORD commands are provided by aconfiguration fileupsmon.conf, which contains theline:¶
MONITOR UPS-1@example.com 1 admin sekret master¶
This says that the UPS to be monitoredisUPS-1@example.com. It provides 1 single power supply. Theadministrative user isadmin withpasswordsekret. The Management Daemon acts as a Primary, althoughcurrent practice still uses the former termmaster.¶
TheUSERNAME andPASSWORD commands are containedwithin the clientupsmon, and the session is of long duration.¶
This document is based on theNUT Projectdocumentation [devguide]. The editoracknowledges the work ofCharles Lepple,Arjen de Korte,Arnaud Quette,Jim Klimov,Russell Kroll,Manuel Wolfshant,Greg Troxel,Mark Hansen, and many others who contribute tothenut-upsuser [nut-upsuser]andnut-upsdev [nut-upsdev] mailing lists.¶
Earlier draft versions of this document were prepared using an SGML DTD[SGML]and an XML meta-DTD defined by HyTime Annex A[HyTimeA]. UnlikeXML, SGML offers markup minimization, and the earlier drafts tookadvantage of this. The osgmlnorm[sgmlnorm] program generated theXML that was used as input to xml2rfc[RFC7991], which then createdthe document's current source. The editor acknowledges the help received fromCarsten Bormann andJulian Reschke in the xml2rfc mailing list.¶
Many helpful comments were received fromEliot Lear,Bart Smit,David Zomaya,Joyce Norris, andTed Mittelstaedt.¶