wdiff rfc9271.original.xml rfc9271.xml

<?xml version='1.0' encoding='UTF-8' ?>
<!-- The SGML source file draft-rprice-ups-management-protocol-15.sgml2rfc
     makes extensive use of markup minimisation.  The required
     XML is generated from the SGML by osgmlnorm:I: "OpenSP" version "1.5.2"
     using a HyTime architectural form, and is verified to
     conform by xml2rfc 3.12.2
     Editor: Roger Price, NUT Project, ietf@rogerprice.org
     2022-05-18 08:24:45 UTC
--> version="1.0" encoding="UTF-8"?>
<!DOCTYPE rfc SYSTEM "rfc2629-xhtml.ent"> [
 <!ENTITY nbsp    "&#160;">
 <!ENTITY zwsp   "&#8203;">
 <!ENTITY nbhy   "&#8209;">
 <!ENTITY wj     "&#8288;">
]>

<rfc xml:lang="en" xmlns:xi="http://www.w3.org/2001/XInclude" obsoletes="" updates="" category="info" ipr="trust200902" submissionType="IETF" submissionType="independent" category="info" docName="draft-rprice-ups-management-protocol-15" number="9271" sortRefs="true" symRefs="true" tocInclude="true" tocDepth="4" version="3">

<front>
<title abbrev="UPS management protocol">Uninterruptible Management Protocol">Uninterruptible Power Supply (UPS) Management Protocol -- Commands and Responses</title>
<seriesInfo name="Internet-Draft" value="draft-rprice-ups-management-protocol-15"/> name="RFC" value="9271"/>
<author initials="R." surname="Price" fullname="Roger Price" role="editor">
<organization>Network UPS Tools Project
  </organization> Project</organization>
<address>
<postal>
<street>
  </street>
<city>
  </city>
<region>
  </region>
<code>
  </code>
<country>France
  </country>
<country>France</country>
</postal>
<phone>
  </phone>
<email>ietf@rogerprice.org
  </email>
<email>ietf@rogerprice.org</email>
</address>
</author>

<date year="2022">
</date>
<area>General
</area>
<workgroup>IETF
</workgroup>
<keyword>Uninterruptible Power Supply UPS NUT
</keyword> year="2022" month="August"/>

<keyword>Uninterruptible</keyword>
<keyword>Power</keyword>
<keyword>Supply</keyword>
 <keyword>UPS</keyword>
<keyword>NUT</keyword>

<abstract>
<t>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, 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 that notifies users
and system administrators of power supply incidents, 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.  The practice current when this protocol was first
developed risks weak security security, and this is addressed in the Security
Considerations sections of this document.
</t>
</abstract>
</front>
<middle>
<section>
<name>Introduction</name>
<section anchor="intro">
<name>Current Practice</name>
<t>This document describes UPS management techniques and current UPS
management practice published by the NUT (Network Network UPS Tools) Tools (NUT) Project.
The document is based on version 2.8.0 of the NUT Project software software,
which supports version 1.3 of the NUT protocol.
</t>
<t>Since May 2002, the protocol described by this document has been
operating on IANA port 3493/TCP (nut).
</t>
<section anchor="proj">
<name>NUT Software Project</name>
<t>The primary goal of the NUT (Network Network UPS Tools) Software Tools (NUT)
Project software <xref target="NUT"></xref> is to provide support for Power
Devices, power
devices, such as Uninterruptible Power Supplies. UPSs.  The Project project has been
in operation since 1998 1998, with a major rework in 2003.  It operates
through a user <xref target="nut-upsuser">mailing list</xref>, a
developer <xref target="nut-upsdev">mailing list</xref>,
a <xref target="NUT">web site</xref> target="NUT">website</xref>, and
a <xref target="nut-repository">GitHub repository</xref>.  See
<xref target="githist"></xref> and Appendix J of <xref target="History"></xref> for
a history of the project.
</t>
</section>
<section anchor="TSS">
<name>The "Shutdown Story"</name>
<t>"The Shutdown Story", see Story</name>
<t>The Shutdown Story section (see <xref target="shutdownstory"></xref>, target="shutdownstory"></xref>)
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 minimize the risk of corruption to data
processed by this infrastructure.
</t>
</section>
<section anchor="HowtoRead">
<name>How to Read this Document</name>
<t>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.
</t>
<t>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 <xref target="symbols"></xref> target="symbols"></xref>, while
the events are listed in
<xref target="events"></xref>.
</t>
<t>This document refers to the "public power supply".  Other texts
frequently refer to "utility power", "input source power" power", or even
"wall power".
</t>
</section>
</section>
<section anchor="AddInf">
<name>Additional Information</name>
<t>Additional information about the NUT Project is available in
the <xref target="Documentation">project documentation</xref>.
Requests for further information about this protocol and related
technical matters may be addressed to
the <xref target="nut-upsuser">mailing list</xref> of the NUT Project.
</t>
</section>
<section>
<name>Requirements Language</name>
<t>The
<t>
The key words "<bcp14>MUST</bcp14>", "<bcp14>MUST NOT</bcp14>", "<bcp14>REQUIRED</bcp14>", "<bcp14>SHALL</bcp14>", "<bcp14>SHALL
NOT</bcp14>", "<bcp14>SHOULD</bcp14>", "<bcp14>SHOULD NOT</bcp14>", "<bcp14>RECOMMENDED</bcp14>", "<bcp14>NOT RECOMMENDED</bcp14>",
"<bcp14>MAY</bcp14>", and "<bcp14>OPTIONAL</bcp14>" in this document are to be interpreted as
described in BCP
14 BCP&nbsp;14 <xref target="RFC2119"></xref> target="RFC2119"/> <xref target="RFC8174"></xref> target="RFC8174"/>
when, and only when, they appear in all capitals, as shown here.
</t>
</section>
</section>
<section anchor="Terminology">
<name>Terminology</name>
<t>The following technical terms appear in this document. They are
listed in alphabetical order.
</t>
<section anchor="au">
<name>Administrative User</name>
<t>In current practice, the commands and other functions offered by
the Attachment Daemon are made available to a set of users known as Management Daemons.  These
Management Daemons authenticate to the Attachment Daemon with basic credentials (username and
password).  Although called "users", the administrative users are not
system users, users; they are specific to an Attachment Daemon and are listed in a text
file (currently <tt>upsd.users</tt>) which that is read by the Attachment Daemon and
which
that assigns to each of them the password, Instant Commands Commands, and
actions which that are allowed, together with the Primary or Secondary
status of the Management Daemon.  For details,
see <xref target="adminuser"></xref>. For details of Primary the Primary, see
<xref target="prim"></xref>, and target="prim"></xref>; for details of Secondary the Secondary, see <xref target="sec"></xref>.  Typically  Typically, a
high-level user will be able to send command <tt>FSD</tt> <tt>FSD</tt>, but a
low-level user might only be allowed to access the test panel.  The
security provisions for administrative users are discussed in
<xref target="adsec"></xref>.
</t>
</section>
<section anchor="AD">
<name>Attachment Daemon</name>
<t>The Attachment Daemon retrieves the 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 <xref target="Driver"></xref>. It
maintains an abstracted view of the hardware through the use of
hardware statuses.  See <xref target="st"></xref>.  A Management Daemon may
consult the abstracted view using the commands described in this
document.
</t>
<t>See <xref target="MinSup"></xref> for details of the recommended
minimum support of variables variables, which calls for Attachment Daemon support
of statuses <tt>OB</tt>, <tt>OL</tt>, <tt>LB</tt> <tt>LB</tt>, and <tt>FSD</tt>.
</t>

<t>The NUT Project has implemented an Attachment Daemon as program <tt>upsd</tt>
and a set of hardware specific drivers, hardware-specific Drivers, all written in K&amp;R C. C <xref target="C2ndEd"/>.  The
Attachment Daemon is launched as system user "root", "root" but for better security, then security; then, it
drops the privilege to run as a detached software service.
</t>
</section>
<section anchor="Driver">
<name>Driver</name>
<t>A Driver is that part of an Attachment Daemon which that is specific to
the UPS hardware, the connection medium medium, and the connection protocol,
e.g., USB, serial.  In current practice practice, the Attachment Daemon has a
driver
Driver for each hardware interface type it supports.  Although this
document considers the driver 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.
</t>
</section>
<section>
<name>Event</name>
<t>A UPS Event event occurs in the Management Daemon when a change in the UPS status is
received from the Attachment Daemon.  This event is internal to the Management Daemon.
See <xref target="events"></xref>.
</t>
</section>
<section anchor="IC">
<name>Instant Command</name>
<t>A
<t>An Instant Command is a command which that, when sent to the Attachment Daemon Daemon,
is passed to the driver Driver and
sent to the hardware without any configured delay to perform a
function. For example example, <tt>INSTCMD su700 test.panel.start</tt>&nbsp;. test.panel.start</tt>.
See <xref target="instcmd"></xref>.
</t>
</section>
<section anchor="MD">
<name>Management Daemon</name>
<t>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 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
<xref target="shutdownstory"></xref>. Although the term includes the
word "Daemon" "Daemon", nothing requires that it be implemented as a detached
software service.  The Management Daemon may also provide
administrative functions functions, such as a graphic interface to view the
hardware activity.
</t>
<t>There are several examples of a Management Daemon: the NUT Project
provides <tt>upsmon</tt> <tt>upsmon</tt>, which takes the system shutdown decision when
the public power supply fails.  Further configuration options options, such as timers timers, are
provided by the helper program <tt>upssched</tt>.
</t>
<t anchor="util">Other programs represent the Management Daemon:
</t>
<ul spacing="compact">
<li><tt>upsc</tt> reports the values of the variables defined for a
given UPS, UPS; see <xref target="typvar"></xref>.
</li>
<li><tt>upsrw</tt> reports on and changes the values of the readable
and writable configuration variables defined for a given UPS, UPS;
see <xref target="rw"></xref>.
</li>
<li><tt>upscmd</tt> reports on and executes the instant action
commands defined for a given UPS, UPS; see <xref target="instcmd"></xref>.
</li>
<li><tt>UPSmon.py</tt> is an experimental Python3 rewrite
of <tt>upsmon</tt> and <tt>upssched</tt> which that includes support
for <xref target="RFC8446">TLS 1.3</xref>.
</li>
</ul>
</section>
<section anchor="prim">
<name>Primary</name>
<t>When a power device device, such as a UPS unit unit, supplies power to more than
one system, the computer running the driver Driver is known as the Primary.
The others are Secondaries.  See figure <xref target="fig.oview4" format="counter"></xref>. target="fig.oview4"/>.  Common current practice for system administrators is
to consider the Management Daemon in the Primary to be the Primary Management
Daemon which that is in charge of the shutdown of all the systems powered
by the UPS.  The Primary Management Daemon sets status
symbol <tt>FSD</tt> to order the secondaries Secondaries to shut down.
</t>
<aside>
  <t>Note: Historically, the Primary was known as the "Master".
</t> "Master".</t>
</aside>
</section>
<section anchor="sec">
<name>Secondary</name>
<t>When a hardware device device, such as a UPS unit unit, supplies power to more
than one system, the system which that communicates directly with the UPS
unit e.g.
unit, e.g., using a USB, RS232, RS-232, or a network connection, is known as the
Primariy.
Primary.  The other others are Secondaries.  There is no Attachment Daemon in a
Secondary. See figure <xref target="fig.oview4" format="counter"></xref>. target="fig.oview4"/>.
Common current practice for system administrators is to consider the
Management Daemon in a Secondary to be a Secondary Management Daemon which that
understands status symbol <tt>FSD</tt> as an order to shut down.
</t>
<aside>
  <t>Note: Historically, the Secondary was known as the "Slave".
</t> "Slave".</t>
</aside>
</section>
<section anchor="sess">
<name>Session</name>
<t>The Management Daemon may initiate a TCP session with a specified device device, such
as a UPS known to the Attachment Daemon. The session structure provides for audit
and security security, as well as access to mission critical mission-critical UPS functions.  For
example
example, good practice requires a password protection for an Instant
Command which that turns off a UPS outlet.  Other than the commands and
responses used, the details of session management are outside the
scope of this document.
</t>
</section>
<section anchor="st">
<name>UPS Status</name>
<t>The status of a hardware device device, such as a UPS unit unit, is a symbolic
description of the state of the unit.  It consists of a space
separated space-separated
list of symbols from the set {<tt>ALARM</tt> <tt>BOOST</tt> <tt>BYPASS</tt>
<tt>CAL</tt> <tt>CHRG</tt> <tt>COMM</tt> <tt>DISCHRG</tt> <tt>FSD</tt> <tt>LB</tt> <tt>NOCOMM</tt> <tt>OB</tt>
<tt>OFF</tt> <tt>OL</tt> <tt>OVER</tt> <tt>RB</tt> <tt>TEST</tt> <tt>TRIM</tt>}.  The symbols <tt>TICK</tt> and
<tt>TOCK</tt> are experimental additions to the statuses and are not in
common current practice.  See <xref target="symbols"></xref> target="symbols"></xref>, which
specifies each of these symbols.
</t>
<t>See <xref target="MinSup"></xref> for details of the recommended
minimum support of status symbols <tt>OB</tt>, <tt>OL</tt>, <tt>LB</tt> <tt>LB</tt>,
and <tt>FSD</tt>.
</t>
</section>
<section anchor="var">
<name>UPS Variable</name>
<t>The metrics and identifiers provided by each UPS are represented by
variables giving the value representing that metric or identifier, identifier. The
UPS variable is an abstraction of the UPS hardware configuration and
activity maintained by the Attachment Daemon.  See <xref target="Annex1"></xref> target="Annex1"></xref>,
which provides examples of variables.  For example example, the
variable <tt>battery.charge</tt> contains the current charge of the
UPS battery as a percentage value.
</t>
<t>Note: Some variables are constants, e.g. e.g., battery type, type and
manufacturer.
</t>
<t>See <xref target="MinSup"></xref> for details of the
recommended minimum support of variables.  A full list of possible
variables is available in <xref target="gitvars">source code file
docs/nut-names.txt</xref>
docs/nut-names.txt</xref>, which serves as the Recording Document.
</t>
</section>
</section>
<section anchor="overview">
<name>Protocol Overview</name>
<t>Figure <xref target="fig.oview" format="counter"></xref>
<t><xref target="fig.oview"/> shows a reference
configuration in which the command/response protocol applies.  The UPS
shown is representative of all managed power devices, devices.
</t>
<figure anchor="fig.oview">
<name>Reference Configuration
</name> Configuration</name>
<artwork align="center"> align="center" type="ascii-art"><![CDATA[
                                            "The client"
           ,--------------,               ,--------------,
 ,-----,   |     UPS      | &lt;-Commands <-Commands    |     UPS      |
 | UPS |---|  Attachment  |---------------|  Management  |
 |     |===|    Daemon    |   Responses-&gt;   Responses-> |    Daemon    |
 /-----\   '--------------'               '--------------'
            UPS Attachment                 UPS Management
                System        Network          System</artwork>          System
]]></artwork>
</figure>
<t>The reference configuration in figure <xref target="fig.oview" format="counter"></xref> target="fig.oview"/> shows a single UPS unit which that
has a power supply link
(<tt>===</tt>) and a data link (<tt>---</tt>) attached to a system
running an Attachment Daemon.  The UPS provides power supply protection to the
system running the Attachment Daemon.
</t>
<t>In practice 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 practice, there may be more than one
Management Daemon, and any one Management Daemon may manage more than
one UPS Attachment Daemon.
</t>
<t>The protocol applies to connections between the Attachment Daemon
and the Management Daemon Daemon, which act as the <strong>server</strong>
and <strong>client</strong> <strong>client</strong>, respectively.  The Management Daemon sends
commands over TCP to the Attachment Daemon and receives responses over
TCP from that daemon.
</t>
<t>The two daemons may run in the same system, system or may be connected
through a local or wide area network.  In simple cases, as shown in
figure
<xref target="fig.oview2" format="counter"></xref>, target="fig.oview2"/>, 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.
</t>
<figure anchor="fig.oview2">
<name>Simplified single-system configuration Single-System Configuration
</name>
<artwork align="center"> align="center" type="ascii-art"><![CDATA[
                                         "The client"
           ,--------------------,---------------------,
 ,-----,   |     UPS       &lt;-Commands       <-Commands        UPS      |
 | UPS |---|  Attachment        |         Management  |
 |     |===|    Daemon       Responses-&gt;       Responses->    Daemon    |
 /-----\   '--------------------'---------------------'
                             Internal
                             loopback
                             Loopback
             UPS Attachment and Management System</artwork> System
]]></artwork>
</figure>
<t>The reference configuration does not require any specific
design. For example figure example, <xref target="fig.oview3" format="counter"></xref> target="fig.oview3"/>
shows an arrangement in which the Attachment Daemon is closely associated with, or
even included in in, the UPS system setup.  This is becoming more
prevalent with the availability of low cost low-cost processors able to run the
Attachment Daemon Daemon, thereby effectively creating a network attached network-attached UPS running a
published protocol.
</t>
<figure anchor="fig.oview3">
<name>UPS and Attachment Daemon integration Integration
</name>
<artwork align="center"> align="center" type="ascii-art"><![CDATA[
                                      "The client"
 ,-----,------------,               ,--------------,
 |     |    UPS     | &lt;-Commands <-Commands    |     UPS      |
 | UPS - Attachment |---------------|  Management  |
 |     |   Daemon   |   Responses-&gt;   Responses-> |    Daemon    |
 /-----'------------\               '--------------'
    UPS Attachment                   UPS Management
        System           Network          System</artwork>          System
]]></artwork>
</figure>
<t>As the power requirements for processors decrease, it is becoming
increasingly common to use a single UPS to protect multiple systems systems, as
shown in figure <xref target="fig.oview4" format="counter"></xref>.  However target="fig.oview4"/>.  However,
there is only one data line (<tt>---</tt>) from the UPS to the Primary
system.  The others have only power connections (<tt>===</tt>) to the
UPS,
UPS and are known as Secondaries.  A Secondary does not run an Attachment Daemon, Daemon;
it connects over a network to the Attachment Daemon in the
Primary. Figure <xref target="fig.oview4" format="counter"></xref> target="fig.oview4"/> shows the
Attachment Daemon and the Primary Management Daemon in the same system.  This is common
practice
practice, but it is not a technical requirement.
</t>
<figure anchor="fig.oview4">
<name>UPS protects multiple systems Protects Multiple Systems
</name>
<artwork align="center"> align="center" type="ascii-art"><![CDATA[
                                      "The client"
           ,--------------------,---------------------,
 ,-----,   |     UPS       &lt;-Commands       <-Commands      Primary    |
 |     |---|  Attachment        |         Management  |   Primary
 |     |===|    Daemon       Responses-&gt;       Responses->    Daemon    |
 |     |   '--------------------'---------------------'
 | UPS |            ^
 |     |            '&lt;-Commands---Responses-&gt;,            '<-Commands---Responses->,
 |     |                                     v
 |     |            ,--------------,-----------------,
 |     |============|              |     Secondary   |
 /-----\            |              |     Management  |   Secondary
                    |              |       Daemon    |
                    '--------------'-----------------'</artwork>
                    '--------------'-----------------'
]]></artwork>
</figure>
<aside>
<t>Note: Should the Primary fail or go off-line, offline, the fate of
the Secondaries depends on the UPS status when the Primary failed.  If
the UPS had status <tt>OL</tt> <tt>OL</tt>, the Secondary continues operation, but if the
UPS had status <tt>OB</tt> <tt>OB</tt>, the Secondary may choose to shut down as a precaution.
</t>
</aside>
</section>
<section anchor="protspec">
<name>Protocol Specification</name>
<t>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;
machine, for example example, to assist the system shutdown of a complex
installation.  The Management Daemon is required to remember the
previous <tt>ups.status</tt> value it received from the Attachment Daemon and
compare it with the next.  Other than that that, the management protocol
used between them is effectively stateless.
</t>
<t>See for example
<t>For example, see <xref target="events"></xref> target="events"></xref>, which shows a map of the
new <tt>ups.status</tt> response and the previous <tt>ups.status</tt>
response to an Event event, which is taken as the basis for Management Daemon action.
</t>
<section anchor="Notation">
<name>Notation Used in this Specification</name>
<t>The character set used for commands
and responses is US-ASCII, US-ASCII; see <xref target="RFC0020"></xref>.
</t>
<t>Multi-word elements are contained between
QUOTATION MARK
quotation mark characters for easier parsing. E.g., parsing, e.g., "UPS on
fire". Embedded quotation marks are escaped with  REVERSE SLANT \ reverse slant (\), often known as backslashes. Embedded
backslashes are also escaped by representing them as \\.
</t>
<t anchor="onenewline">Commands and responses have no leading or
trailing whitespace, blank space and are terminated with a single new
line character  LINE FEED line feed (LF).
</t>
<t>White
<t>Blank space within commands and responses is reduced to
one  SPACE space (SP).
</t>
</section>
<section anchor="commands">
<name>Commands</name>
<t>The commands address the UPS to which they apply
by <tt>&lt;upsname&gt;</tt> <tt>&lt;upsname&gt;</tt>, where</t>
<ul spacing="compact">
<li><tt>&lt;upsname&gt;</tt>
::= <tt>&lt;ups&gt;[@&lt;hostname&gt;[:&lt;port&gt;]]</tt>
</li>
<li><tt>&lt;ups&gt;</tt> is defined by the Attachment Daemon configuration files.
</li>
<li>The default <tt>&lt;hostname&gt;</tt> is <tt>localhost</tt> <tt>localhost</tt>.
</li>
<li>The <tt>&lt;port&gt;</tt> 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.
</li>
</ul>
<t>Examples: <tt>myups</tt>, <tt>UPS-97B@bigserver.example.com</tt>
</t> <tt>UPS-97B@bigserver.example.com</tt></t>
<t>ABNF: see See variable <tt>upsname</tt> in <xref target="fig.ABNF"></xref>.
</t> target="fig.ABNF"></xref>.</t>
<t>Note: Experimental Management Daemons use an extended form
of <tt>&lt;upsname&gt;</tt> in configuration files and in program
parameters, where where:
</t>
<ul spacing="compact">
<li><tt>&lt;upsname&gt;</tt> ::= <tt>[&lt;group&gt;:]&lt;ups&gt;[@&lt;hostname&gt;[:&lt;port&gt;]]</tt>
</li> <tt>[&lt;group&gt;:]&lt;ups&gt;[@&lt;hostname&gt;[:&lt;port&gt;]]</tt></li>
<li><tt>&lt;group&gt;</tt> is an experimental extension to provide for groups of UPSs.  It is not in common current practice.
</li> practice.</li>
<li><tt>&lt;ups&gt;</tt> is defined by the Attachment Daemon configuration files.
</li> files.</li>
<li>The default <tt>&lt;hostname&gt;</tt> is <tt>localhost</tt>
</li> <tt>localhost</tt>.</li>
</ul>
<t>Examples: <tt>ups-1@example.com:3493</tt>, <tt>HB:heartbeat1@example.com:3493</tt>
</t>
<aside>
<t><em>Implementation note:</em> In the current implementation,
the names of commands and subcommands are not case sensitive. For
example
example, <tt>GET VAR</tt> may be written as <tt>Get var</tt>, but in
this specification specification, they are always written in upper case. uppercase.
Similarly, <tt>&lt;upsname&gt;</tt> and <tt>&lt;varname&gt;</tt> are
not case sensitive.  For example example, <tt>UPS341 ups.id</tt> may be written
as <tt>ups341 Ups.Id</tt>, but in this
specification
specification, <tt>&lt;varname&gt;</tt> is always written in lower
case.
</t>
</aside>
<section anchor="attach">
<name><tt>ATTACH</tt></name>
<t>In a configuration such as that like the one shown
in <xref target="fig.oview4"></xref> target="fig.oview4"></xref>, in which a UPS protects more than
one system, the Primary Management Daemon needs to know how many Secondaries are
currently "<em>active</em>", <em>active</em>, 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 "<em>active</em>" <em>active</em> systems powered by a UPS.  The
count is initialised, initialized, one Secondary at a time by the <tt>ATTACH</tt>
command, which should be understood as "<em>count <em>count this Secondary as
active</em>".
active</em>.  <tt>ATTACH</tt> is one of three commands for Secondary
counting:
counting. Additionally, command <tt>DETACH</tt> decrements the count count, and a Management Daemon may
read the count at any time using the command <tt>NUMATTACH</tt>.
</t>
<t>The <tt>ATTACH</tt> command is also sent to the Attachment Daemon for the
Primary
Primary, so during normal, fully protected operation, the count is 1
for the Primary + the number of secondaries. Secondaries.  During a full system
shutdown, the count drops as each Secondary Management Daemon executes command
<tt>DETACH</tt> during its own shutdown.  When the count drops to 1, only
the Primary is "<em>active</em>" <em>active</em>, and it knows that all the secondaries Secondaries
have shut down.
</t>
<t>Command: <tt>ATTACH &lt;upsname&gt;</tt>
</t>
<t>If the command succeeds, the response is <tt>OK</tt>, otherwise <tt>OK</tt>; otherwise,
see the error responses in <xref target="errorresponses"></xref>.
</t>
<t>ABNF: See variable <tt>attach</tt> in <xref target="fig.ABNF"></xref>, target="fig.ABNF"></xref>.
</t>
<aside>
<t>Note: Historically, this command was known as <tt>LOGIN</tt>.
Since that
However, because <tt>LOGIN</tt> was not the conventional user access to a
shell or program program, the name was changed to avoid confusion.
</t> confusion.</t>
</aside>
</section>
<section anchor="detach">
<name><tt>DETACH</tt></name>
<t>This companion command to <tt>ATTACH</tt> reduces the count of
"active" Secondaries.  It should be understood as "<em>this <em>this Secondary
is no longer active</em>", active</em> and is usually used during system shutdown
to decrement a count of how many Secondaries are still "active". <em>active</em>.
</t>
<t>Command: <tt>DETACH</tt>
</t>
<t>If the command succeeds, the response is <tt>OK Goodbye</tt>,
otherwise Goodbye</tt>;
otherwise, see the error responses
in <xref target="errorresponses"></xref>.
</t>
<t>ABNF: See variable <tt>detach</tt> in <xref target="fig.ABNF"></xref>, target="fig.ABNF"></xref>.
</t>
<aside>
  <t>Note: Historically, this command was known as <tt>LOGOUT</tt>.
