Uninterruptible Power Supply (UPS) Management Protocol -- Commands and Responses

2.1. 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 Section 2.3. It maintains an abstracted view of the hardware through the use of hardware statuses. See Section 2.10. A Management Daemon may consult the abstracted view using the commands described in this document.¶

See Section 8.2 for details of the recommended minimum support of variables which calls for Attachment Daemon support of statuses OB, OL, LB and FSD.¶

The NUT Project 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.¶

2.2. 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 Appendix E.1. For details of Primary see Section 2.7, and for details of Secondary see Section 2.8. Typically a high-level user will be able to send command FSD but a low-level user might only be allowed to access the test panel. The security provisions for administrative users are discussed in Appendix E.¶

2.3. Driver

A Driver is that part of an Attachment Daemon which is specific to the UPS hardware, the connection medium and the connection protocol, e.g., USB, serial. In current practice the Attachment Daemon has a driver for each hardware interface type it supports. Although this document considers the driver to be part of the Attachment Daemon, current practice is to see it as a separate software unit running as a daemon "in front of" the Attachment Daemon. The protocol for data exchange between the Driver and the Attachment Daemon is outside the scope of this document.¶

2.5. 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 Section 4.2.6.¶

2.6. Management Daemon

The Management Daemon is primarily responsible for managing the hardware and orchestrating system-wide actions after a power event. Using commands sent to the Attachment Daemon 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 Appendix B. Although the term includes the word "Daemon" nothing requires that it be implemented as a detached software service. The Management Daemon may also provide administrative functions such as a graphic interface to view the hardware activity.¶

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.¶

• upsc reports the values of the variables defined for a given UPS, see Table 6.¶
• upsrw reports on and changes the values of the readable and writable configuration variables defined for a given UPS, see Appendix A.2.¶
• upscmd reports on and executes the instant action commands defined for a given UPS, see Section 4.2.6.¶
• UPSmon.py is an experimental Python3 rewrite of upsmon and upssched which includes support for TLS 1.3 [RFC8446].¶

2.7. Primary

When a power device such as a UPS unit supplies power to more than one system, the computer running the driver is known as the Primary. The others are Secondaries. See figure 4. Common current practice for system administrators is to consider the Management Daemon in the Primary to be the Primary Management Daemon which is in charge of the shutdown of all the systems powered by the UPS. The Primary Management Daemon sets status symbol FSD to order the secondaries to shut down.¶

Note: Historically, the Primary was known as the "Master".¶

2.8. 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 4. 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".¶

2.9. 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.¶

2.10. UPS Status

The status of a hardware device such as a UPS unit is a symbolic description of the state of the unit. It consists of a space separated list of symbols from the set {ALARM BOOST BYPASS CAL CHRG COMM DISCHRG FSD LB NOCOMM OB OFF OL OVER RB TEST TRIM}. The symbols TICK and TOCK are experimental additions to the statuses and are not in common current practice. See Section 5.1 which specifies each of these symbols.¶

See Section 8.2 for details of the recommended minimum support of status symbols OB, OL, LB and FSD.¶

2.11. UPS Variable

The metrics and identifiers 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 Appendix A 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 Section 8.2 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 [gitvars] which serves as the Recording Document.¶

4.1. Notation Used in this Specification

The character set used for commands and responses is UTF-8 but current practice is to limit the character set used to the single byte UTF-8 characters 0-127.¶

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 \\.¶

White space within commands and responses is reduced to one U+0020 SPACE (SP).¶

4.2. Commands

The commands address the UPS to which they apply by <upsname> where¶

• <upsname> ::= <ups>[@<hostname>[:<port>]]¶
• <ups> is defined by the Attachment Daemon 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.¶

netcat localhost 3493
HELP
Commands: HELP VER GET LIST SET INSTCMD ATTACH DETACH
          USERNAME PASSWORD STARTTLS

BEGIN LIST CLIENT <upsname>
CLIENT <upsname> <client_IP_address>
...
END LIST CLIENT <upsname>

BEGIN LIST CLIENT ups1
CLIENT ups1 ::1
CLIENT ups1 203.0.113.1
END LIST CLIENT ups1

BEGIN LIST CMD <upsname>
CMD <upsname> <cmdname>
...
END LIST CMD <upsname>

BEGIN LIST CMD su700
CMD su700 load.on
CMD su700 test.panel.start
...
END LIST CMD su700

