Skip to main content

Uninterruptible Power Supply (UPS) Management Protocol -- Commands and Responses
draft-rprice-ups-management-protocol-11

The information below is for an old version of the document.
Document Type
This is an older version of an Internet-Draft that was ultimately published as RFC 9271.
Author Roger Price
Last updated 2022-04-11 (Latest revision 2022-04-08)
RFC stream Independent Submission
Formats
IETF conflict review conflict-review-rprice-ups-management-protocol, conflict-review-rprice-ups-management-protocol, conflict-review-rprice-ups-management-protocol, conflict-review-rprice-ups-management-protocol, conflict-review-rprice-ups-management-protocol, conflict-review-rprice-ups-management-protocol
Stream ISE state Response to Review Needed
Consensus boilerplate Unknown
Document shepherd Eliot Lear
IESG IESG state Became RFC 9271 (Informational)
Telechat date (None)
Responsible AD (None)
Send notices to rfc-ise@rfc-editor.org
draft-rprice-ups-management-protocol-11
IETF                                                       R. Price, Ed.
Internet-Draft                                 Network UPS Tools Project
Intended status: Informational                             11 April 2022
Expires: 13 October 2022

 Uninterruptible Power Supply (UPS) Management Protocol -- Commands and
                               Responses
                draft-rprice-ups-management-protocol-11

Abstract

   This document describes the command/response protocol currently used
   in the management of Uninterruptible Power Supply (UPS) units and
   other power devices often deployed in small offices, and in IT
   installations subject to an erratic public power supply.  The UPS
   units typically interface to an Attachment Daemon in the system they
   protect.  This daemon is in turn polled by a Management Daemon which
   notifies users and system administrators of power supply incidents,
   and automates system shutdown decisions.  The commands and responses
   described by this document are exchanged between the UPS Attachment
   Daemon and the Management Daemon.  Current practice when this text
   was written risks weak security and this is addressed in the Security
   Considerations sections of this document.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at https://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on 13 October 2022.

Copyright Notice

   Copyright (c) 2022 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

Price                    Expires 13 October 2022                [Page 1]
Internet-Draft           UPS management protocol              April 2022

   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.  Code Components
   extracted from this document must include Revised BSD License text as
   described in Section 4.e of the Trust Legal Provisions and are
   provided without warranty as described in the Revised BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   4
     1.1.  Current Practice  . . . . . . . . . . . . . . . . . . . .   4
       1.1.1.  NUT Software Project  . . . . . . . . . . . . . . . .   4
       1.1.2.  The "Shutdown Story"  . . . . . . . . . . . . . . . .   4
       1.1.3.  How to Read this Document . . . . . . . . . . . . . .   5
     1.2.  Additional Information  . . . . . . . . . . . . . . . . .   5
     1.3.  Requirements Language . . . . . . . . . . . . . . . . . .   5
   2.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   5
     2.1.  Attachment Daemon . . . . . . . . . . . . . . . . . . . .   5
     2.2.  Administrative User . . . . . . . . . . . . . . . . . . .   6
     2.3.  Driver  . . . . . . . . . . . . . . . . . . . . . . . . .   6
     2.4.  Event . . . . . . . . . . . . . . . . . . . . . . . . . .   6
     2.5.  Instant Command . . . . . . . . . . . . . . . . . . . . .   6
     2.6.  Management Daemon . . . . . . . . . . . . . . . . . . . .   7
     2.7.  Primary . . . . . . . . . . . . . . . . . . . . . . . . .   7
     2.8.  Secondary . . . . . . . . . . . . . . . . . . . . . . . .   8
     2.9.  Session . . . . . . . . . . . . . . . . . . . . . . . . .   8
     2.10. UPS Status  . . . . . . . . . . . . . . . . . . . . . . .   8
     2.11. UPS Variable  . . . . . . . . . . . . . . . . . . . . . .   8
   3.  Protocol Overview . . . . . . . . . . . . . . . . . . . . . .   9
   4.  Protocol Specification  . . . . . . . . . . . . . . . . . . .  11
     4.1.  Notation Used in this Specification . . . . . . . . . . .  11
     4.2.  Commands  . . . . . . . . . . . . . . . . . . . . . . . .  12
       4.2.1.  ATTACH  . . . . . . . . . . . . . . . . . . . . . . .  13
       4.2.2.  DETACH  . . . . . . . . . . . . . . . . . . . . . . .  13
       4.2.3.  FSD . . . . . . . . . . . . . . . . . . . . . . . . .  14
       4.2.4.  GET . . . . . . . . . . . . . . . . . . . . . . . . .  14
         4.2.4.1.  GET CMDDESC . . . . . . . . . . . . . . . . . . .  14
         4.2.4.2.  GET DESC  . . . . . . . . . . . . . . . . . . . .  14
         4.2.4.3.  GET NUMATTACH . . . . . . . . . . . . . . . . . .  15
         4.2.4.4.  GET TYPE  . . . . . . . . . . . . . . . . . . . .  15
         4.2.4.5.  GET UPSDESC . . . . . . . . . . . . . . . . . . .  16
         4.2.4.6.  GET VAR . . . . . . . . . . . . . . . . . . . . .  17
       4.2.5.  HELP  . . . . . . . . . . . . . . . . . . . . . . . .  17
       4.2.6.  INSTCMD . . . . . . . . . . . . . . . . . . . . . . .  17
       4.2.7.  LIST  . . . . . . . . . . . . . . . . . . . . . . . .  18
         4.2.7.1.  LIST CLIENT . . . . . . . . . . . . . . . . . . .  18

Price                    Expires 13 October 2022                [Page 2]
Internet-Draft           UPS management protocol              April 2022

         4.2.7.2.  LIST CMD  . . . . . . . . . . . . . . . . . . . .  19
         4.2.7.3.  LIST ENUM . . . . . . . . . . . . . . . . . . . .  19
         4.2.7.4.  LIST RANGE  . . . . . . . . . . . . . . . . . . .  20
         4.2.7.5.  LIST RW . . . . . . . . . . . . . . . . . . . . .  20
         4.2.7.6.  LIST UPS  . . . . . . . . . . . . . . . . . . . .  21
         4.2.7.7.  LIST VAR  . . . . . . . . . . . . . . . . . . . .  22
       4.2.8.  PASSWORD  . . . . . . . . . . . . . . . . . . . . . .  23
       4.2.9.  PRIMARY . . . . . . . . . . . . . . . . . . . . . . .  23
       4.2.10. PROTVER . . . . . . . . . . . . . . . . . . . . . . .  23
       4.2.11. SET . . . . . . . . . . . . . . . . . . . . . . . . .  24
       4.2.12. STARTTLS  . . . . . . . . . . . . . . . . . . . . . .  24
         4.2.12.1.  Key Infrastructure and Self-signed
                 Certificates  . . . . . . . . . . . . . . . . . . .  25
       4.2.13. USERNAME  . . . . . . . . . . . . . . . . . . . . . .  26
       4.2.14. VER . . . . . . . . . . . . . . . . . . . . . . . . .  26
     4.3.  Summary of Responses  . . . . . . . . . . . . . . . . . .  26
       4.3.1.  Response when Command Succeeds  . . . . . . . . . . .  26
       4.3.2.  Error Responses . . . . . . . . . . . . . . . . . . .  27
     4.4.  An ABNF of the Commands . . . . . . . . . . . . . . . . .  31
       4.4.1.  Responses to Commands . . . . . . . . . . . . . . . .  33
   5.  Statuses and Events . . . . . . . . . . . . . . . . . . . . .  34
     5.1.  Status Symbols  . . . . . . . . . . . . . . . . . . . . .  34
     5.2.  Events  . . . . . . . . . . . . . . . . . . . . . . . . .  36
   6.  Security Considerations . . . . . . . . . . . . . . . . . . .  38
     6.1.  Current General Security Practice . . . . . . . . . . . .  38
     6.2.  Communication Security Requirements . . . . . . . . . . .  39
       6.2.1.  Certificate security  . . . . . . . . . . . . . . . .  40
     6.3.  Attacks and Defences  . . . . . . . . . . . . . . . . . .  40
       6.3.1.  Eavesdropping . . . . . . . . . . . . . . . . . . . .  40
         6.3.1.1.  Misplaced declarations requiring TLS  . . . . . .  41
         6.3.1.2.  Weak protection in previous version 2.7.4 . . . .  41
       6.3.2.  Man in the Middle . . . . . . . . . . . . . . . . . .  41
       6.3.3.  Masquerade Attack: Agent Verification . . . . . . . .  41
       6.3.4.  Message insertion, deletion, modification . . . . . .  42
       6.3.5.  Replay  . . . . . . . . . . . . . . . . . . . . . . .  42
       6.3.6.  Denial of Service . . . . . . . . . . . . . . . . . .  42
   7.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  42
   8.  Implementation Status . . . . . . . . . . . . . . . . . . . .  42
     8.1.  Inclusion in Software Distributions . . . . . . . . . . .  43
     8.2.  Recommended Minimum Support . . . . . . . . . . . . . . .  43
       8.2.1.  Desktop PC Variables  . . . . . . . . . . . . . . . .  43
       8.2.2.  Unattended Servers, Additional Variables  . . . . . .  44
       8.2.3.  Commands and other Technical Terms  . . . . . . . . .  44
   9.  Acknowledgments . . . . . . . . . . . . . . . . . . . . . . .  44
   10. Normative References  . . . . . . . . . . . . . . . . . . . .  44
   11. Informative References  . . . . . . . . . . . . . . . . . . .  45
   Appendix A.  Variables  . . . . . . . . . . . . . . . . . . . . .  48
     A.1.  Typical UPS Variables . . . . . . . . . . . . . . . . . .  48

Price                    Expires 13 October 2022                [Page 3]
Internet-Draft           UPS management protocol              April 2022

     A.2.  Typical UPS Readable and Writable Variables . . . . . . .  52
     A.3.  Typical UPS Instant Commands  . . . . . . . . . . . . . .  54
   Appendix B.  The Shutdown Story for System and UPS  . . . . . . .  54
   Appendix C.  Technical Terms: Historical Differences  . . . . . .  56
   Appendix D.  Security Defences in Release 2.7.4 . . . . . . . . .  57
     D.1.  Shims . . . . . . . . . . . . . . . . . . . . . . . . . .  57
       D.1.1.  Attachment Daemon Shim  . . . . . . . . . . . . . . .  58
       D.1.2.  Management Daemon Shim  . . . . . . . . . . . . . . .  58
     D.2.  TLS Tunnels . . . . . . . . . . . . . . . . . . . . . . .  58
     D.3.  VPN . . . . . . . . . . . . . . . . . . . . . . . . . . .  58
     D.4.  VLAN  . . . . . . . . . . . . . . . . . . . . . . . . . .  59
   Appendix E.  Administrative Security  . . . . . . . . . . . . . .  59
     E.1.  Management of Administrative Users  . . . . . . . . . . .  59
     E.2.  An Administrative User of a Client Management Daemon  . .  61
       E.2.1.  An Administrative User Logs into a Short Session  . .  62
         E.2.1.1.  An Administrative User Logs into a Long
                 Session . . . . . . . . . . . . . . . . . . . . . .  62
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .  62

1.  Introduction

1.1.  Current Practice

   This document describes UPS management techniques and current UPS
   management practice published by the NUT Project.  The document is
   based on version 2.8.0 of the NUT Project software which supports
   version 1.3 of the NUT protocol.

   Since May 2002, the protocol described by this document has been
   operating on IANA port 3493/TCP (nut).

1.1.1.  NUT Software Project

   The primary goal of the NUT (Network UPS Tools) Software Project
   [NUT] is to provide support for Power Devices, such as
   Uninterruptible Power Supplies.  The Project has been in operation
   since 1998 with a major rework in 2003.  It operates through a user
   mailing list [nut-upsuser], a developer mailing list [nut-upsdev], a
   web site [NUT] and a GitHub repository [nut-repository].  See
   [githist] and [History] for a history of the project.

1.1.2.  The "Shutdown Story"

   "The Shutdown Story", see Appendix B, describes the current UPS
   management practice for performing a managed shutdown of unattended
   infrastructure after an unscheduled failure of the public power
   supply in order to minimise the risk of corruption to data processed
   by this infrastructure.