</t> <tt>LOGOUT</tt>.</t>
</aside>
</section>
<section anchor="FSD">
<name><tt>FSD</tt></name>
<t>A Management Daemon which that is Primary and has the required authority, authority uses this
command to set status symbol <tt>FSD</tt> <tt>FSD</tt>, meaning "Forced Shutdown" Shutdown", in
the Attachment Daemon.  In current practice practice, the Primary Management Daemon uses the symbol to
tell the Secondaries to shut down.
</t>
<t>Command: <tt>FSD &lt;upsname&gt;</tt>
</t>
<t>If the command succeeds, the response is <tt>OK FSD-SET</tt>,
otherwise FSD-SET</tt>;
otherwise, see the error responses in <xref target="errorresponses"></xref>.
</t>
<t>ABNF: See variable <tt>fsd</tt> in <xref target="fig.ABNF"></xref>.
</t>
<t>In current practice, commands such as <tt>FSD</tt> are made
available only to a privileged administrative user authorized to send
such a mission critical mission-critical command.    The security provisions for
administrative users are discussed in <xref target="adsec"></xref>.
</t>
<t>Note: The symbol "<tt>FSD</tt>" <tt>FSD</tt> is also used for an Event. event.
See <xref target="EventFSD"></xref>.
</t>
</section>
<section anchor="get">
<name><tt>GET</tt></name>
<t>Retrieve a single response from the Attachment Daemon.
</t>
<t>ABNF: See variable <tt>get</tt> in <xref target="fig.ABNF"></xref>.
</t>
<t>The possible sub-commands are: subcommands are listed in the sections below.
</t>
<section anchor="cmddesc">
<name><tt>GET CMDDESC</tt></name>
<t>Retrieve a text description of a command.
</t>
<t>Command: <tt>GET CMDDESC &lt;upsname&gt; &lt;cmdname&gt;</tt>
</t>
<t>Response:
<tt>CMDDESC &lt;upsname&gt; &lt;cmdname&gt; "&lt;description&gt;"</tt>
</t>
<t>For example: command <tt>GET CMDDESC su700 load.on</tt> and
response <tt>CMDDESC su700 load.on "Turn on the load immediately"</tt>
</t>
<t>This is like <tt>GET DESC</tt>, but it applies to an Instant Command;. Command.
See <xref target="desc"></xref>.
</t>
</section>
<section anchor="desc">
<name><tt>GET DESC</tt></name>
<t>Retrieve a text description of a UPS variable.  See <xref target="var"></xref>.
</t>
<t>Command: <tt>GET DESC &lt;upsname&gt; &lt;varname&gt;</tt>
</t>
<t>Response: <tt>DESC &lt;upsname&gt; &lt;varname&gt; "&lt;description&gt;"</tt>
</t>
<t>where <tt>&lt;description&gt;</tt>
<t><tt>&lt;description&gt;</tt> is a string that gives a brief
explanation of the named variable.  The Attachment Daemon <bcp14>MAY</bcp14> return
"Unavailable" if the file which that provides this description is not
installed.
</t>
<t>For example example: command <tt>GET DESC su700 ups.status</tt> and
response <tt>DESC su700 ups.status "UPS status"</tt>
</t>
</section>
<section anchor="numattach">
<name><tt>GET NUMATTACH</tt></name>
<t>Retrieve the count kept by the Attachment Daemon of all the "<em>active</em>" <em>active</em>
systems protected by this UPS.
</t>
<t>Command: <tt>GET NUMATTACH &lt;upsname&gt;</tt>
</t>
<t>Response: <tt>NUMATTACH &lt;upsname&gt; &lt;value&gt;</tt>
</t>
<t>where <tt>&lt;value&gt;</tt>
<t><tt>&lt;value&gt;</tt> is a count of the Primary and the
number of Secondaries currently powered by this UPS.
</t>
<t>For example example: command <tt>GET ATTACH su700</tt> and
response <tt>NUMATTACH su700 1</tt>
</t>
<t>This information is needed by the Management Daemon to determine how many
Secondaries are still connected during the system shutdown process.
</t>
<aside>
<t>Note: Historically, this sub-command subcommand was known
as <tt>NUMLOGINS</tt>.  Since <tt>LOGIN</tt> was not the conventional
user access to a shell or program program, the name was changed to avoid
confusion.
</t>
confusion.</t>
</aside>
</section>
<section anchor="type">
<name><tt>GET TYPE</tt></name>
<t>Retrieve the type of a UPS variable.  See <xref target="var"></xref>.
</t>
<t>Command: <tt>GET TYPE &lt;upsname&gt; &lt;varname&gt;</tt>
</t>
<t>Response: <tt>TYPE &lt;upsname&gt; &lt;varname&gt; &lt;type&gt;...</tt>
</t>
<t>where <tt>&lt;type&gt;...</tt>
<t><tt>&lt;type&gt;...</tt> can be one or more of the following
tokens.  Multiple types may be returned.
</t>
<t>For example example: command <tt>GET TYPE su700 input.transfer.low</tt> and
response <tt>TYPE su700 input.transfer.low ENUM</tt>
</t>
<table>
<name>Variable Types
</name> Types</name>
<thead>
<tr>
<th align="center">&nbsp;&nbsp;&nbsp;&nbsp;Type&nbsp;&nbsp;&nbsp;&nbsp;
    </th> align="center">&nbsp;&nbsp;&nbsp;&nbsp;Type&nbsp;&nbsp;&nbsp;&nbsp;</th>
<th align="center">Meaning
</th> align="center">Meaning</th>
</tr>
</thead>
<tbody>
<tr>
<td>RW </td>
<td>This is a read/write variable.  It may be read with
command <tt>GET VAR</tt>, see VAR</tt> (see <xref target="getvar"></xref>, target="getvar"></xref>) and set to a different value
with command <tt>SET</tt>, see <tt>SET</tt> (see <xref target="set"></xref>. target="set"></xref>).
</td>
</tr>
<tr>
<td>ENUM </td>
<td>An
<td>This is an enumerated type, which supports specific
predetermined values.
</td>
</tr>
<tr>
<td>STRING:n </td>
<td>This is a string of maximum
length <tt>n</tt>.
</td>
</tr>
<tr>
<td>RANGE </td>
<td><t>This is a number, either integer or float,
comprised in the range which that may be seen with the command <tt>LIST
RANGE</tt>, see
RANGE</tt> (see <xref target="range"></xref>. target="range"></xref>).
</t></td>
</tr>
<tr>
<td>NUMBER </td>
<td>This is a single numeric value, either
integer or float.
</td>
</tr>
</tbody>
</table>
<t>Notes:
</t>
<ul>
<ul spacing="normal">
<li>ENUM, STRING:n STRING:n, and RANGE are usually associated with RW, RW but
not always. The default &lt;type&gt;, when omitted, is numeric, so
either integer or float. Each Driver is then responsible for
handling values as either integer or float.
</li>
<li>Current practice is to represent floating point values using
 a decimal (base 10) US
English-based representation. Hexadecimal, Hexadecimals, exponents, and comma commas used as separators for
thousands separator are not allowed. For example: example, "1200.20" is valid,
while "1,200.20" and "1200,20" are not valid.
</li>
</ul>
</section>
<section anchor="upsdesc">
<name><tt>GET UPSDESC</tt></name>
<t>Retrieve a text description of a UPS.
</t>
<t>Command: <tt>GET UPSDESC &lt;upsname&gt;</tt>
</t>
<t>Response: <tt>UPSDESC &lt;upsname&gt; "&lt;description&gt;"</tt>
</t>
<t>where &lt;description&gt;
<t>&lt;description&gt; is defined by the Attachment Daemon configuration. If
it is not set, current practice is for the Attachment Daemon to return
"Unavailable".
</t>
<t>For example example: command <tt>GET UPSDESC su700</tt> and response
<tt>UPSDESC su700 "Development box"</tt>
</t>
<t>This can be used to provide human-readable descriptions descriptions, instead of
a cryptic <tt>ups@hostname</tt> string.
</t>
</section>
<section anchor="getvar">
<name><tt>GET VAR</tt></name>
<t>Retrieve the value of a UPS variable.  See <xref target="var"></xref>.
</t>
<t>Command: <tt>GET VAR &lt;upsname&gt;
&lt;varname&gt;</tt>
</t>
<t>Response: <tt>VAR &lt;upsname&gt; &lt;varname&gt; "&lt;value&gt;"</tt>
</t>
<t>For example example: command <tt>GET VAR su700 ups.status</tt> and response
<tt>VAR su700 ups.status "OB LB"</tt>
</t>
</section>
</section>
<section anchor="help">
<name><tt>HELP</tt></name>
<t>Return a list of the commands supported by the Attachment Daemon.  This command
is intended for human human, as well as program program, use.
</t>
<t>Command
<t>Command: <tt>HELP</tt>
</t>
<t>For example, example: the following command line sequence executed on an
Attachment Daemon:</t>
<sourcecode>netcat Daemon</t>
<sourcecode name="" type="shell">
netcat localhost 3493
HELP
Commands: HELP VER GET LIST SET INSTCMD ATTACH DETACH
    USERNAME PASSWORD STARTTLS</sourcecode> STARTTLS