BEGIN LIST ENUM <upsname> <varname>
ENUM <upsname> <varname> "<value>"
...
END LIST ENUM <upsname> <varname>

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

BEGIN LIST RANGE <upsname> <varname>
RANGE <upsname> <varname> "<min>" "<max>"
...
END LIST RANGE <upsname> <varname>

BEGIN LIST RANGE su700 input.transfer.low
RANGE su700 input.transfer.low "90" "105"
END LIST RANGE su700 input.transfer.low

BEGIN LIST RW <upsname>
RW <upsname> <varname> "<value>"
...
END LIST RW <upsname>

BEGIN LIST RW su700
RW su700 output.voltage.nominal "115"
RW su700 ups.delay.shutdown "020"
...
END LIST RW su700

BEGIN LIST UPS
UPS <upsname> "<description>"
...
END LIST UPS

BEGIN LIST UPS
UPS su700 "Development box"
END LIST UPS

BEGIN LIST VAR <upsname>
VAR <upsname> <varname> "<value>"
...
END LIST VAR <upsname>

BEGIN LIST VAR su700
VAR su700 ups.mfr "Example Mfg"
VAR su700 ups.mfr.date "10/17/96"
...
END LIST VAR su700

netcat localhost 3493
PROTVER
1.3

netcat localhost 3493
VER
Network UPS Tools upsd 2.8.0 - http://www.networkupstools.org/

4.3. Summary of Responses

ERR <error-name> [<extra>]

4.4. An ABNF of the Commands

This section repeats the syntax of Section 4.2, but in Augmented Bachus-Naur Form (ABNF). It does not define any additional feature. For further details of each command and the response, see Section 4.2.¶

The commands may be presented in ABNF [RFC5234], [RFC7405], and represented using Unicode [ISOIEC10646] and encoded in UTF-8 [RFC5198], 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 Section 4.2.4.1, <value> is defined in Section 4.2.11, <varname> is defined in Section 4.2.4.1, <upsname> is defined in Section 4.2.1 and <username> is defined in Section 4.2.13. Current practice tolerates mixed case command names, but it is RECOMMENDED to use upper case only for commands. See Figure 5.¶

   command = attach / detach / fsd / "GET" getsubcommand / help /
             instcmd / "LIST" listsubcommand / password / primary /
             protver / set / starttls / username / ver
   attach = "ATTACH" <upsname>
   detach = "DETACH"
   fsd = "FSD" <upsname>
   getsubcommand = getcmddesc / getdesc / getnumattach / gettype /
                   getupsdesc / getvar
   getcmddesc = "CMDDESC" <upsname> <cmdname>
   getdesc = "DESC" <upsname> <varname>
   getnumattach = "NUMATTACH" <upsname>
   gettype = "TYPE" <upsname> <varname>
   getupsdesc = "UPSDESC" <upsname>
   getvar = "VAR" <upsname> <varname>
   help = "HELP"
   instcmd = "INSTCMD" <upsname> <cmdname>
   listsubcommand = listclient / listcmd / listenum / listrange / listrw /
                    listups / listvar
   listclient = "CLIENT" <upsname>
   listcmd = "CMD" <upsname>
   listenum = "ENUM" <upsname> <varname>
   listrange = "RANGE" <upsname> <varname>
   listrw = "RW" <upsname>
   listups = "UPS"
   listvar = "VAR" <upsname>
   password = "PASSWORD" <password>
   primary = "PRIMARY" <upsname>
   protver = "PROTVER"
   set = "SET" "VAR" <upsname> <varname> U+0022<value>U+0022
   starttls = "STARTTLS"
   username = "USERNAME" <username>
   ver = "VER"

6.1. 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 6 which uses port 3493/TCP (nut) between the two daemons running in the same system. The traffic is often not encrypted, and when encrypted uses deprecated early versions of SSL/TLS.¶

 ,-----,   ,--------------------,---------------------,
 | UPS |---|  Attachment   <-Commands     Management  |
 |     |===|    Daemon       Responses->    Daemon    |
 /-----\   '--------------------'---------------------'
              Listens on
             port 3493/TCP
             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 7, but it also exacerbates the security weakness of figure 6 since the traffic between the daemons is now over an exposed network.¶

 ,-----,------------,               ,--------------,
 | UPS - Attachment | <-Commands    |  Management  |
 |     |   Daemon   |   Responses-> |    Daemon    |
 /-----'------------\               '--------------'
         Listens on
        port 3493/TCP

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 [IEC62351-1]. In addition to equipment security, cyber security is now an essential consideration.¶