Price                    Expires 13 October 2022                [Page 4]
Internet-Draft           UPS management protocol              April 2022

1.1.3.  How to Read this Document

   As a simplification to ease reading, the term "UPS" is used when
   "Managed Power Device" would be more complete.  The reader should
   understand the simple "UPS" to include other managed power devices.

   The statuses and events appearing in this document are named with
   short text-form names, some of which are abbreviations.  A full list
   of the statuses can be found in Section 5.1 while the events are
   listed in Section 5.2.

   This document refers to the "public power supply".  Other texts
   frequently refer to "utility power", "input source power" or even
   "wall power".

1.2.  Additional Information

   Additional information about the NUT Project is available in the
   project documentation [Documentation].  Requests for further
   information about this protocol and related technical matters may be
   addressed to the mailing list [nut-upsuser] of the NUT Project.

1.3.  Requirements Language

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in BCP
   14 [RFC2119] [RFC8174] when, and only when, they appear in all
   capitals, as shown here.

2.  Terminology

   The following technical terms appear in this document.  They are
   listed in alphabetical order.

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.

Price                    Expires 13 October 2022                [Page 5]
Internet-Draft           UPS management protocol              April 2022

   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.4.  Event

   A UPS Event occurs in the Management Daemon when a change in UPS
   status is received from the Attachment Daemon.  This event is
   internal to the Management Daemon.  See Section 5.2.

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.

Price                    Expires 13 October 2022                [Page 6]
Internet-Draft           UPS management protocol              April 2022

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 are provided by helper program upssched.

   Other programs represent the Management Daemon:

   *  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".

Price                    Expires 13 October 2022                [Page 7]
Internet-Draft           UPS management protocol              April 2022

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.

Price                    Expires 13 October 2022                [Page 8]
Internet-Draft           UPS management protocol              April 2022

   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.

3.  Protocol Overview

   Figure 1 shows a reference configuration in which the command/
   response protocol applies.  The UPS shown 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

                     Figure 1: Reference Configuration

   The reference configuration in figure 1 shows a single UPS unit which
   has a power supply link (===) and a data link (---) attached to a
   system running an Attachment Daemon.  The UPS provides power supply
   protection to the system running the Attachment Daemon.

   In practice there may be more than one UPS unit, and a unit may
   provide power protection to more than one system.  The figure also
   shows a single Management Daemon.  In practice there may be more than
   one Management Daemon, and any one Management Daemon may manage more
   than one UPS Attachment Daemon.

   The protocol applies to connections between the Attachment Daemon and
   the Management Daemon which act as *server* and *client*
   respectively.  The Management Daemon sends commands over TCP to the
   Attachment Daemon and receives responses over TCP from that daemon.

   The two daemons may run in the same system, or may be connected
   through a local or wide area network.  In simple cases, as shown in
   figure 2, the Attachment Daemon and the Management Daemon are in the
   same system, the one protected by the UPS.  The commands and
   responses are exchanged through an internal loopback interface.

Price                    Expires 13 October 2022                [Page 9]
Internet-Draft           UPS management protocol              April 2022

                                                   "The client"
                     ,--------------------,---------------------,
           ,-----,   |     UPS       <-Commands        UPS      |
           | UPS |---|  Attachment        |         Management  |
           |     |===|    Daemon       Responses->    Daemon    |
           /-----\   '--------------------'---------------------'
                                       Internal
                                       loopback
                       UPS Attachment and Management System

              Figure 2: Simplified single-system configuration

   The reference configuration does not require any specific design.
   For example figure 3 shows an arrangement in which the Attachment
   Daemon is closely associated with, or even included in the UPS system
   setup.  This is becoming more prevalent with the availability of low
   cost processors able to run the Attachment Daemon thereby effectively
   creating a network attached UPS running a published protocol.

                                                 "The client"
            ,-----,------------,               ,--------------,
            |     |    UPS     | <-Commands    |     UPS      |
            | UPS - Attachment |---------------|  Management  |
            |     |   Daemon   |   Responses-> |    Daemon    |
            /-----'------------\               '--------------'
               UPS Attachment                   UPS Management
                   System           Network          System

              Figure 3: UPS and Attachment Daemon integration

   As the power requirements for processors decrease, it is becoming
   increasingly common to use a single UPS to protect multiple systems
   as shown in figure 4.  However there is only one data line (---) from
   the UPS to the Primary system.  The others have only power
   connections (===) to the UPS, and are known as Secondaries.  A
   Secondary does not run an Attachment Daemon, it connects over a
   network to the Attachment Daemon in the Primary.  Figure 4 shows the
   Attachment Daemon and the Primary Management Daemon in the same
   system.  This is common practice but it is not a technical
   requirement.

Price                    Expires 13 October 2022               [Page 10]
Internet-Draft           UPS management protocol              April 2022

                                          "The client"
               ,--------------------,---------------------,
     ,-----,   |     UPS       <-Commands      Primary    |
     |     |---|  Attachment        |         Management  |   Primary
     |     |===|    Daemon       Responses->    Daemon    |
     |     |   '--------------------'---------------------'
     | UPS |            ^
     |     |            '<-Commands---Responses->,
     |     |                                     v
     |     |            ,--------------,-----------------,
     |     |============|              |     Secondary   |
     /-----\            |              |     Management  |   Secondary
                        |              |       Daemon    |
                        '--------------'-----------------'

                  Figure 4: UPS protects multiple systems

      |  Note: Should the Primary fail or go off-line, the fate of the
      |  Secondaries depends on the UPS status when the Primary failed.
      |  If the UPS had status OL the Secondary continues operation, but
      |  if the UPS had status OB the Secondary may choose to shut down
      |  as a precaution.

4.  Protocol Specification

   This specification includes only the commands and their responses.
   An implementation of the Attachment Daemon has an internal state
   machine, and some complex implementations of the Management Daemon
   include an internal state machine; for example to assist the system
   shutdown of a complex installation.  The Management Daemon is
   required to remember the previous ups.status value it received from
   the Attachment Daemon and compare it with the next.  Other than that
   the management protocol used between them is effectively stateless.

   See for example Section 5.2 which shows a map of the new ups.status
   response and the previous ups.status response to an Event which is
   taken as the basis for Management Daemon action.

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.

      |  Historical note: UTF-8 characters 0-127 were originally known
      |  as the American Standard Code for Information Interchange, US-
      |  ASCII, first published in 1963.

Price                    Expires 13 October 2022               [Page 11]
Internet-Draft           UPS management protocol              April 2022

   Multi-word elements are contained within U+0022 QUOTATION MARK
   characters for easier parsing.  E.g., "UPS on fire".  Embedded
   quotation marks are escaped with U+005C REVERSE SOLIDUS \ often known
   as backslashes.  Embedded backslashes are also escaped by
   representing them as \\.

   Commands and responses have no leading or trailing whitespace, and
   are terminated with a single new line character U+000A LINE FEED
   (LF).

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

4.2.  Commands

   NUT version 2.8.0 supports the commands used in previous version
   2.7.4 either directly or as aliases.

   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

   ABNF: see variable upsname in Figure 5.

   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.

Price                    Expires 13 October 2022               [Page 12]
Internet-Draft           UPS management protocol              April 2022

4.2.1.  ATTACH

   In a configuration such as that shown in Figure 4 in which a UPS
   protects more than one system, the Primary Management Daemon needs to
   know how many Secondaries are currently "_active_", i.e., powered by
   the UPS, either from the public power supply or from battery power.
   The Attachment Daemon supports this by keeping a count of all the
   "_active_" systems powered by a UPS.  The count is initialised, one
   Secondary at a time by the ATTACH command, which should be understood
   as "_count this Secondary as active_".  ATTACH is one of three
   commands for Secondary counting: command DETACH decrements the count
   and a Management Daemon may read the count at any time using command
   NUMATTACH.

   The ATTACH command is also sent to the Attachment Daemon for the
   Primary so during normal, fully protected operation, the count is 1
   for the Primary + the number of secondaries.  During a full system
   shutdown, the count drops as each Secondary Management Daemon
   executes command DETACH during its own shutdown.  When the count
   drops to 1, only the Primary is "_active_" and it knows that all the
   secondaries have shut down.

   Command: ATTACH <upsname>

   If the command succeeds, the response is OK, otherwise see the error
   responses in Section 4.3.2.

   ABNF: See variable attach in Figure 5,

   Note: Historically, this command was known as LOGIN.  Since that
   LOGIN was not the conventional user access to a shell or program the
   name was changed to avoid confusion.

4.2.2.  DETACH

   This companion command to ATTACH reduces the count of "active"
   Secondaries.  It should be understood as "_this Secondary is no
   longer active_", and is usually used during system shutdown to
   decrement a count of how many Secondaries are still "active".

   Command: DETACH

   If the command succeeds, the response is OK Goodbye, otherwise see
   the error responses in Section 4.3.2.

   ABNF: See variable detach in Figure 5,

   Note: Historically, this command was known as LOGOUT.

Price                    Expires 13 October 2022               [Page 13]
Internet-Draft           UPS management protocol              April 2022

4.2.3.  FSD

   A Management Daemon which is Primary and has the required authority,
   uses this command to set status symbol FSD meaning "Forced Shutdown"
   in the Attachment Daemon.  In current practice the Primary Management
   Daemon uses the symbol to tell the Secondaries to shut down.

   Command: FSD <upsname>

   If the command succeeds, the response is OK FSD-SET, otherwise see
   the error responses in Section 4.3.2.

   ABNF: See variable fsd in Figure 5.

   In current practice, commands such as FSD are made available only to
   a privileged administrative user authorized to send such a mission
   critical command.  The security provisions for administrative users
   are discussed in Appendix E.

   Note: The symbol "FSD" is also used for an Event.  See Table 5.

4.2.4.  GET

   Retrieve a single response from the Attachment Daemon.

   ABNF: See variable get in Figure 5.

   The possible sub-commands are:

4.2.4.1.  GET CMDDESC

   Retrieve a text description of a command.

   Command: GET CMDDESC <upsname> <cmdname>

   Response: CMDDESC <upsname> <cmdname> "<description>"

   For example: GET CMDDESC su700 load.on and response CMDDESC su700
   load.on "Turn on the load immediately"

   This is like GET DESC, but it applies to an Instant Command;. See
   Section 4.2.4.2.

4.2.4.2.  GET DESC

   Retrieve a text description of a UPS variable.  See Section 2.11.

   Command: GET DESC <upsname> <varname>

Price                    Expires 13 October 2022               [Page 14]
Internet-Draft           UPS management protocol              April 2022

   Response: DESC <upsname> <varname> "<description>"

   where <description> is a string that gives a brief explanation of the
   named variable.  The Attachment Daemon MAY return "Unavailable" if
   the file which provides this description is not installed.

   For example command GET DESC su700 ups.status and response DESC su700
   ups.status "UPS status"

4.2.4.3.  GET NUMATTACH

   Retrieve the count kept by the Attachment Daemon of all the
   "_active_" systems protected by this UPS.

   Command: GET NUMATTACH <upsname>

   Response: NUMATTACH <upsname> <value>

   where <value> is a count of the Primary and the number of Secondaries
   currently powered by this UPS.

   For example command GET ATTACH su700 and response NUMATTACH su700 1

   This information is needed by the Management Daemon to determine how
   many Secondaries are still connected during the system shutdown
   process.

   Note: Historically, this sub-command was known as NUMLOGINS.  Since
   LOGIN was not the conventional user access to a shell or program the
   name was changed to avoid confusion.

4.2.4.4.  GET TYPE

   Retrieve the type of a UPS variable.  See Section 2.11.

   Command: GET TYPE <upsname> <varname>

   Response: TYPE <upsname> <varname> <type>...

   where <type> can be one or more of the following tokens.  Multiple
   types may be returned.

   For example command GET TYPE su700 input.transfer.low and response
   TYPE su700 input.transfer.low ENUM