</sourcecode>
<t>ABNF: See variable <tt>help</tt> in <xref target="fig.ABNF"></xref>.
</t>
<aside>
<t>Note: Historically, this command also returned <tt>LOGIN</tt>
and <tt>LOGOUT</tt>.  Since  Because <tt>LOGIN</tt> was not the conventional
user access to a shell or program, the command names were changed
to <tt>ATTACH</tt> and <tt>DETACH</tt> to avoid confusion.
</t> confusion.</t>
</aside>
</section>
<section anchor="instcmd">
<name><tt>INSTCMD</tt></name>
<t>Send an Instant Command to the UPS.
</t>
<t>Command: <tt>INSTCMD &lt;upsname&gt; &lt;cmdname&gt;</tt>
</t>
<t>where <tt>&lt;upsname&gt;</tt>
<t><tt>&lt;upsname&gt;</tt> is the name of the UPS UPS,
and <tt>&lt;cmdname&gt;</tt> is the Instant Command to be issued to
that UPS.  See <xref target="instcmdexamples"></xref> for examples of
instant commands.
Instant Commands.
</t>
<t>If the command succeeds, the response is <tt>OK</tt>, otherwise <tt>OK</tt>; otherwise,
see the error responses, responses in <xref target="errorresponses"></xref>.
</t>
<t>For example the command: example: command <tt>INSTCMD su700 test.panel.start</tt>
and the response <tt>OK</tt>
</t>
<t>ABNF: See variable <tt>instcmd</tt> in <xref target="fig.ABNF"></xref>.
</t>
</section>
<section anchor="list">
<name><tt>LIST</tt></name>
<t>All the <tt>LIST</tt> commands produce a response with a common
format. The response will begin begins with <tt>BEGIN LIST</tt> and then
repeat
repeats the initial query.  A list then follows, with as many lines as
are necessary.  The response ends with <tt>END LIST</tt> LIST</tt>, followed by
the initial query.
</t>
<t>The formatting may seem a bit redundant, but it makes a different
form of client possible.  A client can send a <tt>LIST</tt> 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.
</t>
<t>Note: The current NUT Project implementation of the
Attachment Daemon, <tt>upsd</tt>, sends back the response to the <tt>LIST</tt>
command as a sequence of messages.  The Management Daemon should continue reading
these messages until it receives the line beginning <tt>END LIST</tt>.
</t>
<t>ABNF: See the variable <tt>list</tt> in <xref target="fig.ABNF"></xref>.
</t>
<t>The possible subcommands are: are listed in the sections below.
</t>
<section anchor="client">
<name><tt>LIST CLIENT</tt></name>
<t>The command calls for the Attachment Daemon to report all the current Management Daemon
clients of a given UPS.
</t>
<t>Command: <tt>LIST CLIENT &lt;upsname&gt;</tt>
</t>
<t>The response
is
<t>Response:
</t>
<artwork>BEGIN
<sourcecode name="" type="shell">
BEGIN LIST CLIENT &lt;upsname&gt;
CLIENT &lt;upsname&gt; &lt;client_IP_address&gt;
...
END LIST CLIENT &lt;upsname&gt;
</artwork>
</sourcecode>
<t>For example, the example: command <tt>LIST CLIENT ups1</tt> and the response: response
</t>
<artwork>BEGIN
<sourcecode name="" type="shell">
BEGIN LIST CLIENT ups1
CLIENT ups1 ::1
CLIENT ups1 203.0.113.1
END LIST CLIENT ups1
</artwork>
</sourcecode>
</section>
<section anchor="cmd">
<name><tt>LIST CMD</tt></name>
<t>The command calls for the Attachment Daemon to report a list of the Instant
Commands which that 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 Commands, but a
professional model should support more.
</t>
<t>Command: <tt>LIST CMD &lt;upsname&gt;</tt>
</t>
<t>The response is:</t>
<sourcecode>BEGIN
<t>Response:</t>
<sourcecode name="" type="shell">
BEGIN LIST CMD &lt;upsname&gt;
CMD &lt;upsname&gt; &lt;cmdname&gt;
...
END LIST CMD &lt;upsname&gt;
</sourcecode>
<t>where <tt>&lt;upsname&gt;</tt>
<t><tt>&lt;upsname&gt;</tt> is the name of the UPS,
and <tt>&lt;cmdname&gt;</tt> is the name of the Instant Command which that
may be issued to the UPS.
</t>
<t>For example the command: example: command <tt>LIST CMD su700</tt> and the response: response
</t>
<sourcecode>BEGIN
<sourcecode name="" type="shell">
BEGIN LIST CMD su700
CMD su700 load.on
CMD su700 test.panel.start
...
END LIST CMD su700
</sourcecode>
</section>
<section anchor="enum">
<name><tt>LIST ENUM</tt></name>
<t>The command calls for the Attachment Daemon to report the set of possible
values of a UPS variable which that has predetermined values.
</t>
<t>Command: <tt>LIST ENUM &lt;upsname&gt; &lt;varname&gt;</tt>
</t>
<t>The response
is:</t>
<sourcecode>BEGIN
<t>Response:</t>
<sourcecode name="" type="shell">
BEGIN LIST ENUM &lt;upsname&gt; &lt;varname&gt;
ENUM &lt;upsname&gt; &lt;varname&gt; "&lt;value&gt;"
...
END LIST ENUM &lt;upsname&gt; &lt;varname&gt;
</sourcecode>
<t>where <tt>&lt;upsname&gt;</tt>
<t><tt>&lt;upsname&gt;</tt> is the name of the UPS,
<tt>&lt;varname&gt;</tt> is the UPS variable variable,
and <tt>&lt;value&gt;</tt> is one of the possible values of that UPS
variable.  Note that that, in current practice practice, the output is an unordered
list.  Note also  Also note that the  QUOTATION MARKS quotation marks are part of
the response.
</t>
<t>For example the command: example: command <tt>LIST ENUM su700 input.transfer.low</tt>
and the
response:</t>
<sourcecode>BEGIN response</t>
<sourcecode name="" type="shell">
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
</sourcecode>
</section>
<section anchor="range">
<name><tt>LIST RANGE</tt></name>
<t>The command calls for the Attachment Daemon to report the interval in which
valid values of UPS variable lie.
</t>
<t>Command: <tt>LIST RANGE &lt;upsname&gt; &lt;varname&gt;</tt>
</t>
<t>The response
is: </t>
<sourcecode>BEGIN
<t>Response:</t>
<sourcecode name="" type="shell">
BEGIN LIST RANGE &lt;upsname&gt; &lt;varname&gt;
RANGE &lt;upsname&gt; &lt;varname&gt; "&lt;min&gt;" "&lt;max&gt;"
...
END LIST RANGE &lt;upsname&gt; &lt;varname&gt;
</sourcecode>
<t>where <tt>&lt;upsname&gt;</tt>
<t><tt>&lt;upsname&gt;</tt> is the name of the UPS,
<tt>&lt;varname&gt;</tt> is the UPS variable variable, and
{<tt>&lt;min&gt;</tt>,<tt>&lt;max&gt;</tt>} is the interval of valid
values of that UPS variable.  Note that the  QUOTATION
MARKS quotation
marks are part of the response.
</t>
<t>For example, the example: command <tt>LIST RANGE su700
input.transfer.low</tt> and the response: response
</t>
<sourcecode>BEGIN
<sourcecode name="" type="shell">
BEGIN LIST RANGE su700 input.transfer.low
RANGE su700 input.transfer.low "90" "105"
END LIST RANGE su700 input.transfer.low
</sourcecode>
</section>
<section anchor="listrw">
<name><tt>LIST RW</tt></name>
<t>The command calls for the Attachment Daemon to report a list of the UPS
variables associated with a given UPS which that may be read and written by
the Management Daemon.  These variables are the abstracted view of the UPS
hardware capabilities.  An economical UPS may support few variables variables,
but a professional model should support at least the variables which that
are needed for an automatic shutdown and restart, restart;
see <xref target="shutdownstory"></xref>.  See
also  Also,
see <xref target="MinSup"></xref> for details of the recommended
minimum support of variables.  A full list of variables is available
in <xref target="gitvars">source code file docs/nut-names.txt</xref> docs/nut-names.txt</xref>,
which serves as the Recording Document.
</t>
<t>Command: <tt>LIST RW &lt;upsname&gt;</tt>
</t>
<t>The response is:</t>
<sourcecode>BEGIN
<t>Response:</t>
<sourcecode name="" type="shell">
BEGIN LIST RW &lt;upsname&gt;
RW &lt;upsname&gt; &lt;varname&gt; "&lt;value&gt;"
...
END LIST RW &lt;upsname&gt;
</sourcecode>
<t>where <tt>&lt;upsname&gt;</tt>
<t><tt>&lt;upsname&gt;</tt> is the name of the UPS,
<tt>&lt;varname&gt;</tt> is the UPS variable variable, and
<tt>&lt;value&gt;</tt> is the value of that UPS variable.  Note that
the  QUOTATION MARKS quotation marks are part of the response.
</t>
<t>For example the command: example: command <tt>LIST RW su700</tt> and the response: response
</t>
<sourcecode>BEGIN
<sourcecode name="" type="shell">
BEGIN LIST RW su700
RW su700 output.voltage.nominal "115"
RW su700 ups.delay.shutdown "020"
...
END LIST RW su700
</sourcecode>
</section>
<section anchor="ups">
<name><tt>LIST UPS</tt></name>
<t>The command calls for the Attachment Daemon to report a list of the UPS units
to which it is attached.
</t>
<t>Command: <tt>LIST UPS</tt>
</t>
<t>The response is:</t>
<sourcecode>BEGIN
<t>Response:</t>
<sourcecode name="" type="shell">
BEGIN LIST UPS
UPS &lt;upsname&gt; "&lt;description&gt;"
...
END LIST UPS
</sourcecode>
<t>where <tt>&lt;upsname&gt;</tt>
<t><tt>&lt;upsname&gt;</tt> is the name of a UPS, and
<tt>&lt;description&gt;</tt> is the description maintained by the
Attachment Daemon Daemon, if available. It is set to "Unavailable" otherwise.  Note that
the  QUOTATION MARKS quotation marks are part of the response.
</t>
<t>This command can also be used to determine what values of
<tt>&lt;upsname&gt;</tt> 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. UPSs.  It is also useful for clients
which
that perform a UPS discovery process.
</t>
<t>For example, the response: example: response
</t>
<sourcecode>BEGIN
<sourcecode name="" type="shell">
BEGIN LIST UPS
UPS su700 "Development box"
END LIST UPS
</sourcecode>
</section>
<section anchor="listvar">
<name><tt>LIST VAR</tt></name>
<t>The command calls for the Attachment Daemon to report a list of all the UPS
variables which that it maintains for a given UPS, UPS and the values of those
UPS variables.
</t>
<t>Command: <tt>LIST VAR &lt;upsname&gt;</tt>
</t>
<t>The response is:</t>
<sourcecode>BEGIN
<t>Response:</t>
<sourcecode name="" type="shell">
BEGIN LIST VAR &lt;upsname&gt;
VAR &lt;upsname&gt; &lt;varname&gt; "&lt;value&gt;"
...
END LIST VAR &lt;upsname&gt;
</sourcecode>
<t>where <tt>&lt;upsname&gt;</tt>
<t><tt>&lt;upsname&gt;</tt> is the name of the UPS,
<tt>&lt;varname&gt;</tt> is the UPS variable variable, and
<tt>&lt;value&gt;</tt> is the value of that variable.  Note that
the  QUOTATION MARKS quotation marks are part of the response.
</t>
<t>The response to this command lists the UPS variables available for
this UPS and their current values.  For example the values.</t>
<t>For example: command <tt>LIST VAR su700</tt> and the response: response
</t>
<sourcecode>BEGIN
<sourcecode name="" type="shell">
BEGIN LIST VAR su700
VAR su700 ups.mfr "Example Mfg"
VAR su700 ups.mfr.date "10/17/96"
...
END LIST VAR su700</sourcecode> su700
</sourcecode>
<t>See
<xref target="MinSup"></xref> for details of the recommended minimum
support of variables.  A full list of variables is available
in <xref target="gitvars">source code file docs/nut-names.txt</xref> docs/nut-names.txt</xref>,
which serves as the Recording Document.
</t>
</section>
</section>
<section anchor="password">
<name><tt>PASSWORD</tt></name>
<t>This command is a companion to <tt>USERNAME</tt>, <tt>USERNAME</tt> and is used by a
Management Daemon to specify the password required to enter a Session session with the
Attachment Daemon, Daemon; see <xref target="sess"></xref>.
</t>
<t>Command: <tt>PASSWORD &lt;password&gt;</tt>
</t>
<t>If the command succeeds, the response is <tt>OK</tt>, otherwise <tt>OK</tt>; otherwise, see
the error responses, responses in <xref target="errorresponses"></xref>.
</t>
<t>For examples of the use of commands <tt>USERNAME</tt>
and <tt>PASSWORD</tt> by administrative users,
see <xref target="adsecclient"></xref>.
</t>
<t>ABNF: See variable <tt>password</tt> <tt>session-password</tt> in <xref target="fig.ABNF"></xref>.
</t>
</section>
<section anchor="primary">
<name><tt>PRIMARY</tt></name>
<t>In current practice, the Attachment Daemon records in local
file <tt>upsd.users</tt> that an administrative user is a Primary.
See <xref target="adminuser"></xref> for an example.  When a Management Daemon
starts up and opens a Session session with the Attachment Daemon, it lays claim to being a
Primary by sending command <tt>PRIMARY</tt> to the Attachment Daemon, thus
claiming that it has the required authority to perform such critical
actions
actions, such as setting status symbol <tt>FSD</tt>.
</t>
<t>Command: <tt>PRIMARY &lt;upsname&gt;</tt>
</t>
<t>where <tt>&lt;upsname&gt;</tt>
<t><tt>&lt;upsname&gt;</tt> is the name of the UPS.
</t>
<t>If the Attachment Daemon has the authority, the response is <tt>OK</tt>,
otherwise <tt>OK</tt>;
otherwise, see the error
responses in <xref target="errorresponses"></xref>.
</t>
<aside>
  <t>Note: Historically, this command was known as <tt>MASTER</tt>.
</t> <tt>MASTER</tt>.</t>
</aside>
</section>
<section anchor="protver">
<name><tt>PROTVER</tt></name>
<t>Return the version of the command/response protocol
used by the Attachment Daemon.  This command is intended for human human, as well as
program
program, use.
</t>
<t>Command
<t>Command: <tt>PROTVER</tt>
</t>
<t>For example, example: the following command line sequence in the Attachment Daemon: Daemon
</t>
<sourcecode>netcat
<sourcecode name="" type="shell">
netcat localhost 3493
PROTVER
1.3</sourcecode>
1.3
</sourcecode>
<t>Notes:
</t>
<ol spacing="compact" indent="adaptive">
<li>There are no  QUOTATION MARKS quotation marks in the response.
</li>
<li>The version of the protocol returned by <tt>PROTVER</tt> is
different to than the implementation version of the Attachment Daemon returned
by <tt>VER</tt>.
</li>
<li>To ease migration, NUT version 2.8.0 also supports the
equivalent <tt>NETVER</tt> command used in previous
releases. See <xref target="Version.2.7.4"></xref>.
</li>
</ol>
<t>ABNF: See variable <tt>protver</tt> in <xref target="fig.ABNF"></xref>.
</t>
</section>
<section anchor="set">
<name><tt>SET</tt></name>
<t>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. Driver.
</t>
<t>Command: <tt>SET VAR &lt;upsname&gt; &lt;varname&gt;
"&lt;value&gt;"</tt>
</t>
<t>where <tt>&lt;upsname&gt;</tt>
<t><tt>&lt;upsname&gt;</tt> is the name of the UPS,
<tt>&lt;varname&gt;</tt> is the UPS variable variable, and
<tt>&lt;value&gt;</tt> is the value to be assigned to that variable.
Note that the  QUOTATION MARKS quotation marks are part of the command.
</t>
<t>If the command succeeds, the response is <tt>OK</tt>, otherwise <tt>OK</tt>; otherwise, see
the error responses in <xref target="errorresponses"></xref>.
</t>
<t>For example the command: example: command <tt>SET VAR su700 ups.id "My UPS"</tt> and
the
response <tt>OK</tt>
</t>
<t>ABNF: See the variable <tt>set</tt> in <xref target="fig.ABNF"></xref>.
</t>
</section>
<section anchor="starttls">
<name><tt>STARTTLS</tt></name>
<t>The client tells the Attachment Daemon to switch to communication encrypted by
TLS <xref target="RFC8446"></xref> encrypted communication. target="RFC8446"></xref>.  When the
client receives <tt>OK</tt> <tt>OK</tt>, it also switches to TLS encryption.
</t>
<t>Command: <tt>STARTTLS</tt>
</t>
<t>If the command succeeds, the response is <tt>OK STARTTLS</tt>,
otherwise STARTTLS</tt>;
otherwise, see the error responses
in <xref target="errorresponses"></xref>.
</t>
<t>If the client does not send command STARTTLS to the Attachment Daemon Daemon,
communication continues unencrypted, however unencrypted; however, an Attachment Daemon <bcp14>MAY</bcp14> refuse
unencrypted communication.
</t>
<t>NUT 2.8.0 supports the encryption of communications between the
Attachment Daemon and the Management Daemon using TLS
1.3 <xref target="RFC8446"></xref> with X.509 v3 certificates certificates, as
defined by <xref target="RFC5280"></xref> and updates.
See <xref target="AppendixEavesdropping"></xref> for details of the
encryption of communications in previous relase release 2.7.4.
</t>
<t>ABNF: See variable <tt>starttls</tt> in <xref target="fig.ABNF"></xref>.
</t>
<section anchor="selfsigned">
<name>Key Infrastructure and Self-signed Self-Signed Certificates</name>
<t><em>The very restricted nature of UPS management makes it of
interest to consider self-signed certificates.</em>
</t>
<t>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 the client and server requires that the browsers carry a list of
Certificate Authorities which that the clients have to trust.  <em>This is
a many-to-many relationship.</em>
</t>
<t>The management of UPS units is not a many-to-many relationship, relationship; it
is frequently one-to-one. 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 Web, the
server administrators know exactly who they are.  These clients visit
very few servers, typically one only.  This situation is totally
different to from the World Wide Web.  The use of external Certificate
Authorities is a potential security weakness that must be accepted for
the World Wide Web, Web but which can be avoided for UPS management by
either generating locally the private and public keys, or keys locally or, for larger
organisations,
organizations, using a Private Key Infrastructure.. PKI.
</t>
<t>The security policies for UPS management may be subordinate to an
organisation's
organization's own internal IT security plans and procedures, possibly
based on <xref target="RFC7030"></xref>
and <xref target="RFC8894"></xref>, but in simple cases cases, it is possible
to obtain better security using self-signed certificates.
</t>
</section>
</section>
<section anchor="username">
<name><tt>USERNAME</tt></name>
<t>The Attachment Daemon limits access to clients whose credentials match those in
the file <tt>upsd.users</tt>.  There is no anonymous access.  A Management Daemon
program or script uses command <tt>USERNAME</tt> and its companion
command <tt>PASSWORD</tt> to open a Session 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.
</t>
<t>Command: <tt>USERNAME &lt;username&gt;</tt>
</t>
<t>If the command succeeds, the response is <tt>OK</tt>, otherwise <tt>OK</tt>; otherwise, see
the error responses in <xref target="errorresponses"></xref>.
</t>
<t>For examples of the use of commands <tt>USERNAME</tt> and
<tt>PASSWORD</tt> by administrative users,
see <xref target="adsecclient"></xref>.
</t>
<t>ABNF: See variable <tt>username</tt> <tt>session-username</tt> in <xref target="fig.ABNF"></xref>.
</t>
</section>
<section anchor="ver">
<name><tt>VER</tt></name>
<t>Return the implementation version of the Attachment Daemon.  This command is
intended for human human, as well as program program, use.
</t>
<t>Command
<t>Command: <tt>VER</tt>
</t>
<t>For example, example: the following command line sequence: sequence
</t>
<sourcecode>netcat
<sourcecode name="" type="shell">
netcat localhost 3493
VER
Network UPS Tools upsd 2.8.0 - http://www.networkupstools.org/
</sourcecode>
<t>Notes:
</t>
<ol spacing="compact" indent="adaptive">
<li>There are no  QUOTATION MARKS quotation marks in the response.
</li>
<li>The implementation version of the Attachment Daemon returned by VER is
different to than the protocol version returned by <tt>PROTVER</tt>.
</li>
</ol>
<t>ABNF: See variable <tt>ver</tt> in <xref target="fig.ABNF"></xref>.
</t>
</section>
</section>
<section anchor="responses">
<name>Summary of Responses</name>
<section anchor="success">
<name>Response when When Command Succeeds</name>
<t>If the command succeeds, the response has the following
command-dependent form:
</t>
<table>
<name>Response if command succeeds
</name> If Command Succeeds</name>
<thead>
<tr>
<th>Command           </th>
<th>Response             </th>
<th>Reference   </th>
<th>Note
</th>
<th>Command</th>
<th>Response</th>
<th>Reference</th>
<th>Note</th>
</tr>
</thead>
<tbody>
<tr>
<td><tt>ATTACH</tt>   </td>
<td><tt>OK</tt>          </td>
<td><tt>ATTACH</tt></td>
<td><tt>OK</tt></td>
<td><xref target="attach"></xref>   </td> target="attach"></xref></td>
<td>Was LOGIN  </td>
</tr>
<tr>
<td><tt>DETACH</tt>   </td>
<td><tt>DETACH</tt></td>
<td><tt>OK Goodbye</tt>  </td> Goodbye</tt></td>
<td><xref target="detach"></xref>   </td> target="detach"></xref></td>
<td>Was LOGOUT         </td>
</tr>
<tr>
<td><tt>FSD</tt>      </td>
<td><tt>FSD</tt></td>
<td><tt>OK FSD-SET</tt>  </td> FSD-SET</tt></td>
<td><xref target="FSD"></xref>      </td>
<td>
</td> target="FSD"></xref></td>
<td></td>
</tr>
<tr>
<td><tt>GET</tt>      </td>
<td>Sub command specific </td>
<td><tt>GET</tt></td>
<td>Subcommand specific</td>
<td><xref target="get"></xref>      </td>
<td>
</td> target="get"></xref></td>
<td></td>
</tr>
<tr>
<td><tt>HELP</tt>     </td>
<td><tt>HELP</tt></td>
<td>List of commands     </td> commands</td>
<td><xref target="help"></xref>     </td>
<td>
</td> target="help"></xref></td>
<td></td>
</tr>
<tr>
<td><tt>INSTCMD</tt>  </td>
<td><tt>OK </tt>         </td>
<td><tt>INSTCMD</tt></td>
<td><tt>OK</tt></td>
<td><xref target="instcmd"></xref>  </td>
<td>
</td> target="instcmd"></xref></td>
<td></td>
</tr>
<tr>
<td><tt>LIST</tt>     </td>
<td>Sub command specific </td>
<td><tt>LIST</tt></td>
<td>Subcommand specific</td>
<td><xref target="list"></xref>     </td>
<td>
</td> target="list"></xref></td>
<td></td>
</tr>
<tr>
<td><tt>PASSWORD</tt> </td>
<td><tt>OK</tt>          </td>
<td><tt>PASSWORD</tt></td>
<td><tt>OK</tt></td>
<td><xref target="password"></xref> </td>
<td>
</td> target="password"></xref></td>
<td></td>
</tr>
<tr>
<td><tt>PRIMARY</tt> </td>
<td><tt>OK</tt>          </td>
<td><tt>OK</tt></td>
<td><xref target="primary"></xref>  </td>
<td>
</td> target="primary"></xref></td>
<td></td>
</tr>
<tr>
<td><tt>PROTVER</tt>  </td>
<td><tt>PROTVER</tt></td>
<td>Protocol version     </td> version</td>
<td><xref target="protver"></xref>  </td> target="protver"></xref></td>
<td>Was NETVER
</td> NETVER</td>
</tr>
<tr>
<td><tt>SET</tt>      </td>
<td><tt>OK</tt>          </td>
<td><tt>SET</tt></td>
<td><tt>OK</tt></td>
<td><xref target="set"></xref>	   </td>
<td>
</td> target="set"></xref></td>
<td></td>
</tr>
<tr>
<td><tt>STARTTLS</tt> </td>
<td><tt>STARTTLS</tt></td>
<td><tt>OK STARTTLS</tt> </td> STARTTLS</tt></td>
<td><xref target="starttls"></xref> </td>
<td>
</td> target="starttls"></xref></td>
<td></td>
</tr>
<tr>
<td><tt>USERNAME</tt> </td>
<td><tt>OK</tt>          </td>
<td><tt>USERNAME</tt></td>
<td><tt>OK</tt></td>
<td><xref target="username"></xref> </td>
<td>
</td> target="username"></xref></td>
<td></td>
</tr>
<tr>
<td><tt>VER</tt>      </td>
<td><tt>VER</tt></td>
<td>Program version      </td> version</td>
<td><xref target="ver"></xref>	   </td>
<td>
</td> target="ver"></xref></td>
<td></td>
</tr>
</tbody>
</table>
</section>
<section anchor="errorresponses">
<name>Error Responses</name>
<t>Error responses have the following format:
</t>
<sourcecode>ERR
<sourcecode name="" type="shell">
ERR &lt;error-name&gt; [&lt;extra&gt;]
</sourcecode>
<t>where <tt>&lt;error-name&gt;</tt>
<t><tt>&lt;error-name&gt;</tt> is a single word token taken from
the 27 characters A-Z and  HYPHEN
(MINUS). hyphen
(-). Implementations <bcp14>MAY</bcp14> <bcp14>MAY</bcp14>, if needed needed, add an additional additional,
optional <tt>&lt;extra&gt;</tt>.  Current practice does not make use
of this possibility.
</t>
<t>The <tt>&lt;error-name&gt;</tt> may have one of the following
values:
</t>
<table anchor="errors">
<name>Error responses
</name> Responses</name>
<thead>
<tr>
<th align="center">&nbsp;&nbsp;&nbsp;&nbsp;The&nbsp;error&nbsp;name&nbsp;token&nbsp;&nbsp;&nbsp;&nbsp;
               <br/><tt>&lt;error-name&gt;</tt>
    </th> align="center">&nbsp;&nbsp;&nbsp;&nbsp;The&nbsp;Error&nbsp;Name&nbsp;Token&nbsp;&nbsp;&nbsp;&nbsp;
               <br/><tt>&lt;error-name&gt;</tt></th>