Quoting from IEC 62351-1 clause 5.2.3.5 [IEC62351-1]:¶

With the computer systems for power operations presumably kept isolated from the Internet, many utility personnel do not see any reason for adding security measures to these systems. However, as clearly seen from these Subclauses, this may not be true anymore as networking becomes more prevalent and additional information access requirements grow.¶

Clause 5.3.5 [IEC62351-1] lists typical security attacks: Eavesdropping, Masquerade, Man-in-the-Middle, Replay, Resource Exhaustion. RFC3552 [RFC3552] adds message insersion / deletion / modification, and denial of service.¶

Let's look more closely at these requirements:¶

• Eavesdropping, see Section 6.3.1¶
• Man-in-the-Middle, see Section 6.3.2¶
• Masquerade, see Section 6.3.3¶
• Message insersion, deletion, modification, see Section 6.3.4¶
• Replay, see Section 6.3.5¶
• Resource Exhaustion, Denial of Service, see Section 6.3.6¶

6.2. 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 Section 6.2, Paragraph 2, Item 1 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 Section 6.2, Paragraph 2, Item 2 above, then automatically each Management Daemon MUST encrypt as well, since it has to do so in order to gain access.¶
• The SHALL in Section 6.2, Paragraph 2, Item 3 above applies to traffic from the global Internet. An Attachment Daemon MAY accept unencrypted commands from localhost if the local installation's security practices allow it, for example in a dedicated appliance.¶
• 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: 3493/TCP (nut) for the current weakly secure traffic from localhost, and some other port, perhaps TBD1/TCP (ups), 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 Section 6.2, Paragraph 4, Item 1 above on the use of SHOULD.¶

6.3. Attacks and Defences

8.2. 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 [gitvars] which serves as the Recording Document.¶

A.2. Typical UPS Readable and Writable Variables

Some of the features of a UPS are represented by variables which may be tuned by the user. The following variables are typical of such tunable features. The precise list depends on the model of UPS. An implementation of a Management Daemon 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 Section 2.6, Paragraph 3.¶

A.3. Typical UPS Instant Commands

Some of the features of a UPS are actions known as instant commands, see Section 2.5, which may be ordered by the user. The following 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 Section 2.6, Paragraph 3.¶

D.1. Shims

Previous version 2.7.4 of NUT did not support TLS v.3 [RFC8446]. 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 9. 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.¶

              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

D.2. TLS Tunnels

Another technique is the use of TLS tunnels [RFC8446], using a software such as stunnel [stunnel] which adds OpenSSL-based TLS support without modifying the Attachment Daemon or Management Daemon. The NUT Project has no procedure to enforce this on sites.¶

D.3. VPN

A further option to secure communications is very similar to TLS tunnelling [RFC8446] and consists of routing the NUT traffic through a Virtual Private Network, VPN.¶

D.4. VLAN

A fourth option is to isolate the UPS management traffic at the network switching level using a Virtual LAN, VLAN technique.¶

          ,-------------,               ,-------------,
,-----,   | Attachment  |               | Management  |
| UPS |---|   Daemon    |               |   Daemon    |
|     |   |-------------|      UPS      |-------------|
|     |===|             |   Management  |    UPS      |
/-----\   | Protected   |~~~~~~~~~~~~~~~| Management  |
          |  Server     |     VLAN      |   Client    |
          |             |               '-------------'
          '-------------'
      Production | VLAN
             ,---|-------,
            ,-----------,|
           ,-----------,|'
           |  Clients  |'
           '-----------'

In Figure 10 there are two VLANS: The main traffic between the protected server and its clients uses the production VLAN. The UPS management traffic between the Attachment and Management Daemons uses the UPS management VLAN marked as ~~~~~~~~~~~~~.¶

E.1. 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:¶

E.2. An Administrative User of a Client Management Daemon

The following examples show the current security practices for administrative users of a client Management Daemon They also illustrate the command pair USERNAME and PASSWORD. See Section 4.2.13 and Section 4.2.8.¶

upsrw -s battery.charge.low=35 -u admin -p sekret UPS-1@example.com

MONITOR UPS-1@example.com 1 admin sekret master