Price                    Expires 13 October 2022               [Page 15]
Internet-Draft           UPS management protocol              April 2022

      +==============+=============================================+
      |     Type     |                   Meaning                   |
      +==============+=============================================+
      | RW           | This is a read/write variable.  It may be   |
      |              | read with command GET VAR, see              |
      |              | Section 4.2.4.6, and set to a different     |
      |              | value with command SET, see Section 4.2.11. |
      +--------------+---------------------------------------------+
      | ENUM         | An enumerated type, which supports specific |
      |              | predetermined values.                       |
      +--------------+---------------------------------------------+
      | STRING:n     | This is a string of maximum length n.       |
      +--------------+---------------------------------------------+
      | RANGE        | This is a number, either integer or float,  |
      |              | comprised in the range which may be seen    |
      |              | with the command LIST RANGE, see            |
      |              | Section 4.2.7.4.                            |
      +--------------+---------------------------------------------+
      | NUMBER       | This is a single numeric value, either      |
      |              | integer or float.                           |
      +--------------+---------------------------------------------+

                         Table 1: Variable Types

   Notes:

   *  ENUM, STRING:n and RANGE are usually associated with RW, but not
      always.  The default <type>, when omitted, is numeric, so either
      integer or float.  Each Driver is then responsible for handling
      values as either integer or float.

   *  Current practice is to represent floating point values using
      locale C.utf8 which is a decimal (base 10) US English-based
      representation.  Hexadecimal, exponents, and comma for thousands
      separator are not allowed.  For example: "1200.20" is valid, while
      "1,200.20" and "1200,20" are not valid.

4.2.4.5.  GET UPSDESC

   Retrieve a text description of a UPS.

   Command: GET UPSDESC <upsname>

   Response: UPSDESC <upsname> "<description>"

   where <description> is defined by the Attachment Daemon
   configuration.  If it is not set, current practice is for the
   Attachment Daemon to return "Unavailable".

Price                    Expires 13 October 2022               [Page 16]
Internet-Draft           UPS management protocol              April 2022

   For example command GET UPSDESC su700 and response UPSDESC su700
   "Development box"

   This can be used to provide human-readable descriptions instead of a
   cryptic ups@hostname string.

4.2.4.6.  GET VAR

   Retrieve the value of a UPS variable.  See Section 2.11.

   Command: GET VAR <upsname> <varname>

   Response: VAR <upsname> <varname> "<value>"

   For example command GET VAR su700 ups.status and response VAR su700
   ups.status "OB LB"

4.2.5.  HELP

   Return a list of the commands supported by the Attachment Daemon.
   This command is intended for human as well as program use.

   Command HELP

   For example, the following command line sequence executed on an
   Attachment Daemon:

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

   ABNF: See variable help in Figure 5.

   Note: Historically, this command also returned LOGIN and LOGOUT.
   Since LOGIN was not the conventional user access to a shell or
   program, the command names were changed to ATTACH and DETACH to avoid
   confusion.

4.2.6.  INSTCMD

   Send an Instant Command to the UPS.

   Command: INSTCMD <upsname> <cmdname>

   where <upsname> is the name of the UPS and <cmdname> is the Instant
   Command to be issued to that UPS.  See Appendix A.3 for examples of
   instant commands.

Price                    Expires 13 October 2022               [Page 17]
Internet-Draft           UPS management protocol              April 2022

   If the command succeeds, the response is OK, otherwise see the error
   responses, Section 4.3.2.

   For example the command: INSTCMD su700 test.panel.start and the
   response OK

   ABNF: See variable instcmd in Figure 5.

4.2.7.  LIST

   All the LIST commands produce a response with a common format.  The
   response will begin with BEGIN LIST and then repeat the initial
   query.  A list then follows, with as many lines as are necessary.
   The response ends with END LIST followed by the initial query.

   The formatting may seem a bit redundant, but it makes a different
   form of client possible.  A client can send a LIST command and then
   wait for the response.  When it arrives, the Management Daemon
   doesn't need a complicated state machine to remember which list is
   which.

   Note: The current NUT Project implementation of the Attachment
   Daemon, upsd, sends back the response to the LIST command as a
   sequence of messages.  The Management Daemon should continue reading
   these messages until it receives the line beginning END LIST.

   ABNF: See variable list in Figure 5.

   The possible subcommands are:

4.2.7.1.  LIST CLIENT

   The command calls for the Attachment Daemon to report all the current
   Management Daemon clients of a given UPS.

   Command: LIST CLIENT <upsname>

   The response is

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

   For example, the command LIST CLIENT ups1 and the response:

Price                    Expires 13 October 2022               [Page 18]
Internet-Draft           UPS management protocol              April 2022

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

4.2.7.2.  LIST CMD

   The command calls for the Attachment Daemon to report a list of the
   Instant Commands which the Management Daemon may send to the
   Attachment Daemon.  This Instant Command list is the abstracted view
   of the UPS hardware capabilities.  An economical UPS will support few
   or no Instant Commands but a professional model should support more.

   Command: LIST CMD <upsname>

   The response is:

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

   where <upsname> is the name of the UPS, and <cmdname> is the name of
   the Instant Command which may be issued to the UPS.

   For example the command: LIST CMD su700 and the response:

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

4.2.7.3.  LIST ENUM

   The command calls for the Attachment Daemon to report the set of
   possible values of a UPS variable which has predetermined values.

   Command: LIST ENUM <upsname> <varname>

   The response is:

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

Price                    Expires 13 October 2022               [Page 19]
Internet-Draft           UPS management protocol              April 2022

   where <upsname> is the name of the UPS, <varname> is the UPS variable
   and <value> is one of the possible values of that UPS variable.  Note
   that in current practice the output is an unordered list.  Note also
   that the U+0022 QUOTATION MARK characters are part of the response.

   For example the command: LIST ENUM su700 input.transfer.low and the
   response:

   BEGIN LIST ENUM su700 input.transfer.low
   ENUM su700 input.transfer.low "103"
   ENUM su700 input.transfer.low "100"
   ...
   END LIST ENUM su700 input.transfer.low

4.2.7.4.  LIST RANGE

   The command calls for the Attachment Daemon to report the interval in
   which valid values of UPS variable lie.

   Command: LIST RANGE <upsname> <varname>

   The response is:

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

   where <upsname> is the name of the UPS, <varname> is the UPS variable
   and {<min>,<max>} is the interval of valid values of that UPS
   variable.  Note that the U+0022 QUOTATION MARK characters are part of
   the response.

   For example, the command LIST RANGE su700 input.transfer.low and the
   response:

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

4.2.7.5.  LIST RW

   The command calls for the Attachment Daemon to report a list of the
   UPS variables associated with a given UPS which may be read and
   written by the Management Daemon.  These variables are the abstracted
   view of the UPS hardware capabilities.  An economical UPS may support
   few variables but a professional model should support at least the
   variables which are needed for an automatic shutdown and restart, see

Price                    Expires 13 October 2022               [Page 20]
Internet-Draft           UPS management protocol              April 2022

   Appendix B.  See also Section 8.2 for details of the recommended
   minimum support of variables.  A full list of variables is available
   in source code file docs/nut-names.txt [gitvars] which serves as the
   Recording Document.

   Command: LIST RW <upsname>

   The response is:

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

   where <upsname> is the name of the UPS, <varname> is the UPS variable
   and <value> is the value of that UPS variable.  Note that the U+0022
   QUOTATION MARK characters are part of the response.

   For example the command: LIST RW su700 and the response:

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

4.2.7.6.  LIST UPS

   The command calls for the Attachment Daemon to report a list of the
   UPS units to which it is attached.

   Command: LIST UPS

   The response is:

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

   where <upsname> is the name of a UPS, and <description> is the
   description maintained by the Attachment Daemon if available.  It is
   set to "Unavailable" otherwise.  Note that the U+0022 QUOTATION MARK
   characters are part of the response.

Price                    Expires 13 October 2022               [Page 21]
Internet-Draft           UPS management protocol              April 2022

   This command can also be used to determine what values of <upsname>
   are valid before calling other functions on the server.  This is also
   a good way to handle situations where a single Attachment Daemon
   supports multiple UPS's.  It is also useful for clients which perform
   a UPS discovery process.

   For example, the response:

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

4.2.7.7.  LIST VAR

   The command calls for the Attachment Daemon to report a list of all
   the UPS variables which it maintains for a given UPS, and the values
   of those UPS variables.

   Command: LIST VAR <upsname>

   The response is:

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

   where <upsname> is the name of the UPS, <varname> is the UPS variable
   and <value> is the value of that variable.  Note that the U+0022
   QUOTATION MARK characters are part of the response.

   The response to this command lists the UPS variables available for
   this UPS and their current values.  For example the command LIST VAR
   su700 and the response:

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

   See Section 8.2 for details of the recommended minimum support of
   variables.  A full list of variables is available in source code file
   docs/nut-names.txt [gitvars] which serves as the Recording Document.

Price                    Expires 13 October 2022               [Page 22]
Internet-Draft           UPS management protocol              April 2022

4.2.8.  PASSWORD

   This command is a companion to USERNAME, and is used by a Management
   Daemon to specify the password required to enter a Session with the
   Attachment Daemon, see Section 2.9.

   Command: PASSWORD <password>

   If the command succeeds, the response is OK, otherwise see the error
   responses, Section 4.3.2.

   For examples of the use of commands USERNAME and PASSWORD by
   administrative users, see Appendix E.2.

   ABNF: See variable password in Figure 5.

4.2.9.  PRIMARY

   In current practice, the Attachment Daemon records in local file
   upsd.users that an administrative user is a Primary.  See
   Appendix E.1 for an example.  When a Management Daemon starts up and
   opens a Session with the Attachment Daemon, it lays claim to being a
   Primary by sending command PRIMARY to the Attachment Daemon, thus
   claiming that it has the required authority to perform such critical
   actions as setting status symbol FSD.

   Command: PRIMARY <upsname>

   where <upsname> is the name of the UPS.

   If the Attachment Daemon has the authority, the response is OK,
   otherwise see the error responses in Section 4.3.2.

   Note: Historically, this command was known as MASTER.

4.2.10.  PROTVER

   Return the implementation version of the command/response protocol
   used by the Attachment Daemon.  This command is intended for human as
   well as program use.

   Command PROTVER

   For example, the following command line sequence in the Attachment
   Daemon:

Price                    Expires 13 October 2022               [Page 23]
Internet-Draft           UPS management protocol              April 2022

   netcat localhost 3493
   PROTVER
   1.3

   Notes:

   1.  There are no U+0022 QUOTATION MARK characters in the response.
   2.  Historically, this command was known as NETVER and current
       practice is to use NETVER instead of PROTVER.
   3.  The implementation version of the protocol returned by PROTVER is
       different to the implementation version of the Attachment Daemon
       returned by VER.
   4.  The protocol version 1.3 requires support of the commands used in
       previous protocol version 1.2 as aliases.

   ABNF: See variable protver in Figure 5.

4.2.11.  SET

   The command calls for the Attachment Daemon to set a UPS variable to
   a given value.  Whether this has an effect on the UPS hardware is
   specific to the Driver and the UPS model.  Some variables are read-
   only due to the design of the UPS or its driver.

   Command: SET VAR <upsname> <varname> "<value>"

   where <upsname> is the name of the UPS, <varname> is the UPS variable
   and <value> is the value to be assigned to that variable.  Note that
   the U+0022 QUOTATION MARK characters are part of the command.

   If the command succeeds, the response is OK, otherwise see the error
   responses in Section 4.3.2.

   For example the command: SET VAR su700 ups.id "My UPS" and the
   response OK

   ABNF: See variable set in Figure 5.

4.2.12.  STARTTLS

   The client tells the Attachment Daemon to switch to TLS [RFC8446]
   encrypted communication.  When the client receives OK it also
   switches to TLS encryption.

   Command: STARTTLS

   If the command succeeds, the response is OK STARTTLS, otherwise see
   the error responses in Section 4.3.2.

Price                    Expires 13 October 2022               [Page 24]
Internet-Draft           UPS management protocol              April 2022

   If the client does not send command STARTTLS to the Attachment Daemon
   communication continues unencrypted, however an Attachment Daemon MAY
   refuse unencrypted communication.

   NUT 2.8.0 supports the encryption of communications between the
   Attachment Daemon and the Management Daemon using TLS 1.3 [RFC8446]
   with X.509 v3 certificates as defined by [RFC5280] and updates.  See
   Appendix D for details of the encryption of communications in
   previous relase 2.7.4.

   ABNF: See variable starttls in Figure 5.