<th align="center">Meaning
</th> align="center">Meaning</th>
</tr>
</thead>
<tbody>
<tr>
<td><tt>ACCESS-DENIED</tt></td>
<td>The client's host and/or
authentication details supplied by <tt>USERNAME</tt>
and <tt>PASSWORD</tt> are not sufficient to execute the requested
command.
</td>
command.</td>
</tr>
<tr>
<td><tt>ALREADY-ATTACHED</tt></td>
<td><t>The client has already sent a
successful <tt>ATTACH</tt> command for a given UPS and can't do it again.
</t><t>Note: Historically, this error response was <tt>ALREADY-LOGGED-IN</tt>.
</t></td> again.</t>
</td>
</tr>
<tr>
<td><tt>ALREADY-SET-PASSWORD</tt></td>
<td>The client has already
supplied a <tt>PASSWORD</tt> and is attempting to repeat the command
in the same Session.
</td> session.</td>
</tr>
<tr>
<td><tt>ALREADY-SET-USERNAME</tt></td>
<td>The client has already
supplied a <tt>USERNAME</tt>, <tt>USERNAME</tt> and is attempting to repeat the command
within the same Session.
</td> session.</td>
</tr>
<tr>
<td><tt>CMD-NOT-SUPPORTED</tt></td>
<td>The specified UPS doesn't
support the Instant Command.
</td> Command.</td>
</tr>
<tr>
<td><tt>DATA-STALE</tt></td>
<td><t>The Attachment Daemon is connected to the
Driver for the UPS, but that driver 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.
</t><t>This readings.</t>
<t>This generally means that the Driver is running, but it has lost
communication with the hardware. Check the physical connection to the
equipment.
</t></td>
</tr>
<tr>
<td><tt>DRIVER-NOT-CONNECTED</tt></td>
<td>The Attachment Daemon can't perform the
requested command, since the Driver for that UPS is not
connected. This usually means that the driver Driver is not running, or running or, if it
is, is misconfigured.
</td> misconfigured.</td>
</tr>
<tr>
<td><tt>FEATURE-NOT-CONFIGURED</tt></td>
<td>This instance of the Attachment Daemon
hasn't been configured properly to allow the requested feature to
operate. In current practice practice, this error response is possible only for
command <tt>STARTTLS</tt>.
</td> <tt>STARTTLS</tt>.</td>
</tr>
<tr>
<td><tt>FEATURE-NOT-SUPPORTED</tt></td>
<td>This instance of Attachment Daemon does
not support the requested feature.  In current practice practice, this error
response is possible only for command <tt>STARTTLS</tt>.
</td> <tt>STARTTLS</tt>.</td>
</tr>
<tr>
<td><tt>INSTCMD-FAILED</tt></td>
<td>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.
</td>
Driver.</td>
</tr>
<tr>
<td><tt>INVALID-ARGUMENT</tt></td>
<td>The client sent an argument to a
command which that is not recognized or is otherwise not valid in this
context. This is typically caused by sending a valid command command, such as
<tt>GET</tt>
<tt>GET</tt>, with a subcommand which that is not valid.
</td> valid.</td>
</tr>
<tr>
<td><tt>INVALID-PASSWORD</tt></td>
<td>The client sent a non valid
<tt>PASSWORD</tt>.
</td> nonvalid
<tt>PASSWORD</tt>.</td>
</tr>
<tr>
<td><tt>INVALID-USERNAME</tt></td>
<td>The client sent an non valid
<tt>USERNAME</tt>.
</td> a nonvalid
<tt>USERNAME</tt>.</td>
</tr>
<tr>
<td><tt>INVALID-VALUE</tt></td>
<td>The value specified in the request
is not valid. This usually applies to a <tt>SET</tt> of
an <tt>ENUM</tt> type which that is using a value not in the list of
allowed values.  See <xref target="enum"></xref>.
</td> target="enum"></xref>.</td>
</tr>
<tr>
<td><tt>PASSWORD-REQUIRED</tt></td>
<td><tt>PASSWORD-<bcp14>REQUIRED</bcp14></tt></td>
<td>The command requires
a <tt>PASSWORD</tt> for authentication, but the client hasn't provided
one.
</td>
one.</td>
</tr>
<tr>
<td><tt>READONLY</tt></td>
<td>The requested variable in a <tt>SET</tt>
command is not writable.
</td> writable.</td>
</tr>
<tr>
<td><tt>SET-FAILED</tt></td>
<td>The Attachment Daemon failed to deliver
the <tt>SET</tt> request to the Driver. This is similar
to <tt>INSTCMD-FAILED</tt>.
</td> <tt>INSTCMD-FAILED</tt>.</td>
</tr>
<tr>
<td><tt>TLS-ALREADY-ENABLED</tt></td>
<td><t>TLS mode is already enabled
on this connection, so the Attachment Daemon can't start it again.
</t><t>Note: Historically, this message was <tt>ALREADY-SSL-MODE.</tt>
</t></td>
</tr>
<tr>
<td><tt>TLS-NOT-ENABLED</tt></td>
<td><t>TLS mode is required but has
not yet been enabled on this connection, so the Attachment Daemon can't send
commands.
</t><t>Note:
commands.</t>
<t>Note: This message is experimental and not in current common
use.
</t></td>
use.</t></td>
</tr>
<tr>
<td><tt>TOO-LONG</tt></td>
<td>The requested value in a <tt>SET</tt>
command is too long.
</td> long.</td>
</tr>
<tr>
<td><tt>UNKNOWN-COMMAND</tt></td>
<td>The Attachment Daemon doesn't recognize the
command.
</td>
command.</td>
</tr>
<tr>
<td><tt>UNKNOWN-UPS</tt></td>
<td>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.
</td> configuration.</td>
</tr>
<tr>
<td><tt>USERNAME-REQUIRED</tt></td>
<td><tt>USERNAME-<bcp14>REQUIRED</bcp14></tt></td>
<td>The command requires
a <tt>USERNAME</tt> for authentication, but the client hasn't provided
one.
</td>
one.</td>
</tr>
<tr>
<td><tt>VAR-NOT-SUPPORTED</tt></td>
<td>The specified UPS doesn't
support the UPS variable in the command.
</td> command.</td>
</tr>
</tbody>
</table>
<aside>
  <t>Note: Historically, this error response was <tt>ALREADY-LOGGED-IN</tt>.</t>
</aside>
</section>
</section>
<section anchor="ABNF">
<name>An ABNF of the Commands</name>
<t>This section repeats the syntax of <xref target="commands"></xref>, target="commands"></xref>
but in Augmented Bachus-Naur Backus-Naur Form (ABNF).  It does not define any
additional feature. features.  For further details of each command and the
response, see <xref target="commands"></xref>.
</t>
<t>The commands may be presented in ABNF
<xref target="RFC5234"></xref><xref target="RFC7405"></xref>, target="RFC5234"></xref> <xref target="RFC7405"></xref> and
represented using ASCII US-ASCII <xref target="RFC0020"></xref>.
</t>
<t>Current practice tolerates mixed case mixed-case command names, but it is
<bcp14>RECOMMENDED</bcp14> to use upper case uppercase only for commands.
See <xref target="fig.ABNF"></xref>.
</t>
<figure anchor="fig.ABNF" align="center">
<name>ABNF for the Commands
</name>
<sourcecode type="abnf">
;-------------------------------------------------------------------
; This grammar is case sensitive. Terminal keywords SHOULD be
; written in upper case uppercase, as shown.
; The following basic rules written with upper case uppercase names are
; taken from RFC5234 RFC 5234, Appendix B.1.
   SP = 1*%x20                  ; At least one SPACE
   LF = %x0A                    ; Linefeed
   DIGIT = %x30-39              ; Digit 0 through 9
   ALPHA =  %x41-5A / %x61-7A   ; A-Z / a-z
   DQUOTE = %x22                ; Double quote "
   VCHAR = %x21-7E              ; Visible (printing) characters
; Additional basic rules needed by this grammar
   LC = %x61-7A                 ; Letter a through z
   DOT = 1%x2E                  ; Exactly one .
   COLON = 1%x3A                ; Exactly one :
   AT = 1%x40                   ; Exactly one @
   SEP = 1"-" / 1"_" / 1"."     ; A single - or _ or .
   JOIN = COLON / AT            ; A single : or @
; Frequently used in this grammar
   cmdname = 1*LC *62(DOT 1*LC) ; E.g. E.g., load.off.delay
   upschar = DIGIT / ALPHA / SEP
   ups = 1*ALPHA *62upschar     ; E.g. E.g., Example-Mfg-999
   group = ups                  ; E.g. E.g., HB  (Not in common use)
   hostname = ups               ; E.g. E.g., example.com
   port = 1*5DIGIT              ; E.g. E.g., 3493
   upsname = [group COLON] ups [AT hostname [COLON port]]
                                ; Fully Qualified UPS name
                                ; E.g. E.g.,
                                ; HB:heartbeat1@example.com:3493
   username = ups               ; E.g. E.g., Power-Dept.6
   varname = 1*LC *62( DOT 1*(DIGIT / LC) )
                                ; E.g. E.g., outlet.1.status
;-------------------------------------------------------------------
   commandLine = command LF     ; LF is a single %x0A
   command = attach / detach / fsd / get / help / instcmd /
             list / password / primary / protver / set /
             starttls / username / ver
;
   attach  = "ATTACH" SP upsname
;
   detach = "DETACH"
;
   fsd = "FSD" SP upsname
;
   get = "GET" SP getsubcommnd
   getsubcommand = getcmddesc / getdesc / getnumattach /
                   gettype / getupsdesc / getvar
;
   getcmddesc =   "CMDDESC" SP upsname SP cmdname
   getdesc =      "DESC" SP upsname SP varname
   getnumattach = "NUMATTACH" SP upsname
   gettype =      "TYPE" SP upsname SP varname
   getupsdesc =   "UPSDESC" SP upsname
   getvar =       "VAR" SP upsname SP varname
;
   help = "HELP"
;
   instcmd = "INSTCMD" SP upsname SP cmdname
;
   list = "LIST" listsubcommand
   listsubcommand = listclient / listcmd / listenum / listrange /
                    listrw / listups / listvar
;
   listclient = "CLIENT" SP upsname
   listcmd =    "CMD" SP upsname
   listenum =   "ENUM" SP upsname SP varname
   listrange =  "RANGE" SP upsname SP varname
   listrw =     "RW" SP upsname
   listups =    "UPS"
   listvar =    "VAR" SP upsname
;
   password
   session-password = "PASSWORD" SP *63VCHAR
                         ; A sequence of printable characters defined
                         ; in a server configuration file.  Local
                         ; security practices may mandate a minimum
                         ; and maximum number of characters.
;
   primary = "PRIMARY" SP upsname
;
   protver = "PROTVER"
;
   value = *63VCHAR      ; Local practices may limit the choice of
                         ; characters, characters and require non US-ASCII. non-US-ASCII.
   set = "SET" SP %s"VAR" SP upsname SP varname SP
         DQUOTE value DQUOTE
;
   starttls = "STARTTLS"
;
   username
   session-username = "USERNAME" SP username
;
   ver = "VER"
;-------------------------------------------------------------------
</sourcecode>
</figure>
<t>Notes:
</t>
<t>Notes:</t>
<ol spacing="normal" indent="adaptive">
<li><em>Implementation note:</em> The ABNF is written using the
provisions
of <xref target="RFC5234"></xref> and <xref target="RFC7405"></xref> target="RFC7405"></xref>, which
are <xref target="RFC0020">US-ASCII based</xref>.
</li> based</xref>.</li>
<li>The grammar is case sensitive.  The terminal key words <bcp14>SHOULD</bcp14>
be written in upper case uppercase, as specified.
</li> specified.</li>
<li>The repetition factor in front of an expression has the form
&lt;min&gt;*&lt;max&gt;
&lt;min&gt;*&lt;max&gt;, where &lt;min&gt; is the minimum number of
repetitions
repetitions, and &lt;max&gt; is the maximum number.
</li> number.</li>
<li>If &lt;min&gt; is omitted omitted, its value is 0.  If &lt;max&gt; is
omitted, its value is infinity.
</li> infinity.</li>
<li>The notation <tt>n*n</tt> <tt>n*n</tt>, meaning "exactly n copies" copies", may be
written as <tt>n</tt>.
</li> <tt>n</tt>.</li>
<li>Square brackets around an expression mean that the expression is
optional.  This could be written as <tt>0*1</tt>.
</li> <tt>0*1</tt>.</li>
</ol>
<section anchor="ABNF-resp">
<name>Responses to Commands</name>
<t>The responses to the commands are encoded
in <xref target="RFC0020">US-ASCII</xref> and fall into two groups:
</t>
<ol spacing="normal" indent="adaptive">
<li>Short replies to action commands, commands; see <xref target="responses"></xref>.
</li> target="responses"></xref>.</li>
<li>Long replies to requests for information.  In this case case, the reply
is sent in a sequence of messages. The last message will contain a
line beginning <tt>END LIST</tt> .  See for
example For
example, see <xref target="client"></xref>.
</li> target="client"></xref>.</li>
</ol>
</section>
</section>
</section>
<section>
<name>Statuses and Events</name>
<section anchor="symbols">
<name>Status Symbols</name>
<t>These symbols resume the abstracted view of the UPS hardware
maintained by the Attachment Daemon.  The variable <tt>ups.status</tt> contains
one or more space-separated status symbols symbols, which together describe the
UPS state at that instant.  In current practice practice, the Management Daemon will poll
variable <tt>ups.status</tt> every 5 seconds with a command command, such
as <tt>GET VAR su700 ups.status</tt> ups.status</tt>, and response a response, such as <tt>VAR
su700 ups.status "OB LB"</tt> LB"</tt>, to discover changes in the UPS status.
These changes will indicate UPS events.
</t>
<table>
<name>UPS Status Symbols
</name> Symbols</name>
<thead>
<tr>
<th align="center">Status Symbol </th>
<th align="center">Meaning
</th> align="center">Meaning</th>
</tr>
</thead>
<tbody>
<tr>
<td><tt>ALARM</tt>
</td>
<td><tt>ALARM</tt></td>
<td>The UPS reports that it requires intervention.
</td> intervention.</td>
</tr>
<tr>
<td><tt>BOOST</tt>
</td>
<td><tt>BOOST</tt></td>
<td>The UPS has determined that the voltage level of the public power supply is
too low, low and is boosting it to the required level.  The UPS continues
to supply the protected system from the public power supply.
</td> supply.</td>
</tr>
<tr>
<td><tt>BYPASS</tt>
</td>
<td><tt>BYPASS</tt></td>
<td>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.
</td> system.</td>
</tr>
<tr>
<td><tt>CAL</tt>
</td>
<td><tt>CAL</tt></td>
<td>The UPS is calibrating itself, for example example, to determine at what
charge the <tt>LB</tt> status is raised or lowered.
</td> lowered.</td>
</tr>
<tr>
<td><tt>CHRG</tt>
</td>
<td><tt>CHRG</tt></td>
<td><t>The UPS battery is charging.  This usually implies that the UPS
also has status <tt>OL</tt>, <tt>OL</tt> but may not be the case if the UPS also has
status <tt>OFF</tt>.
</t></td>
</tr>
<tr>
<td><tt>COMM</tt>
</td>
<td><tt>COMM</tt></td>
<td>The Attachment Daemon has effective contact with the UPS.
</td> UPS.</td>
</tr>
<tr>
<td><tt>DISCHRG</tt>
</td>
<td><tt>DISCHRG</tt></td>
<td><t>The UPS battery is discharging.  This usually implies that the UPS
also has status <tt>OB</tt>, <tt>OB</tt> but may not be the case if the UPS also has
status <tt>OFF</tt>.
</t></td>
</tr>
<tr>
<td><tt>FSD</tt>
</td>
<td><tt>FSD</tt></td>
<td>This "Forced Shutdown" status signals that the final shutdown
sequence has begun.
</td> begun.</td>
</tr>
<tr>
<td><tt>LB</tt>
</td>
<td><tt>LB</tt></td>
<td>Low Battery. The battery level of the UPS is below a chosen limit.
The UPS may be in status <tt>OL</tt> or <tt>OB</tt>.
</td> <tt>OB</tt>.</td>
</tr>
<tr>
<td><tt>NOCOMM</tt>
</td>
<td><tt>NOCOMM</tt></td>
<td>The Attachment Daemon has no effective contact with the UPS.
</td> UPS.</td>
</tr>
<tr>
<td><tt>OB</tt>
</td>
<td><tt>OB</tt></td>
<td>On Battery. The UPS is taking energy from it's its battery.
The battery is discharging.  A UPS must have status <tt>OB</tt> or <tt>OL</tt>,
otherwise <tt>OL</tt>;
otherwise, it is deemed dead.
</td> dead.</td>
</tr>
<tr>
<td><tt>OFF</tt>
</td>
<td><tt>OFF</tt></td>
<td>The UPS is in state "Off".  It does not react to failure in the
public power supply.  The exact meaning depends on the model.
</td> model.</td>
</tr>
<tr>
<td><tt>OL</tt>
</td>
<td><tt>OL</tt></td>
<td>Online. The UPS is online, receiving energy from the public power supply.  The
battery is charging.  A UPS must have status <tt>OB</tt> or <tt>OL</tt>, otherwise <tt>OL</tt>; otherwise,
it is deemed dead.
</td> dead.</td>
</tr>
<tr>
<td><tt>OVER</tt>
</td>
<td><tt>OVER</tt></td>
<td>Overloaded. The UPS reports that the load on it is beyond it's its
normal operating maximum.
</td> maximum.</td>
</tr>
<tr>
<td><tt>RB</tt>
</td>
<td><tt>RB</tt></td>
<td>Replace battery. The UPS reports that it's battery/batteries its battery or batteries should
be replaced.
</td> replaced.</td>
</tr>
<tr>
<td><tt>TEST</tt>
</td>
<td><tt>TEST</tt></td>
<td>Under test. The UPS is currently undergoing a test, which test that may have
been called for requested manually or internally.
</td> internally.</td>
</tr>
<tr>
<td><tt>TICK</tt>
</td>
<td><tt>TICK</tt></td>
<td>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. <tt>TICK</tt> and <tt>TOCK</tt> are companions, companions; they are considered
experimental.
</td>
experimental.</td>
</tr>
<tr>
<td><tt>TOCK</tt>
</td>
<td><tt>TOCK</tt></td>
<td>Heartbeat. See <tt>TICK</tt>
</td> <tt>TICK</tt></td>
</tr>
<tr>
<td><tt>TRIM</tt>
</td>
<td><tt>TRIM</tt></td>
<td>The UPS has determined that the voltage level of the public power supply is
too high, high and is reducing it to the required level.  The UPS continues
to supply the protected system from the public power supply.
</td> supply.</td>
</tr>
</tbody>
</table>
</section>
<section anchor="events">
<name>Events</name>
<t>A Management Daemon detects the occurrence of a UPS Event 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 <tt>ups.status</tt>.
</t>
<t>The Management Daemon should retrieve the variable <tt>ups.status</tt> 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.
</t>
<t>A default value of 5 seconds is <bcp14>RECOMMENDED</bcp14>, but an implementation
<bcp14>MAY</bcp14> make this value configurable.  By default default, the "old" status is
therefore the previous value retrieved 5 seconds ago.
</t>
<t>Current practice is for the Management Daemon to assign names to certain
events.  These is are shown in the table in parentheses.
</t>
<table>
<name>Event deduction Deduction from status changes
</name> Status Changes</name>
<thead>
<tr>
<th>Old status  </th> Status</th>
<th>New status  </th>
<th>Event                    </th>
<th>&nbsp;&nbsp;&nbsp;&nbsp;
    </th> Status</th>
<th>Event</th>
<th>&nbsp;&nbsp;&nbsp;&nbsp;</th>
<th>Old status  </th> Status</th>
<th>New status  </th>
<th>Event
</th> Status</th>
<th>Event</th>
</tr>
</thead>
<tbody>
<tr>
<td>none        </td>
<td><tt>ALARM</tt>    </td>
<td>none</td>
<td><tt>ALARM</tt></td>
<td>Alarm on                 </td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;
    </td>
<td><tt>ALARM</tt>    </td>
<td>none        </td> on</td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td><tt>ALARM</tt></td>
<td>none</td>
<td>Alarm off
</td> off</td>
</tr>
<tr>
<td>none        </td>
<td><tt>BOOST</tt>    </td>
<td>none</td>
<td><tt>BOOST</tt></td>
<td>Boosting voltage         </td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;
    </td>
<td><tt>BOOST</tt>    </td>
<td>none        </td> voltage</td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td><tt>BOOST</tt></td>
<td>none</td>
<td>Not boosting
</td> boosting</td>
</tr>
<tr>
<td>none        </td>
<td><tt>BYPASS</tt>   </td>
<td>none</td>
<td><tt>BYPASS</tt></td>
<td>Bypass on                </td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;
    </td>
<td><tt>BYPASS</tt>   </td>
<td>none        </td> on</td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td><tt>BYPASS</tt></td>
<td>none</td>
<td>Bypass off
</td> off</td>
</tr>
<tr>
<td>none        </td>
<td><tt>CAL</tt>      </td>
<td>Calibrating              </td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;
    </td>
<td><tt>CAL</tt>      </td>
<td>none        </td>
<td>none</td>
<td><tt>CAL</tt></td>
<td>Calibrating</td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td><tt>CAL</tt></td>
<td>none</td>
<td>Not calibrating
</td> calibrating</td>
</tr>
<tr>
<td>none        </td>
<td><tt>CHRG</tt>     </td>
<td>Charging                 </td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;
    </td>
<td><tt>CHRG</tt>     </td>
<td>none        </td>
<td>none</td>
<td><tt>CHRG</tt></td>
<td>Charging</td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td><tt>CHRG</tt></td>
<td>none</td>
<td>Not charging
</td> charging</td>
</tr>
<tr>
<td>none        </td>
<td><tt>COMM</tt>     </td>
<td>none</td>
<td><tt>COMM</tt></td>
<td>UPS communicating<br/>(Event <tt>COMMOK</tt>)     </td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;
    </td>
<td><tt>COMM</tt>     </td>
<td>none        </td> communicating<br/>(event <tt>COMMOK</tt>)</td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td><tt>COMM</tt></td>
<td>none</td>
<td>See note <xref target="DDD" format="counter"></xref>
</td> format="counter"></xref></td>
</tr>
<tr>
<td>none        </td>
<td><tt>DISCHRG</tt>  </td>
<td>Discharging              </td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;
    </td>
<td><tt>DISCHRG</tt>  </td>
<td>none        </td>
<td>none</td>
<td><tt>DISCHRG</tt></td>
<td>Discharging</td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td><tt>DISCHRG</tt></td>
<td>none</td>
<td>Not discharging
</td> discharging</td>
</tr>
<tr anchor="EventFSD">
<td>none        </td>
<td><tt>FSD</tt> </td>
<td>none</td>
<td><tt>FSD</tt></td>
<td>System shutdown<br/>(Events shutdown<br/>(events <tt>FSD</tt>, <tt>SHUTDOWN</tt>)      </td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;
    </td>
<td><tt>FSD</tt> </td>
<td>none       </td> <tt>SHUTDOWN</tt>)</td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td><tt>FSD</tt></td>
<td>none</td>
<td>Shutdown abandoned.  See note <xref target="AAA" format="counter"></xref>
</td> format="counter"></xref></td>
</tr>
<tr>
<td>none        </td>
<td><tt>LB</tt>       </td>
<td>none</td>
<td><tt>LB</tt></td>
<td>Low battery.  See note <xref target="BBB" format="counter"></xref> (Event <tt>LOWBATT</tt>) </td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;
    </td>
<td><tt>LB</tt>       </td>
<td>none        </td> (event <tt>LOWBATT</tt>)</td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td><tt>LB</tt></td>
<td>none</td>
<td>Battery not low
</td> low</td>
</tr>
<tr>
<td>none        </td>
<td><tt>NOCOMM</tt>   </td>
<td>none</td>
<td><tt>NOCOMM</tt></td>
<td>UPS dead?  See note <xref target="DDD" format="counter"></xref><br/>(Events format="counter"></xref><br/>(events <tt>COMMBAD</tt>, <tt>NOCOMM</tt>) </td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;
    </td>
<td><tt>NOCOMM</tt>   </td>
<td>none        </td> <tt>NOCOMM</tt>)</td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td><tt>NOCOMM</tt></td>
<td>none</td>
<td>See note <xref target="DDD" format="counter"></xref>
</td> format="counter"></xref></td>
</tr>
<tr>
<td>none        </td>
<td><tt>OFF</tt>      </td>
<td>none</td>
<td><tt>OFF</tt></td>
<td>UPS turned off           </td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;
    </td>
<td><tt>OFF</tt>      </td>
<td>none        </td> off</td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td><tt>OFF</tt></td>
<td>none</td>
<td>UPS not turned off
</td> off</td>
</tr>
<tr>
<td><tt>OB</tt>       </td>
<td><tt>OL</tt>       </td>
<td><tt>OB</tt></td>
<td><tt>OL</tt></td>
<td>Receiving power<br/>(Event <tt>ONLINE</tt>)  </td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;
    </td>
<td><tt>OL</tt>       </td>
<td><tt>OB</tt>       </td> power<br/>(event <tt>ONLINE</tt>)</td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td><tt>OL</tt></td>
<td><tt>OB</tt></td>
<td>Power lost<br/>(Event <tt>ONBATT</tt>)
</td> lost<br/>(event <tt>ONBATT</tt>)</td>
</tr>
<tr>
<td>none        </td>
<td><tt>OVER</tt>     </td>
<td>none</td>
<td><tt>OVER</tt></td>
<td>UPS overloaded           </td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;
    </td>
<td><tt>OVER</tt>     </td>
<td>none        </td> overloaded</td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td><tt>OVER</tt></td>
<td>none</td>
<td>Overload gone
</td> gone</td>
</tr>
<tr>
<td>none        </td>
<td><tt>RB</tt>       </td>
<td>none</td>
<td><tt>RB</tt></td>
<td>Replace battery<br/>(Event <tt>REPLBATT</tt>)     </td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;
    </td>
<td><tt>RB</tt>       </td>
<td>none        </td> battery<br/>(event <tt>REPLBATT</tt>)</td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td><tt>RB</tt></td>
<td>none</td>
<td>Replacement canceled
</td> canceled</td>
</tr>
<tr>
<td>none        </td>
<td><tt>TEST</tt>     </td>
<td>none</td>
<td><tt>TEST</tt></td>
<td>Test starts              </td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;
    </td>
<td><tt>TEST</tt>     </td>
<td>none        </td> starts</td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td><tt>TEST</tt></td>
<td>none</td>
<td>Test finished
</td> finished</td>
</tr>
<tr>
<td>none        </td>
<td><tt>TICK</tt>     </td>
<td>none</td>
<td><tt>TICK</tt></td>
<td>Heartbeat event.  See note <xref target="CCC" format="counter"></xref> </td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;
    </td>
<td><tt>TICK</tt>     </td>
<td>none        </td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td><tt>TICK</tt></td>
<td>none</td>
<td>No heartbeat.   See note <xref target="CCC" format="counter"></xref>
</td> format="counter"></xref></td>
</tr>
<tr>
<td>none        </td>
<td><tt>TOCK</tt>     </td>
<td>none</td>
<td><tt>TOCK</tt></td>
<td>Heartbeat event.  See note <xref target="CCC" format="counter"></xref> </td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;
    </td>
<td><tt>TOCK</tt>     </td>
<td>none        </td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td><tt>TOCK</tt></td>
<td>none</td>
<td>No heartbeat.  See note <xref target="CCC" format="counter"></xref>
</td> format="counter"></xref></td>
</tr>
<tr>
<td>none        </td>
<td><tt>TRIM</tt>     </td>
<td>none</td>
<td><tt>TRIM</tt></td>
<td>Trimming voltage         </td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;
    </td>