4.2.12.1.  Key Infrastructure and Self-signed Certificates

   _The very restricted nature of UPS management makes it of interest to
   consider self-signed certificates._

   In the World Wide Web, there are millions of servers and hundreds of
   millions of potential clients for each one.  The servers do not know
   who their clients will be, so they entrust the management of a Public
   Key Infrastructure (PKI) to Certificate Authorities that they trust,
   for some value of trust.  The encryption of communications between
   client and server requires that the browsers carry a list of
   Certificate Authorities which the clients have to trust.  _This is a
   many-to-many relationship._

   The management of UPS units is not a many-to-many relationship, it is
   frequently one-to-one.  In the closely restrained world of UPS
   management, there are a very limited number of clients for each
   server, rarely more than three, and unlike the World Wide Web the
   server administrators know exactly who they are.  These clients visit
   very few servers, typically one only.  This situation is totally
   different to the World Wide Web.  The use of external Certificate
   Authorities is a potential security weakness that must be accepted
   for the World Wide Web, but which can be avoided for UPS management
   by either generating locally the private and public keys, or for
   larger organisations, using a Private Key Infrastructure..

   The security policies for UPS management may be subordinate to an
   organisation's own internal IT security plans and procedures,
   possibly based on [RFC7030] and [RFC8894], but in simple cases it is
   possible to obtain better security using self-signed certificates.

Price                    Expires 13 October 2022               [Page 25]
Internet-Draft           UPS management protocol              April 2022

4.2.13.  USERNAME

   The Attachment Daemon limits access to clients whose credentials
   match those in the file upsd.users.  There is no anonymous access.  A
   Management Daemon program or script uses command USERNAME and its
   companion command PASSWORD to open a Session with the Attachment
   Daemon for an administrative user, Note that this command is for
   program or script use and is not the familiar login command typed on
   a command line to gain access to a shell.

   Command: USERNAME <username>

   If the command succeeds, the response is OK, otherwise see the error
   responses in Section 4.3.2.

   For examples of the use of commands USERNAME and PASSWORD by
   administrative users, see Appendix E.2.

   ABNF: See variable username in Figure 5.

4.2.14.  VER

   Return the implementation version of the Attachment Daemon.  This
   command is intended for human as well as program use.

   Command VER

   For example, the following command line sequence:

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

   Notes:

   1.  There are no U+0022 QUOTATION MARK characters in the response.
   2.  The implementation version of the Attachment Daemon returned by
       VER is different to the protocol version returned by PROTVER.

   ABNF: See variable ver in Figure 5.

4.3.  Summary of Responses

4.3.1.  Response when Command Succeeds

   If the command succeeds, the response has the following command-
   dependent form:

Price                    Expires 13 October 2022               [Page 26]
Internet-Draft           UPS management protocol              April 2022

     +==========+======================+============+================+
     | Command  | Response             | Note       | Reference      |
     +==========+======================+============+================+
     | ATTACH   | OK                   | Was LOGIN  | Section 4.2.1  |
     +----------+----------------------+------------+----------------+
     | DETACH   | OK Goodbye           | Was LOGOUT | Section 4.2.2  |
     +----------+----------------------+------------+----------------+
     | FSD      | OK FSD-SET           |            | Section 4.2.3  |
     +----------+----------------------+------------+----------------+
     | GET      | Sub command specific |            | Section 4.2.4  |
     +----------+----------------------+------------+----------------+
     | HELP     | List of commands     |            | Section 4.2.5  |
     +----------+----------------------+------------+----------------+
     | INSTCMD  | OK                   |            | Section 4.2.6  |
     +----------+----------------------+------------+----------------+
     | LIST     | Sub command specific |            | Section 4.2.7  |
     +----------+----------------------+------------+----------------+
     | PASSWORD | OK                   |            | Section 4.2.8  |
     +----------+----------------------+------------+----------------+
     | PRIMARY  | OK                   |            | Section 4.2.9  |
     +----------+----------------------+------------+----------------+
     | PROTVER  | Protocol version     | Was NETVER | Section 4.2.10 |
     +----------+----------------------+------------+----------------+
     | SET      | OK                   |            | Section 4.2.11 |
     +----------+----------------------+------------+----------------+
     | STARTTLS | OK STARTTLS          |            | Section 4.2.12 |
     +----------+----------------------+------------+----------------+
     | USERNAME | OK                   |            | Section 4.2.13 |
     +----------+----------------------+------------+----------------+
     | VER      | Program version      |            | Section 4.2.14 |
     +----------+----------------------+------------+----------------+

                   Table 2: Response if command succeeds

4.3.2.  Error Responses

   Error responses have the following format:

   ERR <error-name> [<extra>]

   where <error-name> is a single word token taken from the 27
   characters A-Z and U+002D HYPHEN-MINUS.  Implementations MAY if
   needed add an additional optional <extra>.  Current practice does not
   make use of this possibility.

   The <error-name> may have one of the following values:

Price                    Expires 13 October 2022               [Page 27]
Internet-Draft           UPS management protocol              April 2022

    +==============================+==================================+
    |   The error name token       |             Meaning              |
    |         <error-name>         |                                  |
    +==============================+==================================+
    | ACCESS-DENIED                | The client's host and/or         |
    |                              | authentication details supplied  |
    |                              | by USERNAME and PASSWORD are not |
    |                              | sufficient to execute the        |
    |                              | requested command.               |
    +------------------------------+----------------------------------+
    | ALREADY-ATTACHED             | The client has already sent a    |
    |                              | successful ATTACH command for a  |
    |                              | given UPS and can't do it again. |
    |                              |                                  |
    |                              | Note: Historically, this error   |
    |                              | response was ALREADY-LOGGED-IN.  |
    +------------------------------+----------------------------------+
    | ALREADY-SET-PASSWORD         | The client has already supplied  |
    |                              | a PASSWORD and is attempting to  |
    |                              | repeat the command in the same   |
    |                              | Session.                         |
    +------------------------------+----------------------------------+
    | ALREADY-SET-USERNAME         | The client has already supplied  |
    |                              | a USERNAME, and is attempting to |
    |                              | repeat the command within the    |
    |                              | same Session.                    |
    +------------------------------+----------------------------------+
    | CMD-NOT-SUPPORTED            | The specified UPS doesn't        |
    |                              | support the Instant Command.     |
    +------------------------------+----------------------------------+
    | DATA-STALE                   | The Attachment Daemon is         |
    |                              | connected to the Driver for the  |
    |                              | UPS, but that driver isn't       |
    |                              | providing regular updates or has |
    |                              | specifically marked the data as  |
    |                              | stale.  Current practice is for  |
    |                              | the Attachment Daemon to refuse  |
    |                              | to provide the Management Daemon |
    |                              | with variables on stale units to |
    |                              | avoid false readings.            |
    |                              |                                  |
    |                              | This generally means that the    |
    |                              | Driver is running, but it has    |
    |                              | lost communication with the      |
    |                              | hardware.  Check the physical    |
    |                              | connection to the equipment.     |
    +------------------------------+----------------------------------+
    | DRIVER-NOT-CONNECTED         | The Attachment Daemon can't      |

Price                    Expires 13 October 2022               [Page 28]
Internet-Draft           UPS management protocol              April 2022

    |                              | perform the requested command,   |
    |                              | since the Driver for that UPS is |
    |                              | not connected.  This usually     |
    |                              | means that the driver is not     |
    |                              | running, or if it is, is         |
    |                              | misconfigured.                   |
    +------------------------------+----------------------------------+
    | FEATURE-NOT-CONFIGURED       | This instance of the Attachment  |
    |                              | Daemon hasn't been configured    |
    |                              | properly to allow the requested  |
    |                              | feature to operate.  In current  |
    |                              | practice this error response is  |
    |                              | possible only for command        |
    |                              | STARTTLS.                        |
    +------------------------------+----------------------------------+
    | FEATURE-NOT-SUPPORTED        | This instance of Attachment      |
    |                              | Daemon does not support the      |
    |                              | requested feature.  In current   |
    |                              | practice this error response is  |
    |                              | possible only for command        |
    |                              | STARTTLS.                        |
    +------------------------------+----------------------------------+
    | INSTCMD-FAILED               | The Attachment Daemon failed to  |
    |                              | deliver the Instant Command      |
    |                              | request to the Driver.  No       |
    |                              | further information is available |
    |                              | to the client.  This typically   |
    |                              | indicates a dead or broken       |
    |                              | driver.                          |
    +------------------------------+----------------------------------+
    | INVALID-ARGUMENT             | The client sent an argument to a |
    |                              | command which is not recognized  |
    |                              | or is otherwise not valid in     |
    |                              | this context.  This is typically |
    |                              | caused by sending a valid        |
    |                              | command such as GET with a       |
    |                              | subcommand which is not valid.   |
    +------------------------------+----------------------------------+
    | INVALID-PASSWORD             | The client sent a non valid      |
    |                              | PASSWORD.                        |
    +------------------------------+----------------------------------+
    | INVALID-USERNAME             | The client sent an non valid     |
    |                              | USERNAME.                        |
    +------------------------------+----------------------------------+
    | INVALID-VALUE                | The value specified in the       |
    |                              | request is not valid.  This      |
    |                              | usually applies to a SET of an   |
    |                              | ENUM type which is using a value |

Price                    Expires 13 October 2022               [Page 29]
Internet-Draft           UPS management protocol              April 2022

    |                              | not in the list of allowed       |
    |                              | values.  See Section 4.2.7.3.    |
    +------------------------------+----------------------------------+
    | PASSWORD-REQUIRED            | The command requires a PASSWORD  |
    |                              | for authentication, but the      |
    |                              | client hasn't provided one.      |
    +------------------------------+----------------------------------+
    | READONLY                     | The requested variable in a SET  |
    |                              | command is not writable.         |
    +------------------------------+----------------------------------+
    | SET-FAILED                   | The Attachment Daemon failed to  |
    |                              | deliver the SET request to the   |
    |                              | Driver.  This is similar to      |
    |                              | INSTCMD-FAILED.                  |
    +------------------------------+----------------------------------+
    | TLS-ALREADY-ENABLED          | TLS mode is already enabled on   |
    |                              | this connection, so the          |
    |                              | Attachment Daemon can't start it |
    |                              | again.                           |
    |                              |                                  |
    |                              | Note: Historically, this message |
    |                              | was ALREADY-SSL-MODE.            |
    +------------------------------+----------------------------------+
    | TLS-NOT-ENABLED              | TLS mode is required but has not |
    |                              | yet been enabled on this         |
    |                              | connection, so the Attachment    |
    |                              | Daemon can't send commands.      |
    |                              |                                  |
    |                              | Note: This message is            |
    |                              | experimental and not in current  |
    |                              | common use.                      |
    +------------------------------+----------------------------------+
    | TOO-LONG                     | The requested value in a SET     |
    |                              | command is too long.             |
    +------------------------------+----------------------------------+
    | UNKNOWN-COMMAND              | The Attachment Daemon doesn't    |
    |                              | recognize the command.           |
    +------------------------------+----------------------------------+
    | UNKNOWN-UPS                  | The UPS specified in the request |
    |                              | is not known to the Attachment   |
    |                              | Daemon.  This usually means that |
    |                              | it didn't match anything in the  |
    |                              | Attachment Daemon configuration. |
    +------------------------------+----------------------------------+
    | USERNAME-REQUIRED            | The command requires a USERNAME  |
    |                              | for authentication, but the      |
    |                              | client hasn't provided one.      |
    +------------------------------+----------------------------------+

Price                    Expires 13 October 2022               [Page 30]
Internet-Draft           UPS management protocol              April 2022

    | VAR-NOT-SUPPORTED            | The specified UPS doesn't        |
    |                              | support the UPS variable in the  |
    |                              | command.                         |
    +------------------------------+----------------------------------+

                          Table 3: Error responses

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.

   Current practice tolerates mixed case command names, but it is
   RECOMMENDED to use upper case only for commands.  See Figure 5.

      |  _Implementation note:_ The ABNF is written using the provisions
      |  of [RFC5234] [RFC7405] which are US-ASCII based.  Implementors
      |  should be aware that NUT itself is Unicode based and that where
      |  the grammar specifies ALPHA = %x41-5A / %x61-7A ; A-Z / a-z an
      |  implementation should expect letters outside the range
      |  specified by ALPHA.

   ;-------------------------------------------------------------------
   ; The following basic rules written with upper case names are
   ; taken from RFC5234 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

Price                    Expires 13 October 2022               [Page 31]
Internet-Draft           UPS management protocol              April 2022

      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  = %s"ATTACH" SP upsname
   ;
      detach = %s"DETACH"
   ;
      fsd = %s"FSD" SP upsname
   ;
      get = %s"GET" SP getsubcommnd
      getsubcommand = getcmddesc / getdesc / getnumattach /
                      gettype / getupsdesc / getvar
   ;
      getcmddesc =   %s"CMDDESC" SP upsname SP cmdname
      getdesc =      %s"DESC" SP upsname SP varname
      getnumattach = %s"NUMATTACH" SP upsname
      gettype =      %s"TYPE" SP upsname SP varname
      getupsdesc =   %s"UPSDESC" SP upsname
      getvar =       %s"VAR" SP upsname SP varname
   ;
      help = %s"HELP"
   ;
      instcmd = %s"INSTCMD" SP upsname SP cmdname
   ;
      list = %s"LIST" listsubcommand
      listsubcommand = listclient / listcmd / listenum / listrange /
                       listrw / listups / listvar
   ;
      listclient = %s"CLIENT" SP upsname
      listcmd =    %s"CMD" SP upsname
      listenum =   %s"ENUM" SP upsname SP varname
      listrange =  %s"RANGE" SP upsname SP varname
      listrw =     %s"RW" SP upsname
      listups =    %s"UPS"
      listvar =    %s"VAR" SP upsname
   ;

Price                    Expires 13 October 2022               [Page 32]
Internet-Draft           UPS management protocol              April 2022

      password = %s"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 = %s"PRIMARY" SP upsname
   ;
      protver = %s"PROTVER"
   ;
      value = *63VCHAR             ; Local practices may limit the choice of
                                   ; characters, and require non US-ASCII.
      set = %s"SET" SP %s"VAR" SP upsname SP varname SP DQUOTE value DQUOTE
   ;
      starttls = "STARTTLS"
   ;
      username = %s"USERNAME" SP username
   ;
      ver = "VER"
   ;-------------------------------------------------------------------

                      Figure 5: ABNF for the Commands

   Notes:

   1.  %s means "case sensitive".  The terminal must be written as
       specified.

   2.  The repetition factor in front of an expression has the form
       <min>*<max> where <min> is the minimum number of repetitions and
       <max> is the maximum number.

   3.  If <min> is omitted its value is 0.  If <max> is omitted, its
       value is infinity.

   4.  The notation n*n meaning "exactly n copies" may be written as n.

   5.  Square brackets around an expression mean that the expression is
       optional.  This could be written as 0*1.

4.4.1.  Responses to Commands

   The responses to the commands fall into two groups:

   1.  Short replies to action commands, see Section 4.3.

Price                    Expires 13 October 2022               [Page 33]
Internet-Draft           UPS management protocol              April 2022

   2.  Long replies to requests for information.  In this case the reply
       is sent in a sequence of messages.  The last message will contain
       a line beginning END LIST .  See for example Section 4.2.7.1.

5.  Statuses and Events

5.1.  Status Symbols

   These symbols resume the abstracted view of the UPS hardware
   maintained by the Attachment Daemon.  The variable ups.status
   contains one or more space-separated status symbols which together
   describe the UPS state at that instant.  In current practice the
   Management Daemon will poll variable ups.status every 5 seconds with
   a command such as GET VAR su700 ups.status and response such as VAR
   su700 ups.status "OB LB" to discover changes in the UPS status.
   These changes will indicate UPS events.

    +=========+======================================================+
    |  Status |                       Meaning                        |
    |  Symbol |                                                      |
    +=========+======================================================+
    | ALARM   | The UPS reports that it requires intervention.       |
    +---------+------------------------------------------------------+
    | BOOST   | The UPS has determined that the voltage level of the |
    |         | public power supply is too low, and is boosting it   |
    |         | to the required level.  The UPS continues to supply  |
    |         | the protected system from the public power supply.   |
    +---------+------------------------------------------------------+
    | BYPASS  | The UPS is feeding current directly from the public  |
    |         | power supply to the protected system.  The backup    |
    |         | facilities are disconnected.  This state allows      |
    |         | maintenance personnel to change the batteries        |
    |         | without interrupting the protected system.           |
    +---------+------------------------------------------------------+
    | CAL     | The UPS is calibrating itself, for example to        |
    |         | determine at what charge the LB status is raised or  |
    |         | lowered.                                             |
    +---------+------------------------------------------------------+
    | CHRG    | The UPS battery is charging.  This usually implies   |
    |         | that the UPS also has status OL, but may not be the  |
    |         | case if the UPS also has status OFF.                 |
    +---------+------------------------------------------------------+
    | COMM    | The Attachment Daemon has effective contact with the |
    |         | UPS.                                                 |
    +---------+------------------------------------------------------+
    | DISCHRG | The UPS battery is discharging.  This usually        |
    |         | implies that the UPS also has status OB, but may not |
    |         | be the case if the UPS also has status OFF.          |

Price                    Expires 13 October 2022               [Page 34]
Internet-Draft           UPS management protocol              April 2022

    +---------+------------------------------------------------------+
    | FSD     | This "Forced Shutdown" status signals that the final |
    |         | shutdown sequence has begun.                         |
    +---------+------------------------------------------------------+
    | LB      | Low Battery.  The battery level of the UPS is below  |
    |         | a chosen limit.  The UPS may be in status OL or OB.  |
    +---------+------------------------------------------------------+
    | NOCOMM  | The Attachment Daemon has no effective contact with  |
    |         | the UPS.                                             |
    +---------+------------------------------------------------------+
    | OB      | On Battery.  The UPS is taking energy from it's      |
    |         | battery.  The battery is discharging.  A UPS must    |
    |         | have status OB or OL, otherwise it is deemed dead.   |
    +---------+------------------------------------------------------+
    | OFF     | The UPS is in state "Off".  It does not react to     |
    |         | failure in the public power supply.  The exact       |
    |         | meaning depends on the model.                        |
    +---------+------------------------------------------------------+
    | OL      | Online.  The UPS is online, receiving energy from    |
    |         | the public power supply.  The battery is charging.   |
    |         | A UPS must have status OB or OL, otherwise it is     |
    |         | deemed dead.                                         |
    +---------+------------------------------------------------------+
    | OVER    | Overloaded.  The UPS reports that the load on it is  |
    |         | beyond it's normal operating maximum.                |
    +---------+------------------------------------------------------+
    | RB      | Replace battery.  The UPS reports that it's battery/ |
    |         | batteries should be replaced.                        |
    +---------+------------------------------------------------------+
    | TEST    | Under test.  The UPS is currently undergoing a test, |
    |         | which may have been called for manually or           |
    |         | internally.                                          |
    +---------+------------------------------------------------------+
    | TICK    | Heartbeat.  A software UPS in the Attachment Daemon  |
    |         | provides a regular signal monitored by the           |
    |         | Management Daemon as a way of verifying effective    |
    |         | end-to-end management.  TICK and TOCK are            |
    |         | companions, they are considered experimental.        |
    +---------+------------------------------------------------------+
    | TOCK    | Heartbeat.  See TICK                                 |
    +---------+------------------------------------------------------+
    | TRIM    | The UPS has determined that the voltage level of the |
    |         | public power supply is too high, and is reducing it  |
    |         | to the required level.  The UPS continues to supply  |
    |         | the protected system from the public power supply.   |
    +---------+------------------------------------------------------+

                       Table 4: UPS Status Symbols

Price                    Expires 13 October 2022               [Page 35]
Internet-Draft           UPS management protocol              April 2022

5.2.  Events

   A Management Daemon detects the occurrence of a UPS Event from a
   change in the UPS status received from the Attachment Daemon.  The
   following table summarizes the process.  A status of "none" means
   that the status symbol is not present in the variable ups.status.

   The Management Daemon should retrieve the variable ups.status from
   the Attachment Daemon at regular intervals.  If the interval is too
   short, compute and network resources will be wasted, but if the
   interval is too large, the Management Daemon risks missing short-
   lived changes in the UPS status.

   A default value of 5 seconds is RECOMMENDED, but an implementation
   MAY make this value configurable.  By default the "old" status is
   therefore the previous value retrieved 5 seconds ago.

   Current practice is for the Management Daemon to assign names to
   certain events.  These is shown in the table in parentheses.

   +=======+=========+===============++=========+========+=============+
   |Old    | New     |Event          || Old     | New    |Event        |
   |status | status  |               || status  | status |             |
   +=======+=========+===============++=========+========+=============+
   |none   | ALARM   |Alarm on       || ALARM   | none   |Alarm off    |
   +-------+---------+---------------++---------+--------+-------------+
   |none   | BOOST   |Boosting       || BOOST   | none   |Not boosting |
   |       |         |voltage        ||         |        |             |
   +-------+---------+---------------++---------+--------+-------------+
   |none   | BYPASS  |Bypass on      || BYPASS  | none   |Bypass off   |
   +-------+---------+---------------++---------+--------+-------------+
   |none   | CAL     |Calibrating    || CAL     | none   |Not          |
   |       |         |               ||         |        |calibrating  |
   +-------+---------+---------------++---------+--------+-------------+
   |none   | CHRG    |Charging       || CHRG    | none   |Not charging |
   +-------+---------+---------------++---------+--------+-------------+
   |none   | COMM    |UPS            || COMM    | none   |See note 4   |
   |       |         |communicating  ||         |        |             |
   |       |         |(Event COMMOK) ||         |        |             |
   +-------+---------+---------------++---------+--------+-------------+
   |none   | DISCHRG |Discharging    || DISCHRG | none   |Not          |
   |       |         |               ||         |        |discharging  |
   +-------+---------+---------------++---------+--------+-------------+
   |none   | FSD     |System shutdown|| FSD     | none   |Shutdown     |
   |       |         |(Events FSD,   ||         |        |abandoned.   |
   |       |         |SHUTDOWN)      ||         |        |See note 1   |
   +-------+---------+---------------++---------+--------+-------------+
   |none   | LB      |Low battery.   || LB      | none   |Battery not  |

Price                    Expires 13 October 2022               [Page 36]
Internet-Draft           UPS management protocol              April 2022

   |       |         |See note 2     ||         |        |low          |
   |       |         |(Event LOWBATT)||         |        |             |
   +-------+---------+---------------++---------+--------+-------------+
   |none   | NOCOMM  |UPS dead?  See || NOCOMM  | none   |See note 4   |
   |       |         |note 4         ||         |        |             |
   |       |         |(Events        ||         |        |             |
   |       |         |COMMBAD,       ||         |        |             |
   |       |         |NOCOMM)        ||         |        |             |
   +-------+---------+---------------++---------+--------+-------------+
   |none   | OFF     |UPS turned off || OFF     | none   |UPS not      |
   |       |         |               ||         |        |turned off   |
   +-------+---------+---------------++---------+--------+-------------+
   |OB     | OL      |Receiving power|| OL      | OB     |Power lost   |
   |       |         |(Event ONLINE) ||         |        |(Event       |
   |       |         |               ||         |        |ONBATT)      |
   +-------+---------+---------------++---------+--------+-------------+
   |none   | OVER    |UPS overloaded || OVER    | none   |Overload gone|
   +-------+---------+---------------++---------+--------+-------------+
   |none   | RB      |Replace battery|| RB      | none   |Replacement  |
   |       |         |(Event         ||         |        |canceled     |
   |       |         |REPLBATT)      ||         |        |             |
   +-------+---------+---------------++---------+--------+-------------+
   |none   | TEST    |Test starts    || TEST    | none   |Test finished|
   +-------+---------+---------------++---------+--------+-------------+
   |none   | TICK    |Heartbeat      || TICK    | none   |No heartbeat.|
   |       |         |event.  See    ||         |        |See note 3   |
   |       |         |note 3         ||         |        |             |
   +-------+---------+---------------++---------+--------+-------------+
   |none   | TOCK    |Heartbeat      || TOCK    | none   |No heartbeat.|
   |       |         |event.  See    ||         |        |See note 3   |
   |       |         |note 3         ||         |        |             |
   +-------+---------+---------------++---------+--------+-------------+
   |none   | TRIM    |Trimming       || TRIM    | none   |Not trimming |
   |       |         |voltage        ||         |        |             |
   +-------+---------+---------------++---------+--------+-------------+

                Table 5: Event deduction from status changes

   Notes

   1.  Current practice does not include this event.
   2.  If the status OB is present, current practice takes Management
       Daemon reception of LB as an order to perform an emergency system
       shutdown.
   3.  The use of a software defined UPS to provide a heartbeat is
       experimental and is not part of common current practice.