<td><tt>TRIM</tt>     </td>
<td>none        </td> voltage</td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td><tt>TRIM</tt></td>
<td>none</td>
<td>Not trimming
</td> trimming</td>
</tr>
</tbody>
</table>
<t>Notes
</t>
<dl newline="true" spacing="normal">
<dt>Notes:</dt>
<dd>
<ol spacing="compact" indent="adaptive">
<li anchor="AAA">Current practice does not include this event.
</li> event.</li>
<li anchor="BBB">If the status <tt>OB</tt> is present, current practice
takes Management Daemon reception of <tt>LB</tt> as an order to perform an emergency
system shutdown.
</li> shutdown.</li>
<li anchor="CCC">The use of a software defined software-defined UPS to provide a
heartbeat is experimental and is not part of common current practice.
</li> practice.</li>
<li anchor="DDD">Current practice is: is the following: if the UPS has not responded for
15 seconds, the Management Daemon assumes that the UPS is "<em>dead</em>"
(Event <em>dead</em>
(event <tt>NOCOMM</tt>), and if the last known <tt>OL</tt>/<tt>OB</tt> status was <tt>OB</tt> <tt>OB</tt>, a
system shutdown, command <tt>FSD</tt>, shutdown (command <tt>FSD</tt>) is called for.
</li> requested.</li>
</ol>
</dd>
</dl>
</section>
</section>
<section anchor="Sec">
<name>Security Considerations</name>
<section anchor="weak">
<name>Current General Security Practice</name>
<t>Experience over the last 20 years shows that new UPS management
software releases are not frequent, and frequent and, when installed, stay
unmodified for some years.  This is probably because UPS management is
a mature activity, part of site mangement. management.  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 like the one shown in
figure
<xref target="fig.weak" format="counter"></xref> target="fig.weak"/>, which uses port
3493/TCP (nut) between the two daemons running in the same system.
The traffic is often not encrypted, and when encrypted it is encrypted, it uses deprecated
early versions of SSL/TLS.
</t>
<figure anchor="fig.weak">
<name>Common single-system configuration
</name> Single-System Configuration</name>
<artwork align="center"> align="center" type="ascii-art">
 ,-----,   ,--------------------,---------------------,
 | UPS |---|  Attachment   &lt;-Commands     Management  |
 |     |===|    Daemon       Responses-&gt;    Daemon    |
 /-----\   '--------------------'---------------------'
              Listens on
             port 3493/TCP
             for localhost</artwork> localhost
</artwork>
</figure>
<t>This situation is now changing as low cost low-cost processors become
available, costing significantly less than a UPS unit.  This evolution
makes it interesting to shift to a configuration as like the one shown in
figure
<xref target="fig.weaker" format="counter"></xref>, target="fig.weaker"/>, but it also
exacerbates the security weakness of figure <xref target="fig.weak" format="counter"></xref> target="fig.weak"/>, since the traffic between the daemons is now over an
exposed network.
</t>
<figure anchor="fig.weaker">
<name>Integration of UPS and Attachment Daemon
</name>
<artwork align="center"> align="center" type="ascii-art">
 ,-----,------------,               ,--------------,
 | UPS - Attachment | &lt;-Commands    |  Management  |
 |     |   Daemon   |   Responses-&gt; |    Daemon    |
 /-----'------------\               '--------------'
         Listens on
        port 3493/TCP</artwork> 3493/TCP
</artwork>
</figure>
<t>These security issues raised by UPS management are those of the
power industry in general: general; they are addressed in detail in
<xref target="IEC62351-1">IEC Technical Specification 62351</xref>.
In addition to equipment security, cyber security is now an essential
consideration.
</t>
<t>Quoting from IEC 62351-1<xref target="IEC62351-1"></xref>,
Introduction to the standard, clause 5.2.3.5:
</t>
<blockquote> 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.</blockquote>
<t>In IEC 62351-1<xref target="IEC62351-1"></xref> target="IEC62351-1"></xref>, clause 5.3.5 lists
typical security attacks: Eavesdropping, Masquerade,
Man-in-the-Middle, Replay, and Resource Exhaustion.
RFC3552
<xref target="RFC3552"></xref> adds message insersion /
deletion / modification, insertion/deletion/modification
and denial of service.
</t>
<t>Let's look more closely at these requirements:
</t>
<ul>
<li>Eavesdropping,
<ul spacing="normal">
<li>Eavesdropping; see <xref target="Eavesdropping"></xref>
</li>
<li>Man-in-the-Middle, target="Eavesdropping"></xref></li>
<li>Man-in-the-Middle; see <xref target="Man-in-the-Middle"></xref>
</li>
<li>Masquerade, target="Man-in-the-Middle"></xref></li>
<li>Masquerade; see <xref target="Masquerade"></xref>
</li> target="Masquerade"></xref></li>
<li>Message insersion, insertion, deletion, modification, and modification;
see <xref target="Messageidm"></xref>
</li>
<li>Replay, target="Messageidm"></xref></li>
<li>Replay; see <xref target="Replay"></xref>
</li> target="Replay"></xref></li>
<li>Resource Exhaustion, Exhaustion and Denial of Service, Service;
see <xref target="Exhaustion"></xref>
</li> target="Exhaustion"></xref></li>
</ul>
</section>
<section anchor="SecRec">
<name>Communication Security Requirements</name>
<t>Enforcing secure communication requires tightening up the Attachment Daemon to
require the use of command
<tt>STARTTLS</tt> for commands sent over the global Internet.  In such a
situation
situation, an Attachment Daemon listening for traffic other than from
the
<tt>localhost</tt>:
</t>
<ol spacing="normal" indent="adaptive">
<li anchor="should"><bcp14>SHOULD</bcp14> require and accept command
<tt>STARTTLS</tt>,
</li>
<tt>STARTTLS</tt>,</li>
<li anchor="must"><bcp14>MUST</bcp14> encrypt all communication with a Management Daemon,
</li> and</li>
<li anchor="shall"><bcp14>SHALL</bcp14> refuse all non-encrypted commands commands, except
an initial <tt>STARTTLS</tt>.
</li> <tt>STARTTLS</tt>.</li>
</ol>
<t>Notes:  </t>
<ul>
<ul spacing="normal">
<li anchor="note-should">The <bcp14>SHOULD</bcp14> <bcp14>SHOULD</bcp14>, rather than <bcp14>MUST</bcp14> <bcp14>MUST</bcp14>,
in <xref target="should"></xref> above allows system administrators to
enforce secure communication using other techniques which that do not
involve the <tt>STARTTLS</tt> command.
</li> command.</li>
<li>If an Attachment Daemon requires that all commands be encrypted as required by
the <bcp14>MUST</bcp14> in <xref target="must"></xref> above, then automatically then, automatically,
each Management Daemon <bcp14>MUST</bcp14> encrypt as well, since it has to do so in order to
gain access.
</li> access.</li>
<li>The <bcp14>SHALL</bcp14> in <xref target="shall"></xref> above applies to
traffic from the global Internet.  An Attachment Daemon <bcp14>MAY</bcp14> accept unencrypted
commands from <tt>localhost</tt> if the local installation's security
practices allow it, for example example, in a dedicated appliance.
</li> appliance.</li>
</ul>
<t>Firewalls <bcp14>SHOULD</bcp14> 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 <xref target="note-should"></xref> above on the use
of <bcp14>SHOULD</bcp14>.
</t>
<section anchor="certsec">
<name>Certificate security</name> Security</name>
<t>In long-lived installations installations, such as those found in UPS management,
careful certificate management is essential, whether the certificate
is provided by a Certificate Authority, Authority or is a self-signed
certificate. For example example, the specification of expiration times of both the
certificate containing the public key and the signing
certificate. certificate
should be specified. </t>
</section>
</section>
<section anchor="Attacks">
<name>Attacks and Defences</name> Defenses</name>
<section anchor="Eavesdropping">
<name>Eavesdropping</name>
<t>The defence defense against eavesdropping is encryption of the commands and
responses passed between the client Management Daemon and server Attachment Daemon.  The protocol
provides command <tt>STARTTLS</tt>, see <xref target="starttls"></xref>, which calls on
the Attachment Daemon to support TLS encryption of the communication.  If this
command is accepted, the Management Daemon also encrypts.
</t>
<t>In current NUT Project practice, the use of TLS is optional,
however optional;
however, a Management Daemon may refuse to accept unencrypted communication.  This
is done by setting declarations <tt>FORCESSL</tt> to 1
and <tt>CERTVERIFY</tt> to 1 in the Management Daemon configuration file.
</t>
<section>
<name>Misplaced declarations requiring Declarations Requiring TLS</name>
<t>A further weakness is that the <tt>FORCESSL</tt>
and <tt>CERTVERIFY</tt> declarations declarations, which enforce use of encryption encryption,
are in the client Management Daemon configuration file and not in the Attachment Daemon.
Secure practice requires enforcement by the server Attachment Daemon Daemon, rather than a
possibly rogue client Management Daemon out on the Internet.
</t>
<t>This weakness may be mitigated with strict firewall rules which that
would prevent the rogue client Management Daemon from accessing the Attachment Daemon.
</t>
</section>
<section>
<name>Weak protection Protection in previous version Previous Version 2.7.4</name>
<t>Although version 2.8.0 of NUT supports TLS
1.3 <xref target="RFC8446"></xref> with X.509 v3 certificates as
defined by RFC5280 <xref target="RFC5280"></xref>, previous version
2.7.4 only supported earlier SSL/TLS versions.  To overcome this
weakness, The following techniques have been used:
</t>
<ul>
<li>Shims,
<ul spacing="normal">
<li>Shims; see <xref target="Shims"></xref>
</li> target="Shims"></xref></li>
<li>TLS tunnel, tunnel; see <xref target="TLStunnel"></xref>
</li> target="TLStunnel"></xref></li>
<li>Virtual Private Network, VPN, Network (VPN); see <xref target="VPN"></xref>
</li> target="VPN"></xref></li>
<li>Virtual Local Area network, VLAN, Network (VLAN); see <xref target="VLAN"></xref>
</li> target="VLAN"></xref></li>
</ul>
</section>
</section>
<section anchor="Man-in-the-Middle">
<name>Man in the Middle</name>
<name>Man-in-the-Middle</name>
<t>The protocol relies on TLS encryption to prevent man-in-the-middle
attacks.  See <xref target="AppendixEavesdropping"></xref> for defense
methods used for previous NUT version 2.7.4.
</t>
</section>
<section anchor="Masquerade">
<name>Masquerade Attack: Agent Verification</name>
<t anchor="AgentVerif">The protocol allows a malicious client acting
as an a Management Daemon to send command <tt>FSD</tt> to an Attachment Daemon to shut down a
working system and it's its power supply supply, as described in The Shutdown
Story, see
Story section (see <xref target="shutdownstory"></xref>. target="shutdownstory"></xref>).  Similarly, a
malicious client could turn off the UPS power outlets outlets, causing the
system to fail.
</t>
<t>The protocol provides commands <tt>USERNAME</tt>, see <tt>USERNAME</tt> (see <xref target="username"></xref>, target="username"></xref>)
and <tt>PASSWORD</tt>, see <tt>PASSWORD</tt> (see <xref target="password"></xref>, target="password"></xref>), which allow an administrative
user in a Management Daemon to authenticate itself to the Attachment Daemon, as a defence defense
against masquerade attacks.  The administrative user name username and password
need protection against local malicious users. This is done by
restricting access to the configuration files.
</t>
</section>
<section anchor="Messageidm">
<name>Message insertion, deletion, modification</name> Insertion, Deletion, and Modification</name>
<t>The protocol relies on TLS encryption to prevent message insertion,
deletion
deletion, and modification attacks.
See <xref target="AppendixEavesdropping"></xref> for defense methods
used for previous NUT version 2.7.4.
</t>
</section>
<section anchor="Replay">
<name>Replay</name>
<t>There are two cases:
</t>
<ol spacing="normal" indent="adaptive">
<li>The replay is from a system other than an approved Management Daemon: Daemon, i.e.,
the protocol relies on a firewall to block the traffic. </li>
<li>The replay is from an approved Management Daemon: Daemon. i.e., the protocol relies on the
Management Daemon's own security to prevent unauthorised access.
</li> unauthorized access.</li>
</ol>
</section>
<section anchor="Exhaustion">
<name>Denial of Service</name>
<t>The protocol relies on a very tightly specified firewall to prevent
denial of service
denial-of-service attacks.  Only designated client Management Daemons should be
able to reach the server Attachment Daemon.
</t>
</section>
</section>
</section>
<section>
<name>IANA Considerations</name>
<t>The protocol specified by this text runs over port 3493/TCP (nut) (nut), which is
registered by the NUT (Network Network UPS Tools) project. Tools (NUT) Project.
</t>
<t>This document will be has been added to the registration's reference field. Reference field in the
"Service Name and Transport Protocol Port Number Registry" <xref target="Registry" format="default"/>.
</t>
</section>
<section anchor="implementation">
<name>Implementation Status</name>
<t>This section presents a very short summary of the status of the
Network UPS Tools project.
</t>
<ul anchor="vsh" spacing="compact">
<li>May 1996: The first hack as a cron job.
</li> job.</li>
<li>September 1997: The first server-client code.
</li> code.</li>
<li>March 1998: First public release.
</li> release.</li>
<li>June 1999: Code rewrite with a UPS driver Driver <tt>smartups</tt>, an
Attachment Daemon <tt>upsd</tt> <tt>upsd</tt>, and a simple Management Daemon.
</li> Daemon.</li>
<li>September 1999: The project became "Network UPS Tools".  The
Management Daemon <tt>upsmon</tt> supported primary/secondary configurations.
</li> Primary/Secondary configurations.</li>
<li>June 2001: Common core for multiple drivers.
</li> Drivers.</li>
<li>May 2002: IANA granted port 3493/TCP (nut). August: release
1.0.0. November: OpenSSL support.
</li> support.</li>
<li>April 2003: The initial set of command and variable names was
designed.
</li>
designed.</li>
<li anchor="arno">February 2005: Arnaud Quette took over the project
lead from Russell Kroll.
</li> Kroll.</li>
<li>March 2016: Version 2.7.4 released, supported over 100 device
manufacturers and hundreds of UPS models.
</li> models.</li>
<li>November 2020: Evgeny "Jim" Klimov took over project lead from
Arnaud Quette.
</li> Quette.</li>
<li>May 2022: Version 2.8.0 released, supporting protocol version
1.3.
</li>
1.3.</li>
</ul>
<t>See <xref target="githist"></xref>
and Appendix J <xref target="History"></xref> for a detailed history of the
NUT Project.
</t>
<section>
<name>Inclusion in Software Distributions</name>
<t>The programs <tt>upsd</tt>, <tt>upsmon</tt>, <tt>upssched</tt>,
<tt>upsc</tt>, <tt>upscmd</tt> <tt>upscmd</tt>, and <tt>upsrw</tt> have been included
in the package known as "nut" in the package systems of many
distributions:
distributions, i.e., all the major Linux distributions, distributions and Unix
distributions
distributions, such as OpenBSD and OpenSolaris.  A Microsoft Windows
version has been developed but was not maintained.
</t>
</section>
<section anchor="MinSup">
<name>Recommended Minimum Support</name>
<t>The features provided by current UPS units vary widely.  However  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 <xref target="gitvars">source code file
docs/nut-names.txt</xref>
docs/nut-names.txt</xref>, which serves as the Recording Document.
</t>
<section anchor="MinSupPC">
<name>Desktop PC Variables</name>
<t>The following variables form a minimum set suitable for Desktop a desktop PC.
It is expected that that, on public power supply failure, the PC will be halted.  It
will not restart automatically when power returns.
</t>
<ul>
<li><tt>battery.charge</tt>
</li>
<li><tt>battery.charge.low</tt>
</li>
<li><tt>device.mfr</tt>
</li>
<li><tt>device.model</tt>
</li>
<ul spacing="normal">
<li><tt>battery.charge</tt></li>
<li><tt>battery.charge.low</tt></li>
<li><tt>device.mfr</tt></li>
<li><tt>device.model</tt></li>
<li><tt>ups.status</tt> with the minimum status symbol set <tt>OL</tt> <tt>OB</tt>
<tt>LB</tt> <tt>FSD</tt>, <tt>FSD</tt>; see <xref target="symbols"></xref>.
</li> target="symbols"></xref></li>
</ul>
</section>
<section anchor="MinSupServer">
<name>Unattended Servers, Servers and Additional Variables</name>
<t>The following additional variables are needed in a minimum set
suitable for an unattended server.  It is expected that that, on public power supply
failure, the server will be halted.  It will restart automatically
when power returns.
</t>
<ul>
<li><tt>battery.date</tt>
</li>
<li><tt>device.serial</tt>
</li>
<li><tt>ups.delay.shutdown</tt>
</li>
<li><tt>ups.delay.start</tt>
</li>
<ul spacing="normal">
<li><tt>battery.date</tt></li>
<li><tt>device.serial</tt></li>
<li><tt>ups.delay.shutdown</tt></li>
<li><tt>ups.delay.start</tt></li>
</ul>
</section>
<section anchor="MinSupCommands">
<name>Commands and other Other Technical
Terms</name>
<t>Satisfactory use of the NUT Project software requires support for
all the commands specified in protocol version 1.3, software version
2.8.0.
</t>
</section>
<section anchor="Version.2.7.4">
<name>Support for Earlier Versions</name>
<t>In order to ease migration from software version 2.7.4 2.7.4, which
supported protocol version 1.2, software version 2.8.0 also supports
the technical terms used in protocol version 1.2.
See <xref target="differences"></xref> for the differences.
</t>
</section>
</section>
</section>
<section anchor="Ack">
<name>Acknowledgments</name>
<t>This document is based on the
NUT Project <xref target="devguide">documentation</xref>. 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 <xref target="nut-upsuser">nut-upsuser</xref>.
and <xref target="nut-upsdev">nut-upsdev</xref> mailing lists.
</t>
<t>The source for this document is marked up using
an <xref target="SGML">SGML DTD</xref> and an XML meta-DTD as defined
by
<xref target="HyTimeA">HyTime Annex A</xref>.  Unlike XML, SGML offers
markup minimisation, and the source document takes advantage of this.
The <xref target="sgmlnorm"><tt>osgmlnorm</tt></xref> program generates
XML which program <xref target="RFC7991"><tt>xml2rfc</tt></xref> 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.
</t>
<t>Many helpful comments were received from Eliot Lear, Bart Smit,
David Zomaya, Joyce Norris, and Ted Mittelstaedt.
</t>
</section>
</middle>
<back>
<references>
<name>References</name>
<references>
<name>Normative References
  </name>
<reference anchor="RFC0020" target="https://www.rfc-editor.org/info/rfc20">
<front>
<title>ASCII format for network interchange</title>
<author initials="V.G." surname="Cerf" fullname="V.G. Cerf">
</author>
<date month="October" year="1969">
    </date>
</front>
<seriesInfo name="STD" value="80"/>
<seriesInfo name="RFC" value="20"/>
<seriesInfo name="DOI" value="10.17487/RFC0020"/>
</reference>
<reference xml:base="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml" anchor="RFC2119" target="https://www.rfc-editor.org/info/rfc2119">
<front>
<title>Key words for use in RFCs to Indicate Requirement Levels</title>
<seriesInfo name="DOI" value="10.17487/RFC2119"/>
<seriesInfo name="RFC" value="2119"/>
<seriesInfo name="BCP" value="14"/>
<author initials="S." surname="Bradner" fullname="S. Bradner">
</author>
<date month="March" year="1997">
      </date>
<abstract>
<t>In many standards track documents several words are used
        to signify the requirements in the specification.  These
        words are often capitalized. This document defines these
        words as they should be interpreted in IETF documents.  This
        document specifies an Internet Best Current Practices for
        the Internet Community, and requests discussion and
        suggestions for improvements.
      </t>
</abstract>
</front>
</reference>
<reference anchor="RFC5234" target="https://www.rfc-editor.org/info/rfc5234">
<front>
<title>Augmented BNF for Syntax Specifications: ABNF</title>
<author initials="D." surname="Crocker" fullname="D. Crocker" role="editor">
</author>
<author initials="P." surname="Overell" fullname="P. Overell">
</author>
<date month="January" year="2008">
      </date>
<abstract>
<t>Internet technical specifications often need to define a
        formal syntax. Over the years, a modified version of
        Backus-Naur Form (BNF), called Augmented BNF (ABNF), has been
        popular among many Internet specifications. The current
        specification documents ABNF. It balances compactness and
        simplicity with reasonable representational power. The
        differences between standard BNF and ABNF involve naming
        rules, repetition, alternatives, order-independence, and value
        ranges. This specification also supplies additional rule
        definitions and encoding for a core lexical analyzer of the
        type common to several Internet
        specifications. [STANDARDS-TRACK]
      </t>
</abstract>
</front>
<seriesInfo name="STD" value="68"/>
<seriesInfo name="RFC" value="5234"/>
<seriesInfo name="DOI" value="10.17487/RFC5234"/>
</reference>
<reference anchor="RFC7405" target="https://www.rfc-editor.org/info/rfc7405">
<front>
<title>Case-Sensitive String Support in ABNF</title>
<author initials="P." surname="Kyzivat" fullname="P. Kyzivat">
</author>
<date month="December" year="2014">
        </date>
<abstract>
<t>This document extends the base definition of ABNF
          (Augmented Backus-Naur Form) to include a way to specify
          US-ASCII string literals that are matched in a
          case-sensitive manner.
        </t>
</abstract>
</front>
<seriesInfo name="RFC" value="7405"/>
<seriesInfo name="DOI" value="10.17487/RFC7405"/>
</reference>
<reference anchor="RFC8174" target="https://www.rfc-editor.org/info/rfc8174">
<front>
<title>Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words</title>
<author initials="B." surname="Leiba" fullname="B. Leiba">
</author>
<date month="May" year="2017">
      </date>
<abstract>
<t>RFC 2119 specifies common key words that may be used in protocol
        specifications. This document aims to reduce the ambiguity by
        clarifying that only UPPERCASE usage of the key words have the
        defined special meanings.
      </t>
</abstract>
</front>
<seriesInfo name="BCP" value="14"/>
<seriesInfo name="RFC" value="8174"/>
<seriesInfo name="DOI" value="10.17487/RFC8174"/>
</reference> References</name>

<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.0020.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5234.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7405.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8174.xml"/>

</references>

<references>
<name>Informative References </name>
<reference anchor="RFC3552" target="https://www.rfc-editor.org/info/rfc3552">
<front>
<title>Guidelines for Writing RFC Text on Security Considerations</title>
<author initials="E." surname="Rescorla" fullname="E. Rescorla">
</author>
<author initials="B." surname="Korver" fullname="B. Korver">
</author>
<date month="July" year="2003">
    </date>
<abstract>
<t>All RFCs are required to have a Security
    Considerations section. Historically, such sections have been
    relatively weak. This document provides guidelines to RFC authors
    on how to write a good Security Considerations section. This
    document specifies an Internet Best Current Practices for the
    Internet Community, and requests discussion and suggestions for
    improvements.
    </t>
</abstract>
</front>
<seriesInfo name="BCP" value="72"/>
<seriesInfo name="RFC" value="3552"/>
<seriesInfo name="DOI" value="10.17487/RFC3552"/>
</reference>
<reference xml:base="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.7991.xml" anchor="RFC7991" target="https://www.rfc-editor.org/info/rfc7991">
<front>
<title>The "xml2rfc" Version 3 Vocabulary</title>
<seriesInfo name="RFC" value="7991"/>
<author initials="P." surname="Hoffman" fullname="P. Hoffman">
</author>
<date month="December" year="2016">
    </date>
</front>
</reference>
<reference anchor="RFC5280" target="https://www.rfc-editor.org/info/rfc5280">
<front>
<title>
    Internet X.509 Public Key Infrastructure Certificate and
    Certificate Revocation List (CRL) Profile
    </title>
<author initials="D." surname="Cooper" fullname="D. Cooper">
</author>
<author initials="S." surname="Santesson" fullname="S. Santesson">
</author>
<author initials="S." surname="Farrell" fullname="S. Farrell">
</author>
<author initials="S." surname="Boeyen" fullname="S. Boeyen">
</author>
<author initials="R." surname="Housley" fullname="R. Housley">
</author>
<author initials="W." surname="Polk" fullname="W. Polk">
</author>
<date month="May" year="2008">
    </date>
<abstract>
<t>This memo profiles the X.509 v3 certificate and X.509
    v2 certificate revocation list (CRL) for use in the Internet. An
    overview of this approach and model is provided as an
    introduction. The X.509 v3 certificate format is described in
    detail, with additional information regarding the format and
    semantics of Internet name forms. Standard certificate extensions
    are described and two Internet-specific extensions are defined. A
    set of required certificate extensions is specified. The X.509 v2
    CRL format is described in detail along with standard and
    Internet-specific extensions. An algorithm for X.509 certification
    path validation is described. An ASN.1 module and examples are
    provided in the appendices. [STANDARDS-TRACK]
    </t>
</abstract>
</front>
<seriesInfo name="RFC" value="5280"/>
<seriesInfo name="DOI" value="10.17487/RFC5280"/>
</reference>
<reference anchor="RFC7030" target="https://www.rfc-editor.org/info/rfc7030">
<front>
<title>Enrollment over Secure Transport</title>
<author initials="M." surname="Pritikin" fullname="M. Pritikin" role="editor">
</author>
<author initials="P." surname="Yee" fullname="P. Yee" role="editor">
</author>
<author initials="D." surname="Harkins" fullname="D. Harkins" role="editor">
</author>
<date month="October" year="2013">
    </date>
<abstract>
<t>This document profiles certificate enrollment for clients using
    Certificate Management over CMS (CMC) messages over a secure
    transport. This profile, called Enrollment over Secure Transport
    (EST), describes a simple, yet functional, certificate management
    protocol targeting Public Key Infrastructure (PKI) clients that
    need to acquire client certificates and associated Certification
    Authority (CA) certificates. It also supports client-generated
    public/private key pairs as well as key pairs generated by the
    CA.
    </t>
</abstract>
</front>
<seriesInfo name="RFC" value="7030"/>
<seriesInfo name="DOI" value="10.17487/RFC7030"/>
</reference>
<reference anchor="RFC8446" target="https://www.rfc-editor.org/info/rfc8446">
<front>
<title>The Transport Layer Security (TLS) Protocol Version 1.3</title>
<author initials="E." surname="Rescorla" fullname="E. Rescorla">
</author>
<date month="August" year="2018">
  </date>
<abstract>
<t>This document specifies version 1.3 of the Transport
  Layer Security (TLS) protocol.  TLS allows client/server
  applications to communicate over the Internet in a way that is
  designed to prevent eavesdropping, tampering, and message
  forgery.</t>
<t>This document updates RFCs 5705 and 6066, and
  obsoletes RFCs 5077, 5246, and 6961.  This document also specifies
  new requirements for TLS 1.2 implementations.</t>
</abstract>
</front>
<seriesInfo name="RFC" value="8446"/>
<seriesInfo name="DOI" value="10.17487/RFC8446"/>
</reference>
<reference anchor="RFC8894" target="https://www.rfc-editor.org/info/rfc8894">
<front>
<title>Simple Certificate Enrolment Protocol</title>
<author initials="P." surname="Gutmann" fullname="P. Gutmann">
</author>
<date month="September" year="2020">
    </date>
<abstract>
<t>This document specifies the Simple Certificate Enrolment
    Protocol (SCEP), a PKI protocol that leverages existing technology
    by using Cryptographic Message Syntax (CMS, formerly known as PKCS
    #7) and PKCS #10 over HTTP. SCEP is the evolution of the enrolment
    protocol sponsored by Cisco Systems, which enjoys wide support in
    both client and server implementations, as well as being relied
    upon by numerous other industry standards that work with
    certificates.
    </t>
</abstract>
</front>
<seriesInfo name="RFC" value="8894"/>
<seriesInfo name="DOI" value="10.17487/RFC8894"/>
</reference>

<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.3552.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7991.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5280.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7030.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8446.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8894.xml"/>

<reference anchor="IEC62351-1" target="https://nanopdf.com/download/technical-iec-specification-ts-62351-1_pdf">
<front>
<title>IEC TS 62351-1 Power
<title>Power systems management and associated
    information exchange -- Data and communications security.  Part 1:
    Communication network and system security -- Introduction to
    security issues</title>
<author>
<organization>IEC</organization>
</author>
<date day="15" month="May" year="2007">
  </date>
<abstract>
<t>Provides an introduction to the remaining parts of the
    IEC 62351 series, primarily to introduce the reader to various
    aspects of information security as applied to power system
    operations.</t>
</abstract> year="2007"></date>
</front>
<seriesInfo name="IEC" value="Technical Specification Reference number IEC/TS 62351-1:2007(E), 35 pages"/>
<seriesInfo name="CHF" value="205"/>
<seriesInfo name="Technical Committee" value="TC value="TS 62351-1:2007"/>
<refcontent>35 pages, TC 57 - Power systems management and associated information exchange"/> exchange</refcontent>
</reference>

<reference anchor="NUT" target="https://www.networkupstools.org">
<front>
<title>Network UPS Tools (NUT) Project</title> Tools, Devices Dumps Library</title>
<author>
<organization>
    </organization>
<organization/>
</author>
</front>
</reference>

<reference anchor="nut-upsuser" target="https://alioth-lists.debian.net/cgi-bin/mailman/listinfo/nut-upsuser">
<front>
<title>Network UPS Tools (NUT) Project Mailing List for users</title> Users</title>
<author>
<organization>
    </organization>
<organization>NUT</organization>
</author>
</front>
</reference>

<reference anchor="nut-upsdev" target="https://alioth-lists.debian.net/cgi-bin/mailman/listinfo/nut-upsdev">
<front>
<title>Network UPS Tools (NUT) Project Mailing List for developers</title> Developers</title>
<author>
<organization>
    </organization>
<organization>NUT</organization>
</author>
</front>
</reference>

<reference anchor="nut-repository" target="https://github.com/networkupstools/nut/">
<front>
<title>GitHub Repository for the
<title>The Network UPS Tools (NUT) Project</title> repository </title>
<author>
<organization>
    </organization>
<organization/>
</author>
</front>
</reference>

<reference anchor="devguide" target="https://networkupstools.org/docs/developer-guide.chunked/ar01s09.html">
<front>
<title>Network UPS Tools (NUT) Project Developer Guide</title>
<author>
<organization>
    </organization>
<author initials="R" surname="Kroll" fullname="Russell Kroll">
<organization/>
</author>
<author initials="A" surname="Quette" fullname="Arnaud Quette">
<organization/>
</author>
<author initials="C" surname="Lepple" fullname="Charles Lepple">
<organization/>
</author>
<author initials="P" surname="Selinger" fullname="Peter Selinger">
<organization/>
</author>
</front>
</reference>

<reference anchor="SGML">
<front>
<title>The SGML Handbook</title>
<seriesInfo name="ISBN" value="0-19-853737-9"/>
<author initials="Charles F." initials="C." surname="Goldfarb" fullname="Charles F. Goldfarb">
<organization>Oxford University Press
      </organization>
</author>
<date year="1990">
    </date> year="1990"></date>
</front>
<seriesInfo name="ISBN-10" value="0-19-853737-9"/>
<refcontent>Oxford University Press</refcontent>
</reference>

<reference anchor="HyTimeA">
<front>
<title>International Standard ISO/IEC 10744
<title>Information technology --
      Hypermedia/Time-based Structuring Language, Annex A, SGML
      Extended Facilities</title>
<seriesInfo name="ISO/IEC" value="JTC 1/SC 34  Document description and processing languages"/> Language (HyTime)</title>
<author>
<organization>
      </organization>
<organization>ISO/IEC</organization>
</author>
<date year="1997">
    </date> month="August" year="1997"></date>
</front>
<seriesInfo name="ISO/IEC" value="10744:1997"/>
</reference>

<reference anchor="sgmlnorm" target="http://www.jclark.com/sp/sgmlnorm.htm"> target="http://openjade.sourceforge.net/">
<front>
<title>SGMLNORM An SGML System Conforming to International
             Standard ISO 8879 -- Standard Generalized Markup
             Language</title>
<author initials="James" surname="Clark" fullname="James Clark">
<organization>
    </organization>
<title>OpenJade Distribution Page</title>
<author>
<organization>OpenJade Project</organization>
</author>
</front>
</reference>

<reference anchor="Registry" target="https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml">
<front>
<title>Service Name and Transport Protocol Port Number Registry</title>
<seriesInfo name="Publisher:" value="IANA"/>
<author>
</author>
<author><organization>IANA</organization></author>
</front>
</reference>

<reference anchor="Library" target="https://networkupstools.org/ddl/">
<front>
<title>GitHub Network UPS Tools, Devices
<title>Devices  Dumps Library</title>
<author>
</author>
<author></author>
</front>
</reference>

<reference anchor="History" target="https://networkupstools.org/docs/user-manual.pdf">
<front>
<title>Network UPS Tools User Manual, Appendix J Project history</title>
<author>
</author> Manual</title>
<author initials="R" surname="Kroll" fullname="Russell Kroll"/>
<author initials="A" surname="Quette" fullname="Arnaud Quette"/>
<author initials="A" surname="de Korte" fullname="Arjen de Korte"/>
<date month="May" year="2022"/>
</front>
</reference>

<reference anchor="Documentation" target="https://networkupstools.org/documentation.html">
<front>
<title>Network UPS Tools Documentation</title>
<author>
</author>
<author></author>
</front>
</reference>

<reference anchor="gitvars" target="https://github.com/networkupstools/nut/blob/master/docs/nut-names.txt">
<front>
<title>GitHub
<title>The Network UPS Tools code repository, variable names</title>
<author>
</author>
</front>
</reference>
<reference anchor="gitstats" target="https://github.com/networkupstools/nut/blob/master/clients/status.h">
<front>
<title>GitHub Network UPS Tools code repository, status names</title>
<author>
</author>
<author></author>
<date month="April" year="2022"/>
</front>
</reference>

<reference anchor="githist" target="https://github.com/networkupstools/nut/blob/master/docs/history.txt">
<front>
<title>GitHub
<title>The Network UPS Tools code repository, project history</title>
<author>
</author>
<author></author>
<date month="July" year="2022"/>
</front>
</reference>

<reference anchor="stunnel" target="https://www.stunnel.org/">
<front>
<title>Stunnel proxy adds TLS encryption functionality to existing clients and servers</title>
<title>Stunnel</title>
<author></author>
</front>
</reference>

<reference anchor="C2ndEd" target="">
  <front>
    <title>The C Programming Language</title>
    <author initials="Michal" surname="Trojnara" fullname="Michal Trojnara">
</author> initials="B" surname="Kernighan" fullname="Brian W. Kernighan"/>
    <author initials="D" surname="Ritchie" fullname="Dennis M. Ritchie"/>
    <date year="1988"/>
  </front>
  <seriesInfo name="ISBN" value="0-13-110362-8"/>
  <refcontent>2nd edition, Prentice Hall Software Series</refcontent>
</reference>
</references>
</references>

<section anchor="Annex1">
<name>Variables</name>
<t>The UPS variables represent the abstracted state of the UPS unit.
Certain variables represent not only the state of some hardware
feature,
feature but also provide tunable values and instant commands, Instant Commands;
see <xref target="IC"></xref>.  The full set of variables is recorded
in the <xref target="gitvars">reference document for variable
names</xref>.
</t>
<t>The number of variables used in a given deployment depends on the
sophistication of the UPS product: 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 <xref target="Library">large
library of the variable subsets</xref> used by different UPS models.
</t>
<t>Note that successive versions of a given product may add or delete
features
features, causing a change in the subset of variables used.  An example
is the removal of <tt>ups.delay.start</tt> from a "consumer grade"
UPS.  The manufacturer reserves the feature for the "professional"
product.
</t>
<t>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
example, utility program <tt>upsc</tt> <tt>upsc</tt>, as included in the NUT package, package;
see <xref target="util"></xref>.
</t>
<t>The following sections illustrate the use of variables by taking
the values associated with a typical product.  The example is a 1600Va
1000W 1600 Va
1000 W UPS.
</t>
<section>
<name>Typical UPS Variables</name>
<table anchor="typvar">
<name>Typical UPS Variables
</name> Variables</name>
<thead>
<tr>
<th align="center">Variable </th> align="center">Variable</th>
<th align="center">Typical value </th> Value</th>
<th align="center">Default description
</th> Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><tt>battery.charge</tt> </td>
<td><tt>100</tt> </td>
<td><tt>battery.charge</tt></td>
<td><tt>100</tt></td>
<td>"Battery charge (percent of full)"
</td> full)"</td>
</tr>
<tr>
<td><tt>battery.charge.low</tt> </td>
<td><tt>20</tt> </td>
<td><tt>battery.charge.low</tt></td>
<td><tt>20</tt></td>
<td>"Remaining battery level when UPS switches to LB (percent)"
</td> (percent)"</td>
</tr>
<tr>
<td><tt>battery.runtime</tt> </td>
<td><tt>1481</tt> </td>
<td><tt>battery.runtime</tt></td>
<td><tt>1481</tt></td>
<td>"Battery runtime (seconds)"
</td> (seconds)"</td>
</tr>
<tr>
<td><tt>battery.type</tt> </td>
<td><tt>PbAc</tt> </td>
<td><tt>battery.type</tt></td>
<td><tt>PbAc</tt></td>
<td>"Battery chemistry"
</td> chemistry"</td>
</tr>
<tr>
<td><tt>device.mfr</tt> </td>
<td><tt>device.mfr</tt></td>
<td><tt>Example Mfg</tt> </td>
<td>""
</td> Mfg</tt></td>
<td>""</td>
</tr>
<tr>
<td><tt>device.model</tt> </td>
<td><tt>device.model</tt></td>
<td><tt>Economy 1600</tt> </td>
<td>""
</td> 1600</tt></td>
<td>""</td>
</tr>
<tr>
<td><tt>device.serial</tt> </td>
<td><tt>1234567890</tt> </td>
<td>""
</td>
<td><tt>device.serial</tt></td>
<td><tt>1234567890</tt></td>
<td>""</td>
</tr>
<tr>
<td><tt>device.type</tt> </td>
<td><tt>ups</tt> </td>
<td>""
</td>
<td><tt>device.type</tt></td>
<td><tt>ups</tt></td>
<td>""</td>
</tr>
<tr>
<td><tt>driver.name</tt> </td>
<td><tt>usbhid-ups</tt> </td>
<td><tt>driver.name</tt></td>
<td><tt>usbhid-ups</tt></td>
<td>"Driver name"
</td> name"</td>
</tr>
<tr>
<td><tt>driver.parameter.lowbatt</tt> </td>
<td><tt>37</tt> </td>
<td><tt>driver.parameter.lowbatt</tt></td>
<td><tt>37</tt></td>
<td>"Driver parameter: &lt;name&gt;"
</td> &lt;name&gt;"</td>
</tr>
<tr>
<td><tt>driver.parameter.offdelay</tt> </td>
<td><tt>30</tt> </td>
<td><tt>driver.parameter.offdelay</tt></td>
<td><tt>30</tt></td>
<td>"Driver parameter: &lt;name&gt;"
</td> &lt;name&gt;"</td>
</tr>
<tr>
<td><tt>driver.parameter.ondelay</tt> </td>
<td><tt>40</tt> </td>
<td><tt>driver.parameter.ondelay</tt></td>
<td><tt>40</tt></td>
<td>"Driver parameter: &lt;name&gt;"
</td> &lt;name&gt;"</td>
</tr>
<tr>
<td><tt>driver.parameter.pollfreq</tt> </td>
<td><tt>30</tt> </td>
<td><tt>driver.parameter.pollfreq</tt></td>
<td><tt>30</tt></td>
<td>"Driver parameter: &lt;name&gt;"
</td> &lt;name&gt;"</td>
</tr>
<tr>
<td><tt>driver.parameter.pollinterval</tt> </td>
<td><tt>2</tt> </td>
<td><tt>driver.parameter.pollinterval</tt></td>
<td><tt>2</tt></td>
<td>"Driver parameter: &lt;name&gt;"
</td> &lt;name&gt;"</td>
</tr>
<tr>
<td><tt>driver.parameter.port</tt> </td>
<td><tt>auto</tt> </td>
<td><tt>driver.parameter.port</tt></td>
<td><tt>auto</tt></td>
<td>"Driver parameter: &lt;name&gt;"
</td> &lt;name&gt;"</td>
</tr>
<tr>
<td><tt>driver.parameter.synchronous</tt> </td>
<td><tt>no</tt> </td>
<td><tt>driver.parameter.synchronous</tt></td>
<td><tt>no</tt></td>
<td>"Driver parameter: &lt;name&gt;"
</td> &lt;name&gt;"</td>
</tr>
<tr>
<td><tt>driver.parameter.vendorid</tt> </td>
<td><tt>0999</tt> </td>
<td><tt>driver.parameter.vendorid</tt></td>
<td><tt>0999</tt></td>
<td>"Driver parameter: &lt;name&gt;"
</td> &lt;name&gt;"</td>
</tr>
<tr>
<td><tt>driver.version</tt> </td>
<td><tt>2.8.0</tt> </td>
<td><tt>driver.version</tt></td>
<td><tt>2.8.0</tt></td>
<td>"Driver version - NUT release"
</td> release"</td>
</tr>
<tr>
<td><tt>driver.version.data</tt> </td>
<td><tt>driver.version.data</tt></td>
<td><tt>HID 1.39</tt> </td>
<td>""
</td> 1.39</tt></td>
<td>""</td>
</tr>
<tr>
<td><tt>driver.version.internal</tt> </td>
<td><tt>0.41</tt> </td>
<td><tt>driver.version.internal</tt></td>
<td><tt>0.41</tt></td>
<td>"Internal driver version"
</td> version"</td>
</tr>
<tr>
<td><tt>input.transfer.high</tt> </td>
<td><tt>264</tt> </td>
<td><tt>input.transfer.high</tt></td>
<td><tt>264</tt></td>
<td>"High voltage transfer point (V)"
</td> (V)"</td>
</tr>
<tr>
<td><tt>input.transfer.low</tt> </td>
<td><tt>184</tt> </td>
<td><tt>input.transfer.low</tt></td>
<td><tt>184</tt></td>
<td>"Low voltage transfer point (V)"
</td> (V)"</td>
</tr>
<tr>
<td><tt>outlet.1.desc</tt> </td>
<td><tt>outlet.1.desc</tt></td>
<td><tt>PowerShare Outlet 1</tt> </td> 1</tt></td>
<td>"Outlet description"
</td> description"</td>
</tr>
<tr>
<td><tt>outlet.1.id</tt> </td>
<td><tt>2</tt> </td>
<td><tt>outlet.1.id</tt></td>
<td><tt>2</tt></td>
<td>"Outlet system identifier"
</td> identifier"</td>
</tr>
<tr>
<td><tt>outlet.1.status</tt> </td>
<td><tt>on</tt> </td>
<td><tt>outlet.1.status</tt></td>
<td><tt>on</tt></td>
<td>"Outlet switch status"
</td> status"</td>
</tr>
<tr>
<td><tt>outlet.1.switchable</tt> </td>
<td><tt>no</tt> </td>
<td><tt>outlet.1.switchable</tt></td>
<td><tt>no</tt></td>
<td>"Outlet switch ability"
</td> ability"</td>
</tr>
<tr>
<td><tt>outlet.2.desc</tt> </td>
<td><tt>outlet.2.desc</tt></td>
<td><tt>PowerShare Outlet 2</tt> </td> 2</tt></td>
<td>"Outlet description"
</td> description"</td>
</tr>
<tr>
<td><tt>outlet.2.id</tt> </td>
<td><tt>3</tt> </td>
<td><tt>outlet.2.id</tt></td>
<td><tt>3</tt></td>
<td>"Outlet system identifier"
</td> identifier"</td>
</tr>
<tr>
<td><tt>outlet.2.status</tt> </td>
<td><tt>on</tt> </td>
<td><tt>outlet.2.status</tt></td>
<td><tt>on</tt></td>
<td>"Outlet switch status"
</td> status"</td>
</tr>
<tr>
<td><tt>outlet.2.switchable</tt> </td>
<td><tt>no</tt> </td>
<td><tt>outlet.2.switchable</tt></td>
<td><tt>no</tt></td>
<td>"Outlet switch ability"
</td> ability"</td>
</tr>
<tr>
<td><tt>outlet.desc</tt> </td>
<td><tt>outlet.desc</tt></td>
<td><tt>Main Outlet</tt> </td> Outlet</tt></td>
<td>"Outlet description"
</td> description"</td>
</tr>
<tr>
<td><tt>outlet.id</tt> </td>
<td><tt>1</tt> </td>
<td><tt>outlet.id</tt></td>
<td><tt>1</tt></td>
<td>"Outlet system identifier"
</td> identifier"</td>
</tr>
<tr>
<td><tt>outlet.power</tt> </td>
<td><tt>25</tt> </td>
<td>""
</td>
<td><tt>outlet.power</tt></td>
<td><tt>25</tt></td>
<td>""</td>
</tr>
<tr>
<td><tt>outlet.switchable</tt> </td>
<td><tt>no</tt> </td>
<td><tt>outlet.switchable</tt></td>
<td><tt>no</tt></td>
<td>"Outlet switch ability"
</td> ability"</td>
</tr>
<tr>
<td><tt>output.frequency.nominal</tt> </td>
<td><tt>50</tt> </td>
<td><tt>output.frequency.nominal</tt></td>
<td><tt>50</tt></td>
<td>"Nominal output frequency (Hz)"
</td> (Hz)"</td>
</tr>
<tr>
<td><tt>output.voltage</tt> </td>
<td><tt>230.0</tt> </td>
<td><tt>output.voltage</tt></td>
<td><tt>230.0</tt></td>
<td>"Output voltage (V)"
</td> (V)"</td>
</tr>
<tr>
<td><tt>output.voltage.nominal</tt> </td>
<td><tt>230</tt> </td>
<td><tt>output.voltage.nominal</tt></td>
<td><tt>230</tt></td>
<td>"Nominal output voltage (V)"
</td> (V)"</td>
</tr>
<tr>
<td><tt>ups.beeper.status</tt> </td>
<td><tt>enabled</tt> </td>
<td><tt>ups.beeper.status</tt></td>
<td><tt>enabled</tt></td>
<td>"UPS beeper status"
</td> status"</td>
</tr>
<tr>
<td><tt>ups.delay.shutdown</tt> </td>
<td><tt>20</tt> </td>
<td><tt>ups.delay.shutdown</tt></td>
<td><tt>20</tt></td>
<td>"Interval to wait after shutdown with delay command (seconds)"
</td> (seconds)"</td>
</tr>
<tr>
<td><tt>ups.delay.start</tt> </td>
<td><tt>30</tt> </td>
<td><tt>ups.delay.start</tt></td>
<td><tt>30</tt></td>
<td>"Interval to wait before (re)starting the load (seconds)"
</td> (seconds)"</td>
</tr>
<tr>
<td><tt>ups.firmware</tt> </td>
<td><tt>02</tt> </td>
<td><tt>ups.firmware</tt></td>
<td><tt>02</tt></td>
<td>"UPS firmware"
</td> firmware"</td>
</tr>
<tr>
<td><tt>ups.load</tt> </td>
<td><tt>20</tt> </td>
<td><tt>ups.load</tt></td>
<td><tt>20</tt></td>
<td>"Load on UPS (percent of full)"
</td> full)"</td>
</tr>
<tr>
<td><tt>ups.mfr</tt> </td>
<td><tt>ups.mfr</tt></td>
<td><tt>Example Mfg</tt> </td> Mfg</tt></td>
<td>"UPS manufacturer"
</td> manufacturer"</td>
</tr>
<tr>
<td><tt>ups.model</tt> </td>
<td><tt>ups.model</tt></td>
<td><tt>Economy 1600</tt> </td> 1600</tt></td>
<td>"UPS model"
</td> model"</td>
</tr>
<tr>
<td><tt>ups.power.nominal</tt> </td>
<td><tt>1600</tt> </td>
<td><tt>ups.power.nominal</tt></td>
<td><tt>1600</tt></td>
<td>"UPS power rating (VA)"
</td> (VA)"</td>
</tr>
<tr>
<td><tt>ups.productid</tt> </td>
<td><tt>ffff</tt> </td>
<td><tt>ups.productid</tt></td>
<td><tt>ffff</tt></td>
<td>"Product ID for USB devices"
</td> devices"</td>
</tr>
<tr>
<td><tt>ups.serial</tt> </td>
<td><tt>000000000</tt> </td>
<td>"UPS serial number"
</td> number"</td>
</tr>
<tr>
<td><tt>ups.status</tt> </td>
<td><tt>OL</tt> </td>
<td><tt>ups.status</tt></td>
<td><tt>OL</tt></td>
<td>"UPS status"
</td> status"</td>
</tr>
<tr>
<td><tt>ups.temperature</tt> </td>
<td><tt>27</tt> </td>
<td><tt>ups.temperature</tt></td>
<td><tt>27</tt></td>
<td>"UPS temperature (C)"
</td> (C)"</td>
</tr>
<tr>
<td><tt>ups.timer.shutdown</tt> </td>
<td><tt>0</tt> </td>
<td><tt>ups.timer.shutdown</tt></td>
<td><tt>0</tt></td>
<td>"Time before the load will be shutdown (seconds)"
</td> (seconds)"</td>
</tr>
<tr>
<td><tt>ups.timer.start</tt> </td>
<td><tt>0</tt> </td>
<td><tt>ups.timer.start</tt></td>
<td><tt>0</tt></td>
<td>"Time before the load will be started (seconds)"
</td> (seconds)"</td>
</tr>
<tr>
<td><tt>ups.vendorid</tt> </td>
<td><tt>0999</tt> </td>
<td><tt>ups.vendorid</tt></td>
<td><tt>0999</tt></td>
<td>"Vendor ID for USB devices"
</td> devices"</td>
</tr>
</tbody>
</table>
</section>
<section anchor="rw">
<name>Typical UPS Readable and Writable Variables</name>
<t>Some of the features of a UPS are represented by variables which that
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
example, utility program <tt>upsrw</tt> <tt>upsrw</tt>, as included in the NUT package, package;
see <xref target="util"></xref>.
</t>
<table>
<name>Typical readable Readable and writable Writable UPS Variables
</name> Variables</name>
<thead>
<tr>
<th align="center">Variable </th> align="center">Variable</th>
<th align="center">Typical value
    </th> Value</th>