Price                    Expires 13 October 2022               [Page 37]
Internet-Draft           UPS management protocol              April 2022

   4.  Current practice is: if the UPS has not responded for 15 seconds,
       the Management Daemon assumes that the UPS is "_dead_" (Event
       NOCOMM), and if the last known OL/OB status was OB a system
       shutdown, command FSD, is called for.

6.  Security Considerations

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 activity, part of site mangement.  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

                Figure 6: Common single-system configuration

   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

             Figure 7: Integration of UPS and Attachment Daemon

Price                    Expires 13 October 2022               [Page 38]
Internet-Draft           UPS management protocol              April 2022

   These security issues raised by UPS management are those of the power
   industry in general: they are addressed in detail in IEC Technical
   Specification [IEC62351-1].  In addition to equipment security, cyber
   security is now an essential consideration.

   Quoting from IEC [IEC62351-1] clause 5.2.3.5:

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

   In IEC [IEC62351-1] clause 5.3.5 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:

Price                    Expires 13 October 2022               [Page 39]
Internet-Draft           UPS management protocol              April 2022

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

   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.2.1.  Certificate security

   In long-lived installations such as those found in UPS management,
   careful certificate management is essential, whether the certificate
   is provided by a Certificate Authority, or is a self-signed
   certificate.  For example the specification of expiration times of
   both the certificate containing the public key and the signing
   certificate.

6.3.  Attacks and Defences

6.3.1.  Eavesdropping

   The defence against eavesdropping is encryption of the commands and
   responses passed between client Management Daemon and server
   Attachment Daemon.  The protocol provides command STARTTLS, see
   Section 4.2.12, which calls on the Attachment Daemon to support TLS
   encryption of the communication.  If this command is accepted, the
   Management Daemon also encrypts.

   In current NUT Project practice, the use of TLS is optional, however
   a Management Daemon may refuse to accept unencrypted communication.
   This is done by setting declarations FORCESSL to 1 and CERTVERIFY to
   1 in the Management Daemon configuration file.

Price                    Expires 13 October 2022               [Page 40]
Internet-Draft           UPS management protocol              April 2022

6.3.1.1.  Misplaced declarations requiring TLS

   A further weakness is that the FORCESSL and CERTVERIFY declarations
   which enforce use of encryption are in the client Management Daemon
   configuration file and not in the Attachment Daemon.  Secure practice
   requires enforcement by the server Attachment Daemon rather than a
   possibly rogue client Management Daemon out on the Internet.

   This weakness may be mitigated with strict firewall rules which would
   prevent the rogue client Management Daemon from accessing the
   Attachment Daemon.

6.3.1.2.  Weak protection in previous version 2.7.4

   Although version 2.8.0 of NUT supports TLS v.3 [RFC8446] with X.509
   v3 certificates as defined by RFC5280 [RFC5280], previous version
   2.7.4 only supported earlier SSL/TLS versions.  To overcome this
   weakness, The following techniques have been used:

   *  Shims, see Appendix D.1

   *  TLS tunnel, see Appendix D.2

   *  Virtual Private Network, VPN, see Appendix D.3

   *  Virtual Local Area network, VLAN, see Appendix D.4

6.3.2.  Man in the Middle

   The protocol relies on TLS encryption to prevent man-in-the-middle
   attacks.  See Appendix D for defense methods used for previous NUT
   version 2.7.4.

6.3.3.  Masquerade Attack: Agent Verification

   The protocol allows a Management Daemon to send command FSD to an
   Attachment Daemon to shut down a working system and it's power supply
   as described in The Shutdown Story, see Appendix B.  A malicious
   client acting as a Management Daemon could turn off the UPS power
   outlets causing the system to fail.

   The protocol provides commands USERNAME, see Section 4.2.13, and
   PASSWORD, see Section 4.2.8, which allow an administrative user in a
   Management Daemon to authenticate itself to the Attachment Daemon, as
   a defence against masquerade attacks.  The administrative user name
   and password need protection against local malicious users.  This is
   done by restricting access to the configuration files.

Price                    Expires 13 October 2022               [Page 41]
Internet-Draft           UPS management protocol              April 2022

6.3.4.  Message insertion, deletion, modification

   The protocol relies on TLS encryption to prevent message insertion,
   deletion and modification attacks.  See Appendix D for defense
   methods used for previous NUT version 2.7.4.

6.3.5.  Replay

   There are two cases:

   1.  The replay is from a system other than an approved Management
       Daemon: the protocol relies on a firewall to block the traffic.

   2.  The replay is from an approved Management Daemon: the protocol
       relies on the Management Daemon's own security to prevent
       unauthorised access.

6.3.6.  Denial of Service

   The protocol relies on a very tightly specified firewall to prevent
   denial of service attacks.  Only designated client Management Daemons
   should be able to reach the server Attachment Daemon.

7.  IANA Considerations

   The protocol specified by this text runs over port 3493/TCP (nut)
   assigned to the NUT project.

8.  Implementation Status

   This section presents a very short summary of the status of the
   Network UPS Tools project

   *  May 1996: The first hack as a cron job.
   *  September 1997: The first server-client code.
   *  March 1998: First public release.
   *  June 1999: Code rewrite with a UPS driver smartups, an Attachment
      Daemon upsd and a simple Management Daemon.
   *  September 1999: The project became "Network UPS Tools".  The
      Management Daemon upsmon supported primary/secondary
      configurations.
   *  June 2001: Common core for multiple drivers.
   *  May 2002: IANA granted port 3493/TCP (nut).  August: release
      1.0.0.  November: OpenSSL support.
   *  April 2003: The initial set of command and variable names was
      designed.
   *  February 2005: Arnaud Quette took over the project lead from
      Russell Kroll.

Price                    Expires 13 October 2022               [Page 42]
Internet-Draft           UPS management protocol              April 2022

   *  March 2016: Version 2.7.4 released, supported over 100 device
      manufacturers and hundreds of UPS models.
   *  November 2020: Evgeny "Jim" Klimov took over project lead from
      Arnaud Quette.
   *  March 2022: Version 2.8.0 released, supporting protocol version
      1.3.

   See [githist] and [History] for a detailed history of the NUT
   Project.

8.1.  Inclusion in Software Distributions

   The programs upsd, upsmon, upssched, upsc, upscmd and upsrw have been
   included in the package known as "nut" in the package systems of many
   distributions: all the major Linux distributions, and Unix
   distributions such as OpenBSD and OpenSolaris.  A Microsoft Windows
   version has been developed but was not maintained.

8.2.  Recommended Minimum Support

   The features provided by current UPS units vary 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.

8.2.1.  Desktop PC Variables

   The following variables form a minimum set suitable for Desktop PC.
   It is expected that on public power supply failure, the PC will be
   halted.  It will not restart automatically when power returns.

   *  battery.charge

   *  battery.charge.low

   *  device.mfr

   *  device.model

   *  ups.status with the minimum status symbol set OL OB LB FSD, see
      Section 5.1.

Price                    Expires 13 October 2022               [Page 43]
Internet-Draft           UPS management protocol              April 2022

8.2.2.  Unattended Servers, Additional Variables

   The following additional variables are needed in a minimum set
   suitable for an unattended server.  It is expected that on public
   power supply failure, the server will be halted.  It will restart
   automatically when power returns.

   *  battery.date

   *  device.serial

   *  ups.delay.shutdown

   *  ups.delay.start

8.2.3.  Commands and other Technical Terms

   Satisfactory use of the NUT Project software requires support for all
   the commands specified in protocol version 1.3, software version
   2.8.0.  The software should also support the technical terms used in
   protocol version 1.2, software version 2.7.4.  See Appendix C for the
   differences.

9.  Acknowledgments

   This document is based on the NUT Project documentation [devguide].
   The editor acknowledges the work of Charles Lepple, Arjen de Korte,
   Arnaud Quette, Jim Klimov, Russell Kroll, Manuel Wolfshant, Greg
   Troxel, Mark Hansen and many others who contribute to the nut-upsuser
   [nut-upsuser]. and nut-upsdev [nut-upsdev] mailing lists.

   The source for this document is marked up using an SGML DTD [SGML]
   and an XML meta-DTD as defined by HyTime Annex A [HyTimeA].  Unlike
   XML, SGML offers markup minimisation, and the source document takes
   advantage of this.  The osgmlnorm [sgmlnorm] program generates XML
   which program xml2rfc [RFC7991] uses to prepare the HTML and text
   renderings.  The editor acknowledges the help received from Carsten
   Bormann and Julian Reschke in the xml2rfc mailing list.

   Many helpful comments were received from Eliot Lear, Bart Smit, David
   Zomaya, Joyce Norris, and Ted Mittelstaedt.

10.  Normative References

Price                    Expires 13 October 2022               [Page 44]
Internet-Draft           UPS management protocol              April 2022

   [ISOIEC10646]
              "ISO/IEC 10646:2020 Information technology - Universal
              coded character set (UCS)", ISO/IEC Internatioanl Standard
              ISO/IEC 10646:2020(E), 2804 pages, CHF 195, Technical
              Committee JTC1/SC2 Coded character sets, December 2020.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/info/rfc2119>.

   [RFC5198]  Klensin, J. and M. Padlipsky, "Unicode Format for Network
              Interchange", RFC 5198, DOI 10.17487/RFC5198, March 2008,
              <https://www.rfc-editor.org/info/rfc5198>.

   [RFC5234]  Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
              Specifications: ABNF", STD 68, RFC 5234,
              DOI 10.17487/RFC5234, January 2008,
              <https://www.rfc-editor.org/info/rfc5234>.

   [RFC7405]  Kyzivat, P., "Case-Sensitive String Support in ABNF",
              RFC 7405, DOI 10.17487/RFC7405, December 2014,
              <https://www.rfc-editor.org/info/rfc7405>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/info/rfc8174>.

11.  Informative References

   [devguide] "Network UPS Tools (NUT) Project Developer Guide",
              <https://networkupstools.org/docs/developer-guide.chunked/
              ar01s09.html>.

   [Documentation]
              "Network UPS Tools Documentation",
              <https://networkupstools.org/documentation.html>.

   [githist]  "GitHub Network UPS Tools code repository, project
              history",
              <https://github.com/networkupstools/nut/blob/master/docs/
              history.txt>.

   [gitstats] "GitHub Network UPS Tools code repository, status names",
              <https://github.com/networkupstools/nut/blob/master/
              clients/status.h>.

Price                    Expires 13 October 2022               [Page 45]
Internet-Draft           UPS management protocol              April 2022

   [gitvars]  "GitHub Network UPS Tools code repository, variable
              names",
              <https://github.com/networkupstools/nut/blob/master/docs/
              nut-names.txt>.

   [History]  "Network UPS Tools User Manual, Appendix J Project
              history",
              <https://networkupstools.org/docs/user-manual.pdf>.

   [HyTimeA]  "International Standard ISO/IEC 10744 -- Hypermedia/Time-
              based Structuring Language, Annex A, SGML Extended
              Facilities", ISO/IEC JTC 1/SC 34 Document description and
              processing languages, 1997.

   [IEC62351-1]
              "IEC TS 62351-1 Power systems management and associated
              information exchange -- Data and communications security.
              Part 1: Communication network and system security --
              Introduction to security issues", IEC Technical
              Specification Reference number IEC/TS 62351-1:2007(E), 35
              pages, CHF 205, Technical Committee TC 57 - Power systems
              management and associated information exchange, 15 May
              2007, <https://nanopdf.com/download/technical-iec-
              specification-ts-62351-1_pdf>.

   [Library]  "GitHub Network UPS Tools, Devices Dumps Library",
              <https://networkupstools.org/ddl/>.

   [NUT]      "Network UPS Tools (NUT) Project",
              <https://www.networkupstools.org>.

   [nut-repository]
              "GitHub Repository for the Network UPS Tools (NUT)
              Project", <https://github.com/networkupstools/nut/>.

   [nut-upsdev]
              "Network UPS Tools (NUT) Project Mailing List for
              developers", <https://alioth-lists.debian.net/cgi-
              bin/mailman/listinfo/nut-upsdev>.

   [nut-upsuser]
              "Network UPS Tools (NUT) Project Mailing List for users",
              <https://alioth-lists.debian.net/cgi-bin/mailman/listinfo/
              nut-upsuser>.