<th align="center">Default description provided Description Provided as response Response to the command Command <tt>GET DESC</tt>
</th> DESC</tt></th>
</tr>
</thead>
<tbody>
<tr>
<td><tt>battery.charge.low</tt> </td>
<td><tt>20</tt> </td>
<td><tt>battery.charge.low</tt></td>
<td><tt>20</tt></td>
<td><tt>"Remaining battery level when UPS switches to LB (percent)"</tt>
</td> (percent)"</tt></td>
</tr>
<tr>
<td><tt>input.transfer.high</tt> </td>
<td><tt>264</tt> </td>
<td><tt>input.transfer.high</tt></td>
<td><tt>264</tt></td>
<td><tt>"High voltage transfer point (V)"</tt>
</td> (V)"</tt></td>
</tr>
<tr>
<td><tt>input.transfer.low</tt> </td>
<td><tt>184</tt> </td>
<td><tt>input.transfer.low</tt></td>
<td><tt>184</tt></td>
<td><tt>"Low voltage transfer point (V)"</tt>
</td> (V)"</tt></td>
</tr>
<tr>
<td><tt>outlet.1.desc</tt> </td>
<td><tt>outlet.1.desc</tt></td>
<td><tt>PowerShare Outlet 1</tt> </td> 1</tt></td>
<td><tt>"Outlet description"</tt>
</td> description"</tt></td>
</tr>
<tr>
<td><tt>outlet.2.desc</tt> </td>
<td><tt>outlet.2.desc</tt></td>
<td><tt>PowerShare Outlet 2</tt> </td> 2</tt></td>
<td><tt>"Outlet description"</tt>
</td> description"</tt></td>
</tr>
<tr>
<td><tt>outlet.2.switchable</tt> </td>
<td><tt>no</tt> </td>
<td><tt>outlet.2.switchable</tt></td>
<td><tt>no</tt></td>
<td><tt>"Outlet switch ability"</tt>
</td> ability"</tt></td>
</tr>
<tr>
<td><tt>outlet.desc</tt> </td>
<td><tt>outlet.desc</tt></td>
<td><tt>Main Outlet</tt> </td> Outlet</tt></td>
<td><tt>"Outlet description"</tt>
</td> description"</tt></td>
</tr>
<tr>
<td><tt>outlet.power</tt> </td>
<td><tt>25</tt> </td>
<td><tt>outlet.power</tt></td>
<td><tt>25</tt></td>
<td><tt>"Description unavailable"</tt>
</td> unavailable"</tt></td>
</tr>
<tr>
<td><tt>output.voltage.nominal</tt> </td>
<td><tt>230</tt> </td>
<td><tt>output.voltage.nominal</tt></td>
<td><tt>230</tt></td>
<td><tt>"Nominal output voltage (V)"</tt>
</td> (V)"</tt></td>
</tr>
<tr>
<td><tt>ups.delay.shutdown</tt> </td>
<td><tt>20</tt> </td>
<td><tt>ups.delay.shutdown</tt></td>
<td><tt>20</tt></td>
<td><tt>"Interval to wait after shutdown with delay command (seconds)"</tt>
</td> (seconds)"</tt></td>
</tr>
<tr>
<td><tt>ups.delay.start</tt> </td>
<td><tt>30</tt> </td>
<td><tt>ups.delay.start</tt></td>
<td><tt>30</tt></td>
<td><tt>"Interval to wait before (re)starting the load (seconds)"</tt>
</td> (seconds)"</tt></td>
</tr>
</tbody>
</table>
</section>
<section anchor="instcmdexamples">
<name>Typical UPS Instant Commands</name>
<t>Some of the features of a UPS are actions known as instant
commands, see Instant
Commands (see <xref target="IC"></xref>, target="IC"></xref>), which may be ordered by the
user.  The following variables represent such instant commands. 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 example, utility
program <tt>upscmd</tt> <tt>upscmd</tt>, as included in the NUT package, package;
see <xref target="util"></xref>.
</t>
<table>
<name>Typical Instant Commands
</name> Commands</name>
<thead>
<tr>
<th align="center">Command </th> align="center">Command</th>
<th align="center">Meaning
</th> align="center">Meaning</th>
</tr>
</thead>
<tbody>
<tr>
<td><tt>beeper.disable</tt> </td>
<td><tt>beeper.disable</tt></td>
<td>Disable the UPS beeper
</td> beeper</td>
</tr>
<tr>
<td><tt>beeper.enable</tt> </td>
<td><tt>beeper.enable</tt></td>
<td>Enable the UPS beeper
</td> beeper</td>
</tr>
<tr>
<td><tt>beeper.mute</tt> </td>
<td><tt>beeper.mute</tt></td>
<td>Temporarily mute the UPS beeper
</td> beeper</td>
</tr>
<tr>
<td><tt>load.off</tt> </td>
<td><tt>load.off</tt></td>
<td>Turn off the load immediately
</td> immediately</td>
</tr>
<tr>
<td><tt>load.off.delay</tt> </td>
<td><tt>load.off.delay</tt></td>
<td>Turn off the load with a delay (seconds)
</td> (seconds)</td>
</tr>
<tr>
<td><tt>load.on</tt> </td>
<td><tt>load.on</tt></td>
<td>Turn on the load immediately
</td> immediately</td>
</tr>
<tr>
<td><tt>load.on.delay</tt> </td>
<td><tt>load.on.delay</tt></td>
<td>Turn on the load with a delay (seconds)
</td> (seconds)</td>
</tr>
<tr>
<td><tt>shutdown.return</tt> </td>
<td><tt>shutdown.return</tt></td>
<td>Turn off the load and return when power is back
</td> back</td>
</tr>
<tr>
<td><tt>shutdown.stayoff</tt> </td>
<td><tt>shutdown.stayoff</tt></td>
<td>Turn off the load and remain off
</td> off</td>
</tr>
<tr>
<td><tt>shutdown.stop</tt> </td>
<td><tt>shutdown.stop</tt></td>
<td>Stop a shutdown in progress
</td> progress</td>
</tr>
</tbody>
</table>
</section>
</section>
<section anchor="shutdownstory">
<name>The Shutdown Story for System and UPS</name>
<t>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.
</t>
<t>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 <xref target="fig.story"></xref>.
</t>
<figure anchor="fig.story">
<name>Long-running unattended server
</name>
<name>Long-Running Unattended Server</name>
<artwork align="center"> align="center" type="ascii-art">
           ,------------------SERVER------------------,
           |                    |                     |
 ,-----,   |     UPS       &lt;-Commands        UPS      |
 | UPS |---|  Attachment        |         Management  |
 |     |===|    Daemon       Responses-&gt;    Daemon    |
 /-----\   '--------------------'---------------------'
                             Internal
                             loopback</artwork>
                             loopback