Price                    Expires 13 October 2022               [Page 46]
Internet-Draft           UPS management protocol              April 2022

   [Registry] "Service Name and Transport Protocol Port Number
              Registry", Publisher: IANA,
              <https://www.iana.org/assignments/service-names-port-
              numbers/service-names-port-numbers.xhtml>.

   [RFC3552]  Rescorla, E. and B. Korver, "Guidelines for Writing RFC
              Text on Security Considerations", BCP 72, RFC 3552,
              DOI 10.17487/RFC3552, July 2003,
              <https://www.rfc-editor.org/info/rfc3552>.

   [RFC5280]  Cooper, D., Santesson, S., Farrell, S., Boeyen, S.,
              Housley, R., and W. Polk, "Internet X.509 Public Key
              Infrastructure Certificate and Certificate Revocation List
              (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008,
              <https://www.rfc-editor.org/info/rfc5280>.

   [RFC6335]  Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S.
              Cheshire, "Internet Assigned Numbers Authority (IANA)
              Procedures for the Management of the Service Name and
              Transport Protocol Port Number Registry", BCP 165,
              RFC 6335, DOI 10.17487/RFC6335, August 2011,
              <https://www.rfc-editor.org/info/rfc6335>.

   [RFC7030]  Pritikin, M., Ed., Yee, P., Ed., and D. Harkins, Ed.,
              "Enrollment over Secure Transport", RFC 7030,
              DOI 10.17487/RFC7030, October 2013,
              <https://www.rfc-editor.org/info/rfc7030>.

   [RFC7605]  Touch, J., "Recommendations on Using Assigned Transport
              Port Numbers", BCP 165, RFC 7605, DOI 10.17487/RFC7605,
              August 2015, <https://www.rfc-editor.org/info/rfc7605>.

   [RFC7942]  Sheffer, Y. and A. Farrel, "Improving Awareness of Running
              Code: The Implementation Status Section", BCP 205,
              RFC 7942, DOI 10.17487/RFC7942, July 2016,
              <https://www.rfc-editor.org/info/rfc7942>.

   [RFC7991]  Hoffman, P., "The "xml2rfc" Version 3 Vocabulary",
              RFC 7991, December 2016,
              <https://www.rfc-editor.org/info/rfc7991>.

   [RFC8446]  Rescorla, E., "The Transport Layer Security (TLS) Protocol
              Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
              <https://www.rfc-editor.org/info/rfc8446>.

   [RFC8894]  Gutmann, P., "Simple Certificate Enrolment Protocol",
              RFC 8894, DOI 10.17487/RFC8894, September 2020,
              <https://www.rfc-editor.org/info/rfc8894>.

Price                    Expires 13 October 2022               [Page 47]
Internet-Draft           UPS management protocol              April 2022

   [SGML]     Goldfarb, Charles F., "The SGML Handbook",
              ISBN 0-19-853737-9, 1990.

   [sgmlnorm] Clark, James., "SGMLNORM An SGML System Conforming to
              International Standard ISO 8879 -- Standard Generalized
              Markup Language", <http://www.jclark.com/sp/sgmlnorm.htm>.

   [stunnel]  Trojnara, Michal., "Stunnel proxy adds TLS encryption
              functionality to existing clients and servers",
              <https://www.stunnel.org/>.

Appendix A.  Variables

   The UPS variables represent the abstracted state of the UPS unit.
   Certain variables represent not only the state of some hardware
   feature, but also provide tunable values and instant commands, see
   Section 2.5.  The full set of variables is recorded in the reference
   document for variable names [gitvars].

   The number of variables used in a given deployment depends on the
   sophistication of the UPS product: this annex shows a typical example
   of the subset of variables used for a reasonably complete "consumer
   grade" UPS.  The NUT Project maintains a large library of the
   variable subsets [Library] used by different UPS models.

   Note that successive versions of a given product may add or delete
   features causing a change in the subset of variables used.  An
   example is the removal of ups.delay.start from a "consumer grade"
   UPS.  The manufacturer reserves the feature for the "professional"
   product.

   An implementation of a Management Daemon acting as a utility program
   may provide a listing of the variables available for a given product,
   for example utility program upsc as included in the NUT package, see
   Section 2.6, Paragraph 3.

   The following sections illustrate the use of variables by taking the
   values associated with a typical product example of a 1600Va 1000W
   UPS.

A.1.  Typical UPS Variables

    +===============================+============+====================+
    |            Variable           |  Typical   |      Default       |
    |                               |   value    |    description     |
    +===============================+============+====================+
    | battery.charge                | 100        | "Battery charge    |
    |                               |            | (percent of full)" |

Price                    Expires 13 October 2022               [Page 48]
Internet-Draft           UPS management protocol              April 2022

    +-------------------------------+------------+--------------------+
    | 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>"            |
    +-------------------------------+------------+--------------------+

Price                    Expires 13 October 2022               [Page 49]
Internet-Draft           UPS management protocol              April 2022

    | driver.version                | 2.8.0      | "Driver version -  |
    |                               |            | NUT release"       |
    +-------------------------------+------------+--------------------+
    | driver.version.data           | HID 1.39   | ""                 |
    +-------------------------------+------------+--------------------+
    | driver.version.internal       | 0.41       | "Internal driver   |
    |                               |            | version"           |
    +-------------------------------+------------+--------------------+
    | input.transfer.high           | 264        | "High voltage      |
    |                               |            | transfer point     |
    |                               |            | (V)"               |
    +-------------------------------+------------+--------------------+
    | input.transfer.low            | 184        | "Low voltage       |
    |                               |            | transfer point     |
    |                               |            | (V)"               |
    +-------------------------------+------------+--------------------+
    | outlet.1.desc                 | PowerShare | "Outlet            |
    |                               | Outlet 1   | description"       |
    +-------------------------------+------------+--------------------+
    | outlet.1.id                   | 2          | "Outlet system     |
    |                               |            | identifier"        |
    +-------------------------------+------------+--------------------+
    | outlet.1.status               | on         | "Outlet switch     |
    |                               |            | status"            |
    +-------------------------------+------------+--------------------+
    | outlet.1.switchable           | no         | "Outlet switch     |
    |                               |            | ability"           |
    +-------------------------------+------------+--------------------+
    | outlet.2.desc                 | PowerShare | "Outlet            |
    |                               | Outlet 2   | description"       |
    +-------------------------------+------------+--------------------+
    | outlet.2.id                   | 3          | "Outlet system     |
    |                               |            | identifier"        |
    +-------------------------------+------------+--------------------+
    | outlet.2.status               | on         | "Outlet switch     |
    |                               |            | status"            |
    +-------------------------------+------------+--------------------+
    | outlet.2.switchable           | no         | "Outlet switch     |
    |                               |            | ability"           |
    +-------------------------------+------------+--------------------+
    | outlet.desc                   | Main       | "Outlet            |
    |                               | Outlet     | description"       |
    +-------------------------------+------------+--------------------+
    | outlet.id                     | 1          | "Outlet system     |
    |                               |            | identifier"        |
    +-------------------------------+------------+--------------------+
    | outlet.power                  | 25         | ""                 |
    +-------------------------------+------------+--------------------+

Price                    Expires 13 October 2022               [Page 50]
Internet-Draft           UPS management protocol              April 2022

    | outlet.switchable             | no         | "Outlet switch     |
    |                               |            | ability"           |
    +-------------------------------+------------+--------------------+
    | output.frequency.nominal      | 50         | "Nominal output    |
    |                               |            | frequency (Hz)"    |
    +-------------------------------+------------+--------------------+
    | output.voltage                | 230.0      | "Output voltage    |
    |                               |            | (V)"               |
    +-------------------------------+------------+--------------------+
    | output.voltage.nominal        | 230        | "Nominal output    |
    |                               |            | voltage (V)"       |
    +-------------------------------+------------+--------------------+
    | ups.beeper.status             | enabled    | "UPS beeper        |
    |                               |            | status"            |
    +-------------------------------+------------+--------------------+
    | ups.delay.shutdown            | 20         | "Interval to wait  |
    |                               |            | after shutdown     |
    |                               |            | with delay command |
    |                               |            | (seconds)"         |
    +-------------------------------+------------+--------------------+
    | ups.delay.start               | 30         | "Interval to wait  |
    |                               |            | before             |
    |                               |            | (re)starting the   |
    |                               |            | load (seconds)"    |
    +-------------------------------+------------+--------------------+
    | ups.firmware                  | 02         | "UPS firmware"     |
    +-------------------------------+------------+--------------------+
    | ups.load                      | 20         | "Load on UPS       |
    |                               |            | (percent of full)" |
    +-------------------------------+------------+--------------------+
    | ups.mfr                       | Example    | "UPS manufacturer" |
    |                               | Mfg        |                    |
    +-------------------------------+------------+--------------------+
    | ups.model                     | Economy    | "UPS model"        |
    |                               | 1600       |                    |
    +-------------------------------+------------+--------------------+
    | ups.power.nominal             | 1600       | "UPS power rating  |
    |                               |            | (VA)"              |
    +-------------------------------+------------+--------------------+
    | ups.productid                 | ffff       | "Product ID for    |
    |                               |            | USB devices"       |
    +-------------------------------+------------+--------------------+
    | ups.serial                    | 000000000  | "UPS serial        |
    |                               |            | number"            |
    +-------------------------------+------------+--------------------+
    | ups.status                    | OL         | "UPS status"       |
    +-------------------------------+------------+--------------------+
    | ups.temperature               | 27         | "UPS temperature   |

Price                    Expires 13 October 2022               [Page 51]
Internet-Draft           UPS management protocol              April 2022

    |                               |            | (C)"               |
    +-------------------------------+------------+--------------------+
    | ups.timer.shutdown            | 0          | "Time before the   |
    |                               |            | load will be       |
    |                               |            | shutdown           |
    |                               |            | (seconds)"         |
    +-------------------------------+------------+--------------------+
    | ups.timer.start               | 0          | "Time before the   |
    |                               |            | load will be       |
    |                               |            | started (seconds)" |
    +-------------------------------+------------+--------------------+
    | ups.vendorid                  | 0999       | "Vendor ID for USB |
    |                               |            | devices"           |
    +-------------------------------+------------+--------------------+

                       Table 6: Typical UPS Variables

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.

Price                    Expires 13 October 2022               [Page 52]
Internet-Draft           UPS management protocol              April 2022

     +========================+============+=========================+
     |        Variable        |  Typical   |   Default description   |
     |                        |   value    | provided as response to |
     |                        |            |   the command GET DESC  |
     +========================+============+=========================+
     | battery.charge.low     | 20         | "Remaining battery      |
     |                        |            | level when UPS switches |
     |                        |            | to LB (percent)"        |
     +------------------------+------------+-------------------------+
     | input.transfer.high    | 264        | "High voltage transfer  |
     |                        |            | point (V)"              |
     +------------------------+------------+-------------------------+
     | input.transfer.low     | 184        | "Low voltage transfer   |
     |                        |            | point (V)"              |
     +------------------------+------------+-------------------------+
     | outlet.1.desc          | PowerShare | "Outlet description"    |
     |                        | Outlet 1   |                         |
     +------------------------+------------+-------------------------+
     | outlet.2.desc          | PowerShare | "Outlet description"    |
     |                        | Outlet 2   |                         |
     +------------------------+------------+-------------------------+
     | outlet.2.switchable    | no         | "Outlet switch ability" |
     +------------------------+------------+-------------------------+
     | outlet.desc            | Main       | "Outlet description"    |
     |                        | Outlet     |                         |
     +------------------------+------------+-------------------------+
     | outlet.power           | 25         | "Description            |
     |                        |            | unavailable"            |
     +------------------------+------------+-------------------------+
     | output.voltage.nominal | 230        | "Nominal output voltage |
     |                        |            | (V)"                    |
     +------------------------+------------+-------------------------+
     | ups.delay.shutdown     | 20         | "Interval to wait after |
     |                        |            | shutdown with delay     |
     |                        |            | command (seconds)"      |
     +------------------------+------------+-------------------------+
     | ups.delay.start        | 30         | "Interval to wait       |
     |                        |            | before (re)starting the |
     |                        |            | load (seconds)"         |
     +------------------------+------------+-------------------------+

            Table 7: Typical readable and writable UPS Variables

Price                    Expires 13 October 2022               [Page 53]
Internet-Draft           UPS management protocol              April 2022

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.

      +==================+==========================================+
      |     Command      |                 Meaning                  |
      +==================+==========================================+
      | beeper.disable   | Disable the UPS beeper                   |
      +------------------+------------------------------------------+
      | beeper.enable    | Enable the UPS beeper                    |
      +------------------+------------------------------------------+
      | beeper.mute      | Temporarily mute the UPS beeper          |
      +------------------+------------------------------------------+
      | load.off         | Turn off the load immediately            |
      +------------------+------------------------------------------+
      | load.off.delay   | Turn off the load with a delay (seconds) |
      +------------------+------------------------------------------+
      | load.on          | Turn on the load immediately             |
      +------------------+------------------------------------------+
      | load.on.delay    | Turn on the load with a delay (seconds)  |
      +------------------+------------------------------------------+
      | shutdown.return  | Turn off the load and return when power  |
      |                  | is back                                  |
      +------------------+------------------------------------------+
      | shutdown.stayoff | Turn off the load and remain off         |
      +------------------+------------------------------------------+
      | shutdown.stop    | Stop a shutdown in progress              |
      +------------------+------------------------------------------+

                     Table 8: Typical Instant Commands

Appendix B.  The Shutdown Story for System and UPS

   This appendix provides background material helpful for a general
   understanding of the relation between system and UPS.  It does not
   define any feature of the command-response protocol.

   We consider the steps involved in the shutdown and restart of a long-
   running unattended server protected by a single UPS.  The Management
   Daemon runs in the server as shown in Figure 8.

Price                    Expires 13 October 2022               [Page 54]
Internet-Draft           UPS management protocol              April 2022

                     ,------------------SERVER------------------,
                     |                    |                     |
           ,-----,   |     UPS       <-Commands        UPS      |
           | UPS |---|  Attachment        |         Management  |
           |     |===|    Daemon       Responses->    Daemon    |
           /-----\   '--------------------'---------------------'
                                       Internal
                                       loopback

                  Figure 8: Long-running unattended server

   1.   _The public power supply is on_ -- The system runs normally.
        Every 5 seconds, variable ups.status reports OL. -- _Days,
        weeks, months go by..._

   2.   _Winter storm.  Tree falls on power lines.  The public power
        supply fails_ -- The server remains operational running on the
        UPS battery.  The Management Daemon polls the Attachment Daemon,
        and detects status change OL->OB.

   3.   The Management Daemon logs warning messages.  The server is
        still operational running on the UPS battery. -- _Minutes go
        by..._

   4.   The battery discharges below the level specified by variable
        battery.charge.low.  The server remains operational, but the UPS
        battery will not last much longer.  The Management Daemon polls
        the Attachment Daemon, and detects status change OB->OB+LB.

   5.   The Management Daemon logs the low battery event.

   6.   The Management Daemon decides to call for a system shutdown.  It
        sets status FSD in the Attachment Daemon to call on any
        secondaries to shut down and waits for command GET NUMATTACH to
        report one single attachment, i.e. the Primary itself.  The
        Management Daemon then issues the system shutdown command for
        itself.

   7.   The operating system's shutdown process takes over.  During the
        system shutdown, a NUT Project specific script or an equivalent
        systemd service unit runs the command upsdrvctl shutdown.  This
        tells the UPS that it is to shut down N seconds later where the
        default is N=20.  Note that the "shutdown" of a UPS removes
        power from the outlet sockets, but may not turn the UPS off
        completely.  A delayed shutdown is sometimes audible, and the
        characteristic beeping of the UPS stops.

Price                    Expires 13 October 2022               [Page 55]
Internet-Draft           UPS management protocol              April 2022

   8.   The system shuts down and powers down, hopefully before the N=20
        seconds have passed.

   9.   _N seconds after item 7_ -- The UPS shuts down, i.e., it turns
        off its outlet sockets when N=20 seconds have passed.  With some
        UPS units, there is an audible "clunk".

        What if the public power supply returns before the UPS shuts
        down?  The UPS unit should be able to wait a configurable time
        with default 30 seconds.  These two timers start from the moment
        the UPS receives the upsdrvctl shutdown command. -- _Minutes,
        hours, days go by..._

   10.  _Some time later, maybe much later, the public power supply
        returns_ -- The UPS reconnects it's outlets to send power to the
        protected system.

   11.  The system BIOS option "Restore power on AC return" or "Restore
        to previous state" has hopefully been selected and the system
        powers up.  The bootstrap process of the operating system
        begins.

   12.  The operating system starts the Attachment Daemon and the
        Management Daemon.  The Attachment Daemon starts the Driver and
        scans the UPS.  The UPS status becomes OL+LB.

   13.  After some time, the battery charges above the
        battery.charge.low threshold and the Attachment Daemon declares
        the status change OL+LB->OL.  We are now back in the same
        situation as 1 above.

Appendix C.  Technical Terms: Historical Differences

   This appendix lists the major differences between the technical terms
   used in NUT software release 2.8.0 and documented in this text, and
   those used in previous version 2.7.4 of the NUT Project.

Price                    Expires 13 October 2022               [Page 56]
Internet-Draft           UPS management protocol              April 2022

        +===================+========================+===========+
        | Term in previous  | Term in this document, | Reference |
        | release NUT 2.7.4 | release NUT 2.8.0      |           |
        +===================+========================+===========+
        | ALREADY-LOGGED-IN | ALREADY-ATTACHED       | Table 3   |
        +-------------------+------------------------+-----------+
        | ALREADY-SSL-MODE  | TLS-ALREADY-ENABLED    | Table 3   |
        +-------------------+------------------------+-----------+
        | LOGIN             | ATTACH                 | Section   |
        |                   |                        | 4.2.1     |
        +-------------------+------------------------+-----------+
        | LOGOUT            | DETACH                 | Section   |
        |                   |                        | 4.2.2     |
        +-------------------+------------------------+-----------+
        | Master            | Primary                | Section   |
        |                   |                        | 2.7       |
        +-------------------+------------------------+-----------+
        | NETVER            | PROTVER                | Section   |
        |                   |                        | 4.2.10    |
        +-------------------+------------------------+-----------+
        | NUMLOGINS         | NUMATTACH              | Section   |
        |                   |                        | 4.2.4.3   |
        +-------------------+------------------------+-----------+
        | Slave             | Secondary              | Section   |
        |                   |                        | 2.8       |
        +-------------------+------------------------+-----------+

                                 Table 9

Appendix D.  Security Defences in Release 2.7.4

   Previous NUT version 2.7.4 did not provide support for TLS v.3
   [RFC8446].  The following subsections describe mitigating techniques.

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.

Price                    Expires 13 October 2022               [Page 57]
Internet-Draft           UPS management protocol              April 2022

                      TLS shim listens     TLS shim listens
                      on port TBD1/TCP     on port 3493/TCP
       ,-----,------------,----,               ,----,--------------,
       | UPS - Attachment |TLS | <-STARTTLS    | TLS|  Management  |
       |     |   Daemon   |shim|         OK--> |shim|    Daemon    |
       /-----'------------'----\               '----'--------------'
               Listens on
             port 3493/TCP

            Figure 9: Shims provide TLS support during migration

D.1.1.  Attachment Daemon Shim

   The shim in front of the Attachment Daemon listens to incoming
   traffic on port TBD1/TCP.  When it receives the command STARTTLS it

   1.  Returns OK to the client and sets up TLS encapsulation.
   2.  Does not send 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.

D.1.2.  Management Daemon Shim

   The shim in front of the Management Daemon listens for incoming
   traffic on port 3493/TCP.  When it receives the command STARTTLS it

   1.  Returns FEATURE-NOT-CONFIGURED to the client.
   2.  Sends STARTTLS to the Attachment Daemon on port TBD1/TCP.

   All other commands and responses are passed through.

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.

Price                    Expires 13 October 2022               [Page 58]
Internet-Draft           UPS management protocol              April 2022

D.4.  VLAN

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

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

         Figure 10: UPS Management Protocol runs over its own VLAN

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

Appendix E.  Administrative Security

   Administrative commands such as FSD, INSTCMD and SET are powerful and
   can have a deep effect on system integrity, For example, the command
   FSD is involved in mission critical system shutdown decisions.
   Access to them needs to be managed and restricted.  This clause
   presents the current practice.

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.

Price                    Expires 13 October 2022               [Page 59]
Internet-Draft           UPS management protocol              April 2022

   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:

Price                    Expires 13 October 2022               [Page 60]
Internet-Draft           UPS management protocol              April 2022

        +=============+==========================================+
        | Declaration |                 Meaning                  |
        +=============+==========================================+
        | actions     | Allow the user to do certain things in   |
        |             | the Attachment Daemon.  To specify       |
        |             | multiple actions, use multiple instances |
        |             | of the declaration.  Valid actions are:  |
        |             |                                          |
        |             | *  FSD Set the "Forced Shutdown" flag    |
        |             |    for this UPS.  See Section 4.2.3.     |
        |             |                                          |
        |             | *  SET Change the value of a UPS         |
        |             |    variable.  See Section 4.2.11.        |
        +-------------+------------------------------------------+
        | instcmds    | Let a user initiate specific instant     |
        |             | commands.  See Section 4.2.6.  Use value |
        |             | ALL to grant all commands automatically. |
        |             | To specify multiple commands, use        |
        |             | multiple instances of the instcmds       |
        |             | field.  For the full list of what a      |
        |             | given UPS supports, use client upscmd -l |
        |             | supplied by the NUT Project.  The LIST   |
        |             | CMD command is issued within the client  |
        |             | upscmd.                                  |
        +-------------+------------------------------------------+
        | password    | Set the password for this user.  _Your   |
        |             | password should be more secure than the  |
        |             | examples shown._                         |
        +-------------+------------------------------------------+
        | upsmon      | Add the necessary actions for a          |
        |             | Management Daemon to process a system    |
        |             | shutdown.  In current practice the value |
        |             | is still master or slave.  Note that     |
        |             | there is no U+003D EQUALS SIGN =.        |
        +-------------+------------------------------------------+

                Table 10: Administrative user declarations

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.

Price                    Expires 13 October 2022               [Page 61]
Internet-Draft           UPS management protocol              April 2022

E.2.1.  An Administrative User Logs into a Short Session

   In this simple example of current practice, the system administrator
   sets the battery level at which an Attachment Daemon will raise the
   status LB, represented by variable battery.charge.low, to 35% of full
   charge.  A system administrator types the following command to call
   the client upsrw supplied by the NUT Project.

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

   The USERNAME and PASSWORD commands are issued within the client upsrw
   and the Session is of short duration.

E.2.1.1.  An Administrative User Logs into a Long Session

   In this second example of current practice, the long-running
   Management Daemon upsmon which is responsible for initiating system
   shutdowns and which is provided by the NUT Project issues commands
   USERNAME and PASSWORD when it starts up.  The data values needed for
   the USERNAME and PASSWORD commands are provided by a configuration
   file upsmon.conf which contains the line

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

   This says that the UPS to be monitored is UPS-1@example.com, it
   provides 1 single power supply, the administrative user is admin with
   password sekret.  The Management Daemon acts as a Primary, although
   current practice uses the term master.

   The USERNAME and PASSWORD commands are contained within the client
   upsmon and the Session is of long duration.

Author's Address

   Roger Price (editor)
   Network UPS Tools Project
   France
   Email: ietf@rogerprice.org

Price                    Expires 13 October 2022               [Page 62]