</artwork>
</figure>
<ol spacing="normal" indent="adaptive">
<li anchor="start"><em>The public power supply is on</em> -- on.</em> The system runs
normally. Every 5 seconds, variable <tt>ups.status</tt> reports
<tt>OL</tt>. -- <em>Days, weeks, months go by...</em>
</li> by...</em></li>
<li><em>Winter storm. Tree falls on power lines. The public power supply fails</em>
-- fails.</em>
The server remains operational operational, running on the UPS battery. The
Management Daemon polls the Attachment Daemon, Daemon and detects status change <tt>OL</tt>-&gt;<tt>OB</tt>.
</li> <tt>OL</tt>-&gt;<tt>OB</tt>.</li>
<li>The Management Daemon logs warning messages. The server is still operational operational,
running on the UPS battery. -- <em>Minutes go by...</em>
</li> by...</em></li>
<li>The battery discharges below the level specified by variable
<tt>battery.charge.low</tt>. The server remains operational, but the
UPS battery will not last much longer.  The Management Daemon polls the Attachment Daemon, Daemon and
detects status change <tt>OB</tt>-&gt;<tt>OB</tt>+<tt>LB</tt>.
</li> <tt>OB</tt>-&gt;<tt>OB</tt>+<tt>LB</tt>.</li>
<li>The Management Daemon logs the low battery event.
</li> event.</li>
<li anchor="setFSD">The Management Daemon decides to call for a system shutdown.
It sets status <tt>FSD</tt> in the Attachment Daemon to call on any secondaries Secondaries to
shut down and waits for command <tt>GET NUMATTACH</tt> to report one
single attachment, i.e. i.e., the Primary itself. The Management Daemon then issues the
system shutdown command for itself.
</li> itself.</li>
<li anchor="upsdrvctl">The operating system's shutdown process takes
over. During the system shutdown, a NUT Project specific script to the NUT Project or an
equivalent systemd system service unit runs the command <tt>upsdrvctl
shutdown</tt>. 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, sockets but may not turn the UPS off completely.
A delayed shutdown is sometimes audible, and the characteristic
beeping of the UPS stops.
</li> stops.</li>
<li>The system shuts down and powers down, hopefully before the N=20
seconds have passed.
</li> passed.</li>
<li anchor="UPSshutdown"><t><em>N seconds after
item <xref target="upsdrvctl" format="counter"></xref></em> -- 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".
</t><t>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
<tt>upsdrvctl shutdown</tt> command. -- <em>Minutes, hours, days go
by...</em>
</t></li>
by...</em></t></li>
<li><em>Some time later, maybe much later, the public power supply returns</em> -- returns.</em>
The UPS reconnects it's its outlets to send power to the protected system.
</li> system.</li>
<li anchor="UPSrestart">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.
</li>
begins.</li>
<li>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
<tt>OL</tt>+<tt>LB</tt>.
</li>
<tt>OL</tt>+<tt>LB</tt>.</li>
<li>After some time, the battery charges above
the <tt>battery.charge.low</tt> threshold threshold, and the Attachment Daemon declares the
status change <tt>OL</tt>+<tt>LB</tt>-&gt;<tt>OL</tt>. We are now back in the same
situation as item <xref target="start" format="counter"></xref> above.
</li> above.</li>
</ol>
</section>
<section anchor="differences">
<name>Technical Terms: Historical Differences</name>
<t>This appendix lists the major differences between the technical
terms used in NUT software release 2.8.0 and documented in this text,
and
as well as those used in previous version 2.7.4 of the NUT Project.
</t>
<table>
  <name>Technical Terms: Historical Differences</name>
<thead>
<tr>
<th>Term in previous<br/>release Previous<br/>Release NUT 2.7.4
	                    </th> 2.7.4</th>
<th>Term in this document,<br/>release Document,<br/>Release NUT 2.8.0
	                                              </th> 2.8.0</th>
<th>Reference
</th>
</tr>
</thead>
<tbody>
<tr>
<td>ALREADY-LOGGED-IN   </td>
<td>ALREADY-ATTACHED      </td>
<td>ALREADY-LOGGED-IN</td>
<td>ALREADY-ATTACHED</td>
<td><xref target="errors"></xref>
</td> target="errors"></xref></td>
</tr>
<tr>
<td>ALREADY-SSL-MODE    </td>
<td>TLS-ALREADY-ENABLED   </td>
<td>ALREADY-SSL-MODE</td>
<td>TLS-ALREADY-ENABLED</td>
<td><xref target="errors"></xref>
</td> target="errors"></xref></td>
</tr>
<tr>
<td><tt>LOGIN</tt>      </td>
<td><tt>ATTACH</tt>       </td>
<td><tt>LOGIN</tt></td>
<td><tt>ATTACH</tt></td>
<td><xref target="attach"></xref>
</td> target="attach"></xref></td>
</tr>
<tr>
<td><tt>LOGOUT</tt>     </td>
<td><tt>DETACH</tt>       </td>
<td><tt>LOGOUT</tt></td>
<td><tt>DETACH</tt></td>
<td><xref target="detach"></xref>
</td> target="detach"></xref></td>
</tr>
<tr>
<td>Master              </td>
<td>Primary               </td>
<td>Master</td>
<td>Primary</td>
<td><xref target="prim"></xref>
</td> target="prim"></xref></td>
</tr>
<tr>
<td><tt>NETVER</tt>     </td>
<td><tt>PROTVER</tt>      </td>
<td><tt>NETVER</tt></td>
<td><tt>PROTVER</tt></td>
<td><xref target="protver"></xref>
</td> target="protver"></xref></td>
</tr>
<tr>
<td><tt>NUMLOGINS</tt>  </td>
<td><tt>NUMATTACH</tt>    </td>
<td><tt>NUMLOGINS</tt></td>
<td><tt>NUMATTACH</tt></td>
<td><xref target="numattach"></xref>
</td> target="numattach"></xref></td>
</tr>
<tr>
<td>Slave               </td>
<td>Secondary             </td>
<td>Slave</td>
<td>Secondary</td>
<td><xref target="sec"></xref>
</td> target="sec"></xref></td>
</tr>
</tbody>
</table>
</section>
<section anchor="AppendixEavesdropping">
<name>Security Defences Defenses in Release 2.7.4</name>
<t>Previous NUT version 2.7.4 did not provide support for TLS
1.3 <xref target="RFC8446"></xref>.  The following subsections
describe mitigating techniques.
</t>
<section anchor="Shims">
<name>Shims</name>
<t>Previous version 2.7.4 of NUT did not support TLS
1.3 <xref target="RFC8446"></xref>.  Where such protection is needed
for version 2.7.4, a possible technique introduces shims between the
Attachment Daemon and the network, network and between the network and the Management Daemon Daemon, as shown
in figure <xref target="fig.shim" format="counter"></xref>. target="fig.shim"/>.  These shims
provide TLS 1.3 support, thus allowing the Attachment Daemon and Management Daemon to continue
temporarily without native TLS. having TLS implementations themselves.  The technique has been successfully
tested.
</t>
<figure anchor="fig.shim">
<name>Shims provide Provide TLS support during migration Support During Migration
</name>
<artwork align="center"> align="center" type="ascii-art">
                TLS shim listens     TLS shim listens
                on port TBD1/TCP     on port 3493/TCP
 ,-----,------------,----,               ,----,--------------,
 | UPS - Attachment |TLS | &lt;-STARTTLS    | TLS|  Management  |
 |     |   Daemon   |shim|         OK--&gt; |shim|    Daemon    |
 /-----'------------'----\               '----'--------------'
         Listens on
       port 3493/TCP</artwork> 3493/TCP
</artwork>
</figure>
<section>
<name>Attachment Daemon Shim</name>
<t>The shim in front of the Attachment Daemon listens to incoming traffic on port
TBD1/TCP.  When it receives the command <tt>STARTTLS</tt> it <tt>STARTTLS</tt>, it:
</t>
<ol spacing="compact" indent="adaptive">
<li>Returns
<li>returns <tt>OK</tt> to the client and sets up TLS encapsulation.
</li>
<li>Does encapsulation.</li>
<li>does not send <tt>STARTTLS</tt> to the Attachment Daemon port 3493/TCP.
</li> 3493/TCP.</li>
</ol>
<t>All other commands and responses are passed through.
</t>
<t>Note: Port TBD1/TCP is not specified by this text.
</t>
</section>
<section>
<name>Management Daemon Shim</name>
<t>The shim in front of the Management Daemon listens for incoming traffic on port
3493/TCP.  When it receives the command <tt>STARTTLS</tt> it <tt>STARTTLS</tt>, it:
</t>
<ol spacing="compact" indent="adaptive">
<li>Returns
<li>returns <tt>FEATURE-NOT-CONFIGURED</tt> to the client.
</li>
<li>Sends client.</li>
<li>sends <tt>STARTTLS</tt> to the Attachment Daemon on port TBD1/TCP.
</li> TBD1/TCP.</li>
</ol>
<t>All other commands and responses are passed through.
</t>
</section>
</section>
<section anchor="TLStunnel">
<name>TLS Tunnels</name>
<t>Another technique is the use of <xref target="RFC8446">TLS
tunnels</xref>, using a software software, such as
stunnel <xref target="stunnel"></xref> target="stunnel"></xref>, 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.
</t>
</section>
<section anchor="VPN">
<name>VPN</name>
<t>A further option to secure communications is very similar
to <xref target="RFC8446">TLS tunnelling</xref> tunneling</xref> and consists of
routing the NUT traffic through a Virtual Private Network, VPN. Network (VPN).
</t>
</section>
<section anchor="VLAN">
<name>VLAN</name>
<t>A fourth option is to isolate the UPS management traffic at the
network switching level using a Virtual LAN, VLAN LAN (VLAN) technique.
</t>
<figure anchor="fig.VLAN">
<name>UPS Management Protocol runs Runs over its own Its Own VLAN
</name>
<artwork align="center"> align="center" type="ascii-art">
          ,-------------,               ,-------------,
,-----,   | Attachment  |               | Management  |
| UPS |---|   Daemon    |               |   Daemon    |
|     |   |-------------|      UPS      |-------------|
|     |===|             |   Management  |    UPS      |
/-----\   | Protected   |~~~~~~~~~~~~~~~| Management  |
          |  Server     |     VLAN      |   Client    |
          |             |               '-------------'
          '-------------'
      Production | VLAN
             ,---|-------,
            ,-----------,|
           ,-----------,|'
           |  Clients  |'
           '-----------'</artwork>
           '-----------'
</artwork>
</figure>
<t>In <xref target="fig.VLAN"></xref> target="fig.VLAN"></xref>, there are two VLANS: The the main
traffic between the protected server and its clients uses using the
production VLAN. The UPS management traffic between the Attachment and
Management Daemons uses the UPS management VLAN marked as
~~~~~~~~~~~~~.
</t>
</section>
</section>
<section anchor="adsec">
<name>Administrative Security</name>
<t>Administrative commands commands, such as <tt>FSD</tt>, <tt>INSTCMD</tt> <tt>INSTCMD</tt>,
and <tt>SET</tt> <tt>SET</tt>, are powerful and can have a deep effect on system
integrity,
integrity. For example, the command <tt>FSD</tt> is involved in
mission critical
mission-critical system shutdown decisions.  Access to them needs to
be managed and restricted.  This clause section presents the current practice.
</t>
<section anchor="adminuser">
<name>Management of Administrative Users</name>
<t>The Attachment Daemon maintains a file (currently <tt>upsd.users</tt>) defining that defines
each administrative user.  Note that these users are independent of
those recorded in file <tt>/etc/passwd</tt>.  Each administrative user
gets its own section in file <tt>upsd.users</tt>. The declarations in
that section set the parameters which that define that user's
privileges. The section begins with the name of the user enclosed in
square brackets,  OPENING BRACKET [
and  CLOSING BRACKET ],  opening bracket ([)
and  closing bracket (]), and continues until
the next user name username in brackets or EOF.
</t>
<t>For example example, the following file declares two administrative users users,
<tt>admin</tt> and <tt>pfy</tt>:</t>
<sourcecode>
<sourcecode name="" type="shell">
   [admin]
       password = sekret
       upsmon master
       actions = SET
       instcmds = ALL
   [pfy]
       password = sekret
       instcmds = test.panel.start
       instcmds = test.panel.stop
</sourcecode>
<t>Within each section section, the administrative user declarations are:
</t>
<table>
<name>Administrative user declarations
</name> User Declarations</name>
<thead>
<tr>
<th align="center">Declaration </th>
<th align="center">Meaning
</th> align="center">Meaning</th>
</tr>
</thead>
<tbody>
<tr>
<td><tt>actions</tt>
    </td>
<td><tt>actions</tt></td>
<td><t>Allow the user to do certain things in the Attachment Daemon. To
        specify multiple actions, use multiple instances of the
        declaration. Valid actions are:
        </t><ul> are:</t>
<ul spacing="normal">
<li><tt>FSD</tt> Set the "Forced Shutdown" flag for this UPS.
See <xref target="FSD"></xref>.
        </li> target="FSD"></xref>.</li>
<li><tt>SET</tt> Change the value of a UPS variable.  See <xref target="set"></xref>.
        </li>
</ul></td>
</tr> target="set"></xref>.</li>
</ul></td></tr>
<tr>
<td><tt>instcmds</tt>
    </td>
<td><tt>instcmds</tt></td>
<td>Let a user initiate specific instant commands. Instant Commands. See
        <xref target="instcmd"></xref>.  Use value <tt>ALL</tt> 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 <tt>upscmd -l</tt> supplied by
        the NUT Project.  The <tt>LIST CMD</tt> command is issued within
        the client <tt>upscmd</tt>.
    </td> <tt>upscmd</tt>.</td>
</tr>
<tr>
<td><tt>password</tt>
    </td>
<td><tt>password</tt></td>
<td>Set the password for this user.  <em>Your password should be
    more secure than the examples shown.</em>
</td> shown.</em></td>
</tr>
<tr>
<td><tt>upsmon</tt>
    </td>
<td><tt>upsmon</tt></td>
<td>Add the necessary actions for a Management Daemon to process a system
    shutdown. In current practice practice, the value is still <tt>master</tt>
    or <tt>slave</tt>.  Note that there is no
    EQUALS  =.
</td>  =.</td>
</tr>
</tbody>
</table>
</section>
<section anchor="adsecclient">
<name>An Administrative User of a Client Management Daemon</name>
<t>The following examples show the current security practices for
administrative users of a client Management Daemon Daemon. They also illustrate the
command pair <tt>USERNAME</tt> and <tt>PASSWORD</tt>.  See Sections <xref target="username"></xref> target="username" format="counter"></xref>
and <xref target="password"></xref>. target="password" format="counter"></xref>.
</t>
<section>
<name>An Administrative User Logs into a Short Session</name>
<t>In this simple example of current practice, the system
administrator sets the battery level at which an Attachment Daemon will raise the
status <tt>LB</tt>, represented by variable <tt>battery.charge.low</tt>, to
35% of full charge.  A system administrator types the following command
to call the client <tt>upsrw</tt> supplied by the
NUT Project.</t>
<sourcecode>upsrw
<sourcecode name="" type="shell">
upsrw -s battery.charge.low=35 -u admin -p sekret UPS-1@example.com
</sourcecode>
<t>Option <tt>-s</tt> specifies the variable and the value,
option <tt>-u</tt> specifies the <tt>USERNAME</tt>, option <tt>-p</tt>
specifies the <tt>PASSWORD</tt>, and <tt>UPS-1@example.com</tt> is the
UPS.  The <tt>USERNAME</tt> and <tt>PASSWORD</tt> commands are issued
within the client <tt>upsrw</tt> <tt>upsrw</tt>, and the Session session is of short duration.
</t>
<t>Note: Your password should be stronger than the example shown.
</t>
</section>
<section anchor="longsess">
<name>An Administrative User Logs into a Long Session</name>
<t>In this second example of current practice, the long-running
Management Daemon <tt>upsmon</tt> <tt>upsmon</tt>, which is responsible for initiating system
shutdowns and which is provided by the NUT Project Project, issues commands
<tt>USERNAME</tt> and <tt>PASSWORD</tt> when it starts up. The data
values needed for the
<tt>USERNAME</tt> and <tt>PASSWORD</tt> commands are provided by a
configuration file <tt>upsmon.conf</tt> <tt>upsmon.conf</tt>, which contains the
line</t>
<sourcecode>MONITOR
line:</t>
<sourcecode name="" type="shell">
MONITOR UPS-1@example.com 1 admin sekret master
</sourcecode>
<t> This says that the UPS to be monitored
is <tt>UPS-1@example.com</tt>, it <tt>UPS-1@example.com</tt>. It provides 1 single power supply, the supply. The
administrative user is <tt>admin</tt> with
password <tt>sekret</tt>. The Management Daemon acts as a Primary, although
current practice still uses the former term <tt>master</tt>.
</t>
<t>The <tt>USERNAME</tt> and <tt>PASSWORD</tt> commands are contained
within the client <tt>upsmon</tt> <tt>upsmon</tt>, and the Session session is of long duration.
</t>
</section>
</section>
</section>
<section anchor="Ack" numbered="false">
<name>Acknowledgments</name>
<t>This document is based on the
NUT Project <xref target="devguide">documentation</xref>. The editor
acknowledges the work of <contact fullname="Charles Lepple"/>, <contact
fullname="Arjen de Korte"/>, <contact fullname="Arnaud Quette"/>,
<contact fullname="Jim Klimov"/>, <contact fullname="Russell Kroll"/>,
<contact fullname="Manuel Wolfshant"/>, <contact fullname="Greg Troxel"/>,
<contact fullname="Mark Hansen"/>, and many others who contribute to
the <xref target="nut-upsuser">nut-upsuser</xref>
and <xref target="nut-upsdev">nut-upsdev</xref> mailing lists.
</t>

<t>Earlier draft versions of this document were prepared using an SGML DTD <xref target="SGML"/>
and an XML meta-DTD defined by HyTime Annex A <xref target="HyTimeA"/>.  Unlike
XML, SGML offers markup minimization, and the earlier drafts took
advantage of this.  The osgmlnorm <xref target="sgmlnorm"/> program generated the
XML that was used as input to xml2rfc <xref target="RFC7991"/>, which then created
the document's current source. The editor acknowledges the help received
from <contact fullname="Carsten Bormann"/> and <contact fullname="Julian Reschke"/> in the xml2rfc mailing list.</t>
<t>Many helpful comments were received from <contact fullname="Eliot Lear"/>,
<contact fullname="Bart Smit"/>, <contact fullname="David Zomaya"/>,
<contact fullname="Joyce Norris"/>, and <contact fullname="Ted Mittelstaedt"/>.
</t>
</section>
</back>
</rfc>