Diff: rfc9271.original.xml

	rfc9271.original.xml	rfc9271.xml

	<?xml version='1.0' encoding='UTF-8' ?>	<?xml version="1.0" encoding="UTF-8"?>
	<!-- The SGML source file draft-rprice-ups-management-protocol-15.sgml2rfc	<!DOCTYPE rfc [
	makes extensive use of markup minimisation. The required	<!ENTITY nbsp " ">
	XML is generated from the SGML by osgmlnorm:I: "OpenSP" version "1.5.2"	<!ENTITY zwsp "">
	using a HyTime architectural form, and is verified to	<!ENTITY nbhy "‑">
	conform by xml2rfc 3.12.2	<!ENTITY wj "⁠">
	Editor: Roger Price, NUT Project, ietf@rogerprice.org	]>
	2022-05-18 08:24:45 UTC
	<!DOCTYPE rfc SYSTEM "rfc2629-xhtml.ent">	<rfc xml:lang="en" xmlns:xi="http://www.w3.org/2001/XInclude" obsoletes="" updat
	<rfc xml:lang="en" xmlns:xi="http://www.w3.org/2001/XInclude" obsoletes="" updat	es="" ipr="trust200902" submissionType="independent" category="info" docName="dr
	es="" category="info" ipr="trust200902" submissionType="IETF" docName="draft-rpr	aft-rprice-ups-management-protocol-15" number="9271" sortRefs="true" symRefs="tr
	ice-ups-management-protocol-15" sortRefs="true" symRefs="true" tocInclude="true"	ue" tocInclude="true" tocDepth="4" version="3">
	tocDepth="4" version="3">
	<front>	<front>

	<title abbrev="UPS management protocol">Uninterruptible Power Supply (UPS) Manag	<title abbrev="UPS Management Protocol">Uninterruptible Power Supply (UPS) Manag
	ement Protocol	ement Protocol -- Commands and Responses</title>
	-- Commands and Responses</title>	<seriesInfo name="RFC" value="9271"/>
	<seriesInfo name="Internet-Draft" value="draft-rprice-ups-management-protocol-15
	"/>
	<author initials="R." surname="Price" fullname="Roger Price" role="editor">	<author initials="R." surname="Price" fullname="Roger Price" role="editor">

	<organization>Network UPS Tools Project	<organization>Network UPS Tools Project</organization>
	</organization>
	<address>	<address>
	<postal>	<postal>

	<street>	<country>France</country>
	</street>
	<city>
	</city>
	<region>
	</region>
	<code>
	</code>
	<country>France
	</country>
	</postal>	</postal>

	<phone>	<email>ietf@rogerprice.org</email>
	</phone>
	<email>ietf@rogerprice.org
	</email>
	</address>	</address>
	</author>	</author>

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

	<abstract>	<abstract>
	<t>This document describes the command/response protocol currently	<t>This document describes the command/response protocol currently
	used in the management of Uninterruptible Power Supply (UPS) units and	used in the management of Uninterruptible Power Supply (UPS) units and

	other power devices often deployed in small offices, and in IT	other power devices often deployed in small offices and in IT
	installations subject to an erratic public power supply. The UPS units typicall y	installations subject to an erratic public power supply. The UPS units typicall y
	interface to an Attachment Daemon in the system they protect. This	interface to an Attachment Daemon in the system they protect. This

	daemon is in turn polled by a Management Daemon which notifies users	daemon is in turn polled by a Management Daemon that notifies users
	and system administrators of power supply incidents, and automates	and system administrators of power supply incidents and automates
	system shutdown decisions. The commands and responses described by	system shutdown decisions. The commands and responses described by
	this document are exchanged between the UPS Attachment Daemon and the	this document are exchanged between the UPS Attachment Daemon and the
	Management Daemon. The practice current when this protocol was first	Management Daemon. The practice current when this protocol was first

	developed risks weak security and this is addressed in the Security	developed risks weak security, and this is addressed in the Security
	Considerations sections of this document.	Considerations sections of this document.
	</t>	</t>
	</abstract>	</abstract>
	</front>	</front>
	<middle>	<middle>
	<section>	<section>
	<name>Introduction</name>	<name>Introduction</name>
	<section anchor="intro">	<section anchor="intro">
	<name>Current Practice</name>	<name>Current Practice</name>
	<t>This document describes UPS management techniques and current UPS	<t>This document describes UPS management techniques and current UPS

	management practice published by the NUT (Network UPS Tools) Project.	management practice published by the Network UPS Tools (NUT) Project.
	The document is based on version 2.8.0 of the NUT Project software	The document is based on version 2.8.0 of the NUT Project software,
	which supports version 1.3 of the NUT protocol.	which supports version 1.3 of the NUT protocol.
	</t>	</t>
	<t>Since May 2002, the protocol described by this document has been	<t>Since May 2002, the protocol described by this document has been
	operating on IANA port 3493/TCP (nut).	operating on IANA port 3493/TCP (nut).
	</t>	</t>
	<section anchor="proj">	<section anchor="proj">

	<name>NUT Software Project</name>	<name>NUT Project</name>
	<t>The primary goal of the NUT (Network UPS Tools) Software	<t>The primary goal of the Network UPS Tools (NUT)
	Project <xref target="NUT"></xref> is to provide support for Power	Project software <xref target="NUT"></xref> is to provide support for power
	Devices, such as Uninterruptible Power Supplies. The Project has been	devices, such as UPSs. The project has been
	in operation since 1998 with a major rework in 2003. It operates	in operation since 1998, with a major rework in 2003. It operates
	through a user <xref target="nut-upsuser">mailing list</xref>, a	through a user <xref target="nut-upsuser">mailing list</xref>, a
	developer <xref target="nut-upsdev">mailing list</xref>,	developer <xref target="nut-upsdev">mailing list</xref>,

	a <xref target="NUT">web site</xref> and	a <xref target="NUT">website</xref>, and
	a <xref target="nut-repository">GitHub repository</xref>. See	a <xref target="nut-repository">GitHub repository</xref>. See

	<xref target="githist"></xref> and <xref target="History"></xref> for	<xref target="githist"></xref> and Appendix J of <xref target="History"></xref> for
	a history of the project.	a history of the project.
	</t>	</t>
	</section>	</section>
	<section anchor="TSS">	<section anchor="TSS">

	<name>The "Shutdown Story"</name>	<name>The Shutdown Story</name>
	<t>"The Shutdown Story", see <xref target="shutdownstory"></xref>,	<t>The Shutdown Story section (see <xref target="shutdownstory"></xref>)
	describes the current UPS management practice for performing a managed	describes the current UPS management practice for performing a managed
	shutdown of unattended infrastructure after an unscheduled failure of	shutdown of unattended infrastructure after an unscheduled failure of

	the public power supply in order to minimise the risk of corruption to data	the public power supply in order to minimize the risk of corruption to data
	processed by this infrastructure.	processed by this infrastructure.
	</t>	</t>
	</section>	</section>
	<section anchor="HowtoRead">	<section anchor="HowtoRead">
	<name>How to Read this Document</name>	<name>How to Read this Document</name>
	<t>As a simplification to ease reading, the term "UPS" is used when	<t>As a simplification to ease reading, the term "UPS" is used when
	"Managed Power Device" would be more complete. The reader should	"Managed Power Device" would be more complete. The reader should
	understand the simple "UPS" to include other managed power devices.	understand the simple "UPS" to include other managed power devices.
	</t>	</t>
	<t>The statuses and events appearing in this document are named with	<t>The statuses and events appearing in this document are named with
	short text-form names, some of which are abbreviations. A full list	short text-form names, some of which are abbreviations. A full list

	of the statuses can be found in <xref target="symbols"></xref> while	of the statuses can be found in <xref target="symbols"></xref>, while
	the events are listed in	the events are listed in
	<xref target="events"></xref>.	<xref target="events"></xref>.
	</t>	</t>
	<t>This document refers to the "public power supply". Other texts	<t>This document refers to the "public power supply". Other texts

	frequently refer to "utility power", "input source power" or even	frequently refer to "utility power", "input source power", or even
	"wall power".	"wall power".
	</t>	</t>
	</section>	</section>
	</section>	</section>
	<section anchor="AddInf">	<section anchor="AddInf">
	<name>Additional Information</name>	<name>Additional Information</name>
	<t>Additional information about the NUT Project is available in	<t>Additional information about the NUT Project is available in
	the <xref target="Documentation">project documentation</xref>.	the <xref target="Documentation">project documentation</xref>.
	Requests for further information about this protocol and related	Requests for further information about this protocol and related
	technical matters may be addressed to	technical matters may be addressed to
	the <xref target="nut-upsuser">mailing list</xref> of the NUT Project.	the <xref target="nut-upsuser">mailing list</xref> of the NUT Project.
	</t>	</t>
	</section>	</section>
	<section>	<section>
	<name>Requirements Language</name>	<name>Requirements Language</name>

	<t>The key words "<bcp14>MUST</bcp14>", "<bcp14>MUST NOT</bcp14>", "<bcp14>REQUI	<t>
	RED</bcp14>", "<bcp14>SHALL</bcp14>",	The key words "<bcp14>MUST</bcp14>", "<bcp14>MUST NOT</bcp14>", "<bcp14>REQUIRED
	"<bcp14>SHALL NOT</bcp14>", "<bcp14>SHOULD</bcp14>", "<bcp14>SHOULD NOT</bcp14>"	</bcp14>", "<bcp14>SHALL</bcp14>", "<bcp14>SHALL
	, "<bcp14>RECOMMENDED</bcp14>", "<bcp14>NOT RECOMMENDED</bcp14>",	NOT</bcp14>", "<bcp14>SHOULD</bcp14>", "<bcp14>SHOULD NOT</bcp14>", "<bcp14>RECO
		MMENDED</bcp14>", "<bcp14>NOT RECOMMENDED</bcp14>",
	"<bcp14>MAY</bcp14>", and "<bcp14>OPTIONAL</bcp14>" in this document are to be i nterpreted as	"<bcp14>MAY</bcp14>", and "<bcp14>OPTIONAL</bcp14>" in this document are to be i nterpreted as

	described in BCP	described in BCP 14 <xref target="RFC2119"/> <xref target="RFC8174"/>
	14 <xref target="RFC2119"></xref> <xref target="RFC8174"></xref> when,	when, and only when, they appear in all capitals, as shown here.
	and only when, they appear in all capitals, as shown here.
	</t>	</t>
	</section>	</section>
	</section>	</section>
	<section anchor="Terminology">	<section anchor="Terminology">
	<name>Terminology</name>	<name>Terminology</name>
	<t>The following technical terms appear in this document. They are	<t>The following technical terms appear in this document. They are
	listed in alphabetical order.	listed in alphabetical order.
	</t>	</t>
	<section anchor="au">	<section anchor="au">
	<name>Administrative User</name>	<name>Administrative User</name>
	<t>In current practice, the commands and other functions offered by	<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 D aemons. These	the Attachment Daemon are made available to a set of users known as Management D aemons. These
	Management Daemons authenticate to the Attachment Daemon with basic credentials (username and	Management Daemons authenticate to the Attachment Daemon with basic credentials (username and
	password). Although called "users", the administrative users are not	password). Although called "users", the administrative users are not

	system users, they are specific to an Attachment Daemon and are listed in a text	system users; they are specific to an Attachment Daemon and are listed in a text
	file (currently <tt>upsd.users</tt>) which is read by the Attachment Daemon and	file (currently <tt>upsd.users</tt>) that is read by the Attachment Daemon and
	which assigns to each of them the password, Instant Commands and	that assigns to each of them the password, Instant Commands, and
	actions which are allowed, together with the Primary or Secondary	actions that are allowed, together with the Primary or Secondary
	status of the Management Daemon. For details,	status of the Management Daemon. For details,

	see <xref target="adminuser"></xref>. For details of Primary see	see <xref target="adminuser"></xref>. For details of the Primary, see
	<xref target="prim"></xref>, and for details of Secondary see <xref target="sec"	<xref target="prim"></xref>; for details of the Secondary, see <xref target="sec
	></xref>. Typically a	"></xref>. Typically, a
	high-level user will be able to send command <tt>FSD</tt> but a	high-level user will be able to send command <tt>FSD</tt>, but a
	low-level user might only be allowed to access the test panel. The	low-level user might only be allowed to access the test panel. The
	security provisions for administrative users are discussed in	security provisions for administrative users are discussed in
	<xref target="adsec"></xref>.	<xref target="adsec"></xref>.
	</t>	</t>
	</section>	</section>
	<section anchor="AD">	<section anchor="AD">
	<name>Attachment Daemon</name>	<name>Attachment Daemon</name>

	<t>The Attachment Daemon retrieves status from the UPS and sends	<t>The Attachment Daemon retrieves the status from the UPS and sends
	commands to it often through a Driver specific to the hardware model	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	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	maintains an abstracted view of the hardware through the use of
	hardware statuses. See <xref target="st"></xref>. A Management Daemon may	hardware statuses. See <xref target="st"></xref>. A Management Daemon may
	consult the abstracted view using the commands described in this	consult the abstracted view using the commands described in this
	document.	document.
	</t>	</t>
	<t>See <xref target="MinSup"></xref> for details of the recommended	<t>See <xref target="MinSup"></xref> for details of the recommended

	minimum support of variables which calls for Attachment Daemon support	minimum support of variables, which calls for Attachment Daemon support
	of statuses <tt>OB</tt>, <tt>OL</tt>, <tt>LB</tt> and <tt>FSD</tt>.	of statuses <tt>OB</tt>, <tt>OL</tt>, <tt>LB</tt>, and <tt>FSD</tt>.
	</t>	</t>


	<t>The NUT Project has implemented an Attachment Daemon as program <tt>upsd</tt>	<t>The NUT Project has implemented an Attachment Daemon as program <tt>upsd</tt>

	and a set of hardware specific drivers, all written in K&R C. The	and a set of hardware-specific Drivers, all written in K&R C <xref target="C
	Attachment Daemon is launched as system user "root", but for better security, th	2ndEd"/>. The
	en	Attachment Daemon is launched as system user "root" but for better security; the
	drops privilege to run as a detached software service.	n, it
		drops the privilege to run as a detached software service.
	</t>	</t>
	</section>	</section>
	<section anchor="Driver">	<section anchor="Driver">
	<name>Driver</name>	<name>Driver</name>

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

	<t>A UPS Event occurs in the Management Daemon when a change in UPS status is	<t>A UPS event occurs in the Management Daemon when a change in the UPS status i s
	received from the Attachment Daemon. This event is internal to the Management D aemon.	received from the Attachment Daemon. This event is internal to the Management D aemon.
	See <xref target="events"></xref>.	See <xref target="events"></xref>.
	</t>	</t>
	</section>	</section>
	<section anchor="IC">	<section anchor="IC">
	<name>Instant Command</name>	<name>Instant Command</name>

	<t>A command which when sent to the Attachment Daemon is passed to the driver an	<t>An Instant Command is a command that, when sent to the Attachment Daemon,
	d	is passed to the Driver and
	sent to the hardware without any configured delay to perform a	sent to the hardware without any configured delay to perform a

	function. For example <tt>INSTCMD su700 test.panel.start</tt> .	function. For example, <tt>INSTCMD su700 test.panel.start</tt>;.
	See <xref target="instcmd"></xref>.	See <xref target="instcmd"></xref>.
	</t>	</t>
	</section>	</section>
	<section anchor="MD">	<section anchor="MD">
	<name>Management Daemon</name>	<name>Management Daemon</name>
	<t>The Management Daemon is primarily responsible for managing the	<t>The Management Daemon is primarily responsible for managing the
	hardware and orchestrating system-wide actions after a power event.	hardware and orchestrating system-wide actions after a power event.

	Using commands sent to the Attachment Daemon it follows the status of the UPS an d	Using commands sent to the Attachment Daemon, it follows the status of the UPS a nd
	determines when UPS events occur. It takes decisions based on the	determines when UPS events occur. It takes decisions based on the
	events, such as calling for a system shutdown. See	events, such as calling for a system shutdown. See
	<xref target="shutdownstory"></xref>. Although the term includes the	<xref target="shutdownstory"></xref>. Although the term includes the

	word "Daemon" nothing requires that it be implemented as a detached	word "Daemon", nothing requires that it be implemented as a detached
	software service. The Management Daemon may also provide	software service. The Management Daemon may also provide

	administrative functions such as a graphic interface to view the	administrative functions, such as a graphic interface to view the
	hardware activity.	hardware activity.
	</t>	</t>
	<t>There are several examples of a Management Daemon: the NUT Project	<t>There are several examples of a Management Daemon: the NUT Project

	provides <tt>upsmon</tt> which takes the system shutdown decision when	provides <tt>upsmon</tt>, which takes the system shutdown decision when
	the public power supply fails. Further configuration options such as timers are	the public power supply fails. Further configuration options, such as timers, a
	provided by helper program <tt>upssched</tt>.	re
		provided by the helper program <tt>upssched</tt>.
	</t>	</t>
	<t anchor="util">Other programs represent the Management Daemon:	<t anchor="util">Other programs represent the Management Daemon:
	</t>	</t>
	<ul spacing="compact">	<ul spacing="compact">
	<li><tt>upsc</tt> reports the values of the variables defined for a	<li><tt>upsc</tt> reports the values of the variables defined for a

	given UPS, see <xref target="typvar"></xref>.	given UPS; see <xref target="typvar"></xref>.
	</li>	</li>
	<li><tt>upsrw</tt> reports on and changes the values of the readable	<li><tt>upsrw</tt> reports on and changes the values of the readable

	and writable configuration variables defined for a given UPS,	and writable configuration variables defined for a given UPS;
	see <xref target="rw"></xref>.	see <xref target="rw"></xref>.
	</li>	</li>
	<li><tt>upscmd</tt> reports on and executes the instant action	<li><tt>upscmd</tt> reports on and executes the instant action

	commands defined for a given UPS, see <xref target="instcmd"></xref>.	commands defined for a given UPS; see <xref target="instcmd"></xref>.
	</li>	</li>
	<li><tt>UPSmon.py</tt> is an experimental Python3 rewrite	<li><tt>UPSmon.py</tt> is an experimental Python3 rewrite

	of <tt>upsmon</tt> and <tt>upssched</tt> which includes support	of <tt>upsmon</tt> and <tt>upssched</tt> that includes support
	for <xref target="RFC8446">TLS 1.3</xref>.	for <xref target="RFC8446">TLS 1.3</xref>.
	</li>	</li>
	</ul>	</ul>
	</section>	</section>
	<section anchor="prim">	<section anchor="prim">
	<name>Primary</name>	<name>Primary</name>

	<t>When a power device such as a UPS unit supplies power to more than	<t>When a power device, such as a UPS unit, supplies power to more than
	one system, the computer running the driver is known as the Primary.	one system, the computer running the Driver is known as the Primary.
	The others are Secondaries. See figure <xref target="fig.oview4" format="counte	The others are Secondaries. See <xref target="fig.oview4"/>. Common current pr
	r"></xref>. Common current practice for system administrators is	actice for system administrators is
	to consider the Management Daemon in the Primary to be the Primary Management	to consider the Management Daemon in the Primary to be the Primary Management

	Daemon which is in charge of the shutdown of all the systems powered	Daemon that is in charge of the shutdown of all the systems powered
	by the UPS. The Primary Management Daemon sets status	by the UPS. The Primary Management Daemon sets status

	symbol <tt>FSD</tt> to order the secondaries to shut down.	symbol <tt>FSD</tt> to order the Secondaries to shut down.
	</t>
	<t>Note: Historically, the Primary was known as the "Master".
	</t>	</t>

		<aside>
		<t>Note: Historically, the Primary was known as the "Master".</t>
		</aside>
	</section>	</section>
	<section anchor="sec">	<section anchor="sec">
	<name>Secondary</name>	<name>Secondary</name>

	<t>When a hardware device such as a UPS unit supplies power to more	<t>When a hardware device, such as a UPS unit, supplies power to more
	than one system, the system which communicates directly with the UPS	than one system, the system that communicates directly with the UPS
	unit e.g. using a USB, RS232, or network connection, is known as the	unit, e.g., using a USB, RS-232, or a network connection, is known as the
	Primariy. The other are Secondaries. There is no Attachment Daemon in a	Primary. The others are Secondaries. There is no Attachment Daemon in a
	Secondary. See figure <xref target="fig.oview4" format="counter"></xref>.	Secondary. See <xref target="fig.oview4"/>.
	Common current practice for system administrators is to consider the	Common current practice for system administrators is to consider the

	Management Daemon in a Secondary to be a Secondary Management Daemon which	Management Daemon in a Secondary to be a Secondary Management Daemon that
	understands status symbol <tt>FSD</tt> as an order to shut down.	understands status symbol <tt>FSD</tt> as an order to shut down.
	</t>	</t>

	<t>Note: Historically, the Secondary was known as the "Slave".	<aside>
	</t>	<t>Note: Historically, the Secondary was known as the "Slave".</t>
		</aside>
	</section>	</section>
	<section anchor="sess">	<section anchor="sess">
	<name>Session</name>	<name>Session</name>

	<t>The Management Daemon may initiate a TCP session with a specified device such	<t>The Management Daemon may initiate a TCP session with a specified device, suc h
	as a UPS known to the Attachment Daemon. The session structure provides for audi t	as a UPS known to the Attachment Daemon. The session structure provides for audi t

	and security as well as access to mission critical UPS functions. For	and security, as well as access to mission-critical UPS functions. For
	example good practice requires a password protection for an Instant	example, good practice requires password protection for an Instant
	Command which turns off a UPS outlet. Other than the commands and	Command that turns off a UPS outlet. Other than the commands and
	responses used, the details of session management are outside the	responses used, the details of session management are outside the
	scope of this document.	scope of this document.
	</t>	</t>
	</section>	</section>
	<section anchor="st">	<section anchor="st">
	<name>UPS Status</name>	<name>UPS Status</name>

	<t>The status of a hardware device such as a UPS unit is a symbolic	<t>The status of a hardware device, such as a UPS unit, is a symbolic
	description of the state of the unit. It consists of a space	description of the state of the unit. It consists of a space-separated
	separated list of symbols from the set {<tt>ALARM</tt> <tt>BOOST</tt> <tt>BYPASS	list of symbols from the set {<tt>ALARM</tt> <tt>BOOST</tt> <tt>BYPASS</tt>
	</tt>
	<tt>CAL</tt> <tt>CHRG</tt> <tt>COMM</tt> <tt>DISCHRG</tt> <tt>FSD</tt> <tt>LB</t t> <tt>NOCOMM</tt> <tt>OB</tt>	<tt>CAL</tt> <tt>CHRG</tt> <tt>COMM</tt> <tt>DISCHRG</tt> <tt>FSD</tt> <tt>LB</t t> <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>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	<tt>TOCK</tt> are experimental additions to the statuses and are not in

	common current practice. See <xref target="symbols"></xref> which	common current practice. See <xref target="symbols"></xref>, which
	specifies each of these symbols.	specifies each of these symbols.
	</t>	</t>
	<t>See <xref target="MinSup"></xref> for details of the recommended	<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>	minimum support of status symbols <tt>OB</tt>, <tt>OL</tt>, <tt>LB</tt>,
	and <tt>FSD</tt>.	and <tt>FSD</tt>.
	</t>	</t>
	</section>	</section>
	<section anchor="var">	<section anchor="var">
	<name>UPS Variable</name>	<name>UPS Variable</name>
	<t>The metrics and identifiers provided by each UPS are represented by	<t>The metrics and identifiers provided by each UPS are represented by

	variables giving the value representing that metric or identifier, The	variables giving the value representing that metric or identifier. The
	UPS variable is an abstraction of the UPS hardware configuration and	UPS variable is an abstraction of the UPS hardware configuration and

	activity maintained by the Attachment Daemon. See <xref target="Annex1"></xref>	activity maintained by the Attachment Daemon. See <xref target="Annex1"></xref>
	which provides examples of variables. For example the	,
		which provides examples of variables. For example, the
	variable <tt>battery.charge</tt> contains the current charge of the	variable <tt>battery.charge</tt> contains the current charge of the
	UPS battery as a percentage value.	UPS battery as a percentage value.
	</t>	</t>

	<t>Note: Some variables are constants, e.g. battery type,	<t>Note: Some variables are constants, e.g., battery type and
	manufacturer.	manufacturer.
	</t>	</t>
	<t>See <xref target="MinSup"></xref> for details of the	<t>See <xref target="MinSup"></xref> for details of the
	recommended minimum support of variables. A full list of possible	recommended minimum support of variables. A full list of possible
	variables is available in <xref target="gitvars">source code file	variables is available in <xref target="gitvars">source code file

	docs/nut-names.txt</xref> which serves as the Recording Document.	docs/nut-names.txt</xref>, which serves as the Recording Document.
	</t>	</t>
	</section>	</section>
	</section>	</section>
	<section anchor="overview">	<section anchor="overview">
	<name>Protocol Overview</name>	<name>Protocol Overview</name>

	<t>Figure <xref target="fig.oview" format="counter"></xref> shows a reference	<t><xref target="fig.oview"/> shows a reference
	configuration in which the command/response protocol applies. The UPS	configuration in which the command/response protocol applies. The UPS

	shown is representative of all managed power devices,	shown is representative of all managed power devices.
	</t>	</t>
	<figure anchor="fig.oview">	<figure anchor="fig.oview">

	<name>Reference Configuration	<name>Reference Configuration</name>
	</name>	<artwork align="center" type="ascii-art"><![CDATA[
	<artwork align="center"> "The client"	"The client"
	,--------------, ,--------------,	,--------------, ,--------------,
	,-----, \| UPS \| <-Commands \| UPS \|	,-----, \| UPS \| <-Commands \| UPS \|
	\| UPS \|---\| Attachment \|---------------\| Management \|	\| UPS \|---\| Attachment \|---------------\| Management \|

	\| \|===\| Daemon \| Responses-> \| Daemon \|	\| \|===\| Daemon \| Responses-> \| Daemon \|
	/-----\ '--------------' '--------------'	/-----\ '--------------' '--------------'
	UPS Attachment UPS Management	UPS Attachment UPS Management

	System Network System</artwork>	System Network System
		]]></artwork>
	</figure>	</figure>

	<t>The reference configuration in figure <xref target="fig.oview" format="counte	<t>The reference configuration in <xref target="fig.oview"/> shows a single UPS
	r"></xref> shows a single UPS unit which has a power supply link	unit that
		has a power supply link
	(<tt>===</tt>) and a data link (<tt>---</tt>) attached to a system	(<tt>===</tt>) and a data link (<tt>---</tt>) attached to a system
	running an Attachment Daemon. The UPS provides power supply protection to the	running an Attachment Daemon. The UPS provides power supply protection to the
	system running the Attachment Daemon.	system running the Attachment Daemon.
	</t>	</t>

	<t>In practice there may be more than one UPS unit, and a unit may	<t>In practice, there may be more than one UPS unit, and a unit may
	provide power protection to more than one system. The figure also	provide power protection to more than one system. The figure also

	shows a single Management Daemon. In practice there may be more than one	shows a single Management Daemon. In practice, there may be more than one
	Management Daemon, and any one Management Daemon may manage more than	Management Daemon, and any one Management Daemon may manage more than
	one UPS Attachment Daemon.	one UPS Attachment Daemon.
	</t>	</t>
	<t>The protocol applies to connections between the Attachment Daemon	<t>The protocol applies to connections between the Attachment Daemon

	and the Management Daemon which act as <strong>server</strong>	and the Management Daemon, which act as the <strong>server</strong>
	and <strong>client</strong> respectively. The Management Daemon sends	and <strong>client</strong>, respectively. The Management Daemon sends
	commands over TCP to the Attachment Daemon and receives responses over	commands over TCP to the Attachment Daemon and receives responses over
	TCP from that daemon.	TCP from that daemon.
	</t>	</t>

	<t>The two daemons may run in the same system, or may be connected	<t>The two daemons may run in the same system or may be connected
	through a local or wide area network. In simple cases, as shown in	through a local or wide area network. In simple cases, as shown in

	figure <xref target="fig.oview2" format="counter"></xref>, the Attachment Daemon	<xref target="fig.oview2"/>, the Attachment Daemon
	and the Management Daemon are in the same system, the one protected by the UPS.	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	The commands and responses are exchanged through an internal loopback
	interface.	interface.
	</t>	</t>
	<figure anchor="fig.oview2">	<figure anchor="fig.oview2">

	<name>Simplified single-system configuration	<name>Simplified Single-System Configuration
	</name>	</name>

	<artwork align="center"> "The client"	<artwork align="center" type="ascii-art"><![CDATA[
	,--------------------,---------------------,	"The client"
	,-----, \| UPS <-Commands UPS \|	,--------------------,---------------------,
		,-----, \| UPS <-Commands UPS \|
	\| UPS \|---\| Attachment \| Management \|	\| UPS \|---\| Attachment \| Management \|

	\| \|===\| Daemon Responses-> Daemon \|	\| \|===\| Daemon Responses-> Daemon \|
	/-----\ '--------------------'---------------------'	/-----\ '--------------------'---------------------'
	Internal	Internal

	loopback	Loopback
	UPS Attachment and Management System</artwork>	UPS Attachment and Management System
		]]></artwork>
	</figure>	</figure>
	<t>The reference configuration does not require any specific	<t>The reference configuration does not require any specific

	design. For example figure <xref target="fig.oview3" format="counter"></xref>	design. For example, <xref target="fig.oview3"/>
	shows an arrangement in which the Attachment Daemon is closely associated with, or	shows an arrangement in which the Attachment Daemon is closely associated with, or

	even included in the UPS system setup. This is becoming more	even included in, the UPS system setup. This is becoming more
	prevalent with the availability of low cost processors able to run the	prevalent with the availability of low-cost processors able to run the
	Attachment Daemon thereby effectively creating a network attached UPS running a	Attachment Daemon, thereby effectively creating a network-attached UPS running a
	published protocol.	published protocol.
	</t>	</t>
	<figure anchor="fig.oview3">	<figure anchor="fig.oview3">

	<name>UPS and Attachment Daemon integration	<name>UPS and Attachment Daemon Integration
	</name>	</name>

	<artwork align="center"> "The client"	<artwork align="center" type="ascii-art"><![CDATA[
		"The client"
	,-----,------------, ,--------------,	,-----,------------, ,--------------,

	\| \| UPS \| <-Commands \| UPS \|	\| \| UPS \| <-Commands \| UPS \|
	\| UPS - Attachment \|---------------\| Management \|	\| UPS - Attachment \|---------------\| Management \|

	\| \| Daemon \| Responses-> \| Daemon \|	\| \| Daemon \| Responses-> \| Daemon \|
	/-----'------------\ '--------------'	/-----'------------\ '--------------'
	UPS Attachment UPS Management	UPS Attachment UPS Management

	System Network System</artwork>	System Network System
		]]></artwork>
	</figure>	</figure>
	<t>As the power requirements for processors decrease, it is becoming	<t>As the power requirements for processors decrease, it is becoming

	increasingly common to use a single UPS to protect multiple systems as	increasingly common to use a single UPS to protect multiple systems, as
	shown in figure <xref target="fig.oview4" format="counter"></xref>. However	shown in <xref target="fig.oview4"/>. However,
	there is only one data line (<tt>---</tt>) from the UPS to the Primary	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	system. The others have only power connections (<tt>===</tt>) to the

	UPS, and are known as Secondaries. A Secondary does not run an Attachment Daemo n,	UPS and are known as Secondaries. A Secondary does not run an Attachment Daemon ;
	it connects over a network to the Attachment Daemon in the	it connects over a network to the Attachment Daemon in the

	Primary. Figure <xref target="fig.oview4" format="counter"></xref> shows the	Primary. <xref target="fig.oview4"/> shows the
	Attachment Daemon and the Primary Management Daemon in the same system. This is common	Attachment Daemon and the Primary Management Daemon in the same system. This is common

	practice but it is not a technical requirement.	practice, but it is not a technical requirement.
	</t>	</t>
	<figure anchor="fig.oview4">	<figure anchor="fig.oview4">

	<name>UPS protects multiple systems	<name>UPS Protects Multiple Systems
	</name>	</name>

	<artwork align="center"> "The client"	<artwork align="center" type="ascii-art"><![CDATA[
	,--------------------,---------------------,	"The client"
	,-----, \| UPS <-Commands Primary \|	,--------------------,---------------------,
		,-----, \| UPS <-Commands Primary \|
	\| \|---\| Attachment \| Management \| Primary	\| \|---\| Attachment \| Management \| Primary

	\| \|===\| Daemon Responses-> Daemon \|	\| \|===\| Daemon Responses-> Daemon \|
	\| \| '--------------------'---------------------'	\| \| '--------------------'---------------------'
	\| UPS \| ^	\| UPS \| ^

	\| \| '<-Commands---Responses->,	\| \| '<-Commands---Responses->,
	\| \| v	\| \| v
	\| \| ,--------------,-----------------,	\| \| ,--------------,-----------------,
	\| \|============\| \| Secondary \|	\| \|============\| \| Secondary \|
	/-----\ \| \| Management \| Secondary	/-----\ \| \| Management \| Secondary
	\| \| Daemon \|	\| \| Daemon \|

	'--------------'-----------------'</artwork>	'--------------'-----------------'
		]]></artwork>
	</figure>	</figure>
	<aside>	<aside>

	<t>Note: Should the Primary fail or go off-line, the fate of	<t>Note: Should the Primary fail or go offline, the fate of
	the Secondaries depends on the UPS status when the Primary failed. If	the Secondaries depends on the UPS status when the Primary failed. If

	the UPS had status <tt>OL</tt> the Secondary continues operation, but if the	the UPS had status <tt>OL</tt>, the Secondary continues operation, but if the
	UPS had status <tt>OB</tt> the Secondary may choose to shut down as a precaution	UPS had status <tt>OB</tt>, the Secondary may choose to shut down as a precautio
	.	n.
	</t>	</t>
	</aside>	</aside>
	</section>	</section>
	<section anchor="protspec">	<section anchor="protspec">
	<name>Protocol Specification</name>	<name>Protocol Specification</name>
	<t>This specification includes only the commands and their responses.	<t>This specification includes only the commands and their responses.
	An implementation of the Attachment Daemon has an internal state machine, and so me	An implementation of the Attachment Daemon has an internal state machine, and so me
	complex implementations of the Management Daemon include an internal state	complex implementations of the Management Daemon include an internal state

	machine; for example to assist the system shutdown of a complex	machine, for example, to assist the system shutdown of a complex
	installation. The Management Daemon is required to remember the	installation. The Management Daemon is required to remember the
	previous <tt>ups.status</tt> value it received from the Attachment Daemon and	previous <tt>ups.status</tt> value it received from the Attachment Daemon and

	compare it with the next. Other than that the management protocol	compare it with the next. Other than that, the management protocol
	used between them is effectively stateless.	used between them is effectively stateless.
	</t>	</t>

	<t>See for example <xref target="events"></xref> which shows a map of the	<t>For example, see <xref target="events"></xref>, which shows a map of the
	new <tt>ups.status</tt> response and the previous <tt>ups.status</tt>	new <tt>ups.status</tt> response and the previous <tt>ups.status</tt>

	response to an Event which is taken as the basis for Management Daemon action.	response to an event, which is taken as the basis for Management Daemon action.
	</t>	</t>
	<section anchor="Notation">	<section anchor="Notation">
	<name>Notation Used in this Specification</name>	<name>Notation Used in this Specification</name>

	<t>The character set used for commands and responses is US-ASCII,	<t>The character set used for commands
	see <xref target="RFC0020"></xref>.	and responses is US-ASCII; see <xref target="RFC0020"></xref>.
	</t>	</t>
	<t>Multi-word elements are contained between	<t>Multi-word elements are contained between

	QUOTATION MARK characters for easier parsing. E.g., "UPS on	quotation mark characters for easier parsing, e.g., "UPS on
	fire". Embedded quotation marks are escaped with REVERSE SLANT \ often known as	fire". Embedded quotation marks are escaped with reverse slant (\), often known
	backslashes. Embedded	as backslashes. Embedded
	backslashes are also escaped by representing them as \\.	backslashes are also escaped by representing them as \\.
	</t>	</t>
	<t anchor="onenewline">Commands and responses have no leading or	<t anchor="onenewline">Commands and responses have no leading or

	trailing whitespace, and are terminated with a single new	trailing blank space and are terminated with a single new
	line character LINE FEED (LF).	line character line feed (LF).
	</t>	</t>

	<t>White space within commands and responses is reduced to	<t>Blank space within commands and responses is reduced to
	one SPACE (SP).	one space (SP).
	</t>	</t>
	</section>	</section>
	<section anchor="commands">	<section anchor="commands">
	<name>Commands</name>	<name>Commands</name>
	<t>The commands address the UPS to which they apply	<t>The commands address the UPS to which they apply

	by <tt><upsname></tt> where</t>	by <tt><upsname></tt>, where</t>
	<ul spacing="compact">	<ul spacing="compact">
	<li><tt><upsname></tt>	<li><tt><upsname></tt>
	::= <tt><ups>[@<hostname>[:<port>]]</tt>	::= <tt><ups>[@<hostname>[:<port>]]</tt>
	</li>	</li>
	<li><tt><ups></tt> is defined by the Attachment Daemon configuration files .	<li><tt><ups></tt> is defined by the Attachment Daemon configuration files .
	</li>	</li>

	<li>The default <tt><hostname></tt> is <tt>localhost</tt>	<li>The default <tt><hostname></tt> is <tt>localhost</tt>.
	</li>	</li>
	<li>The <tt><port></tt> is the number of the TCP port on which	<li>The <tt><port></tt> is the number of the TCP port on which
	the Attachment Daemon is listening. The default is 3493. This is supported by	the Attachment Daemon is listening. The default is 3493. This is supported by
	all current Management Daemons.	all current Management Daemons.
	</li>	</li>
	</ul>	</ul>

	<t>Examples: <tt>myups</tt>, <tt>UPS-97B@bigserver.example.com</tt>	<t>Examples: <tt>myups</tt>, <tt>UPS-97B@bigserver.example.com</tt></t>
	</t>	<t>ABNF: See variable <tt>upsname</tt> in <xref target="fig.ABNF"></xref>.</t>
	<t>ABNF: see variable <tt>upsname</tt> in <xref target="fig.ABNF"></xref>.
	</t>
	<t>Note: Experimental Management Daemons use an extended form	<t>Note: Experimental Management Daemons use an extended form
	of <tt><upsname></tt> in configuration files and in program	of <tt><upsname></tt> in configuration files and in program

	parameters, where	parameters, where:
	</t>	</t>
	<ul spacing="compact">	<ul spacing="compact">

	<li><tt><upsname></tt> ::= <tt>[<group>:]<ups>[@<hostname&g	<li><tt><upsname></tt> ::= <tt>[<group>:]<ups>[@<hostname&g
	t;[:<port>]]</tt>	t;[:<port>]]</tt></li>
	</li>	<li><tt><group></tt> is an experimental extension to provide for groups of
	<li><tt><group></tt> is an experimental extension to provide for groups of	UPSs. It is not in common current practice.</li>
	UPSs. It is not in common current practice.	<li><tt><ups></tt> is defined by the Attachment Daemon configuration files
	</li>	.</li>
	<li><tt><ups></tt> is defined by the Attachment Daemon configuration files	<li>The default <tt><hostname></tt> is <tt>localhost</tt>.</li>
	.
	</li>
	<li>The default <tt><hostname></tt> is <tt>localhost</tt>
	</li>
	</ul>	</ul>
	<t>Examples: <tt>ups-1@example.com:3493</tt>, <tt>HB:heartbeat1@example.com:3493 </tt>	<t>Examples: <tt>ups-1@example.com:3493</tt>, <tt>HB:heartbeat1@example.com:3493 </tt>
	</t>	</t>
	<aside>	<aside>
	<t><em>Implementation note:</em> In the current implementation,	<t><em>Implementation note:</em> In the current implementation,
	the names of commands and subcommands are not case sensitive. For	the names of commands and subcommands are not case sensitive. For

	example <tt>GET VAR</tt> may be written as <tt>Get var</tt>, but in	example, <tt>GET VAR</tt> may be written as <tt>Get var</tt>, but in
	this specification they are always written in upper case.	this specification, they are always written in uppercase.
	Similarly, <tt><upsname></tt> and <tt><varname></tt> are	Similarly, <tt><upsname></tt> and <tt><varname></tt> are

	not case sensitive. For example <tt>UPS341 ups.id</tt> may be written	not case sensitive. For example, <tt>UPS341 ups.id</tt> may be written
	as <tt>ups341 Ups.Id</tt>, but in this	as <tt>ups341 Ups.Id</tt>, but in this

	specification <tt><varname></tt> is always written in lower	specification, <tt><varname></tt> is always written in lower
	case.	case.
	</t>	</t>
	</aside>	</aside>
	<section anchor="attach">	<section anchor="attach">
	<name><tt>ATTACH</tt></name>	<name><tt>ATTACH</tt></name>

	<t>In a configuration such as that shown	<t>In a configuration like the one shown
	in <xref target="fig.oview4"></xref> in which a UPS protects more than	in <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	one system, the Primary Management Daemon needs to know how many Secondaries are

	currently "<em>active</em>", i.e., powered by the UPS, either from the	currently <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	public power supply or from battery power. The Attachment Daemon supports this by keeping a

	count of all the "<em>active</em>" systems powered by a UPS. The	count of all the <em>active</em> systems powered by a UPS. The
	count is initialised, one Secondary at a time by the <tt>ATTACH</tt>	count is initialized, one Secondary at a time by the <tt>ATTACH</tt>
	command, which should be understood as "<em>count this Secondary as	command, which should be understood as <em>count this Secondary as
	active</em>". <tt>ATTACH</tt> is one of three commands for Secondary	active</em>. <tt>ATTACH</tt> is one of three commands for Secondary
	counting: command <tt>DETACH</tt> decrements the count and a Management Daemon m	counting. Additionally, command <tt>DETACH</tt> decrements the count, and a Mana
	ay	gement Daemon may
	read the count at any time using command <tt>NUMATTACH</tt>.	read the count at any time using the command <tt>NUMATTACH</tt>.
	</t>	</t>
	<t>The <tt>ATTACH</tt> command is also sent to the Attachment Daemon for the	<t>The <tt>ATTACH</tt> command is also sent to the Attachment Daemon for the

	Primary so during normal, fully protected operation, the count is 1	Primary, so during normal, fully protected operation, the count is 1
	for the Primary + the number of secondaries. During a full system	for the Primary + the number of Secondaries. During a full system
	shutdown, the count drops as each Secondary Management Daemon executes command	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	<tt>DETACH</tt> during its own shutdown. When the count drops to 1, only

	the Primary is "<em>active</em>" and it knows that all the secondaries	the Primary is <em>active</em>, and it knows that all the Secondaries
	have shut down.	have shut down.
	</t>	</t>
	<t>Command: <tt>ATTACH <upsname></tt>	<t>Command: <tt>ATTACH <upsname></tt>
	</t>	</t>

	<t>If the command succeeds, the response is <tt>OK</tt>, otherwise	<t>If the command succeeds, the response is <tt>OK</tt>; otherwise,
	see the error responses in <xref target="errorresponses"></xref>.	see the error responses in <xref target="errorresponses"></xref>.
	</t>	</t>

	<t>ABNF: See variable <tt>attach</tt> in <xref target="fig.ABNF"></xref>,	<t>ABNF: See variable <tt>attach</tt> in <xref target="fig.ABNF"></xref>.
	</t>	</t>

		<aside>
	<t>Note: Historically, this command was known as <tt>LOGIN</tt>.	<t>Note: Historically, this command was known as <tt>LOGIN</tt>.

	Since that <tt>LOGIN</tt> was not the conventional user access to a	However, because <tt>LOGIN</tt> was not the conventional user access to a
	shell or program the name was changed to avoid confusion.	shell or program, the name was changed to avoid confusion.</t>
	</t>	</aside>
	</section>	</section>
	<section anchor="detach">	<section anchor="detach">
	<name><tt>DETACH</tt></name>	<name><tt>DETACH</tt></name>
	<t>This companion command to <tt>ATTACH</tt> reduces the count of	<t>This companion command to <tt>ATTACH</tt> reduces the count of

	"active" Secondaries. It should be understood as "<em>this Secondary	"active" Secondaries. It should be understood as <em>this Secondary
	is no longer active</em>", and is usually used during system shutdown	is no longer active</em> and is usually used during system shutdown
	to decrement a count of how many Secondaries are still "active".	to decrement a count of how many Secondaries are still <em>active</em>.
	</t>	</t>
	<t>Command: <tt>DETACH</tt>	<t>Command: <tt>DETACH</tt>
	</t>	</t>

	<t>If the command succeeds, the response is <tt>OK Goodbye</tt>,	<t>If the command succeeds, the response is <tt>OK Goodbye</tt>;
	otherwise see the error responses	otherwise, see the error responses
	in <xref target="errorresponses"></xref>.	in <xref target="errorresponses"></xref>.
	</t>	</t>

	<t>ABNF: See variable <tt>detach</tt> in <xref target="fig.ABNF"></xref>,	<t>ABNF: See variable <tt>detach</tt> in <xref target="fig.ABNF"></xref>.
	</t>
	<t>Note: Historically, this command was known as <tt>LOGOUT</tt>.
	</t>	</t>

		<aside>
		<t>Note: Historically, this command was known as <tt>LOGOUT</tt>.</t>
		</aside>
	</section>	</section>
	<section anchor="FSD">	<section anchor="FSD">
	<name><tt>FSD</tt></name>	<name><tt>FSD</tt></name>

	<t>A Management Daemon which is Primary and has the required authority, uses thi	<t>A Management Daemon that is Primary and has the required authority uses this
	s	command to set status symbol <tt>FSD</tt>, meaning "Forced Shutdown", in
	command to set status symbol <tt>FSD</tt> meaning "Forced Shutdown" in	the Attachment Daemon. In current practice, the Primary Management Daemon uses
	the Attachment Daemon. In current practice the Primary Management Daemon uses t	the symbol to
	he symbol to
	tell the Secondaries to shut down.	tell the Secondaries to shut down.
	</t>	</t>
	<t>Command: <tt>FSD <upsname></tt>	<t>Command: <tt>FSD <upsname></tt>
	</t>	</t>

	<t>If the command succeeds, the response is <tt>OK FSD-SET</tt>,	<t>If the command succeeds, the response is <tt>OK FSD-SET</tt>;
	otherwise see the error responses in <xref target="errorresponses"></xref>.	otherwise, see the error responses in <xref target="errorresponses"></xref>.
	</t>	</t>
	<t>ABNF: See variable <tt>fsd</tt> in <xref target="fig.ABNF"></xref>.	<t>ABNF: See variable <tt>fsd</tt> in <xref target="fig.ABNF"></xref>.
	</t>	</t>
	<t>In current practice, commands such as <tt>FSD</tt> are made	<t>In current practice, commands such as <tt>FSD</tt> are made
	available only to a privileged administrative user authorized to send	available only to a privileged administrative user authorized to send

	such a mission critical command. The security provisions for	such a mission-critical command. The security provisions for
	administrative users are discussed in <xref target="adsec"></xref>.	administrative users are discussed in <xref target="adsec"></xref>.
	</t>	</t>

	<t>Note: The symbol "<tt>FSD</tt>" is also used for an Event.	<t>Note: The symbol <tt>FSD</tt> is also used for an event.
	See <xref target="EventFSD"></xref>.	See <xref target="EventFSD"></xref>.
	</t>	</t>
	</section>	</section>
	<section anchor="get">	<section anchor="get">
	<name><tt>GET</tt></name>	<name><tt>GET</tt></name>
	<t>Retrieve a single response from the Attachment Daemon.	<t>Retrieve a single response from the Attachment Daemon.
	</t>	</t>
	<t>ABNF: See variable <tt>get</tt> in <xref target="fig.ABNF"></xref>.	<t>ABNF: See variable <tt>get</tt> in <xref target="fig.ABNF"></xref>.
	</t>	</t>

	<t>The possible sub-commands are:	<t>The possible subcommands are listed in the sections below.
	</t>	</t>
	<section anchor="cmddesc">	<section anchor="cmddesc">
	<name><tt>GET CMDDESC</tt></name>	<name><tt>GET CMDDESC</tt></name>
	<t>Retrieve a text description of a command.	<t>Retrieve a text description of a command.
	</t>	</t>
	<t>Command: <tt>GET CMDDESC <upsname> <cmdname></tt>	<t>Command: <tt>GET CMDDESC <upsname> <cmdname></tt>
	</t>	</t>
	<t>Response:	<t>Response:
	<tt>CMDDESC <upsname> <cmdname> "<description>"</tt>	<tt>CMDDESC <upsname> <cmdname> "<description>"</tt>
	</t>	</t>

	<t>For example: <tt>GET CMDDESC su700 load.on</tt> and	<t>For example: command <tt>GET CMDDESC su700 load.on</tt> and
	response <tt>CMDDESC su700 load.on "Turn on the load immediately"</tt>	response <tt>CMDDESC su700 load.on "Turn on the load immediately"</tt>
	</t>	</t>

	<t>This is like <tt>GET DESC</tt>, but it applies to an Instant Command;.	<t>This is like <tt>GET DESC</tt>, but it applies to an Instant Command.
	See <xref target="desc"></xref>.	See <xref target="desc"></xref>.
	</t>	</t>
	</section>	</section>
	<section anchor="desc">	<section anchor="desc">
	<name><tt>GET DESC</tt></name>	<name><tt>GET DESC</tt></name>
	<t>Retrieve a text description of a UPS variable. See <xref target="var"></xref >.	<t>Retrieve a text description of a UPS variable. See <xref target="var"></xref >.
	</t>	</t>
	<t>Command: <tt>GET DESC <upsname> <varname></tt>	<t>Command: <tt>GET DESC <upsname> <varname></tt>
	</t>	</t>
	<t>Response: <tt>DESC <upsname> <varname> "<description>"</tt>	<t>Response: <tt>DESC <upsname> <varname> "<description>"</tt>
	</t>	</t>

	<t>where <tt><description></tt> is a string that gives a brief	<t><tt><description></tt> is a string that gives a brief
	explanation of the named variable. The Attachment Daemon <bcp14>MAY</bcp14> ret urn	explanation of the named variable. The Attachment Daemon <bcp14>MAY</bcp14> ret urn

	"Unavailable" if the file which provides this description is not	"Unavailable" if the file that provides this description is not
	installed.	installed.
	</t>	</t>

	<t>For example command <tt>GET DESC su700 ups.status</tt> and	<t>For example: command <tt>GET DESC su700 ups.status</tt> and
	response <tt>DESC su700 ups.status "UPS status"</tt>	response <tt>DESC su700 ups.status "UPS status"</tt>
	</t>	</t>
	</section>	</section>
	<section anchor="numattach">	<section anchor="numattach">
	<name><tt>GET NUMATTACH</tt></name>	<name><tt>GET NUMATTACH</tt></name>

	<t>Retrieve the count kept by the Attachment Daemon of all the "<em>active</em>"	<t>Retrieve the count kept by the Attachment Daemon of all the <em>active</em>
	systems protected by this UPS.	systems protected by this UPS.
	</t>	</t>
	<t>Command: <tt>GET NUMATTACH <upsname></tt>	<t>Command: <tt>GET NUMATTACH <upsname></tt>
	</t>	</t>
	<t>Response: <tt>NUMATTACH <upsname> <value></tt>	<t>Response: <tt>NUMATTACH <upsname> <value></tt>
	</t>	</t>

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

	<t>For example command <tt>GET ATTACH su700</tt> and	<t>For example: command <tt>GET ATTACH su700</tt> and
	response <tt>NUMATTACH su700 1</tt>	response <tt>NUMATTACH su700 1</tt>
	</t>	</t>
	<t>This information is needed by the Management Daemon to determine how many	<t>This information is needed by the Management Daemon to determine how many
	Secondaries are still connected during the system shutdown process.	Secondaries are still connected during the system shutdown process.
	</t>	</t>

	<t>Note: Historically, this sub-command was known	<aside>
		<t>Note: Historically, this subcommand was known
	as <tt>NUMLOGINS</tt>. Since <tt>LOGIN</tt> was not the conventional	as <tt>NUMLOGINS</tt>. Since <tt>LOGIN</tt> was not the conventional

	user access to a shell or program the name was changed to avoid	user access to a shell or program, the name was changed to avoid
	confusion.	confusion.</t>
	</t>	</aside>
	</section>	</section>
	<section anchor="type">	<section anchor="type">
	<name><tt>GET TYPE</tt></name>	<name><tt>GET TYPE</tt></name>
	<t>Retrieve the type of a UPS variable. See <xref target="var"></xref>.	<t>Retrieve the type of a UPS variable. See <xref target="var"></xref>.
	</t>	</t>
	<t>Command: <tt>GET TYPE <upsname> <varname></tt>	<t>Command: <tt>GET TYPE <upsname> <varname></tt>
	</t>	</t>
	<t>Response: <tt>TYPE <upsname> <varname> <type>...</tt>	<t>Response: <tt>TYPE <upsname> <varname> <type>...</tt>
	</t>	</t>

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

	<t>For example command <tt>GET TYPE su700 input.transfer.low</tt> and	<t>For example: command <tt>GET TYPE su700 input.transfer.low</tt> and
	response <tt>TYPE su700 input.transfer.low ENUM</tt>	response <tt>TYPE su700 input.transfer.low ENUM</tt>
	</t>	</t>
	<table>	<table>

	<name>Variable Types	<name>Variable Types</name>
	</name>
	<thead>	<thead>
	<tr>	<tr>

	<th align="center">    Type	<th align="center">    Type    </th>
	</th>	<th align="center">Meaning</th>
	<th align="center">Meaning
	</th>
	</tr>	</tr>
	</thead>	</thead>
	<tbody>	<tbody>
	<tr>	<tr>
	<td>RW </td>	<td>RW </td>
	<td>This is a read/write variable. It may be read with	<td>This is a read/write variable. It may be read with

	command <tt>GET VAR</tt>, see <xref target="getvar"></xref>, and set to a differ	command <tt>GET VAR</tt> (see <xref target="getvar"></xref>) and set to a differ
	ent value	ent value
	with command <tt>SET</tt>, see <xref target="set"></xref>.	with command <tt>SET</tt> (see <xref target="set"></xref>).
	</td>	</td>
	</tr>	</tr>
	<tr>	<tr>
	<td>ENUM </td>	<td>ENUM </td>

	<td>An enumerated type, which supports specific	<td>This is an enumerated type, which supports specific
	predetermined values.	predetermined values.
	</td>	</td>
	</tr>	</tr>
	<tr>	<tr>
	<td>STRING:n </td>	<td>STRING:n </td>
	<td>This is a string of maximum	<td>This is a string of maximum
	length <tt>n</tt>.	length <tt>n</tt>.
	</td>	</td>
	</tr>	</tr>
	<tr>	<tr>
	<td>RANGE </td>	<td>RANGE </td>
	<td><t>This is a number, either integer or float,	<td><t>This is a number, either integer or float,

	comprised in the range which may be seen with the command <tt>LIST	comprised in the range that may be seen with the command <tt>LIST
	RANGE</tt>, see <xref target="range"></xref>.	RANGE</tt> (see <xref target="range"></xref>).
	</t></td>	</t></td>
	</tr>	</tr>
	<tr>	<tr>
	<td>NUMBER </td>	<td>NUMBER </td>
	<td>This is a single numeric value, either	<td>This is a single numeric value, either
	integer or float.	integer or float.
	</td>	</td>
	</tr>	</tr>
	</tbody>	</tbody>
	</table>	</table>
	<t>Notes:	<t>Notes:
	</t>	</t>

	<ul>	<ul spacing="normal">
	<li>ENUM, STRING:n and RANGE are usually associated with RW, but	<li>ENUM, STRING:n, and RANGE are usually associated with RW but
	not always. The default <type>, when omitted, is numeric, so	not always. The default <type>, when omitted, is numeric, so
	either integer or float. Each Driver is then responsible for	either integer or float. Each Driver is then responsible for
	handling values as either integer or float.	handling values as either integer or float.
	</li>	</li>
	<li>Current practice is to represent floating point values using	<li>Current practice is to represent floating point values using

	a decimal (base 10) US	a decimal (base 10)
	English-based representation. Hexadecimal, exponents, and comma for	English-based representation. Hexadecimals, exponents, and commas used as separa
	thousands separator are not allowed. For example: "1200.20" is valid,	tors for
		thousands are not allowed. For example, "1200.20" is valid,
	while "1,200.20" and "1200,20" are not valid.	while "1,200.20" and "1200,20" are not valid.
	</li>	</li>
	</ul>	</ul>
	</section>	</section>
	<section anchor="upsdesc">	<section anchor="upsdesc">
	<name><tt>GET UPSDESC</tt></name>	<name><tt>GET UPSDESC</tt></name>
	<t>Retrieve a text description of a UPS.	<t>Retrieve a text description of a UPS.
	</t>	</t>
	<t>Command: <tt>GET UPSDESC <upsname></tt>	<t>Command: <tt>GET UPSDESC <upsname></tt>
	</t>	</t>
	<t>Response: <tt>UPSDESC <upsname> "<description>"</tt>	<t>Response: <tt>UPSDESC <upsname> "<description>"</tt>
	</t>	</t>

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

	<t>For example command <tt>GET UPSDESC su700</tt> and response	<t>For example: command <tt>GET UPSDESC su700</tt> and response
	<tt>UPSDESC su700 "Development box"</tt>	<tt>UPSDESC su700 "Development box"</tt>
	</t>	</t>

	<t>This can be used to provide human-readable descriptions instead of	<t>This can be used to provide human-readable descriptions, instead of
	a cryptic <tt>ups@hostname</tt> string.	a cryptic <tt>ups@hostname</tt> string.
	</t>	</t>
	</section>	</section>
	<section anchor="getvar">	<section anchor="getvar">
	<name><tt>GET VAR</tt></name>	<name><tt>GET VAR</tt></name>
	<t>Retrieve the value of a UPS variable. See <xref target="var"></xref>.	<t>Retrieve the value of a UPS variable. See <xref target="var"></xref>.
	</t>	</t>
	<t>Command: <tt>GET VAR <upsname>	<t>Command: <tt>GET VAR <upsname>
	<varname></tt>	<varname></tt>
	</t>	</t>
	<t>Response: <tt>VAR <upsname> <varname> "<value>"</tt>	<t>Response: <tt>VAR <upsname> <varname> "<value>"</tt>
	</t>	</t>

	<t>For example command <tt>GET VAR su700 ups.status</tt> and response	<t>For example: command <tt>GET VAR su700 ups.status</tt> and response
	<tt>VAR su700 ups.status "OB LB"</tt>	<tt>VAR su700 ups.status "OB LB"</tt>
	</t>	</t>
	</section>	</section>
	</section>	</section>
	<section anchor="help">	<section anchor="help">
	<name><tt>HELP</tt></name>	<name><tt>HELP</tt></name>
	<t>Return a list of the commands supported by the Attachment Daemon. This comma nd	<t>Return a list of the commands supported by the Attachment Daemon. This comma nd

	is intended for human as well as program use.	is intended for human, as well as program, use.
	</t>	</t>

	<t>Command <tt>HELP</tt>	<t>Command: <tt>HELP</tt>
	</t>	</t>

	<t>For example, the following command line sequence executed on an	<t>For example: the following command line sequence executed on an
	Attachment Daemon:</t>	Attachment Daemon</t>
	<sourcecode>netcat localhost 3493	<sourcecode name="" type="shell">
		netcat localhost 3493
	HELP	HELP
	Commands: HELP VER GET LIST SET INSTCMD ATTACH DETACH	Commands: HELP VER GET LIST SET INSTCMD ATTACH DETACH

	USERNAME PASSWORD STARTTLS</sourcecode>	USERNAME PASSWORD STARTTLS
		</sourcecode>
	<t>ABNF: See variable <tt>help</tt> in <xref target="fig.ABNF"></xref>.	<t>ABNF: See variable <tt>help</tt> in <xref target="fig.ABNF"></xref>.
	</t>	</t>

		<aside>
	<t>Note: Historically, this command also returned <tt>LOGIN</tt>	<t>Note: Historically, this command also returned <tt>LOGIN</tt>

	and <tt>LOGOUT</tt>. Since <tt>LOGIN</tt> was not the conventional	and <tt>LOGOUT</tt>. Because <tt>LOGIN</tt> was not the conventional
	user access to a shell or program, the command names were changed	user access to a shell or program, the command names were changed

	to <tt>ATTACH</tt> and <tt>DETACH</tt> to avoid confusion.	to <tt>ATTACH</tt> and <tt>DETACH</tt> to avoid confusion.</t>
	</t>	</aside>
	</section>	</section>
	<section anchor="instcmd">	<section anchor="instcmd">
	<name><tt>INSTCMD</tt></name>	<name><tt>INSTCMD</tt></name>
	<t>Send an Instant Command to the UPS.	<t>Send an Instant Command to the UPS.
	</t>	</t>
	<t>Command: <tt>INSTCMD <upsname> <cmdname></tt>	<t>Command: <tt>INSTCMD <upsname> <cmdname></tt>
	</t>	</t>

	<t>where <tt><upsname></tt> is the name of the UPS	<t><tt><upsname></tt> is the name of the UPS,
	and <tt><cmdname></tt> is the Instant Command to be issued to	and <tt><cmdname></tt> is the Instant Command to be issued to
	that UPS. See <xref target="instcmdexamples"></xref> for examples of	that UPS. See <xref target="instcmdexamples"></xref> for examples of

	instant commands.	Instant Commands.
	</t>	</t>

	<t>If the command succeeds, the response is <tt>OK</tt>, otherwise	<t>If the command succeeds, the response is <tt>OK</tt>; otherwise,
	see the error responses, <xref target="errorresponses"></xref>.	see the error responses in <xref target="errorresponses"></xref>.
	</t>	</t>

	<t>For example the command: <tt>INSTCMD su700 test.panel.start</tt>	<t>For example: command <tt>INSTCMD su700 test.panel.start</tt>
	and the response <tt>OK</tt>	and response <tt>OK</tt>
	</t>	</t>
	<t>ABNF: See variable <tt>instcmd</tt> in <xref target="fig.ABNF"></xref>.	<t>ABNF: See variable <tt>instcmd</tt> in <xref target="fig.ABNF"></xref>.
	</t>	</t>
	</section>	</section>
	<section anchor="list">	<section anchor="list">
	<name><tt>LIST</tt></name>	<name><tt>LIST</tt></name>
	<t>All the <tt>LIST</tt> commands produce a response with a common	<t>All the <tt>LIST</tt> commands produce a response with a common

	format. The response will begin with <tt>BEGIN LIST</tt> and then	format. The response begins with <tt>BEGIN LIST</tt> and then
	repeat the initial query. A list then follows, with as many lines as	repeats the initial query. A list then follows, with as many lines as
	are necessary. The response ends with <tt>END LIST</tt> followed by	are necessary. The response ends with <tt>END LIST</tt>, followed by
	the initial query.	the initial query.
	</t>	</t>
	<t>The formatting may seem a bit redundant, but it makes a different	<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	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	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.	need a complicated state machine to remember which list is which.
	</t>	</t>
	<t>Note: The current NUT Project implementation of the	<t>Note: The current NUT Project implementation of the
	Attachment Daemon, <tt>upsd</tt>, sends back the response to the <tt>LIST</tt>	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 readin g	command as a sequence of messages. The Management Daemon should continue readin g
	these messages until it receives the line beginning <tt>END LIST</tt>.	these messages until it receives the line beginning <tt>END LIST</tt>.
	</t>	</t>

	<t>ABNF: See variable <tt>list</tt> in <xref target="fig.ABNF"></xref>.	<t>ABNF: See the variable <tt>list</tt> in <xref target="fig.ABNF"></xref>.
	</t>	</t>

	<t>The possible subcommands are:	<t>The possible subcommands are listed in the sections below.
	</t>	</t>
	<section anchor="client">	<section anchor="client">
	<name><tt>LIST CLIENT</tt></name>	<name><tt>LIST CLIENT</tt></name>
	<t>The command calls for the Attachment Daemon to report all the current Managem ent Daemon	<t>The command calls for the Attachment Daemon to report all the current Managem ent Daemon
	clients of a given UPS.	clients of a given UPS.
	</t>	</t>
	<t>Command: <tt>LIST CLIENT <upsname></tt>	<t>Command: <tt>LIST CLIENT <upsname></tt>
	</t>	</t>

	<t>The response	<t>Response:
	is </t>	</t>
	<artwork>BEGIN LIST CLIENT <upsname>	<sourcecode name="" type="shell">
		BEGIN LIST CLIENT <upsname>
	CLIENT <upsname> <client_IP_address>	CLIENT <upsname> <client_IP_address>
	...	...
	END LIST CLIENT <upsname>	END LIST CLIENT <upsname>

	</artwork>	</sourcecode>
	<t>For example, the command <tt>LIST CLIENT ups1</tt> and the response:	<t>For example: command <tt>LIST CLIENT ups1</tt> and response
	</t>	</t>

	<artwork>BEGIN LIST CLIENT ups1	<sourcecode name="" type="shell">
		BEGIN LIST CLIENT ups1
	CLIENT ups1 ::1	CLIENT ups1 ::1
	CLIENT ups1 203.0.113.1	CLIENT ups1 203.0.113.1
	END LIST CLIENT ups1	END LIST CLIENT ups1

	</artwork>	</sourcecode>
	</section>	</section>
	<section anchor="cmd">	<section anchor="cmd">
	<name><tt>LIST CMD</tt></name>	<name><tt>LIST CMD</tt></name>
	<t>The command calls for the Attachment Daemon to report a list of the Instant	<t>The command calls for the Attachment Daemon to report a list of the Instant

	Commands which the Management Daemon may send to the Attachment Daemon. This In stant Command	Commands that the Management Daemon may send to the Attachment Daemon. This Ins tant Command
	list is the abstracted view of the UPS hardware capabilities. An	list is the abstracted view of the UPS hardware capabilities. An

	economical UPS will support few or no Instant Commands but a	economical UPS will support few or no Instant Commands, but a
	professional model should support more.	professional model should support more.
	</t>	</t>
	<t>Command: <tt>LIST CMD <upsname></tt>	<t>Command: <tt>LIST CMD <upsname></tt>
	</t>	</t>

	<t>The response is:</t>	<t>Response:</t>
	<sourcecode>BEGIN LIST CMD <upsname>	<sourcecode name="" type="shell">
		BEGIN LIST CMD <upsname>
	CMD <upsname> <cmdname>	CMD <upsname> <cmdname>
	...	...
	END LIST CMD <upsname>	END LIST CMD <upsname>
	</sourcecode>	</sourcecode>

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

	<t>For example the command: <tt>LIST CMD su700</tt> and the response:	<t>For example: command <tt>LIST CMD su700</tt> and response
	</t>	</t>

	<sourcecode>BEGIN LIST CMD su700	<sourcecode name="" type="shell">
		BEGIN LIST CMD su700
	CMD su700 load.on	CMD su700 load.on
	CMD su700 test.panel.start	CMD su700 test.panel.start
	...	...
	END LIST CMD su700	END LIST CMD su700
	</sourcecode>	</sourcecode>
	</section>	</section>
	<section anchor="enum">	<section anchor="enum">
	<name><tt>LIST ENUM</tt></name>	<name><tt>LIST ENUM</tt></name>
	<t>The command calls for the Attachment Daemon to report the set of possible	<t>The command calls for the Attachment Daemon to report the set of possible

	values of a UPS variable which has predetermined values.	values of a UPS variable that has predetermined values.
	</t>	</t>
	<t>Command: <tt>LIST ENUM <upsname> <varname></tt>	<t>Command: <tt>LIST ENUM <upsname> <varname></tt>
	</t>	</t>

	<t>The response	<t>Response:</t>
	is:</t>	<sourcecode name="" type="shell">
	<sourcecode>BEGIN LIST ENUM <upsname> <varname>	BEGIN LIST ENUM <upsname> <varname>
	ENUM <upsname> <varname> "<value>"	ENUM <upsname> <varname> "<value>"
	...	...
	END LIST ENUM <upsname> <varname>	END LIST ENUM <upsname> <varname>
	</sourcecode>	</sourcecode>

	<t>where <tt><upsname></tt> is the name of the UPS,	<t><tt><upsname></tt> is the name of the UPS,
	<tt><varname></tt> is the UPS variable	<tt><varname></tt> is the UPS variable,
	and <tt><value></tt> is one of the possible values of that UPS	and <tt><value></tt> is one of the possible values of that UPS

	variable. Note that in current practice the output is an unordered	variable. Note that, in current practice, the output is an unordered
	list. Note also that the QUOTATION MARKS are part of	list. Also note that the quotation marks are part of
	the response.	the response.
	</t>	</t>

	<t>For example the command: <tt>LIST ENUM su700 input.transfer.low</tt>	<t>For example: command <tt>LIST ENUM su700 input.transfer.low</tt>
	and the	and response</t>
	response:</t>	<sourcecode name="" type="shell">
	<sourcecode>BEGIN LIST ENUM su700 input.transfer.low	BEGIN LIST ENUM su700 input.transfer.low
	ENUM su700 input.transfer.low "103"	ENUM su700 input.transfer.low "103"
	ENUM su700 input.transfer.low "100"	ENUM su700 input.transfer.low "100"
	...	...
	END LIST ENUM su700 input.transfer.low	END LIST ENUM su700 input.transfer.low
	</sourcecode>	</sourcecode>
	</section>	</section>
	<section anchor="range">	<section anchor="range">
	<name><tt>LIST RANGE</tt></name>	<name><tt>LIST RANGE</tt></name>
	<t>The command calls for the Attachment Daemon to report the interval in which	<t>The command calls for the Attachment Daemon to report the interval in which
	valid values of UPS variable lie.	valid values of UPS variable lie.
	</t>	</t>
	<t>Command: <tt>LIST RANGE <upsname> <varname></tt>	<t>Command: <tt>LIST RANGE <upsname> <varname></tt>
	</t>	</t>

	<t>The response	<t>Response:</t>
	is: </t>	<sourcecode name="" type="shell">
	<sourcecode>BEGIN LIST RANGE <upsname> <varname>	BEGIN LIST RANGE <upsname> <varname>
	RANGE <upsname> <varname> "<min>" "<max>"	RANGE <upsname> <varname> "<min>" "<max>"
	...	...
	END LIST RANGE <upsname> <varname>	END LIST RANGE <upsname> <varname>
	</sourcecode>	</sourcecode>

	<t>where <tt><upsname></tt> is the name of the UPS,	<t><tt><upsname></tt> is the name of the UPS,
	<tt><varname></tt> is the UPS variable and	<tt><varname></tt> is the UPS variable, and
	{<tt><min></tt>,<tt><max></tt>} is the interval of valid	{<tt><min></tt>,<tt><max></tt>} is the interval of valid

	values of that UPS variable. Note that the QUOTATION	values of that UPS variable. Note that the quotation
	MARKS are part of the response.	marks are part of the response.
	</t>	</t>

	<t>For example, the command <tt>LIST RANGE su700	<t>For example: command <tt>LIST RANGE su700
	input.transfer.low</tt> and the response:	input.transfer.low</tt> and response
	</t>	</t>

	<sourcecode>BEGIN LIST RANGE su700 input.transfer.low	<sourcecode name="" type="shell">
		BEGIN LIST RANGE su700 input.transfer.low
	RANGE su700 input.transfer.low "90" "105"	RANGE su700 input.transfer.low "90" "105"
	END LIST RANGE su700 input.transfer.low	END LIST RANGE su700 input.transfer.low
	</sourcecode>	</sourcecode>
	</section>	</section>
	<section anchor="listrw">	<section anchor="listrw">
	<name><tt>LIST RW</tt></name>	<name><tt>LIST RW</tt></name>
	<t>The command calls for the Attachment Daemon to report a list of the UPS	<t>The command calls for the Attachment Daemon to report a list of the UPS

	variables associated with a given UPS which may be read and written by	variables associated with a given UPS that may be read and written by
	the Management Daemon. These variables are the abstracted view of the UPS	the Management Daemon. These variables are the abstracted view of the UPS

	hardware capabilities. An economical UPS may support few variables	hardware capabilities. An economical UPS may support few variables,
	but a professional model should support at least the variables which	but a professional model should support at least the variables that
	are needed for an automatic shutdown and restart,	are needed for an automatic shutdown and restart;
	see <xref target="shutdownstory"></xref>. See	see <xref target="shutdownstory"></xref>. Also,
	also <xref target="MinSup"></xref> for details of the recommended	see <xref target="MinSup"></xref> for details of the recommended
	minimum support of variables. A full list of variables is available	minimum support of variables. A full list of variables is available

	in <xref target="gitvars">source code file docs/nut-names.txt</xref>	in <xref target="gitvars">source code file docs/nut-names.txt</xref>,
	which serves as the Recording Document.	which serves as the Recording Document.
	</t>	</t>
	<t>Command: <tt>LIST RW <upsname></tt>	<t>Command: <tt>LIST RW <upsname></tt>
	</t>	</t>

	<t>The response is:</t>	<t>Response:</t>
	<sourcecode>BEGIN LIST RW <upsname>	<sourcecode name="" type="shell">
		BEGIN LIST RW <upsname>
	RW <upsname> <varname> "<value>"	RW <upsname> <varname> "<value>"
	...	...
	END LIST RW <upsname>	END LIST RW <upsname>
	</sourcecode>	</sourcecode>

	<t>where <tt><upsname></tt> is the name of the UPS,	<t><tt><upsname></tt> is the name of the UPS,
	<tt><varname></tt> is the UPS variable and	<tt><varname></tt> is the UPS variable, and
	<tt><value></tt> is the value of that UPS variable. Note that	<tt><value></tt> is the value of that UPS variable. Note that

	the QUOTATION MARKS are part of the response.	the quotation marks are part of the response.
	</t>	</t>

	<t>For example the command: <tt>LIST RW su700</tt> and the response:	<t>For example: command <tt>LIST RW su700</tt> and response
	</t>	</t>

	<sourcecode>BEGIN LIST RW su700	<sourcecode name="" type="shell">
		BEGIN LIST RW su700
	RW su700 output.voltage.nominal "115"	RW su700 output.voltage.nominal "115"
	RW su700 ups.delay.shutdown "020"	RW su700 ups.delay.shutdown "020"
	...	...
	END LIST RW su700	END LIST RW su700
	</sourcecode>	</sourcecode>
	</section>	</section>
	<section anchor="ups">	<section anchor="ups">
	<name><tt>LIST UPS</tt></name>	<name><tt>LIST UPS</tt></name>
	<t>The command calls for the Attachment Daemon to report a list of the UPS units	<t>The command calls for the Attachment Daemon to report a list of the UPS units
	to which it is attached.	to which it is attached.
	</t>	</t>
	<t>Command: <tt>LIST UPS</tt>	<t>Command: <tt>LIST UPS</tt>
	</t>	</t>

	<t>The response is:</t>	<t>Response:</t>
	<sourcecode>BEGIN LIST UPS	<sourcecode name="" type="shell">
		BEGIN LIST UPS
	UPS <upsname> "<description>"	UPS <upsname> "<description>"
	...	...
	END LIST UPS	END LIST UPS
	</sourcecode>	</sourcecode>

	<t>where <tt><upsname></tt> is the name of a UPS, and	<t><tt><upsname></tt> is the name of a UPS, and
	<tt><description></tt> is the description maintained by the	<tt><description></tt> is the description maintained by the

	Attachment Daemon if available. It is set to "Unavailable" otherwise. Note that	Attachment Daemon, if available. It is set to "Unavailable" otherwise. Note tha
	the QUOTATION MARKS are part of the response.	t
		the quotation marks are part of the response.
	</t>	</t>
	<t>This command can also be used to determine what values of	<t>This command can also be used to determine what values of
	<tt><upsname></tt> are valid before calling other functions on	<tt><upsname></tt> are valid before calling other functions on
	the server. This is also a good way to handle situations where a	the server. This is also a good way to handle situations where a

	single Attachment Daemon supports multiple UPS's. It is also useful for clients	single Attachment Daemon supports multiple UPSs. It is also useful for clients
	which perform a UPS discovery process.	that perform a UPS discovery process.
	</t>	</t>

	<t>For example, the response:	<t>For example: response
	</t>	</t>

	<sourcecode>BEGIN LIST UPS	<sourcecode name="" type="shell">
		BEGIN LIST UPS
	UPS su700 "Development box"	UPS su700 "Development box"
	END LIST UPS	END LIST UPS
	</sourcecode>	</sourcecode>
	</section>	</section>
	<section anchor="listvar">	<section anchor="listvar">
	<name><tt>LIST VAR</tt></name>	<name><tt>LIST VAR</tt></name>
	<t>The command calls for the Attachment Daemon to report a list of all the UPS	<t>The command calls for the Attachment Daemon to report a list of all the UPS

	variables which it maintains for a given UPS, and the values of those	variables that it maintains for a given UPS and the values of those
	UPS variables.	UPS variables.
	</t>	</t>
	<t>Command: <tt>LIST VAR <upsname></tt>	<t>Command: <tt>LIST VAR <upsname></tt>
	</t>	</t>

	<t>The response is:</t>	<t>Response:</t>
	<sourcecode>BEGIN LIST VAR <upsname>	<sourcecode name="" type="shell">
		BEGIN LIST VAR <upsname>
	VAR <upsname> <varname> "<value>"	VAR <upsname> <varname> "<value>"
	...	...
	END LIST VAR <upsname>	END LIST VAR <upsname>
	</sourcecode>	</sourcecode>

	<t>where <tt><upsname></tt> is the name of the UPS,	<t><tt><upsname></tt> is the name of the UPS,
	<tt><varname></tt> is the UPS variable and	<tt><varname></tt> is the UPS variable, and
	<tt><value></tt> is the value of that variable. Note that	<tt><value></tt> is the value of that variable. Note that

	the QUOTATION MARKS are part of the response.	the quotation marks are part of the response.
	</t>	</t>
	<t>The response to this command lists the UPS variables available for	<t>The response to this command lists the UPS variables available for

	this UPS and their current values. For example the command <tt>LIST	this UPS and their current values.</t>
	VAR su700</tt> and the response:	<t>For example: command <tt>LIST VAR su700</tt> and response
	</t>	</t>

	<sourcecode>BEGIN LIST VAR su700	<sourcecode name="" type="shell">
		BEGIN LIST VAR su700
	VAR su700 ups.mfr "Example Mfg"	VAR su700 ups.mfr "Example Mfg"
	VAR su700 ups.mfr.date "10/17/96"	VAR su700 ups.mfr.date "10/17/96"
	...	...

	END LIST VAR su700</sourcecode>	END LIST VAR su700
		</sourcecode>
	<t>See	<t>See
	<xref target="MinSup"></xref> for details of the recommended minimum	<xref target="MinSup"></xref> for details of the recommended minimum
	support of variables. A full list of variables is available	support of variables. A full list of variables is available

	in <xref target="gitvars">source code file docs/nut-names.txt</xref>	in <xref target="gitvars">source code file docs/nut-names.txt</xref>,
	which serves as the Recording Document.	which serves as the Recording Document.
	</t>	</t>
	</section>	</section>
	</section>	</section>
	<section anchor="password">	<section anchor="password">
	<name><tt>PASSWORD</tt></name>	<name><tt>PASSWORD</tt></name>

	<t>This command is a companion to <tt>USERNAME</tt>, and is used by a	<t>This command is a companion to <tt>USERNAME</tt> and is used by a
	Management Daemon to specify the password required to enter a Session with the	Management Daemon to specify the password required to enter a session with the
	Attachment Daemon, see <xref target="sess"></xref>.	Attachment Daemon; see <xref target="sess"></xref>.
	</t>	</t>
	<t>Command: <tt>PASSWORD <password></tt>	<t>Command: <tt>PASSWORD <password></tt>
	</t>	</t>

	<t>If the command succeeds, the response is <tt>OK</tt>, otherwise see	<t>If the command succeeds, the response is <tt>OK</tt>; otherwise, see
	the error responses, <xref target="errorresponses"></xref>.	the error responses in <xref target="errorresponses"></xref>.
	</t>	</t>
	<t>For examples of the use of commands <tt>USERNAME</tt>	<t>For examples of the use of commands <tt>USERNAME</tt>
	and <tt>PASSWORD</tt> by administrative users,	and <tt>PASSWORD</tt> by administrative users,
	see <xref target="adsecclient"></xref>.	see <xref target="adsecclient"></xref>.
	</t>	</t>

	<t>ABNF: See variable <tt>password</tt> in <xref target="fig.ABNF"></xref>.	<t>ABNF: See variable <tt>session-password</tt> in <xref target="fig.ABNF"></xre f>.
	</t>	</t>
	</section>	</section>
	<section anchor="primary">	<section anchor="primary">
	<name><tt>PRIMARY</tt></name>	<name><tt>PRIMARY</tt></name>
	<t>In current practice, the Attachment Daemon records in local	<t>In current practice, the Attachment Daemon records in local
	file <tt>upsd.users</tt> that an administrative user is a Primary.	file <tt>upsd.users</tt> that an administrative user is a Primary.
	See <xref target="adminuser"></xref> for an example. When a Management Daemon	See <xref target="adminuser"></xref> for an example. When a Management Daemon

	starts up and opens a Session with the Attachment Daemon, it lays claim to being a	starts up and opens a session with the Attachment Daemon, it lays claim to being a
	Primary by sending command <tt>PRIMARY</tt> to the Attachment Daemon, thus	Primary by sending command <tt>PRIMARY</tt> to the Attachment Daemon, thus

	claiming that it has the required authority to perform such critical	claiming that it has the required authority to perform critical
	actions as setting status symbol <tt>FSD</tt>.	actions, such as setting status symbol <tt>FSD</tt>.
	</t>	</t>
	<t>Command: <tt>PRIMARY <upsname></tt>	<t>Command: <tt>PRIMARY <upsname></tt>
	</t>	</t>

	<t>where <tt><upsname></tt> is the name of the UPS.	<t><tt><upsname></tt> is the name of the UPS.
	</t>	</t>

	<t>If the Attachment Daemon has the authority, the response is <tt>OK</tt>,	<t>If the Attachment Daemon has the authority, the response is <tt>OK</tt>;
	otherwise see the error	otherwise, see the error
	responses in <xref target="errorresponses"></xref>.	responses in <xref target="errorresponses"></xref>.
	</t>	</t>

	<t>Note: Historically, this command was known as <tt>MASTER</tt>.	<aside>
	</t>	<t>Note: Historically, this command was known as <tt>MASTER</tt>.</t>
		</aside>
	</section>	</section>
	<section anchor="protver">	<section anchor="protver">
	<name><tt>PROTVER</tt></name>	<name><tt>PROTVER</tt></name>
	<t>Return the version of the command/response protocol	<t>Return the version of the command/response protocol

	used by the Attachment Daemon. This command is intended for human as well as	used by the Attachment Daemon. This command is intended for human, as well as
	program use.	program, use.
	</t>	</t>

	<t>Command <tt>PROTVER</tt>	<t>Command: <tt>PROTVER</tt>
	</t>	</t>

	<t>For example, the following command line sequence in the Attachment Daemon:	<t>For example: the following command line sequence in the Attachment Daemon
	</t>	</t>

	<sourcecode>netcat localhost 3493	<sourcecode name="" type="shell">
		netcat localhost 3493
	PROTVER	PROTVER

	1.3</sourcecode>	1.3
		</sourcecode>
	<t>Notes:	<t>Notes:
	</t>	</t>
	<ol spacing="compact" indent="adaptive">	<ol spacing="compact" indent="adaptive">

	<li>There are no QUOTATION MARKS in the response.	<li>There are no quotation marks in the response.
	</li>	</li>
	<li>The version of the protocol returned by <tt>PROTVER</tt> is	<li>The version of the protocol returned by <tt>PROTVER</tt> is

	different to the implementation version of the Attachment Daemon returned	different than the implementation version of the Attachment Daemon returned
	by <tt>VER</tt>.	by <tt>VER</tt>.
	</li>	</li>
	<li>To ease migration, NUT version 2.8.0 also supports the	<li>To ease migration, NUT version 2.8.0 also supports the
	equivalent <tt>NETVER</tt> command used in previous	equivalent <tt>NETVER</tt> command used in previous
	releases. See <xref target="Version.2.7.4"></xref>.	releases. See <xref target="Version.2.7.4"></xref>.
	</li>	</li>
	</ol>	</ol>
	<t>ABNF: See variable <tt>protver</tt> in <xref target="fig.ABNF"></xref>.	<t>ABNF: See variable <tt>protver</tt> in <xref target="fig.ABNF"></xref>.
	</t>	</t>
	</section>	</section>
	<section anchor="set">	<section anchor="set">
	<name><tt>SET</tt></name>	<name><tt>SET</tt></name>
	<t>The command calls for the Attachment Daemon to set a UPS variable to a given	<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	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	the Driver and the UPS model. Some variables are read-only due to the

	design of the UPS or its driver.	design of the UPS or its Driver.
	</t>	</t>
	<t>Command: <tt>SET VAR <upsname> <varname>	<t>Command: <tt>SET VAR <upsname> <varname>
	"<value>"</tt>	"<value>"</tt>
	</t>	</t>

	<t>where <tt><upsname></tt> is the name of the UPS,	<t><tt><upsname></tt> is the name of the UPS,
	<tt><varname></tt> is the UPS variable and	<tt><varname></tt> is the UPS variable, and
	<tt><value></tt> is the value to be assigned to that variable.	<tt><value></tt> is the value to be assigned to that variable.

	Note that the QUOTATION MARKS are part of the command.	Note that the quotation marks are part of the command.
	</t>	</t>

	<t>If the command succeeds, the response is <tt>OK</tt>, otherwise see	<t>If the command succeeds, the response is <tt>OK</tt>; otherwise, see
	the error responses in <xref target="errorresponses"></xref>.	the error responses in <xref target="errorresponses"></xref>.
	</t>	</t>

	<t>For example the command: <tt>SET VAR su700 ups.id "My UPS"</tt> and	<t>For example: command <tt>SET VAR su700 ups.id "My UPS"</tt> and
	the response <tt>OK</tt>	response <tt>OK</tt>
	</t>	</t>

	<t>ABNF: See variable <tt>set</tt> in <xref target="fig.ABNF"></xref>.	<t>ABNF: See the variable <tt>set</tt> in <xref target="fig.ABNF"></xref>.
	</t>	</t>
	</section>	</section>
	<section anchor="starttls">	<section anchor="starttls">
	<name><tt>STARTTLS</tt></name>	<name><tt>STARTTLS</tt></name>

	<t>The client tells the Attachment Daemon to switch to	<t>The client tells the Attachment Daemon to switch to communication encrypted b
	TLS <xref target="RFC8446"></xref> encrypted communication. When the	y
	client receives <tt>OK</tt> it also switches to TLS encryption.	TLS <xref target="RFC8446"></xref>. When the
		client receives <tt>OK</tt>, it also switches to TLS encryption.
	</t>	</t>
	<t>Command: <tt>STARTTLS</tt>	<t>Command: <tt>STARTTLS</tt>
	</t>	</t>

	<t>If the command succeeds, the response is <tt>OK STARTTLS</tt>,	<t>If the command succeeds, the response is <tt>OK STARTTLS</tt>;
	otherwise see the error responses	otherwise, see the error responses
	in <xref target="errorresponses"></xref>.	in <xref target="errorresponses"></xref>.
	</t>	</t>

	<t>If the client does not send command STARTTLS to the Attachment Daemon	<t>If the client does not send command STARTTLS to the Attachment Daemon,
	communication continues unencrypted, however an Attachment Daemon <bcp14>MAY</bc	communication continues unencrypted; however, an Attachment Daemon <bcp14>MAY</b
	p14> refuse	cp14> refuse
	unencrypted communication.	unencrypted communication.
	</t>	</t>
	<t>NUT 2.8.0 supports the encryption of communications between the	<t>NUT 2.8.0 supports the encryption of communications between the
	Attachment Daemon and the Management Daemon using TLS	Attachment Daemon and the Management Daemon using TLS

	1.3 <xref target="RFC8446"></xref> with X.509 v3 certificates as	1.3 <xref target="RFC8446"></xref> with X.509 v3 certificates, as
	defined by <xref target="RFC5280"></xref> and updates.	defined by <xref target="RFC5280"></xref> and updates.
	See <xref target="AppendixEavesdropping"></xref> for details of the	See <xref target="AppendixEavesdropping"></xref> for details of the

	encryption of communications in previous relase 2.7.4.	encryption of communications in previous release 2.7.4.
	</t>	</t>
	<t>ABNF: See variable <tt>starttls</tt> in <xref target="fig.ABNF"></xref>.	<t>ABNF: See variable <tt>starttls</tt> in <xref target="fig.ABNF"></xref>.
	</t>	</t>
	<section anchor="selfsigned">	<section anchor="selfsigned">

	<name>Key Infrastructure and Self-signed Certificates</name>	<name>Key Infrastructure and Self-Signed Certificates</name>
	<t><em>The very restricted nature of UPS management makes it of	<t><em>The very restricted nature of UPS management makes it of
	interest to consider self-signed certificates.</em>	interest to consider self-signed certificates.</em>
	</t>	</t>
	<t>In the World Wide Web, there are millions of servers and hundreds	<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	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	know who their clients will be, so they entrust the management of a
	Public Key Infrastructure (PKI) to Certificate Authorities that they	Public Key Infrastructure (PKI) to Certificate Authorities that they

	trust, for some value of trust. The encryption of communications	trust. The encryption of communications
	between client and server requires that the browsers carry a list of	between the client and server requires that the browsers carry a list of
	Certificate Authorities which the clients have to trust. <em>This is	Certificate Authorities that the clients have to trust. <em>This is
	a many-to-many relationship.</em>	a many-to-many relationship.</em>
	</t>	</t>

	<t>The management of UPS units is not a many-to-many relationship, it	<t>The management of UPS units is not a many-to-many relationship; it
	is frequently one-to-one. In the closely restrained world of UPS	is frequently one to one. In the closely restrained world of UPS
	management, there are a very limited number of clients for each	management, there are a very limited number of clients for each

	server, rarely more than three, and unlike the World Wide Web the	server, rarely more than three, and unlike the World Wide Web, the
	server administrators know exactly who they are. These clients visit	server administrators know exactly who they are. These clients visit
	very few servers, typically one only. This situation is totally	very few servers, typically one only. This situation is totally

	different to the World Wide Web. The use of external Certificate	different from the World Wide Web. The use of external Certificate
	Authorities is a potential security weakness that must be accepted for	Authorities is a potential security weakness that must be accepted for

	the World Wide Web, but which can be avoided for UPS management by	the World Wide Web but which can be avoided for UPS management by
	either generating locally the private and public keys, or for larger	either generating the private and public keys locally or, for larger
	organisations, using a Private Key Infrastructure..	organizations, using a PKI.
	</t>	</t>
	<t>The security policies for UPS management may be subordinate to an	<t>The security policies for UPS management may be subordinate to an

	organisation's own internal IT security plans and procedures, possibly	organization's own internal IT security plans and procedures, possibly
	based on <xref target="RFC7030"></xref>	based on <xref target="RFC7030"></xref>

	and <xref target="RFC8894"></xref>, but in simple cases it is possible	and <xref target="RFC8894"></xref>, but in simple cases, it is possible
	to obtain better security using self-signed certificates.	to obtain better security using self-signed certificates.
	</t>	</t>
	</section>	</section>
	</section>	</section>
	<section anchor="username">	<section anchor="username">
	<name><tt>USERNAME</tt></name>	<name><tt>USERNAME</tt></name>
	<t>The Attachment Daemon limits access to clients whose credentials match those in	<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 Daemo n	the file <tt>upsd.users</tt>. There is no anonymous access. A Management Daemo n
	program or script uses command <tt>USERNAME</tt> and its companion	program or script uses command <tt>USERNAME</tt> and its companion

	command <tt>PASSWORD</tt> to open a Session with the Attachment Daemon for an	command <tt>PASSWORD</tt> to open a session with the Attachment Daemon for an
	administrative user. Note that this command is for program or script	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	use and is not the familiar login command typed on a command line to
	gain access to a shell.	gain access to a shell.
	</t>	</t>
	<t>Command: <tt>USERNAME <username></tt>	<t>Command: <tt>USERNAME <username></tt>
	</t>	</t>

	<t>If the command succeeds, the response is <tt>OK</tt>, otherwise see	<t>If the command succeeds, the response is <tt>OK</tt>; otherwise, see
	the error responses in <xref target="errorresponses"></xref>.	the error responses in <xref target="errorresponses"></xref>.
	</t>	</t>
	<t>For examples of the use of commands <tt>USERNAME</tt> and	<t>For examples of the use of commands <tt>USERNAME</tt> and
	<tt>PASSWORD</tt> by administrative users,	<tt>PASSWORD</tt> by administrative users,
	see <xref target="adsecclient"></xref>.	see <xref target="adsecclient"></xref>.
	</t>	</t>

	<t>ABNF: See variable <tt>username</tt> in <xref target="fig.ABNF"></xref>.	<t>ABNF: See variable <tt>session-username</tt> in <xref target="fig.ABNF"></xre f>.
	</t>	</t>
	</section>	</section>
	<section anchor="ver">	<section anchor="ver">
	<name><tt>VER</tt></name>	<name><tt>VER</tt></name>
	<t>Return the implementation version of the Attachment Daemon. This command is	<t>Return the implementation version of the Attachment Daemon. This command is

	intended for human as well as program use.	intended for human, as well as program, use.
	</t>	</t>

	<t>Command <tt>VER</tt>	<t>Command: <tt>VER</tt>
	</t>	</t>

	<t>For example, the following command line sequence:	<t>For example: the following command line sequence
	</t>	</t>

	<sourcecode>netcat localhost 3493	<sourcecode name="" type="shell">
		netcat localhost 3493
	VER	VER
	Network UPS Tools upsd 2.8.0 - http://www.networkupstools.org/	Network UPS Tools upsd 2.8.0 - http://www.networkupstools.org/
	</sourcecode>	</sourcecode>
	<t>Notes:	<t>Notes:
	</t>	</t>
	<ol spacing="compact" indent="adaptive">	<ol spacing="compact" indent="adaptive">

	<li>There are no QUOTATION MARKS in the response.	<li>There are no quotation marks in the response.
	</li>	</li>
	<li>The implementation version of the Attachment Daemon returned by VER is	<li>The implementation version of the Attachment Daemon returned by VER is

	different to the protocol version returned by <tt>PROTVER</tt>.	different than the protocol version returned by <tt>PROTVER</tt>.
	</li>	</li>
	</ol>	</ol>
	<t>ABNF: See variable <tt>ver</tt> in <xref target="fig.ABNF"></xref>.	<t>ABNF: See variable <tt>ver</tt> in <xref target="fig.ABNF"></xref>.
	</t>	</t>
	</section>	</section>
	</section>	</section>
	<section anchor="responses">	<section anchor="responses">
	<name>Summary of Responses</name>	<name>Summary of Responses</name>
	<section anchor="success">	<section anchor="success">

	<name>Response when Command Succeeds</name>	<name>Response When Command Succeeds</name>
	<t>If the command succeeds, the response has the following	<t>If the command succeeds, the response has the following
	command-dependent form:	command-dependent form:
	</t>	</t>
	<table>	<table>

	<name>Response if command succeeds	<name>Response If Command Succeeds</name>
	</name>
	<thead>	<thead>
	<tr>	<tr>

	<th>Command </th>	<th>Command</th>
	<th>Response </th>	<th>Response</th>
	<th>Reference </th>	<th>Reference</th>
	<th>Note	<th>Note</th>
	</th>
	</tr>	</tr>
	</thead>	</thead>
	<tbody>	<tbody>
	<tr>	<tr>

	<td><tt>ATTACH</tt> </td>	<td><tt>ATTACH</tt></td>
	<td><tt>OK</tt> </td>	<td><tt>OK</tt></td>
	<td><xref target="attach"></xref> </td>	<td><xref target="attach"></xref></td>
	<td>Was LOGIN	<td>Was LOGIN </td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>DETACH</tt> </td>	<td><tt>DETACH</tt></td>
	<td><tt>OK Goodbye</tt> </td>	<td><tt>OK Goodbye</tt></td>
	<td><xref target="detach"></xref> </td>	<td><xref target="detach"></xref></td>
	<td>Was LOGOUT	<td>Was LOGOUT </td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>FSD</tt> </td>	<td><tt>FSD</tt></td>
	<td><tt>OK FSD-SET</tt> </td>	<td><tt>OK FSD-SET</tt></td>
	<td><xref target="FSD"></xref> </td>	<td><xref target="FSD"></xref></td>
	<td>	<td></td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>GET</tt> </td>	<td><tt>GET</tt></td>
	<td>Sub command specific </td>	<td>Subcommand specific</td>
	<td><xref target="get"></xref> </td>	<td><xref target="get"></xref></td>
	<td>	<td></td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>HELP</tt> </td>	<td><tt>HELP</tt></td>
	<td>List of commands </td>	<td>List of commands</td>
	<td><xref target="help"></xref> </td>	<td><xref target="help"></xref></td>
	<td>	<td></td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>INSTCMD</tt> </td>	<td><tt>INSTCMD</tt></td>
	<td><tt>OK </tt> </td>	<td><tt>OK</tt></td>
	<td><xref target="instcmd"></xref> </td>	<td><xref target="instcmd"></xref></td>
	<td>	<td></td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>LIST</tt> </td>	<td><tt>LIST</tt></td>
	<td>Sub command specific </td>	<td>Subcommand specific</td>
	<td><xref target="list"></xref> </td>	<td><xref target="list"></xref></td>
	<td>	<td></td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>PASSWORD</tt> </td>	<td><tt>PASSWORD</tt></td>
	<td><tt>OK</tt> </td>	<td><tt>OK</tt></td>
	<td><xref target="password"></xref> </td>	<td><xref target="password"></xref></td>
	<td>	<td></td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>PRIMARY</tt> </td>	<td><tt>PRIMARY</tt> </td>
	<td><tt>OK</tt> </td>	<td><tt>OK</tt></td>
	<td><xref target="primary"></xref> </td>	<td><xref target="primary"></xref></td>
	<td>	<td></td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>PROTVER</tt> </td>	<td><tt>PROTVER</tt></td>
	<td>Protocol version </td>	<td>Protocol version</td>
	<td><xref target="protver"></xref> </td>	<td><xref target="protver"></xref></td>
	<td>Was NETVER	<td>Was NETVER</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>SET</tt> </td>	<td><tt>SET</tt></td>
	<td><tt>OK</tt> </td>	<td><tt>OK</tt></td>
	<td><xref target="set"></xref> </td>	<td><xref target="set"></xref></td>
	<td>	<td></td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>STARTTLS</tt> </td>	<td><tt>STARTTLS</tt></td>
	<td><tt>OK STARTTLS</tt> </td>	<td><tt>OK STARTTLS</tt></td>
	<td><xref target="starttls"></xref> </td>	<td><xref target="starttls"></xref></td>
	<td>	<td></td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>USERNAME</tt> </td>	<td><tt>USERNAME</tt></td>
	<td><tt>OK</tt> </td>	<td><tt>OK</tt></td>
	<td><xref target="username"></xref> </td>	<td><xref target="username"></xref></td>
	<td>	<td></td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>VER</tt> </td>	<td><tt>VER</tt></td>
	<td>Program version </td>	<td>Program version</td>
	<td><xref target="ver"></xref> </td>	<td><xref target="ver"></xref></td>
	<td>	<td></td>
	</td>
	</tr>	</tr>
	</tbody>	</tbody>
	</table>	</table>
	</section>	</section>
	<section anchor="errorresponses">	<section anchor="errorresponses">
	<name>Error Responses</name>	<name>Error Responses</name>
	<t>Error responses have the following format:	<t>Error responses have the following format:
	</t>	</t>

	<sourcecode>ERR <error-name> [<extra>]	<sourcecode name="" type="shell">
		ERR <error-name> [<extra>]
	</sourcecode>	</sourcecode>

	<t>where <tt><error-name></tt> is a single word token taken from	<t><tt><error-name></tt> is a single word token taken from
	the 27 characters A-Z and HYPHEN	the 27 characters A-Z and hyphen
	(MINUS). Implementations <bcp14>MAY</bcp14> if needed add an additional	(-). Implementations <bcp14>MAY</bcp14>, if needed, add an additional,
	optional <tt><extra></tt>. Current practice does not make use	optional <tt><extra></tt>. Current practice does not make use
	of this possibility.	of this possibility.
	</t>	</t>
	<t>The <tt><error-name></tt> may have one of the following	<t>The <tt><error-name></tt> may have one of the following
	values:	values:
	</t>	</t>
	<table anchor="errors">	<table anchor="errors">

	<name>Error responses	<name>Error Responses</name>
	</name>
	<thead>	<thead>
	<tr>	<tr>

	<th align="center">    The error name token&n	<th align="center">    The Error Name Token&n
	bsp;	bsp;
	<br/><tt><error-name></tt>	<br/><tt><error-name></tt></th>
	</th>	<th align="center">Meaning</th>
	<th align="center">Meaning
	</th>
	</tr>	</tr>
	</thead>	</thead>
	<tbody>	<tbody>
	<tr>	<tr>
	<td><tt>ACCESS-DENIED</tt></td>	<td><tt>ACCESS-DENIED</tt></td>
	<td>The client's host and/or	<td>The client's host and/or
	authentication details supplied by <tt>USERNAME</tt>	authentication details supplied by <tt>USERNAME</tt>
	and <tt>PASSWORD</tt> are not sufficient to execute the requested	and <tt>PASSWORD</tt> are not sufficient to execute the requested

	command.	command.</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>
	<td><tt>ALREADY-ATTACHED</tt></td>	<td><tt>ALREADY-ATTACHED</tt></td>
	<td><t>The client has already sent a	<td><t>The client has already sent a

	successful <tt>ATTACH</tt> command for a given UPS and can't do it again.	successful <tt>ATTACH</tt> command for a given UPS and can't do it again.</t>
	</t><t>Note: Historically, this error response was <tt>ALREADY-LOGGED-IN</tt>.	</td>
	</t></td>
	</tr>	</tr>
	<tr>	<tr>
	<td><tt>ALREADY-SET-PASSWORD</tt></td>	<td><tt>ALREADY-SET-PASSWORD</tt></td>
	<td>The client has already	<td>The client has already
	supplied a <tt>PASSWORD</tt> and is attempting to repeat the command	supplied a <tt>PASSWORD</tt> and is attempting to repeat the command

	in the same Session.	in the same session.</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>
	<td><tt>ALREADY-SET-USERNAME</tt></td>	<td><tt>ALREADY-SET-USERNAME</tt></td>
	<td>The client has already	<td>The client has already

	supplied a <tt>USERNAME</tt>, and is attempting to repeat the command	supplied a <tt>USERNAME</tt> and is attempting to repeat the command
	within the same Session.	within the same session.</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>
	<td><tt>CMD-NOT-SUPPORTED</tt></td>	<td><tt>CMD-NOT-SUPPORTED</tt></td>
	<td>The specified UPS doesn't	<td>The specified UPS doesn't

	support the Instant Command.	support the Instant Command.</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>
	<td><tt>DATA-STALE</tt></td>	<td><tt>DATA-STALE</tt></td>
	<td><t>The Attachment Daemon is connected to the	<td><t>The Attachment Daemon is connected to the

	Driver for the UPS, but that driver isn't providing regular updates	Driver for the UPS, but that Driver isn't providing regular updates
	or has specifically marked the data as stale. Current practice is for	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	the Attachment Daemon to refuse to provide the Management Daemon with variables on stale units

	to avoid false readings.	to avoid false readings.</t>
	</t><t>This generally means that the Driver is running, but it has lost	<t>This generally means that the Driver is running, but it has lost
	communication with the hardware. Check the physical connection to the	communication with the hardware. Check the physical connection to the
	equipment.	equipment.
	</t></td>	</t></td>
	</tr>	</tr>
	<tr>	<tr>
	<td><tt>DRIVER-NOT-CONNECTED</tt></td>	<td><tt>DRIVER-NOT-CONNECTED</tt></td>
	<td>The Attachment Daemon can't perform the	<td>The Attachment Daemon can't perform the
	requested command, since the Driver for that UPS is not	requested command, since the Driver for that UPS is not

	connected. This usually means that the driver is not running, or if it	connected. This usually means that the Driver is not running or, if it
	is, is misconfigured.	is, is misconfigured.</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>
	<td><tt>FEATURE-NOT-CONFIGURED</tt></td>	<td><tt>FEATURE-NOT-CONFIGURED</tt></td>
	<td>This instance of the Attachment Daemon	<td>This instance of the Attachment Daemon
	hasn't been configured properly to allow the requested feature to	hasn't been configured properly to allow the requested feature to

	operate. In current practice this error response is possible only for	operate. In current practice, this error response is possible only for
	command <tt>STARTTLS</tt>.	command <tt>STARTTLS</tt>.</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>
	<td><tt>FEATURE-NOT-SUPPORTED</tt></td>	<td><tt>FEATURE-NOT-SUPPORTED</tt></td>
	<td>This instance of Attachment Daemon does	<td>This instance of Attachment Daemon does

	not support the requested feature. In current practice this error	not support the requested feature. In current practice, this error
	response is possible only for command <tt>STARTTLS</tt>.	response is possible only for command <tt>STARTTLS</tt>.</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>
	<td><tt>INSTCMD-FAILED</tt></td>	<td><tt>INSTCMD-FAILED</tt></td>
	<td>The Attachment Daemon failed to deliver the	<td>The Attachment Daemon failed to deliver the
	Instant Command request to the Driver. No further information is	Instant Command request to the Driver. No further information is
	available to the client. This typically indicates a dead or broken	available to the client. This typically indicates a dead or broken

	driver.	Driver.</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>
	<td><tt>INVALID-ARGUMENT</tt></td>	<td><tt>INVALID-ARGUMENT</tt></td>
	<td>The client sent an argument to a	<td>The client sent an argument to a

	command which is not recognized or is otherwise not valid in this	command that is not recognized or is otherwise not valid in this
	context. This is typically caused by sending a valid command such as	context. This is typically caused by sending a valid command, such as
	<tt>GET</tt> with a subcommand which is not valid.	<tt>GET</tt>, with a subcommand that is not valid.</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>
	<td><tt>INVALID-PASSWORD</tt></td>	<td><tt>INVALID-PASSWORD</tt></td>

	<td>The client sent a non valid	<td>The client sent a nonvalid
	<tt>PASSWORD</tt>.	<tt>PASSWORD</tt>.</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>
	<td><tt>INVALID-USERNAME</tt></td>	<td><tt>INVALID-USERNAME</tt></td>

	<td>The client sent an non valid	<td>The client sent a nonvalid
	<tt>USERNAME</tt>.	<tt>USERNAME</tt>.</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>
	<td><tt>INVALID-VALUE</tt></td>	<td><tt>INVALID-VALUE</tt></td>
	<td>The value specified in the request	<td>The value specified in the request
	is not valid. This usually applies to a <tt>SET</tt> of	is not valid. This usually applies to a <tt>SET</tt> of

	an <tt>ENUM</tt> type which is using a value not in the list of	an <tt>ENUM</tt> type that is using a value not in the list of
	allowed values. See <xref target="enum"></xref>.	allowed values. See <xref target="enum"></xref>.</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>PASSWORD-REQUIRED</tt></td>	<td><tt>PASSWORD-<bcp14>REQUIRED</bcp14></tt></td>
	<td>The command requires	<td>The command requires
	a <tt>PASSWORD</tt> for authentication, but the client hasn't provided	a <tt>PASSWORD</tt> for authentication, but the client hasn't provided

	one.	one.</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>
	<td><tt>READONLY</tt></td>	<td><tt>READONLY</tt></td>
	<td>The requested variable in a <tt>SET</tt>	<td>The requested variable in a <tt>SET</tt>

	command is not writable.	command is not writable.</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>
	<td><tt>SET-FAILED</tt></td>	<td><tt>SET-FAILED</tt></td>
	<td>The Attachment Daemon failed to deliver	<td>The Attachment Daemon failed to deliver
	the <tt>SET</tt> request to the Driver. This is similar	the <tt>SET</tt> request to the Driver. This is similar

	to <tt>INSTCMD-FAILED</tt>.	to <tt>INSTCMD-FAILED</tt>.</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>
	<td><tt>TLS-ALREADY-ENABLED</tt></td>	<td><tt>TLS-ALREADY-ENABLED</tt></td>
	<td><t>TLS mode is already enabled	<td><t>TLS mode is already enabled
	on this connection, so the Attachment Daemon can't start it again.	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><t>Note: Historically, this message was <tt>ALREADY-SSL-MODE.</tt>
	</t></td>	</t></td>
	</tr>	</tr>
	<tr>	<tr>
	<td><tt>TLS-NOT-ENABLED</tt></td>	<td><tt>TLS-NOT-ENABLED</tt></td>
	<td><t>TLS mode is required but has	<td><t>TLS mode is required but has
	not yet been enabled on this connection, so the Attachment Daemon can't send	not yet been enabled on this connection, so the Attachment Daemon can't send

	commands.	commands.</t>
	</t><t>Note: This message is experimental and not in current common	<t>Note: This message is experimental and not in current common
	use.	use.</t></td>
	</t></td>
	</tr>	</tr>
	<tr>	<tr>
	<td><tt>TOO-LONG</tt></td>	<td><tt>TOO-LONG</tt></td>
	<td>The requested value in a <tt>SET</tt>	<td>The requested value in a <tt>SET</tt>

	command is too long.	command is too long.</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>
	<td><tt>UNKNOWN-COMMAND</tt></td>	<td><tt>UNKNOWN-COMMAND</tt></td>
	<td>The Attachment Daemon doesn't recognize the	<td>The Attachment Daemon doesn't recognize the

	command.	command.</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>
	<td><tt>UNKNOWN-UPS</tt></td>	<td><tt>UNKNOWN-UPS</tt></td>
	<td>The UPS specified in the request is	<td>The UPS specified in the request is
	not known to the Attachment Daemon. This usually means that it didn't match	not known to the Attachment Daemon. This usually means that it didn't match

	anything in the Attachment Daemon configuration.	anything in the Attachment Daemon configuration.</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>USERNAME-REQUIRED</tt></td>	<td><tt>USERNAME-<bcp14>REQUIRED</bcp14></tt></td>
	<td>The command requires	<td>The command requires
	a <tt>USERNAME</tt> for authentication, but the client hasn't provided	a <tt>USERNAME</tt> for authentication, but the client hasn't provided

	one.	one.</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>
	<td><tt>VAR-NOT-SUPPORTED</tt></td>	<td><tt>VAR-NOT-SUPPORTED</tt></td>
	<td>The specified UPS doesn't	<td>The specified UPS doesn't

	support the UPS variable in the command.	support the UPS variable in the command.</td>
	</td>
	</tr>	</tr>
	</tbody>	</tbody>
	</table>	</table>

		<aside>
		<t>Note: Historically, this error response was <tt>ALREADY-LOGGED-IN</tt>.</t>
		</aside>
	</section>	</section>
	</section>	</section>
	<section anchor="ABNF">	<section anchor="ABNF">
	<name>An ABNF of the Commands</name>	<name>An ABNF of the Commands</name>

	<t>This section repeats the syntax of <xref target="commands"></xref>,	<t>This section repeats the syntax of <xref target="commands"></xref>
	but in Augmented Bachus-Naur Form (ABNF). It does not define any	but in Augmented Backus-Naur Form (ABNF). It does not define any
	additional feature. For further details of each command and the	additional features. For further details of each command and the
	response, see <xref target="commands"></xref>.	response, see <xref target="commands"></xref>.
	</t>	</t>
	<t>The commands may be presented in ABNF	<t>The commands may be presented in ABNF

	<xref target="RFC5234"></xref><xref target="RFC7405"></xref>, and	<xref target="RFC5234"></xref> <xref target="RFC7405"></xref> and
	represented using ASCII <xref target="RFC0020"></xref>.	represented using US-ASCII <xref target="RFC0020"></xref>.
	</t>	</t>

	<t>Current practice tolerates mixed case command names, but it is	<t>Current practice tolerates mixed-case command names, but it is
	<bcp14>RECOMMENDED</bcp14> to use upper case only for commands.	<bcp14>RECOMMENDED</bcp14> to use uppercase only for commands.
	See <xref target="fig.ABNF"></xref>.	See <xref target="fig.ABNF"></xref>.
	</t>	</t>
	<figure anchor="fig.ABNF" align="center">	<figure anchor="fig.ABNF" align="center">
	<name>ABNF for the Commands	<name>ABNF for the Commands
	</name>	</name>
	<sourcecode type="abnf">	<sourcecode type="abnf">
	;-------------------------------------------------------------------	;-------------------------------------------------------------------
	; This grammar is case sensitive. Terminal keywords SHOULD be	; This grammar is case sensitive. Terminal keywords SHOULD be

	; written in upper case as shown.	; written in uppercase, as shown.
	; The following basic rules written with upper case names are	; The following basic rules written with uppercase names are
	; taken from RFC5234 Appendix B.1.	; taken from RFC 5234, Appendix B.1.
	SP = 1*%x20 ; At least one SPACE	SP = 1*%x20 ; At least one SPACE
	LF = %x0A ; Linefeed	LF = %x0A ; Linefeed
	DIGIT = %x30-39 ; Digit 0 through 9	DIGIT = %x30-39 ; Digit 0 through 9
	ALPHA = %x41-5A / %x61-7A ; A-Z / a-z	ALPHA = %x41-5A / %x61-7A ; A-Z / a-z
	DQUOTE = %x22 ; Double quote "	DQUOTE = %x22 ; Double quote "
	VCHAR = %x21-7E ; Visible (printing) characters	VCHAR = %x21-7E ; Visible (printing) characters
	; Additional basic rules needed by this grammar	; Additional basic rules needed by this grammar
	LC = %x61-7A ; Letter a through z	LC = %x61-7A ; Letter a through z
	DOT = 1%x2E ; Exactly one .	DOT = 1%x2E ; Exactly one .
	COLON = 1%x3A ; Exactly one :	COLON = 1%x3A ; Exactly one :
	AT = 1%x40 ; Exactly one @	AT = 1%x40 ; Exactly one @
	SEP = 1"-" / 1"_" / 1"." ; A single - or _ or .	SEP = 1"-" / 1"_" / 1"." ; A single - or _ or .
	JOIN = COLON / AT ; A single : or @	JOIN = COLON / AT ; A single : or @
	; Frequently used in this grammar	; Frequently used in this grammar

	cmdname = 1LC 62(DOT 1*LC) ; E.g. load.off.delay	cmdname = 1LC 62(DOT 1*LC) ; E.g., load.off.delay
	upschar = DIGIT / ALPHA / SEP	upschar = DIGIT / ALPHA / SEP

	ups = 1ALPHA 62upschar ; E.g. Example-Mfg-999	ups = 1ALPHA 62upschar ; E.g., Example-Mfg-999
	group = ups ; E.g. HB (Not in common use)	group = ups ; E.g., HB (Not in common use)
	hostname = ups ; E.g. example.com	hostname = ups ; E.g., example.com
	port = 1*5DIGIT ; E.g. 3493	port = 1*5DIGIT ; E.g., 3493
	upsname = [group COLON] ups [AT hostname [COLON port]]	upsname = [group COLON] ups [AT hostname [COLON port]]
	; Fully Qualified UPS name	; Fully Qualified UPS name

	; E.g. HB:heartbeat1@example.com:3493	; E.g.,
	username = ups ; E.g. Power-Dept.6	; HB:heartbeat1@example.com:3493
		username = ups ; E.g., Power-Dept.6
	varname = 1LC 62( DOT 1*(DIGIT / LC) )	varname = 1LC 62( DOT 1*(DIGIT / LC) )

	; E.g. outlet.1.status	; E.g., outlet.1.status
	;-------------------------------------------------------------------	;-------------------------------------------------------------------
	commandLine = command LF ; LF is a single %x0A	commandLine = command LF ; LF is a single %x0A
	command = attach / detach / fsd / get / help / instcmd /	command = attach / detach / fsd / get / help / instcmd /
	list / password / primary / protver / set /	list / password / primary / protver / set /
	starttls / username / ver	starttls / username / ver
	;	;
	attach = "ATTACH" SP upsname	attach = "ATTACH" SP upsname
	;	;
	detach = "DETACH"	detach = "DETACH"
	;	;

	skipping to change at line 1654 ¶	skipping to change at line 1629 ¶
	listrw / listups / listvar	listrw / listups / listvar
	;	;
	listclient = "CLIENT" SP upsname	listclient = "CLIENT" SP upsname
	listcmd = "CMD" SP upsname	listcmd = "CMD" SP upsname
	listenum = "ENUM" SP upsname SP varname	listenum = "ENUM" SP upsname SP varname
	listrange = "RANGE" SP upsname SP varname	listrange = "RANGE" SP upsname SP varname
	listrw = "RW" SP upsname	listrw = "RW" SP upsname
	listups = "UPS"	listups = "UPS"
	listvar = "VAR" SP upsname	listvar = "VAR" SP upsname
	;	;

	password = "PASSWORD" SP *63VCHAR	session-password = "PASSWORD" SP *63VCHAR
	; A sequence of printable characters defined	; A sequence of printable characters defined
	; in a server configuration file. Local	; in a server configuration file. Local
	; security practices may mandate a minimum	; security practices may mandate a minimum
	; and maximum number of characters.	; and maximum number of characters.
	;	;
	primary = "PRIMARY" SP upsname	primary = "PRIMARY" SP upsname
	;	;
	protver = "PROTVER"	protver = "PROTVER"
	;	;

	value = *63VCHAR ; Local practices may limit the choice of	value = *63VCHAR ; Local practices may limit the choice of
	; characters, and require non US-ASCII.	; characters and require non-US-ASCII.
	set = "SET" SP %s"VAR" SP upsname SP varname SP DQUOTE value DQUOTE	set = "SET" SP %s"VAR" SP upsname SP varname SP
		DQUOTE value DQUOTE
	;	;
	starttls = "STARTTLS"	starttls = "STARTTLS"
	;	;

	username = "USERNAME" SP username	session-username = "USERNAME" SP username
	;	;
	ver = "VER"	ver = "VER"
	;-------------------------------------------------------------------	;-------------------------------------------------------------------
	</sourcecode>	</sourcecode>
	</figure>	</figure>

	<t>Notes:	<t>Notes:</t>
	</t>	<ol spacing="normal" indent="adaptive">
	<ol indent="adaptive">
	<li><em>Implementation note:</em> The ABNF is written using the	<li><em>Implementation note:</em> The ABNF is written using the
	provisions	provisions

	of <xref target="RFC5234"></xref> <xref target="RFC7405"></xref> which	of <xref target="RFC5234"></xref> and <xref target="RFC7405"></xref>, which
	are <xref target="RFC0020">US-ASCII based</xref>.	are <xref target="RFC0020">US-ASCII based</xref>.</li>
	</li>
	<li>The grammar is case sensitive. The terminal key words <bcp14>SHOULD</bcp14>	<li>The grammar is case sensitive. The terminal key words <bcp14>SHOULD</bcp14>

	be written in upper case as specified.	be written in uppercase, as specified.</li>
	</li>
	<li>The repetition factor in front of an expression has the form	<li>The repetition factor in front of an expression has the form

	<min>*<max> where <min> is the minimum number of	<min>*<max>, where <min> is the minimum number of
	repetitions and <max> is the maximum number.	repetitions, and <max> is the maximum number.</li>
	</li>	<li>If <min> is omitted, its value is 0. If <max> is
	<li>If <min> is omitted its value is 0. If <max> is	omitted, its value is infinity.</li>
	omitted, its value is infinity.	<li>The notation <tt>n*n</tt>, meaning "exactly n copies", may be
	</li>	written as <tt>n</tt>.</li>
	<li>The notation <tt>n*n</tt> meaning "exactly n copies" may be
	written as <tt>n</tt>.
	</li>
	<li>Square brackets around an expression mean that the expression is	<li>Square brackets around an expression mean that the expression is

	optional. This could be written as <tt>0*1</tt>.	optional. This could be written as <tt>0*1</tt>.</li>
	</li>
	</ol>	</ol>
	<section anchor="ABNF-resp">	<section anchor="ABNF-resp">
	<name>Responses to Commands</name>	<name>Responses to Commands</name>
	<t>The responses to the commands are encoded	<t>The responses to the commands are encoded
	in <xref target="RFC0020">US-ASCII</xref> and fall into two groups:	in <xref target="RFC0020">US-ASCII</xref> and fall into two groups:
	</t>	</t>

	<ol indent="adaptive">	<ol spacing="normal" indent="adaptive">
	<li>Short replies to action commands, see <xref target="responses"></xref>.	<li>Short replies to action commands; see <xref target="responses"></xref>.</li>
	</li>	<li>Long replies to requests for information. In this case, the reply
	<li>Long replies to requests for information. In this case the reply	is sent in a sequence of messages. The last message will contain a
	is sent in a sequence of messages. The last message will contain a	line beginning <tt>END LIST</tt> . For
	line beginning <tt>END LIST</tt> . See for	example, see <xref target="client"></xref>.</li>
	example <xref target="client"></xref>.
	</li>
	</ol>	</ol>
	</section>	</section>
	</section>	</section>
	</section>	</section>
	<section>	<section>
	<name>Statuses and Events</name>	<name>Statuses and Events</name>
	<section anchor="symbols">	<section anchor="symbols">
	<name>Status Symbols</name>	<name>Status Symbols</name>
	<t>These symbols resume the abstracted view of the UPS hardware	<t>These symbols resume the abstracted view of the UPS hardware
	maintained by the Attachment Daemon. The variable <tt>ups.status</tt> contains	maintained by the Attachment Daemon. The variable <tt>ups.status</tt> contains

	one or more space-separated status symbols which together describe the	one or more space-separated status symbols, which together describe the
	UPS state at that instant. In current practice the Management Daemon will poll	UPS state at that instant. In current practice, the Management Daemon will poll
	variable <tt>ups.status</tt> every 5 seconds with a command such	variable <tt>ups.status</tt> every 5 seconds with a command, such
	as <tt>GET VAR su700 ups.status</tt> and response such as <tt>VAR	as <tt>GET VAR su700 ups.status</tt>, and a response, such as <tt>VAR
	su700 ups.status "OB LB"</tt> to discover changes in the UPS status.	su700 ups.status "OB LB"</tt>, to discover changes in the UPS status.
	These changes will indicate UPS events.	These changes will indicate UPS events.
	</t>	</t>
	<table>	<table>

	<name>UPS Status Symbols	<name>UPS Status Symbols</name>
	</name>
	<thead>	<thead>
	<tr>	<tr>
	<th align="center">Status Symbol </th>	<th align="center">Status Symbol </th>

	<th align="center">Meaning	<th align="center">Meaning</th>
	</th>
	</tr>	</tr>
	</thead>	</thead>
	<tbody>	<tbody>
	<tr>	<tr>

	<td><tt>ALARM</tt>	<td><tt>ALARM</tt></td>
	</td>	<td>The UPS reports that it requires intervention.</td>
	<td>The UPS reports that it requires intervention.
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>BOOST</tt>	<td><tt>BOOST</tt></td>
	</td>
	<td>The UPS has determined that the voltage level of the public power supply is	<td>The UPS has determined that the voltage level of the public power supply is

	too low, and is boosting it to the required level. The UPS continues	too low and is boosting it to the required level. The UPS continues
	to supply the protected system from the public power supply.	to supply the protected system from the public power supply.</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>BYPASS</tt>	<td><tt>BYPASS</tt></td>
	</td>
	<td>The UPS is feeding current directly from the public power supply to the	<td>The UPS is feeding current directly from the public power supply to the
	protected system. The backup facilities are disconnected. This state	protected system. The backup facilities are disconnected. This state
	allows maintenance personnel to change the batteries without	allows maintenance personnel to change the batteries without

	interrupting the protected system.	interrupting the protected system.</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>CAL</tt>	<td><tt>CAL</tt></td>
	</td>	<td>The UPS is calibrating itself, for example, to determine at what
	<td>The UPS is calibrating itself, for example to determine at what	charge the <tt>LB</tt> status is raised or lowered.</td>
	charge the <tt>LB</tt> status is raised or lowered.
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>CHRG</tt>	<td><tt>CHRG</tt></td>
	</td>
	<td><t>The UPS battery is charging. This usually implies that the UPS	<td><t>The UPS battery is charging. This usually implies that the UPS

	also has status <tt>OL</tt>, but may not be the case if the UPS also has	also has status <tt>OL</tt> but may not be the case if the UPS also has
	status <tt>OFF</tt>.	status <tt>OFF</tt>.
	</t></td>	</t></td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>COMM</tt>	<td><tt>COMM</tt></td>
	</td>	<td>The Attachment Daemon has effective contact with the UPS.</td>
	<td>The Attachment Daemon has effective contact with the UPS.
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>DISCHRG</tt>	<td><tt>DISCHRG</tt></td>
	</td>
	<td><t>The UPS battery is discharging. This usually implies that the UPS	<td><t>The UPS battery is discharging. This usually implies that the UPS

	also has status <tt>OB</tt>, but may not be the case if the UPS also has	also has status <tt>OB</tt> but may not be the case if the UPS also has
	status <tt>OFF</tt>.	status <tt>OFF</tt>.
	</t></td>	</t></td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>FSD</tt>	<td><tt>FSD</tt></td>
	</td>
	<td>This "Forced Shutdown" status signals that the final shutdown	<td>This "Forced Shutdown" status signals that the final shutdown

	sequence has begun.	sequence has begun.</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>LB</tt>	<td><tt>LB</tt></td>
	</td>
	<td>Low Battery. The battery level of the UPS is below a chosen limit.	<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>.	The UPS may be in status <tt>OL</tt> or <tt>OB</tt>.</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>NOCOMM</tt>	<td><tt>NOCOMM</tt></td>
	</td>	<td>The Attachment Daemon has no effective contact with the UPS.</td>
	<td>The Attachment Daemon has no effective contact with the UPS.
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>OB</tt>	<td><tt>OB</tt></td>
	</td>	<td>On Battery. The UPS is taking energy from its battery.
	<td>On Battery. The UPS is taking energy from it's battery.	The battery is discharging. A UPS must have status <tt>OB</tt> or <tt>OL</tt>;
	The battery is discharging. A UPS must have status <tt>OB</tt> or <tt>OL</tt>,	otherwise, it is deemed dead.</td>
	otherwise it is deemed dead.
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>OFF</tt>	<td><tt>OFF</tt></td>
	</td>
	<td>The UPS is in state "Off". It does not react to failure in the	<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.	public power supply. The exact meaning depends on the model.</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>OL</tt>	<td><tt>OL</tt></td>
	</td>
	<td>Online. The UPS is online, receiving energy from the public power supply. T he	<td>Online. The UPS is online, receiving energy from the public power supply. T he

	battery is charging. A UPS must have status <tt>OB</tt> or <tt>OL</tt>, otherwi	battery is charging. A UPS must have status <tt>OB</tt> or <tt>OL</tt>; otherwi
	se	se,
	it is deemed dead.	it is deemed dead.</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>OVER</tt>	<td><tt>OVER</tt></td>
	</td>	<td>Overloaded. The UPS reports that the load on it is beyond its
	<td>Overloaded. The UPS reports that the load on it is beyond it's	normal operating maximum.</td>
	normal operating maximum.
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>RB</tt>	<td><tt>RB</tt></td>
	</td>	<td>Replace battery. The UPS reports that its battery or batteries should
	<td>Replace battery. The UPS reports that it's battery/batteries should	be replaced.</td>
	be replaced.
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>TEST</tt>	<td><tt>TEST</tt></td>
	</td>	<td>Under test. The UPS is currently undergoing a test that may have
	<td>Under test. The UPS is currently undergoing a test, which may have	been requested manually or internally.</td>
	been called for manually or internally.
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>TICK</tt>	<td><tt>TICK</tt></td>
	</td>
	<td>Heartbeat. A software UPS in the Attachment Daemon provides a regular signal	<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	monitored by the Management Daemon as a way of verifying effective end-to-end

	management. <tt>TICK</tt> and <tt>TOCK</tt> are companions, they are considered	management. <tt>TICK</tt> and <tt>TOCK</tt> are companions; they are considered
	experimental.	experimental.</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>TOCK</tt>	<td><tt>TOCK</tt></td>
	</td>	<td>Heartbeat. See <tt>TICK</tt></td>
	<td>Heartbeat. See <tt>TICK</tt>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>TRIM</tt>	<td><tt>TRIM</tt></td>
	</td>
	<td>The UPS has determined that the voltage level of the public power supply is	<td>The UPS has determined that the voltage level of the public power supply is

	too high, and is reducing it to the required level. The UPS continues	too high and is reducing it to the required level. The UPS continues
	to supply the protected system from the public power supply.	to supply the protected system from the public power supply.</td>
	</td>
	</tr>	</tr>
	</tbody>	</tbody>
	</table>	</table>
	</section>	</section>
	<section anchor="events">	<section anchor="events">
	<name>Events</name>	<name>Events</name>

	<t>A Management Daemon detects the occurrence of a UPS Event from a change in th e	<t>A Management Daemon detects the occurrence of a UPS event from a change in th e
	UPS status received from the Attachment Daemon. The following table summarizes	UPS status received from the Attachment Daemon. The following table summarizes
	the process. A status of "none" means that the status symbol is not	the process. A status of "none" means that the status symbol is not
	present in the variable <tt>ups.status</tt>.	present in the variable <tt>ups.status</tt>.
	</t>	</t>
	<t>The Management Daemon should retrieve the variable <tt>ups.status</tt> from t he	<t>The Management Daemon should retrieve the variable <tt>ups.status</tt> from t he
	Attachment Daemon at regular intervals. If the interval is too short, compute a nd	Attachment Daemon at regular intervals. If the interval is too short, compute a nd
	network resources will be wasted, but if the interval is too large,	network resources will be wasted, but if the interval is too large,
	the Management Daemon risks missing short-lived changes in the UPS status.	the Management Daemon risks missing short-lived changes in the UPS status.
	</t>	</t>
	<t>A default value of 5 seconds is <bcp14>RECOMMENDED</bcp14>, but an implementa tion	<t>A default value of 5 seconds is <bcp14>RECOMMENDED</bcp14>, but an implementa tion

	<bcp14>MAY</bcp14> make this value configurable. By default the "old" status is	<bcp14>MAY</bcp14> make this value configurable. By default, the "old" status i s
	therefore the previous value retrieved 5 seconds ago.	therefore the previous value retrieved 5 seconds ago.
	</t>	</t>
	<t>Current practice is for the Management Daemon to assign names to certain	<t>Current practice is for the Management Daemon to assign names to certain

	events. These is shown in the table in parentheses.	events. These are shown in the table in parentheses.
	</t>	</t>
	<table>	<table>

	<name>Event deduction from status changes	<name>Event Deduction from Status Changes</name>
	</name>
	<thead>	<thead>
	<tr>	<tr>

	<th>Old status </th>	<th>Old Status</th>
	<th>New status </th>	<th>New Status</th>
	<th>Event </th>	<th>Event</th>
	<th>	<th>    </th>
	</th>	<th>Old Status</th>
	<th>Old status </th>	<th>New Status</th>
	<th>New status </th>	<th>Event</th>
	<th>Event
	</th>
	</tr>	</tr>
	</thead>	</thead>
	<tbody>	<tbody>
	<tr>	<tr>

	<td>none </td>	<td>none</td>
	<td><tt>ALARM</tt> </td>	<td><tt>ALARM</tt></td>
	<td>Alarm on </td>	<td>Alarm on</td>
	<td>	<td>    </td>
	</td>	<td><tt>ALARM</tt></td>
	<td><tt>ALARM</tt> </td>	<td>none</td>
	<td>none </td>	<td>Alarm off</td>
	<td>Alarm off
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td>none </td>	<td>none</td>
	<td><tt>BOOST</tt> </td>	<td><tt>BOOST</tt></td>
	<td>Boosting voltage </td>	<td>Boosting voltage</td>
	<td>	<td>    </td>
	</td>	<td><tt>BOOST</tt></td>
	<td><tt>BOOST</tt> </td>	<td>none</td>
	<td>none </td>	<td>Not boosting</td>
	<td>Not boosting
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td>none </td>	<td>none</td>
	<td><tt>BYPASS</tt> </td>	<td><tt>BYPASS</tt></td>
	<td>Bypass on </td>	<td>Bypass on</td>
	<td>	<td>    </td>
	</td>	<td><tt>BYPASS</tt></td>
	<td><tt>BYPASS</tt> </td>	<td>none</td>
	<td>none </td>	<td>Bypass off</td>
	<td>Bypass off
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td>none </td>	<td>none</td>
	<td><tt>CAL</tt> </td>	<td><tt>CAL</tt></td>
	<td>Calibrating </td>	<td>Calibrating</td>
	<td>	<td>    </td>
	</td>	<td><tt>CAL</tt></td>
	<td><tt>CAL</tt> </td>	<td>none</td>
	<td>none </td>	<td>Not calibrating</td>
	<td>Not calibrating
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td>none </td>	<td>none</td>
	<td><tt>CHRG</tt> </td>	<td><tt>CHRG</tt></td>
	<td>Charging </td>	<td>Charging</td>
	<td>	<td>    </td>
	</td>	<td><tt>CHRG</tt></td>
	<td><tt>CHRG</tt> </td>	<td>none</td>
	<td>none </td>	<td>Not charging</td>
	<td>Not charging
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td>none </td>	<td>none</td>
	<td><tt>COMM</tt> </td>	<td><tt>COMM</tt></td>
	<td>UPS communicating<br/>(Event <tt>COMMOK</tt>) </td>	<td>UPS communicating<br/>(event <tt>COMMOK</tt>)</td>
	<td>	<td>    </td>
	</td>	<td><tt>COMM</tt></td>
	<td><tt>COMM</tt> </td>	<td>none</td>
	<td>none </td>	<td>See note <xref target="DDD" format="counter"></xref></td>
	<td>See note <xref target="DDD" format="counter"></xref>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td>none </td>	<td>none</td>
	<td><tt>DISCHRG</tt> </td>	<td><tt>DISCHRG</tt></td>
	<td>Discharging </td>	<td>Discharging</td>
	<td>	<td>    </td>
	</td>	<td><tt>DISCHRG</tt></td>
	<td><tt>DISCHRG</tt> </td>	<td>none</td>
	<td>none </td>	<td>Not discharging</td>
	<td>Not discharging
	</td>
	</tr>	</tr>
	<tr anchor="EventFSD">	<tr anchor="EventFSD">

	<td>none </td>	<td>none</td>
	<td><tt>FSD</tt> </td>	<td><tt>FSD</tt></td>
	<td>System shutdown<br/>(Events <tt>FSD</tt>, <tt>SHUTDOWN</tt>) </td>	<td>System shutdown<br/>(events <tt>FSD</tt>, <tt>SHUTDOWN</tt>)</td>
	<td>	<td>    </td>
	</td>	<td><tt>FSD</tt></td>
	<td><tt>FSD</tt> </td>	<td>none</td>
	<td>none </td>	<td>Shutdown abandoned. See note <xref target="AAA" format="counter"></xref></t
	<td>Shutdown abandoned. See note <xref target="AAA" format="counter"></xref>	d>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td>none </td>	<td>none</td>
	<td><tt>LB</tt> </td>	<td><tt>LB</tt></td>
	<td>Low battery. See note <xref target="BBB" format="counter"></xref> (Event <t	<td>Low battery. See note <xref target="BBB" format="counter"></xref> (event <t
	t>LOWBATT</tt>) </td>	t>LOWBATT</tt>)</td>
	<td>	<td>    </td>
	</td>	<td><tt>LB</tt></td>
	<td><tt>LB</tt> </td>	<td>none</td>
	<td>none </td>	<td>Battery not low</td>
	<td>Battery not low
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td>none </td>	<td>none</td>
	<td><tt>NOCOMM</tt> </td>	<td><tt>NOCOMM</tt></td>
	<td>UPS dead? See note <xref target="DDD" format="counter"></xref><br/>(Events	<td>UPS dead? See note <xref target="DDD" format="counter"></xref><br/>(events
	<tt>COMMBAD</tt>, <tt>NOCOMM</tt>) </td>	<tt>COMMBAD</tt>, <tt>NOCOMM</tt>)</td>
	<td>	<td>    </td>
	</td>	<td><tt>NOCOMM</tt></td>
	<td><tt>NOCOMM</tt> </td>	<td>none</td>
	<td>none </td>	<td>See note <xref target="DDD" format="counter"></xref></td>
	<td>See note <xref target="DDD" format="counter"></xref>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td>none </td>	<td>none</td>
	<td><tt>OFF</tt> </td>	<td><tt>OFF</tt></td>
	<td>UPS turned off </td>	<td>UPS turned off</td>
	<td>	<td>    </td>
	</td>	<td><tt>OFF</tt></td>
	<td><tt>OFF</tt> </td>	<td>none</td>
	<td>none </td>	<td>UPS not turned off</td>
	<td>UPS not turned off
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>OB</tt> </td>	<td><tt>OB</tt></td>
	<td><tt>OL</tt> </td>	<td><tt>OL</tt></td>
	<td>Receiving power<br/>(Event <tt>ONLINE</tt>) </td>	<td>Receiving power<br/>(event <tt>ONLINE</tt>)</td>
	<td>	<td>    </td>
	</td>	<td><tt>OL</tt></td>
	<td><tt>OL</tt> </td>	<td><tt>OB</tt></td>
	<td><tt>OB</tt> </td>	<td>Power lost<br/>(event <tt>ONBATT</tt>)</td>
	<td>Power lost<br/>(Event <tt>ONBATT</tt>)
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td>none </td>	<td>none</td>
	<td><tt>OVER</tt> </td>	<td><tt>OVER</tt></td>
	<td>UPS overloaded </td>	<td>UPS overloaded</td>
	<td>	<td>    </td>
	</td>	<td><tt>OVER</tt></td>
	<td><tt>OVER</tt> </td>	<td>none</td>
	<td>none </td>	<td>Overload gone</td>
	<td>Overload gone
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td>none </td>	<td>none</td>
	<td><tt>RB</tt> </td>	<td><tt>RB</tt></td>
	<td>Replace battery<br/>(Event <tt>REPLBATT</tt>) </td>	<td>Replace battery<br/>(event <tt>REPLBATT</tt>)</td>
	<td>	<td>    </td>
	</td>	<td><tt>RB</tt></td>
	<td><tt>RB</tt> </td>	<td>none</td>
	<td>none </td>	<td>Replacement canceled</td>
	<td>Replacement canceled
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td>none </td>	<td>none</td>
	<td><tt>TEST</tt> </td>	<td><tt>TEST</tt></td>
	<td>Test starts </td>	<td>Test starts</td>
	<td>	<td>    </td>
	</td>	<td><tt>TEST</tt></td>
	<td><tt>TEST</tt> </td>	<td>none</td>
	<td>none </td>	<td>Test finished</td>
	<td>Test finished
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td>none </td>	<td>none</td>
	<td><tt>TICK</tt> </td>	<td><tt>TICK</tt></td>
	<td>Heartbeat event. See note <xref target="CCC" format="counter"></xref> </td>	<td>Heartbeat event. See note <xref target="CCC" format="counter"></xref> </td>

	<td>	<td>    </td>
	</td>	<td><tt>TICK</tt></td>
	<td><tt>TICK</tt> </td>	<td>none</td>
	<td>none </td>	<td>No heartbeat. See note <xref target="CCC" format="counter"></xref></td>
	<td>No heartbeat. See note <xref target="CCC" format="counter"></xref>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td>none </td>	<td>none</td>
	<td><tt>TOCK</tt> </td>	<td><tt>TOCK</tt></td>
	<td>Heartbeat event. See note <xref target="CCC" format="counter"></xref> </td>	<td>Heartbeat event. See note <xref target="CCC" format="counter"></xref> </td>

	<td>	<td>    </td>
	</td>	<td><tt>TOCK</tt></td>
	<td><tt>TOCK</tt> </td>	<td>none</td>
	<td>none </td>	<td>No heartbeat. See note <xref target="CCC" format="counter"></xref></td>
	<td>No heartbeat. See note <xref target="CCC" format="counter"></xref>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td>none </td>	<td>none</td>
	<td><tt>TRIM</tt> </td>	<td><tt>TRIM</tt></td>
	<td>Trimming voltage </td>	<td>Trimming voltage</td>
	<td>	<td>    </td>
	</td>	<td><tt>TRIM</tt></td>
	<td><tt>TRIM</tt> </td>	<td>none</td>
	<td>none </td>	<td>Not trimming</td>
	<td>Not trimming
	</td>
	</tr>	</tr>
	</tbody>	</tbody>
	</table>	</table>

	<t>Notes	<dl newline="true" spacing="normal">
	</t>	<dt>Notes:</dt>
		<dd>
	<ol spacing="compact" indent="adaptive">	<ol spacing="compact" indent="adaptive">

	<li anchor="AAA">Current practice does not include this event.	<li anchor="AAA">Current practice does not include this event.</li>
	</li>
	<li anchor="BBB">If the status <tt>OB</tt> is present, current practice	<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 emerg ency	takes Management Daemon reception of <tt>LB</tt> as an order to perform an emerg ency

	system shutdown.	system shutdown.</li>
	</li>	<li anchor="CCC">The use of a software-defined UPS to provide a
	<li anchor="CCC">The use of a software defined UPS to provide a	heartbeat is experimental and is not part of common current practice.</li>
	heartbeat is experimental and is not part of common current practice.	<li anchor="DDD">Current practice is the following: if the UPS has not responded
	</li>	for
	<li anchor="DDD">Current practice is: if the UPS has not responded for	15 seconds, the Management Daemon assumes that the UPS is <em>dead</em>
	15 seconds, the Management Daemon assumes that the UPS is "<em>dead</em>"	(event <tt>NOCOMM</tt>), and if the last known <tt>OL</tt>/<tt>OB</tt> status wa
	(Event <tt>NOCOMM</tt>), and if the last known <tt>OL</tt>/<tt>OB</tt> status wa	s <tt>OB</tt>, a
	s <tt>OB</tt> a	system shutdown (command <tt>FSD</tt>) is requested.</li>
	system shutdown, command <tt>FSD</tt>, is called for.
	</li>
	</ol>	</ol>

		</dd>
		</dl>
	</section>	</section>
	</section>	</section>
	<section anchor="Sec">	<section anchor="Sec">
	<name>Security Considerations</name>	<name>Security Considerations</name>
	<section anchor="weak">	<section anchor="weak">
	<name>Current General Security Practice</name>	<name>Current General Security Practice</name>
	<t>Experience over the last 20 years shows that new UPS management	<t>Experience over the last 20 years shows that new UPS management

	software releases are not frequent, and when installed, stay	software releases are not frequent and, when installed, stay
	unmodified for some years. This is probably because UPS management is	unmodified for some years. This is probably because UPS management is

	a mature activity, part of site mangement. A limited number of	a mature activity, part of site management. A limited number of
	system administrators have access to the UPS hardware and software and	system administrators have access to the UPS hardware and software and
	tend to assume a certain "security by obscurity" since many	tend to assume a certain "security by obscurity" since many

	installations have a configuration as shown in	installations have a configuration like the one shown in
	figure <xref target="fig.weak" format="counter"></xref> which uses port	<xref target="fig.weak"/>, which uses port
	3493/TCP (nut) between the two daemons running in the same system.	3493/TCP (nut) between the two daemons running in the same system.

	The traffic is often not encrypted, and when encrypted uses deprecated	The traffic is often not encrypted, and when it is encrypted, it uses deprecated
	early versions of SSL/TLS.	early versions of SSL/TLS.
	</t>	</t>
	<figure anchor="fig.weak">	<figure anchor="fig.weak">

	<name>Common single-system configuration	<name>Common Single-System Configuration</name>
	</name>	<artwork align="center" type="ascii-art">
	<artwork align="center"> ,-----, ,--------------------,---------------------,	,-----, ,--------------------,---------------------,
	\| UPS \|---\| Attachment <-Commands Management \|	\| UPS \|---\| Attachment <-Commands Management \|
	\| \|===\| Daemon Responses-> Daemon \|	\| \|===\| Daemon Responses-> Daemon \|
	/-----\ '--------------------'---------------------'	/-----\ '--------------------'---------------------'
	Listens on	Listens on
	port 3493/TCP	port 3493/TCP

	for localhost</artwork>	for localhost
		</artwork>
	</figure>	</figure>

	<t>This situation is now changing as low cost processors become	<t>This situation is now changing as low-cost processors become
	available, costing significantly less than a UPS unit. This evolution	available, costing significantly less than a UPS unit. This evolution

	makes it interesting to shift to a configuration as shown in	makes it interesting to shift to a configuration like the one shown in
	figure <xref target="fig.weaker" format="counter"></xref>, but it also	<xref target="fig.weaker"/>, but it also
	exacerbates the security weakness of figure <xref target="fig.weak" format="coun	exacerbates the security weakness of <xref target="fig.weak"/>, since the traffi
	ter"></xref> since the traffic between the daemons is now over an	c between the daemons is now over an
	exposed network.	exposed network.
	</t>	</t>
	<figure anchor="fig.weaker">	<figure anchor="fig.weaker">
	<name>Integration of UPS and Attachment Daemon	<name>Integration of UPS and Attachment Daemon
	</name>	</name>

	<artwork align="center"> ,-----,------------, ,--------------,	<artwork align="center" type="ascii-art">
		,-----,------------, ,--------------,
	\| UPS - Attachment \| <-Commands \| Management \|	\| UPS - Attachment \| <-Commands \| Management \|
	\| \| Daemon \| Responses-> \| Daemon \|	\| \| Daemon \| Responses-> \| Daemon \|
	/-----'------------\ '--------------'	/-----'------------\ '--------------'
	Listens on	Listens on

	port 3493/TCP</artwork>	port 3493/TCP
		</artwork>
	</figure>	</figure>
	<t>These security issues raised by UPS management are those of the	<t>These security issues raised by UPS management are those of the

	power industry in general: they are addressed in detail in	power industry in general; they are addressed in detail in
	<xref target="IEC62351-1">IEC Technical Specification 62351</xref>.	<xref target="IEC62351-1">IEC Technical Specification 62351</xref>.
	In addition to equipment security, cyber security is now an essential	In addition to equipment security, cyber security is now an essential
	consideration.	consideration.
	</t>	</t>
	<t>Quoting from IEC 62351-1<xref target="IEC62351-1"></xref>,	<t>Quoting from IEC 62351-1<xref target="IEC62351-1"></xref>,
	Introduction to the standard, clause 5.2.3.5:	Introduction to the standard, clause 5.2.3.5:
	</t>	</t>
	<blockquote> With the computer systems for power operations presumably	<blockquote> With the computer systems for power operations presumably
	kept isolated from the Internet, many utility personnel do not see any	kept isolated from the Internet, many utility personnel do not see any
	reason for adding security measures to these systems. However, as	reason for adding security measures to these systems. However, as
	clearly seen from these Subclauses, this may not be true anymore as	clearly seen from these Subclauses, this may not be true anymore as
	networking becomes more prevalent and additional information access	networking becomes more prevalent and additional information access
	requirements grow.</blockquote>	requirements grow.</blockquote>

	<t>In IEC 62351-1<xref target="IEC62351-1"></xref> clause 5.3.5 lists	<t>In IEC 62351-1<xref target="IEC62351-1"></xref>, clause 5.3.5 lists
	typical security attacks: Eavesdropping, Masquerade,	typical security attacks: Eavesdropping, Masquerade,

	Man-in-the-Middle, Replay, Resource Exhaustion.	Man-in-the-Middle, Replay, and Resource Exhaustion.
	RFC3552 <xref target="RFC3552"></xref> adds message insersion /	<xref target="RFC3552"></xref> adds message insertion/deletion/modification
	deletion / modification, and denial of service.	and denial of service.
	</t>	</t>
	<t>Let's look more closely at these requirements:	<t>Let's look more closely at these requirements:
	</t>	</t>

	<ul>	<ul spacing="normal">
	<li>Eavesdropping, see <xref target="Eavesdropping"></xref>	<li>Eavesdropping; see <xref target="Eavesdropping"></xref></li>
	</li>	<li>Man-in-the-Middle; see <xref target="Man-in-the-Middle"></xref></li>
	<li>Man-in-the-Middle, see <xref target="Man-in-the-Middle"></xref>	<li>Masquerade; see <xref target="Masquerade"></xref></li>
	</li>	<li>Message insertion, deletion, and modification;
	<li>Masquerade, see <xref target="Masquerade"></xref>	see <xref target="Messageidm"></xref></li>
	</li>	<li>Replay; see <xref target="Replay"></xref></li>
	<li>Message insersion, deletion, modification,	<li>Resource Exhaustion and Denial of Service;
	see <xref target="Messageidm"></xref>	see <xref target="Exhaustion"></xref></li>
	</li>
	<li>Replay, see <xref target="Replay"></xref>
	</li>
	<li>Resource Exhaustion, Denial of Service,
	see <xref target="Exhaustion"></xref>
	</li>
	</ul>	</ul>
	</section>	</section>
	<section anchor="SecRec">	<section anchor="SecRec">
	<name>Communication Security Requirements</name>	<name>Communication Security Requirements</name>
	<t>Enforcing secure communication requires tightening up the Attachment Daemon t o	<t>Enforcing secure communication requires tightening up the Attachment Daemon t o
	require the use of command	require the use of command
	<tt>STARTTLS</tt> for commands sent over the global Internet. In such a	<tt>STARTTLS</tt> for commands sent over the global Internet. In such a

	situation an Attachment Daemon listening for traffic other than from	situation, an Attachment Daemon listening for traffic other than from
	the <tt>localhost</tt>:	<tt>localhost</tt>:
	</t>	</t>

	<ol indent="adaptive">	<ol spacing="normal" indent="adaptive">
	<li anchor="should"><bcp14>SHOULD</bcp14> require and accept command	<li anchor="should"><bcp14>SHOULD</bcp14> require and accept command

	<tt>STARTTLS</tt>,	<tt>STARTTLS</tt>,</li>
	</li>	<li anchor="must"><bcp14>MUST</bcp14> encrypt all communication with a Managemen
	<li anchor="must"><bcp14>MUST</bcp14> encrypt all communication with a Managemen	t Daemon, and</li>
	t Daemon,	<li anchor="shall"><bcp14>SHALL</bcp14> refuse all non-encrypted commands, excep
	</li>	t
	<li anchor="shall"><bcp14>SHALL</bcp14> refuse all non-encrypted commands except	an initial <tt>STARTTLS</tt>.</li>
	an initial <tt>STARTTLS</tt>.
	</li>
	</ol>	</ol>

	<t>Notes:	<t>Notes: </t>
	</t>	<ul spacing="normal">
	<ul>	<li anchor="note-should">The <bcp14>SHOULD</bcp14>, rather than <bcp14>MUST</bcp
	<li anchor="note-should">The <bcp14>SHOULD</bcp14> rather than <bcp14>MUST</bcp1	14>,
	4>
	in <xref target="should"></xref> above allows system administrators to	in <xref target="should"></xref> above allows system administrators to

	enforce secure communication using other techniques which do not	enforce secure communication using other techniques that do not
	involve the <tt>STARTTLS</tt> command.	involve the <tt>STARTTLS</tt> command.</li>
	</li>
	<li>If an Attachment Daemon requires that all commands be encrypted as required by	<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	the <bcp14>MUST</bcp14> in <xref target="must"></xref> above, then, automaticall y,
	each Management Daemon <bcp14>MUST</bcp14> encrypt as well, since it has to do s o in order to	each Management Daemon <bcp14>MUST</bcp14> encrypt as well, since it has to do s o in order to

	gain access.	gain access.</li>
	</li>
	<li>The <bcp14>SHALL</bcp14> in <xref target="shall"></xref> above applies to	<li>The <bcp14>SHALL</bcp14> in <xref target="shall"></xref> above applies to
	traffic from the global Internet. An Attachment Daemon <bcp14>MAY</bcp14> accep t unencrypted	traffic from the global Internet. An Attachment Daemon <bcp14>MAY</bcp14> accep t unencrypted
	commands from <tt>localhost</tt> if the local installation's security	commands from <tt>localhost</tt> if the local installation's security

	practices allow it, for example in a dedicated appliance.	practices allow it, for example, in a dedicated appliance.</li>
	</li>
	</ul>	</ul>
	<t>Firewalls <bcp14>SHOULD</bcp14> be used to restrict the communication between	<t>Firewalls <bcp14>SHOULD</bcp14> be used to restrict the communication between
	the Attachment Daemon and the accepted Management Daemons, prohibiting and disca rding traffic	the Attachment Daemon and the accepted Management Daemons, prohibiting and disca rding traffic
	from any systems that are not part of the envisioned power management	from any systems that are not part of the envisioned power management
	setup. Note: See <xref target="note-should"></xref> above on the use	setup. Note: See <xref target="note-should"></xref> above on the use
	of <bcp14>SHOULD</bcp14>.	of <bcp14>SHOULD</bcp14>.
	</t>	</t>
	<section anchor="certsec">	<section anchor="certsec">

	<name>Certificate security</name>	<name>Certificate Security</name>
	<t>In long-lived installations such as those found in UPS management,	<t>In long-lived installations, such as those found in UPS management,
	careful certificate management is essential, whether the certificate	careful certificate management is essential, whether the certificate

	is provided by a Certificate Authority, or is a self-signed	is provided by a Certificate Authority or is a self-signed
	certificate. For example the specification of expiration times of	certificate. For example, the expiration times of both the
	both the certificate containing the public key and the signing	certificate containing the public key and the signing certificate
	certificate.	should be specified. </t>
	</t>
	</section>	</section>
	</section>	</section>
	<section anchor="Attacks">	<section anchor="Attacks">

	<name>Attacks and Defences</name>	<name>Attacks and Defenses</name>
	<section anchor="Eavesdropping">	<section anchor="Eavesdropping">
	<name>Eavesdropping</name>	<name>Eavesdropping</name>

	<t>The defence against eavesdropping is encryption of the commands and	<t>The defense against eavesdropping is encryption of the commands and
	responses passed between client Management Daemon and server Attachment Daemon.	responses passed between the client Management Daemon and server Attachment Daem
	The protocol	on. The protocol
	provides command <tt>STARTTLS</tt>, see <xref target="starttls"></xref>, which c alls on	provides command <tt>STARTTLS</tt>, see <xref target="starttls"></xref>, which c alls on
	the Attachment Daemon to support TLS encryption of the communication. If this	the Attachment Daemon to support TLS encryption of the communication. If this
	command is accepted, the Management Daemon also encrypts.	command is accepted, the Management Daemon also encrypts.
	</t>	</t>

	<t>In current NUT Project practice, the use of TLS is optional,	<t>In current NUT Project practice, the use of TLS is optional;
	however a Management Daemon may refuse to accept unencrypted communication. Thi	however, a Management Daemon may refuse to accept unencrypted communication. Th
	s	is
	is done by setting declarations <tt>FORCESSL</tt> to 1	is done by setting declarations <tt>FORCESSL</tt> to 1
	and <tt>CERTVERIFY</tt> to 1 in the Management Daemon configuration file.	and <tt>CERTVERIFY</tt> to 1 in the Management Daemon configuration file.
	</t>	</t>
	<section>	<section>

	<name>Misplaced declarations requiring TLS</name>	<name>Misplaced Declarations Requiring TLS</name>
	<t>A further weakness is that the <tt>FORCESSL</tt>	<t>A further weakness is that the <tt>FORCESSL</tt>

	and <tt>CERTVERIFY</tt> declarations which enforce use of encryption	and <tt>CERTVERIFY</tt> declarations, which enforce use of encryption,
	are in the client Management Daemon configuration file and not in the Attachment Daemon.	are in the client Management Daemon configuration file and not in the Attachment Daemon.

	Secure practice requires enforcement by the server Attachment Daemon rather than a	Secure practice requires enforcement by the server Attachment Daemon, rather tha n a
	possibly rogue client Management Daemon out on the Internet.	possibly rogue client Management Daemon out on the Internet.
	</t>	</t>

	<t>This weakness may be mitigated with strict firewall rules which	<t>This weakness may be mitigated with strict firewall rules that
	would prevent the rogue client Management Daemon from accessing the Attachment D aemon.	would prevent the rogue client Management Daemon from accessing the Attachment D aemon.
	</t>	</t>
	</section>	</section>
	<section>	<section>

	<name>Weak protection in previous version 2.7.4</name>	<name>Weak Protection in Previous Version 2.7.4</name>
	<t>Although version 2.8.0 of NUT supports TLS	<t>Although version 2.8.0 of NUT supports TLS
	1.3 <xref target="RFC8446"></xref> with X.509 v3 certificates as	1.3 <xref target="RFC8446"></xref> with X.509 v3 certificates as

	defined by RFC5280 <xref target="RFC5280"></xref>, previous version	defined by <xref target="RFC5280"></xref>, previous version
	2.7.4 only supported earlier SSL/TLS versions. To overcome this	2.7.4 only supported earlier SSL/TLS versions. To overcome this
	weakness, The following techniques have been used:	weakness, The following techniques have been used:
	</t>	</t>

	<ul>	<ul spacing="normal">
	<li>Shims, see <xref target="Shims"></xref>	<li>Shims; see <xref target="Shims"></xref></li>
	</li>	<li>TLS tunnel; see <xref target="TLStunnel"></xref></li>
	<li>TLS tunnel, see <xref target="TLStunnel"></xref>	<li>Virtual Private Network (VPN); see <xref target="VPN"></xref></li>
	</li>	<li>Virtual Local Area Network (VLAN); see <xref target="VLAN"></xref></li>
	<li>Virtual Private Network, VPN, see <xref target="VPN"></xref>
	</li>
	<li>Virtual Local Area network, VLAN, see <xref target="VLAN"></xref>
	</li>
	</ul>	</ul>
	</section>	</section>
	</section>	</section>
	<section anchor="Man-in-the-Middle">	<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	<t>The protocol relies on TLS encryption to prevent man-in-the-middle
	attacks. See <xref target="AppendixEavesdropping"></xref> for defense	attacks. See <xref target="AppendixEavesdropping"></xref> for defense
	methods used for previous NUT version 2.7.4.	methods used for previous NUT version 2.7.4.
	</t>	</t>
	</section>	</section>
	<section anchor="Masquerade">	<section anchor="Masquerade">
	<name>Masquerade Attack: Agent Verification</name>	<name>Masquerade Attack: Agent Verification</name>
	<t anchor="AgentVerif">The protocol allows a malicious client acting	<t anchor="AgentVerif">The protocol allows a malicious client acting

	as an Management Daemon to send command <tt>FSD</tt> to an Attachment Daemon to	as a Management Daemon to send command <tt>FSD</tt> to an Attachment Daemon to s
	shut down a	hut down a
	working system and it's power supply as described in The Shutdown	working system and its power supply, as described in The Shutdown
	Story, see <xref target="shutdownstory"></xref>. Similarly, a	Story section (see <xref target="shutdownstory"></xref>). Similarly, a
	malicious client could turn off the UPS power outlets causing the	malicious client could turn off the UPS power outlets, causing the
	system to fail.	system to fail.
	</t>	</t>

	<t>The protocol provides commands <tt>USERNAME</tt>, see <xref target="username"	<t>The protocol provides commands <tt>USERNAME</tt> (see <xref target="username"
	></xref>,	></xref>)
	and <tt>PASSWORD</tt>, see <xref target="password"></xref>, which allow an admin	and <tt>PASSWORD</tt> (see <xref target="password"></xref>), which allow an admi
	istrative	nistrative
	user in a Management Daemon to authenticate itself to the Attachment Daemon, as	user in a Management Daemon to authenticate itself to the Attachment Daemon, as
	a defence	a defense
	against masquerade attacks. The administrative user name and password	against masquerade attacks. The administrative username and password
	need protection against local malicious users. This is done by	need protection against local malicious users. This is done by
	restricting access to the configuration files.	restricting access to the configuration files.
	</t>	</t>
	</section>	</section>
	<section anchor="Messageidm">	<section anchor="Messageidm">

	<name>Message insertion, deletion, modification</name>	<name>Message Insertion, Deletion, and Modification</name>
	<t>The protocol relies on TLS encryption to prevent message insertion,	<t>The protocol relies on TLS encryption to prevent message insertion,

	deletion and modification attacks.	deletion, and modification attacks.
	See <xref target="AppendixEavesdropping"></xref> for defense methods	See <xref target="AppendixEavesdropping"></xref> for defense methods
	used for previous NUT version 2.7.4.	used for previous NUT version 2.7.4.
	</t>	</t>
	</section>	</section>
	<section anchor="Replay">	<section anchor="Replay">
	<name>Replay</name>	<name>Replay</name>
	<t>There are two cases:	<t>There are two cases:
	</t>	</t>

	<ol indent="adaptive">	<ol spacing="normal" indent="adaptive">
	<li>The replay is from a system other than an approved Management Daemon:	<li>The replay is from a system other than an approved Management Daemon, i.e.,
	the protocol relies on a firewall to block the traffic.	the protocol relies on a firewall to block the traffic. </li>
	</li>	<li>The replay is from an approved Management Daemon. i.e., the protocol relies
	<li>The replay is from an approved Management Daemon: the protocol relies on the	on the
	Management Daemon's own security to prevent unauthorised access.	Management Daemon's own security to prevent unauthorized access.</li>
	</li>
	</ol>	</ol>
	</section>	</section>
	<section anchor="Exhaustion">	<section anchor="Exhaustion">
	<name>Denial of Service</name>	<name>Denial of Service</name>
	<t>The protocol relies on a very tightly specified firewall to prevent	<t>The protocol relies on a very tightly specified firewall to prevent

	denial of service attacks. Only designated client Management Daemons should be	denial-of-service attacks. Only designated client Management Daemons should be
	able to reach the server Attachment Daemon.	able to reach the server Attachment Daemon.
	</t>	</t>
	</section>	</section>
	</section>	</section>
	</section>	</section>
	<section>	<section>
	<name>IANA Considerations</name>	<name>IANA Considerations</name>

	<t>The protocol specified by this text runs over port 3493/TCP (nut)	<t>The protocol specified by this text runs over port 3493/TCP (nut), which is
	registered by the NUT (Network UPS Tools) project.	registered by the Network UPS Tools (NUT) Project.
	</t>	</t>

	<t>This document will be added to the registration's reference field.	<t>This document has been added to the registration's Reference field in the
		"Service Name and Transport Protocol Port Number Registry" <xref target="Registr
		y" format="default"/>.
	</t>	</t>
	</section>	</section>
	<section anchor="implementation">	<section anchor="implementation">
	<name>Implementation Status</name>	<name>Implementation Status</name>
	<t>This section presents a very short summary of the status of the	<t>This section presents a very short summary of the status of the
	Network UPS Tools project.	Network UPS Tools project.
	</t>	</t>
	<ul anchor="vsh" spacing="compact">	<ul anchor="vsh" spacing="compact">

	<li>May 1996: The first hack as a cron job.	<li>May 1996: The first hack as a cron job.</li>
	</li>	<li>September 1997: The first server-client code.</li>
	<li>September 1997: The first server-client code.	<li>March 1998: First public release.</li>
	</li>	<li>June 1999: Code rewrite with a UPS Driver <tt>smartups</tt>, an
	<li>March 1998: First public release.	Attachment Daemon <tt>upsd</tt>, and a simple Management Daemon.</li>
	</li>
	<li>June 1999: Code rewrite with a UPS driver <tt>smartups</tt>, an
	Attachment Daemon <tt>upsd</tt> and a simple Management Daemon.
	</li>
	<li>September 1999: The project became "Network UPS Tools". The	<li>September 1999: The project became "Network UPS Tools". The

	Management Daemon <tt>upsmon</tt> supported primary/secondary configurations.	Management Daemon <tt>upsmon</tt> supported Primary/Secondary configurations.</l
	</li>	i>
	<li>June 2001: Common core for multiple drivers.	<li>June 2001: Common core for multiple Drivers.</li>
	</li>
	<li>May 2002: IANA granted port 3493/TCP (nut). August: release	<li>May 2002: IANA granted port 3493/TCP (nut). August: release

	1.0.0. November: OpenSSL support.	1.0.0. November: OpenSSL support.</li>
	</li>
	<li>April 2003: The initial set of command and variable names was	<li>April 2003: The initial set of command and variable names was

	designed.	designed.</li>
	</li>
	<li anchor="arno">February 2005: Arnaud Quette took over the project	<li anchor="arno">February 2005: Arnaud Quette took over the project

	lead from Russell Kroll.	lead from Russell Kroll.</li>
	</li>
	<li>March 2016: Version 2.7.4 released, supported over 100 device	<li>March 2016: Version 2.7.4 released, supported over 100 device

	manufacturers and hundreds of UPS models.	manufacturers and hundreds of UPS models.</li>
	</li>
	<li>November 2020: Evgeny "Jim" Klimov took over project lead from	<li>November 2020: Evgeny "Jim" Klimov took over project lead from

	Arnaud Quette.	Arnaud Quette.</li>
	</li>
	<li>May 2022: Version 2.8.0 released, supporting protocol version	<li>May 2022: Version 2.8.0 released, supporting protocol version

	1.3.	1.3.</li>
	</li>
	</ul>	</ul>
	<t>See <xref target="githist"></xref>	<t>See <xref target="githist"></xref>

	and <xref target="History"></xref> for a detailed history of the	and Appendix J <xref target="History"></xref> for a detailed history of the
	NUT Project.	NUT Project.
	</t>	</t>
	<section>	<section>
	<name>Inclusion in Software Distributions</name>	<name>Inclusion in Software Distributions</name>
	<t>The programs <tt>upsd</tt>, <tt>upsmon</tt>, <tt>upssched</tt>,	<t>The programs <tt>upsd</tt>, <tt>upsmon</tt>, <tt>upssched</tt>,

	<tt>upsc</tt>, <tt>upscmd</tt> and <tt>upsrw</tt> have been included	<tt>upsc</tt>, <tt>upscmd</tt>, and <tt>upsrw</tt> have been included
	in the package known as "nut" in the package systems of many	in the package known as "nut" in the package systems of many

	distributions: all the major Linux distributions, and Unix	distributions, i.e., all the major Linux distributions and Unix
	distributions such as OpenBSD and OpenSolaris. A Microsoft Windows	distributions, such as OpenBSD and OpenSolaris. A Microsoft Windows
	version has been developed but was not maintained.	version has been developed but was not maintained.
	</t>	</t>
	</section>	</section>
	<section anchor="MinSup">	<section anchor="MinSup">
	<name>Recommended Minimum Support</name>	<name>Recommended Minimum Support</name>

	<t>The features provided by current UPS units vary widely. However	<t>The features provided by current UPS units vary widely. However,
	experience shows that a minimum feature set is needed for satisfactory	experience shows that a minimum feature set is needed for satisfactory
	use of the NUT Project software. A full list of variables is	use of the NUT Project software. A full list of variables is
	available in <xref target="gitvars">source code file	available in <xref target="gitvars">source code file

	docs/nut-names.txt</xref> which serves as the Recording Document.	docs/nut-names.txt</xref>, which serves as the Recording Document.
	</t>	</t>
	<section anchor="MinSupPC">	<section anchor="MinSupPC">
	<name>Desktop PC Variables</name>	<name>Desktop PC Variables</name>

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

	<ul>	<ul spacing="normal">
	<li><tt>battery.charge</tt>	<li><tt>battery.charge</tt></li>
	</li>	<li><tt>battery.charge.low</tt></li>
	<li><tt>battery.charge.low</tt>	<li><tt>device.mfr</tt></li>
	</li>	<li><tt>device.model</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</t t>	<li><tt>ups.status</tt> with the minimum status symbol set <tt>OL</tt> <tt>OB</t t>

	<tt>LB</tt> <tt>FSD</tt>, see <xref target="symbols"></xref>.	<tt>LB</tt> <tt>FSD</tt>; see <xref target="symbols"></xref></li>
	</li>
	</ul>	</ul>
	</section>	</section>
	<section anchor="MinSupServer">	<section anchor="MinSupServer">

	<name>Unattended Servers, Additional Variables</name>	<name>Unattended Servers and Additional Variables</name>
	<t>The following additional variables are needed in a minimum set	<t>The following additional variables are needed in a minimum set

	suitable for an unattended server. It is expected that on public power supply	suitable for an unattended server. It is expected that, on public power supply
	failure, the server will be halted. It will restart automatically	failure, the server will be halted. It will restart automatically
	when power returns.	when power returns.
	</t>	</t>

	<ul>	<ul spacing="normal">
	<li><tt>battery.date</tt>	<li><tt>battery.date</tt></li>
	</li>	<li><tt>device.serial</tt></li>
	<li><tt>device.serial</tt>	<li><tt>ups.delay.shutdown</tt></li>
	</li>	<li><tt>ups.delay.start</tt></li>
	<li><tt>ups.delay.shutdown</tt>
	</li>
	<li><tt>ups.delay.start</tt>
	</li>
	</ul>	</ul>
	</section>	</section>
	<section anchor="MinSupCommands">	<section anchor="MinSupCommands">

	<name>Commands and other Technical	<name>Commands and Other Technical
	Terms</name>	Terms</name>
	<t>Satisfactory use of the NUT Project software requires support for	<t>Satisfactory use of the NUT Project software requires support for
	all the commands specified in protocol version 1.3, software version	all the commands specified in protocol version 1.3, software version
	2.8.0.	2.8.0.
	</t>	</t>
	</section>	</section>
	<section anchor="Version.2.7.4">	<section anchor="Version.2.7.4">
	<name>Support for Earlier Versions</name>	<name>Support for Earlier Versions</name>

	<t>In order to ease migration from software version 2.7.4 which	<t>In order to ease migration from software version 2.7.4, which
	supported protocol version 1.2, software version 2.8.0 also supports	supported protocol version 1.2, software version 2.8.0 also supports
	the technical terms used in protocol version 1.2.	the technical terms used in protocol version 1.2.
	See <xref target="differences"></xref> for the differences.	See <xref target="differences"></xref> for the differences.
	</t>	</t>
	</section>	</section>
	</section>	</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>	</middle>
	<back>	<back>
	<references>	<references>

	<name>Normative References	<name>References</name>
	</name>	<references>
	<reference anchor="RFC0020" target="https://www.rfc-editor.org/info/rfc20">	<name>Normative References</name>
	<front>
	<title>ASCII format for network interchange</title>	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.0020.
	<author initials="V.G." surname="Cerf" fullname="V.G. Cerf">	xml"/>
	</author>	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2119.
	<date month="October" year="1969">	xml"/>
	</date>	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5234.
	</front>	xml"/>
	<seriesInfo name="STD" value="80"/>	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7405.
	<seriesInfo name="RFC" value="20"/>	xml"/>
	<seriesInfo name="DOI" value="10.17487/RFC0020"/>	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8174.
	</reference>	xml"/>
	<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>	</references>


	<references>	<references>

	<name>Informative References	<name>Informative References </name>
	</name>
	<reference anchor="RFC3552" target="https://www.rfc-editor.org/info/rfc3552">	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.3552.
	<front>	xml"/>
	<title>Guidelines for Writing RFC Text on Security Considerations</title>	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7991.
	<author initials="E." surname="Rescorla" fullname="E. Rescorla">	xml"/>
	</author>	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5280.
	<author initials="B." surname="Korver" fullname="B. Korver">	xml"/>
	</author>	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7030.
	<date month="July" year="2003">	xml"/>
	</date>	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8446.
	<abstract>	xml"/>
	<t>All RFCs are required to have a Security	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8894.
	Considerations section. Historically, such sections have been	xml"/>
	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>
	<reference anchor="IEC62351-1" target="https://nanopdf.com/download/technical-ie c-specification-ts-62351-1_pdf">	<reference anchor="IEC62351-1" target="https://nanopdf.com/download/technical-ie c-specification-ts-62351-1_pdf">
	<front>	<front>

	<title>IEC TS 62351-1 Power systems management and associated	<title>Power systems management and associated
	information exchange -- Data and communications security. Part 1:	information exchange -- Data and communications security. Part 1:
	Communication network and system security -- Introduction to	Communication network and system security -- Introduction to
	security issues</title>	security issues</title>
	<author>	<author>

		<organization>IEC</organization>
	</author>	</author>

	<date day="15" month="May" year="2007">	<date month="May" year="2007"></date>
	</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>
	</front>	</front>

	<seriesInfo name="IEC" value="Technical Specification Reference number IEC/TS 62	<seriesInfo name="IEC" value="TS 62351-1:2007"/>
	351-1:2007(E), 35 pages"/>	<refcontent>35 pages, TC 57 - Power systems management and associated informatio
	<seriesInfo name="CHF" value="205"/>	n exchange</refcontent>
	<seriesInfo name="Technical Committee" value="TC 57 - Power systems management a
	nd associated information exchange"/>
	</reference>	</reference>


	<reference anchor="NUT" target="https://www.networkupstools.org">	<reference anchor="NUT" target="https://www.networkupstools.org">
	<front>	<front>

	<title>Network UPS Tools (NUT) Project</title>	<title>Network UPS Tools, Devices Dumps Library</title>
	<author>	<author>

	<organization>	<organization/>
	</organization>
	</author>	</author>
	</front>	</front>
	</reference>	</reference>


	<reference anchor="nut-upsuser" target="https://alioth-lists.debian.net/cgi-bin/ mailman/listinfo/nut-upsuser">	<reference anchor="nut-upsuser" target="https://alioth-lists.debian.net/cgi-bin/ mailman/listinfo/nut-upsuser">
	<front>	<front>

	<title>Network UPS Tools (NUT) Project Mailing List for users</title>	<title>Network UPS Tools (NUT) Project Mailing List for Users</title>
	<author>	<author>

	<organization>	<organization>NUT</organization>
	</organization>
	</author>	</author>
	</front>	</front>
	</reference>	</reference>


	<reference anchor="nut-upsdev" target="https://alioth-lists.debian.net/cgi-bin/m ailman/listinfo/nut-upsdev">	<reference anchor="nut-upsdev" target="https://alioth-lists.debian.net/cgi-bin/m ailman/listinfo/nut-upsdev">
	<front>	<front>

	<title>Network UPS Tools (NUT) Project Mailing List for developers</title>	<title>Network UPS Tools (NUT) Project Mailing List for Developers</title>
	<author>	<author>

	<organization>	<organization>NUT</organization>
	</organization>
	</author>	</author>
	</front>	</front>
	</reference>	</reference>


	<reference anchor="nut-repository" target="https://github.com/networkupstools/nu t/">	<reference anchor="nut-repository" target="https://github.com/networkupstools/nu t/">
	<front>	<front>

	<title>GitHub Repository for the Network UPS Tools (NUT) Project</title>	<title>The Network UPS Tools repository </title>
	<author>	<author>

	<organization>	<organization/>
	</organization>
	</author>	</author>
	</front>	</front>
	</reference>	</reference>


	<reference anchor="devguide" target="https://networkupstools.org/docs/developer- guide.chunked/ar01s09.html">	<reference anchor="devguide" target="https://networkupstools.org/docs/developer- guide.chunked/ar01s09.html">
	<front>	<front>

	<title>Network UPS Tools (NUT) Project Developer Guide</title>	<title>Network UPS Tools Project Developer Guide</title>
	<author>	<author initials="R" surname="Kroll" fullname="Russell Kroll">
	<organization>	<organization/>
	</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>	</author>
	</front>	</front>
	</reference>	</reference>


	<reference anchor="SGML">	<reference anchor="SGML">
	<front>	<front>
	<title>The SGML Handbook</title>	<title>The SGML Handbook</title>

	<seriesInfo name="ISBN" value="0-19-853737-9"/>	<author initials="C." surname="Goldfarb" fullname="Charles F. Goldfarb">
	<author initials="Charles F." surname="Goldfarb" fullname="Charles F. Goldfarb">
	<organization>Oxford University Press
	</organization>
	</author>	</author>

	<date year="1990">	<date year="1990"></date>
	</date>
	</front>	</front>

		<seriesInfo name="ISBN-10" value="0-19-853737-9"/>
		<refcontent>Oxford University Press</refcontent>
	</reference>	</reference>


	<reference anchor="HyTimeA">	<reference anchor="HyTimeA">
	<front>	<front>

	<title>International Standard ISO/IEC 10744 --	<title>Information technology --
	Hypermedia/Time-based Structuring Language, Annex A, SGML	Hypermedia/Time-based Structuring Language (HyTime)</title>
	Extended Facilities</title>
	<seriesInfo name="ISO/IEC" value="JTC 1/SC 34 Document description and processi
	ng languages"/>
	<author>	<author>

	<organization>	<organization>ISO/IEC</organization>
	</organization>
	</author>	</author>

	<date year="1997">	<date month="August" year="1997"></date>
	</date>
	</front>	</front>

		<seriesInfo name="ISO/IEC" value="10744:1997"/>
	</reference>	</reference>

	<reference anchor="sgmlnorm" target="http://www.jclark.com/sp/sgmlnorm.htm">
		<reference anchor="sgmlnorm" target="http://openjade.sourceforge.net/">
	<front>	<front>

	<title>SGMLNORM An SGML System Conforming to International	<title>OpenJade Distribution Page</title>
	Standard ISO 8879 -- Standard Generalized Markup	<author>
	Language</title>	<organization>OpenJade Project</organization>
	<author initials="James" surname="Clark" fullname="James Clark">
	<organization>
	</organization>
	</author>	</author>
	</front>	</front>
	</reference>	</reference>


	<reference anchor="Registry" target="https://www.iana.org/assignments/service-na mes-port-numbers/service-names-port-numbers.xhtml">	<reference anchor="Registry" target="https://www.iana.org/assignments/service-na mes-port-numbers/service-names-port-numbers.xhtml">
	<front>	<front>
	<title>Service Name and Transport Protocol Port Number Registry</title>	<title>Service Name and Transport Protocol Port Number Registry</title>

	<seriesInfo name="Publisher:" value="IANA"/>	<author><organization>IANA</organization></author>
	<author>
	</author>
	</front>	</front>
	</reference>	</reference>


	<reference anchor="Library" target="https://networkupstools.org/ddl/">	<reference anchor="Library" target="https://networkupstools.org/ddl/">
	<front>	<front>

	<title>GitHub Network UPS Tools, Devices Dumps Library</title>	<title>Devices Dumps Library</title>
	<author>	<author></author>
	</author>
	</front>	</front>
	</reference>	</reference>


	<reference anchor="History" target="https://networkupstools.org/docs/user-manual .pdf">	<reference anchor="History" target="https://networkupstools.org/docs/user-manual .pdf">
	<front>	<front>

	<title>Network UPS Tools User Manual, Appendix J Project history</title>	<title>Network UPS Tools User Manual</title>
	<author>	<author initials="R" surname="Kroll" fullname="Russell Kroll"/>
	</author>	<author initials="A" surname="Quette" fullname="Arnaud Quette"/>
		<author initials="A" surname="de Korte" fullname="Arjen de Korte"/>
		<date month="May" year="2022"/>
	</front>	</front>
	</reference>	</reference>


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

	<author>	<author></author>
	</author>
	</front>	</front>
	</reference>	</reference>


	<reference anchor="gitvars" target="https://github.com/networkupstools/nut/blob/ master/docs/nut-names.txt">	<reference anchor="gitvars" target="https://github.com/networkupstools/nut/blob/ master/docs/nut-names.txt">
	<front>	<front>

	<title>GitHub Network UPS Tools code repository, variable names</title>	<title>The Network UPS Tools repository, variable names</title>
	<author>	<author></author>
	</author>	<date month="April" year="2022"/>
	</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>
	</front>	</front>
	</reference>	</reference>


	<reference anchor="githist" target="https://github.com/networkupstools/nut/blob/ master/docs/history.txt">	<reference anchor="githist" target="https://github.com/networkupstools/nut/blob/ master/docs/history.txt">
	<front>	<front>

	<title>GitHub Network UPS Tools code repository, project history</title>	<title>The Network UPS Tools repository, project history</title>
	<author>	<author></author>
	</author>	<date month="July" year="2022"/>
	</front>	</front>
	</reference>	</reference>


	<reference anchor="stunnel" target="https://www.stunnel.org/">	<reference anchor="stunnel" target="https://www.stunnel.org/">
	<front>	<front>

	<title>Stunnel proxy adds TLS encryption functionality to existing clients and s	<title>Stunnel</title>
	ervers</title>	<author></author>
	<author initials="Michal" surname="Trojnara" fullname="Michal Trojnara">
	</author>
	</front>	</front>
	</reference>	</reference>


		<reference anchor="C2ndEd" target="">
		<front>
		<title>The C Programming Language</title>
		<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>	</references>


	<section anchor="Annex1">	<section anchor="Annex1">
	<name>Variables</name>	<name>Variables</name>
	<t>The UPS variables represent the abstracted state of the UPS unit.	<t>The UPS variables represent the abstracted state of the UPS unit.
	Certain variables represent not only the state of some hardware	Certain variables represent not only the state of some hardware

	feature, but also provide tunable values and instant commands,	feature but also provide tunable values and Instant Commands;
	see <xref target="IC"></xref>. The full set of variables is recorded	see <xref target="IC"></xref>. The full set of variables is recorded
	in the <xref target="gitvars">reference document for variable	in the <xref target="gitvars">reference document for variable
	names</xref>.	names</xref>.
	</t>	</t>
	<t>The number of variables used in a given deployment depends on the	<t>The number of variables used in a given deployment depends on the

	sophistication of the UPS product: this annex shows a typical example	sophistication of the UPS product; this annex shows a typical example
	of the subset of variables used for a reasonably complete "consumer	of the subset of variables used for a reasonably complete "consumer
	grade" UPS. The NUT Project maintains a <xref target="Library">large	grade" UPS. The NUT Project maintains a <xref target="Library">large
	library of the variable subsets</xref> used by different UPS models.	library of the variable subsets</xref> used by different UPS models.
	</t>	</t>
	<t>Note that successive versions of a given product may add or delete	<t>Note that successive versions of a given product may add or delete

	features causing a change in the subset of variables used. An example	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"	is the removal of <tt>ups.delay.start</tt> from a "consumer grade"
	UPS. The manufacturer reserves the feature for the "professional"	UPS. The manufacturer reserves the feature for the "professional"
	product.	product.
	</t>	</t>
	<t>An implementation of a Management Daemon acting as a utility program may	<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	provide a listing of the variables available for a given product, for

	example utility program <tt>upsc</tt> as included in the NUT package,	example, utility program <tt>upsc</tt>, as included in the NUT package;
	see <xref target="util"></xref>.	see <xref target="util"></xref>.
	</t>	</t>
	<t>The following sections illustrate the use of variables by taking	<t>The following sections illustrate the use of variables by taking

	the values associated with a typical product. The example is a 1600Va	the values associated with a typical product. The example is a 1600 Va
	1000W UPS.	1000 W UPS.
	</t>	</t>
	<section>	<section>
	<name>Typical UPS Variables</name>	<name>Typical UPS Variables</name>
	<table anchor="typvar">	<table anchor="typvar">

	<name>Typical UPS Variables	<name>Typical UPS Variables</name>
	</name>
	<thead>	<thead>
	<tr>	<tr>

	<th align="center">Variable </th>	<th align="center">Variable</th>
	<th align="center">Typical value </th>	<th align="center">Typical Value</th>
	<th align="center">Default description	<th align="center">Default Description</th>
	</th>
	</tr>	</tr>
	</thead>	</thead>
	<tbody>	<tbody>
	<tr>	<tr>

	<td><tt>battery.charge</tt> </td>	<td><tt>battery.charge</tt></td>
	<td><tt>100</tt> </td>	<td><tt>100</tt></td>
	<td>"Battery charge (percent of full)"	<td>"Battery charge (percent of full)"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>battery.charge.low</tt> </td>	<td><tt>battery.charge.low</tt></td>
	<td><tt>20</tt> </td>	<td><tt>20</tt></td>
	<td>"Remaining battery level when UPS switches to LB (percent)"	<td>"Remaining battery level when UPS switches to LB (percent)"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>battery.runtime</tt> </td>	<td><tt>battery.runtime</tt></td>
	<td><tt>1481</tt> </td>	<td><tt>1481</tt></td>
	<td>"Battery runtime (seconds)"	<td>"Battery runtime (seconds)"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>battery.type</tt> </td>	<td><tt>battery.type</tt></td>
	<td><tt>PbAc</tt> </td>	<td><tt>PbAc</tt></td>
	<td>"Battery chemistry"	<td>"Battery chemistry"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>device.mfr</tt> </td>	<td><tt>device.mfr</tt></td>
	<td><tt>Example Mfg</tt> </td>	<td><tt>Example Mfg</tt></td>
	<td>""	<td>""</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>device.model</tt> </td>	<td><tt>device.model</tt></td>
	<td><tt>Economy 1600</tt> </td>	<td><tt>Economy 1600</tt></td>
	<td>""	<td>""</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>device.serial</tt> </td>	<td><tt>device.serial</tt></td>
	<td><tt>1234567890</tt> </td>	<td><tt>1234567890</tt></td>
	<td>""	<td>""</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>device.type</tt> </td>	<td><tt>device.type</tt></td>
	<td><tt>ups</tt> </td>	<td><tt>ups</tt></td>
	<td>""	<td>""</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>driver.name</tt> </td>	<td><tt>driver.name</tt></td>
	<td><tt>usbhid-ups</tt> </td>	<td><tt>usbhid-ups</tt></td>
	<td>"Driver name"	<td>"Driver name"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>driver.parameter.lowbatt</tt> </td>	<td><tt>driver.parameter.lowbatt</tt></td>
	<td><tt>37</tt> </td>	<td><tt>37</tt></td>
	<td>"Driver parameter: <name>"	<td>"Driver parameter: <name>"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>driver.parameter.offdelay</tt> </td>	<td><tt>driver.parameter.offdelay</tt></td>
	<td><tt>30</tt> </td>	<td><tt>30</tt></td>
	<td>"Driver parameter: <name>"	<td>"Driver parameter: <name>"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>driver.parameter.ondelay</tt> </td>	<td><tt>driver.parameter.ondelay</tt></td>
	<td><tt>40</tt> </td>	<td><tt>40</tt></td>
	<td>"Driver parameter: <name>"	<td>"Driver parameter: <name>"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>driver.parameter.pollfreq</tt> </td>	<td><tt>driver.parameter.pollfreq</tt></td>
	<td><tt>30</tt> </td>	<td><tt>30</tt></td>
	<td>"Driver parameter: <name>"	<td>"Driver parameter: <name>"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>driver.parameter.pollinterval</tt> </td>	<td><tt>driver.parameter.pollinterval</tt></td>
	<td><tt>2</tt> </td>	<td><tt>2</tt></td>
	<td>"Driver parameter: <name>"	<td>"Driver parameter: <name>"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>driver.parameter.port</tt> </td>	<td><tt>driver.parameter.port</tt></td>
	<td><tt>auto</tt> </td>	<td><tt>auto</tt></td>
	<td>"Driver parameter: <name>"	<td>"Driver parameter: <name>"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>driver.parameter.synchronous</tt> </td>	<td><tt>driver.parameter.synchronous</tt></td>
	<td><tt>no</tt> </td>	<td><tt>no</tt></td>
	<td>"Driver parameter: <name>"	<td>"Driver parameter: <name>"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>driver.parameter.vendorid</tt> </td>	<td><tt>driver.parameter.vendorid</tt></td>
	<td><tt>0999</tt> </td>	<td><tt>0999</tt></td>
	<td>"Driver parameter: <name>"	<td>"Driver parameter: <name>"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>driver.version</tt> </td>	<td><tt>driver.version</tt></td>
	<td><tt>2.8.0</tt> </td>	<td><tt>2.8.0</tt></td>
	<td>"Driver version - NUT release"	<td>"Driver version - NUT release"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>driver.version.data</tt> </td>	<td><tt>driver.version.data</tt></td>
	<td><tt>HID 1.39</tt> </td>	<td><tt>HID 1.39</tt></td>
	<td>""	<td>""</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>driver.version.internal</tt> </td>	<td><tt>driver.version.internal</tt></td>
	<td><tt>0.41</tt> </td>	<td><tt>0.41</tt></td>
	<td>"Internal driver version"	<td>"Internal driver version"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>input.transfer.high</tt> </td>	<td><tt>input.transfer.high</tt></td>
	<td><tt>264</tt> </td>	<td><tt>264</tt></td>
	<td>"High voltage transfer point (V)"	<td>"High voltage transfer point (V)"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>input.transfer.low</tt> </td>	<td><tt>input.transfer.low</tt></td>
	<td><tt>184</tt> </td>	<td><tt>184</tt></td>
	<td>"Low voltage transfer point (V)"	<td>"Low voltage transfer point (V)"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>outlet.1.desc</tt> </td>	<td><tt>outlet.1.desc</tt></td>
	<td><tt>PowerShare Outlet 1</tt> </td>	<td><tt>PowerShare Outlet 1</tt></td>
	<td>"Outlet description"	<td>"Outlet description"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>outlet.1.id</tt> </td>	<td><tt>outlet.1.id</tt></td>
	<td><tt>2</tt> </td>	<td><tt>2</tt></td>
	<td>"Outlet system identifier"	<td>"Outlet system identifier"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>outlet.1.status</tt> </td>	<td><tt>outlet.1.status</tt></td>
	<td><tt>on</tt> </td>	<td><tt>on</tt></td>
	<td>"Outlet switch status"	<td>"Outlet switch status"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>outlet.1.switchable</tt> </td>	<td><tt>outlet.1.switchable</tt></td>
	<td><tt>no</tt> </td>	<td><tt>no</tt></td>
	<td>"Outlet switch ability"	<td>"Outlet switch ability"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>outlet.2.desc</tt> </td>	<td><tt>outlet.2.desc</tt></td>
	<td><tt>PowerShare Outlet 2</tt> </td>	<td><tt>PowerShare Outlet 2</tt></td>
	<td>"Outlet description"	<td>"Outlet description"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>outlet.2.id</tt> </td>	<td><tt>outlet.2.id</tt></td>
	<td><tt>3</tt> </td>	<td><tt>3</tt></td>
	<td>"Outlet system identifier"	<td>"Outlet system identifier"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>outlet.2.status</tt> </td>	<td><tt>outlet.2.status</tt></td>
	<td><tt>on</tt> </td>	<td><tt>on</tt></td>
	<td>"Outlet switch status"	<td>"Outlet switch status"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>outlet.2.switchable</tt> </td>	<td><tt>outlet.2.switchable</tt></td>
	<td><tt>no</tt> </td>	<td><tt>no</tt></td>
	<td>"Outlet switch ability"	<td>"Outlet switch ability"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>outlet.desc</tt> </td>	<td><tt>outlet.desc</tt></td>
	<td><tt>Main Outlet</tt> </td>	<td><tt>Main Outlet</tt></td>
	<td>"Outlet description"	<td>"Outlet description"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>outlet.id</tt> </td>	<td><tt>outlet.id</tt></td>
	<td><tt>1</tt> </td>	<td><tt>1</tt></td>
	<td>"Outlet system identifier"	<td>"Outlet system identifier"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>outlet.power</tt> </td>	<td><tt>outlet.power</tt></td>
	<td><tt>25</tt> </td>	<td><tt>25</tt></td>
	<td>""	<td>""</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>outlet.switchable</tt> </td>	<td><tt>outlet.switchable</tt></td>
	<td><tt>no</tt> </td>	<td><tt>no</tt></td>
	<td>"Outlet switch ability"	<td>"Outlet switch ability"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>output.frequency.nominal</tt> </td>	<td><tt>output.frequency.nominal</tt></td>
	<td><tt>50</tt> </td>	<td><tt>50</tt></td>
	<td>"Nominal output frequency (Hz)"	<td>"Nominal output frequency (Hz)"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>output.voltage</tt> </td>	<td><tt>output.voltage</tt></td>
	<td><tt>230.0</tt> </td>	<td><tt>230.0</tt></td>
	<td>"Output voltage (V)"	<td>"Output voltage (V)"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>output.voltage.nominal</tt> </td>	<td><tt>output.voltage.nominal</tt></td>
	<td><tt>230</tt> </td>	<td><tt>230</tt></td>
	<td>"Nominal output voltage (V)"	<td>"Nominal output voltage (V)"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>ups.beeper.status</tt> </td>	<td><tt>ups.beeper.status</tt></td>
	<td><tt>enabled</tt> </td>	<td><tt>enabled</tt></td>
	<td>"UPS beeper status"	<td>"UPS beeper status"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>ups.delay.shutdown</tt> </td>	<td><tt>ups.delay.shutdown</tt></td>
	<td><tt>20</tt> </td>	<td><tt>20</tt></td>
	<td>"Interval to wait after shutdown with delay command (seconds)"	<td>"Interval to wait after shutdown with delay command (seconds)"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>ups.delay.start</tt> </td>	<td><tt>ups.delay.start</tt></td>
	<td><tt>30</tt> </td>	<td><tt>30</tt></td>
	<td>"Interval to wait before (re)starting the load (seconds)"	<td>"Interval to wait before (re)starting the load (seconds)"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>ups.firmware</tt> </td>	<td><tt>ups.firmware</tt></td>
	<td><tt>02</tt> </td>	<td><tt>02</tt></td>
	<td>"UPS firmware"	<td>"UPS firmware"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>ups.load</tt> </td>	<td><tt>ups.load</tt></td>
	<td><tt>20</tt> </td>	<td><tt>20</tt></td>
	<td>"Load on UPS (percent of full)"	<td>"Load on UPS (percent of full)"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>ups.mfr</tt> </td>	<td><tt>ups.mfr</tt></td>
	<td><tt>Example Mfg</tt> </td>	<td><tt>Example Mfg</tt></td>
	<td>"UPS manufacturer"	<td>"UPS manufacturer"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>ups.model</tt> </td>	<td><tt>ups.model</tt></td>
	<td><tt>Economy 1600</tt> </td>	<td><tt>Economy 1600</tt></td>
	<td>"UPS model"	<td>"UPS model"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>ups.power.nominal</tt> </td>	<td><tt>ups.power.nominal</tt></td>
	<td><tt>1600</tt> </td>	<td><tt>1600</tt></td>
	<td>"UPS power rating (VA)"	<td>"UPS power rating (VA)"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>ups.productid</tt> </td>	<td><tt>ups.productid</tt></td>
	<td><tt>ffff</tt> </td>	<td><tt>ffff</tt></td>
	<td>"Product ID for USB devices"	<td>"Product ID for USB devices"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>
	<td><tt>ups.serial</tt> </td>	<td><tt>ups.serial</tt> </td>
	<td><tt>000000000</tt> </td>	<td><tt>000000000</tt> </td>

	<td>"UPS serial number"	<td>"UPS serial number"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>ups.status</tt> </td>	<td><tt>ups.status</tt></td>
	<td><tt>OL</tt> </td>	<td><tt>OL</tt></td>
	<td>"UPS status"	<td>"UPS status"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>ups.temperature</tt> </td>	<td><tt>ups.temperature</tt></td>
	<td><tt>27</tt> </td>	<td><tt>27</tt></td>
	<td>"UPS temperature (C)"	<td>"UPS temperature (C)"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>ups.timer.shutdown</tt> </td>	<td><tt>ups.timer.shutdown</tt></td>
	<td><tt>0</tt> </td>	<td><tt>0</tt></td>
	<td>"Time before the load will be shutdown (seconds)"	<td>"Time before the load will be shutdown (seconds)"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>ups.timer.start</tt> </td>	<td><tt>ups.timer.start</tt></td>
	<td><tt>0</tt> </td>	<td><tt>0</tt></td>
	<td>"Time before the load will be started (seconds)"	<td>"Time before the load will be started (seconds)"</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>ups.vendorid</tt> </td>	<td><tt>ups.vendorid</tt></td>
	<td><tt>0999</tt> </td>	<td><tt>0999</tt></td>
	<td>"Vendor ID for USB devices"	<td>"Vendor ID for USB devices"</td>
	</td>
	</tr>	</tr>
	</tbody>	</tbody>
	</table>	</table>
	</section>	</section>
	<section anchor="rw">	<section anchor="rw">
	<name>Typical UPS Readable and Writable Variables</name>	<name>Typical UPS Readable and Writable Variables</name>

	<t>Some of the features of a UPS are represented by variables which	<t>Some of the features of a UPS are represented by variables that
	may be tuned by the user. The following variables are typical of such	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	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	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	listing of the variables available, as well as acting on them, for

	example utility program <tt>upsrw</tt> as included in the NUT package,	example, utility program <tt>upsrw</tt>, as included in the NUT package;
	see <xref target="util"></xref>.	see <xref target="util"></xref>.
	</t>	</t>
	<table>	<table>

	<name>Typical readable and writable UPS Variables	<name>Typical Readable and Writable UPS Variables</name>
	</name>
	<thead>	<thead>
	<tr>	<tr>

	<th align="center">Variable </th>	<th align="center">Variable</th>
	<th align="center">Typical value	<th align="center">Typical Value</th>
	</th>	<th align="center">Default Description Provided as Response to the Command <tt>G
	<th align="center">Default description provided as response to the command <tt>G	ET DESC</tt></th>
	ET DESC</tt>
	</th>
	</tr>	</tr>
	</thead>	</thead>
	<tbody>	<tbody>
	<tr>	<tr>

	<td><tt>battery.charge.low</tt> </td>	<td><tt>battery.charge.low</tt></td>
	<td><tt>20</tt> </td>	<td><tt>20</tt></td>
	<td><tt>"Remaining battery level when UPS switches to LB (percent)"</tt>	<td><tt>"Remaining battery level when UPS switches to LB (percent)"</tt></td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>input.transfer.high</tt> </td>	<td><tt>input.transfer.high</tt></td>
	<td><tt>264</tt> </td>	<td><tt>264</tt></td>
	<td><tt>"High voltage transfer point (V)"</tt>	<td><tt>"High voltage transfer point (V)"</tt></td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>input.transfer.low</tt> </td>	<td><tt>input.transfer.low</tt></td>
	<td><tt>184</tt> </td>	<td><tt>184</tt></td>
	<td><tt>"Low voltage transfer point (V)"</tt>	<td><tt>"Low voltage transfer point (V)"</tt></td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>outlet.1.desc</tt> </td>	<td><tt>outlet.1.desc</tt></td>
	<td><tt>PowerShare Outlet 1</tt> </td>	<td><tt>PowerShare Outlet 1</tt></td>
	<td><tt>"Outlet description"</tt>	<td><tt>"Outlet description"</tt></td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>outlet.2.desc</tt> </td>	<td><tt>outlet.2.desc</tt></td>
	<td><tt>PowerShare Outlet 2</tt> </td>	<td><tt>PowerShare Outlet 2</tt></td>
	<td><tt>"Outlet description"</tt>	<td><tt>"Outlet description"</tt></td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>outlet.2.switchable</tt> </td>	<td><tt>outlet.2.switchable</tt></td>
	<td><tt>no</tt> </td>	<td><tt>no</tt></td>
	<td><tt>"Outlet switch ability"</tt>	<td><tt>"Outlet switch ability"</tt></td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>outlet.desc</tt> </td>	<td><tt>outlet.desc</tt></td>
	<td><tt>Main Outlet</tt> </td>	<td><tt>Main Outlet</tt></td>
	<td><tt>"Outlet description"</tt>	<td><tt>"Outlet description"</tt></td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>outlet.power</tt> </td>	<td><tt>outlet.power</tt></td>
	<td><tt>25</tt> </td>	<td><tt>25</tt></td>
	<td><tt>"Description unavailable"</tt>	<td><tt>"Description unavailable"</tt></td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>output.voltage.nominal</tt> </td>	<td><tt>output.voltage.nominal</tt></td>
	<td><tt>230</tt> </td>	<td><tt>230</tt></td>
	<td><tt>"Nominal output voltage (V)"</tt>	<td><tt>"Nominal output voltage (V)"</tt></td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>ups.delay.shutdown</tt> </td>	<td><tt>ups.delay.shutdown</tt></td>
	<td><tt>20</tt> </td>	<td><tt>20</tt></td>
	<td><tt>"Interval to wait after shutdown with delay command (seconds)"</tt>	<td><tt>"Interval to wait after shutdown with delay command (seconds)"</tt></td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>ups.delay.start</tt> </td>	<td><tt>ups.delay.start</tt></td>
	<td><tt>30</tt> </td>	<td><tt>30</tt></td>
	<td><tt>"Interval to wait before (re)starting the load (seconds)"</tt>	<td><tt>"Interval to wait before (re)starting the load (seconds)"</tt></td>
	</td>
	</tr>	</tr>
	</tbody>	</tbody>
	</table>	</table>
	</section>	</section>
	<section anchor="instcmdexamples">	<section anchor="instcmdexamples">
	<name>Typical UPS Instant Commands</name>	<name>Typical UPS Instant Commands</name>

	<t>Some of the features of a UPS are actions known as instant	<t>Some of the features of a UPS are actions known as Instant
	commands, see <xref target="IC"></xref>, which may be ordered by the	Commands (see <xref target="IC"></xref>), which may be ordered by the
	user. The following variables represent such instant commands. The	user. The following variables represent such Instant Commands. The
	precise list depends on the model of UPS. An implementation of a	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	Management Daemon acting as a utility program may provide a listing of the

	variables available, as well as acting on them, for example utility	variables available, as well as acting on them, for example, utility
	program <tt>upscmd</tt> as included in the NUT package,	program <tt>upscmd</tt>, as included in the NUT package;
	see <xref target="util"></xref>.	see <xref target="util"></xref>.
	</t>	</t>
	<table>	<table>

	<name>Typical Instant Commands	<name>Typical Instant Commands</name>
	</name>
	<thead>	<thead>
	<tr>	<tr>

	<th align="center">Command </th>	<th align="center">Command</th>
	<th align="center">Meaning	<th align="center">Meaning</th>
	</th>
	</tr>	</tr>
	</thead>	</thead>
	<tbody>	<tbody>
	<tr>	<tr>

	<td><tt>beeper.disable</tt> </td>	<td><tt>beeper.disable</tt></td>
	<td>Disable the UPS beeper	<td>Disable the UPS beeper</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>beeper.enable</tt> </td>	<td><tt>beeper.enable</tt></td>
	<td>Enable the UPS beeper	<td>Enable the UPS beeper</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>beeper.mute</tt> </td>	<td><tt>beeper.mute</tt></td>
	<td>Temporarily mute the UPS beeper	<td>Temporarily mute the UPS beeper</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>load.off</tt> </td>	<td><tt>load.off</tt></td>
	<td>Turn off the load immediately	<td>Turn off the load immediately</td>
	</td>
	</tr>	</tr>
	<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>Turn off the load with a delay (seconds)</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>load.on</tt> </td>	<td><tt>load.on</tt></td>
	<td>Turn on the load immediately	<td>Turn on the load immediately</td>
	</td>
	</tr>	</tr>
	<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>Turn on the load with a delay (seconds)</td>
	</td>
	</tr>	</tr>
	<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>Turn off the load and return when power is back</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>shutdown.stayoff</tt> </td>	<td><tt>shutdown.stayoff</tt></td>
	<td>Turn off the load and remain off	<td>Turn off the load and remain off</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>shutdown.stop</tt> </td>	<td><tt>shutdown.stop</tt></td>
	<td>Stop a shutdown in progress	<td>Stop a shutdown in progress</td>
	</td>
	</tr>	</tr>
	</tbody>	</tbody>
	</table>	</table>
	</section>	</section>
	</section>	</section>
	<section anchor="shutdownstory">	<section anchor="shutdownstory">
	<name>The Shutdown Story for System and UPS</name>	<name>The Shutdown Story for System and UPS</name>
	<t>This appendix provides background material helpful for a general	<t>This appendix provides background material helpful for a general
	understanding of the relation between system and UPS. It does not	understanding of the relation between system and UPS. It does not
	define any feature of the command-response protocol.	define any feature of the command-response protocol.
	</t>	</t>
	<t>We consider the steps involved in the shutdown and restart of a	<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	long-running unattended server protected by a single UPS. The Management Daemon
	runs in the server as shown in <xref target="fig.story"></xref>.	runs in the server as shown in <xref target="fig.story"></xref>.
	</t>	</t>
	<figure anchor="fig.story">	<figure anchor="fig.story">

	<name>Long-running unattended server	<name>Long-Running Unattended Server</name>
	</name>	<artwork align="center" type="ascii-art">
	<artwork align="center"> ,------------------SERVER------------------,	,------------------SERVER------------------,
	\| \| \|	\| \| \|
	,-----, \| UPS <-Commands UPS \|	,-----, \| UPS <-Commands UPS \|
	\| UPS \|---\| Attachment \| Management \|	\| UPS \|---\| Attachment \| Management \|
	\| \|===\| Daemon Responses-> Daemon \|	\| \|===\| Daemon Responses-> Daemon \|
	/-----\ '--------------------'---------------------'	/-----\ '--------------------'---------------------'
	Internal	Internal

	loopback</artwork>	loopback
		</artwork>
	</figure>	</figure>

	<ol indent="adaptive">	<ol spacing="normal" indent="adaptive">
	<li anchor="start"><em>The public power supply is on</em> -- The system runs	<li anchor="start"><em>The public power supply is on.</em> The system runs
	normally. Every 5 seconds, variable <tt>ups.status</tt> reports	normally. Every 5 seconds, variable <tt>ups.status</tt> reports

	<tt>OL</tt>. -- <em>Days, weeks, months go by...</em>	<tt>OL</tt>. <em>Days, weeks, months go by...</em></li>
	</li>	<li><em>Winter storm. Tree falls on power lines. The public power supply fails.<
	<li><em>Winter storm. Tree falls on power lines. The public power supply fails</	/em>
	em>	The server remains operational, running on the UPS battery. The
	Management Daemon polls the Attachment Daemon, and detects status change <tt>OL<	Management Daemon polls the Attachment Daemon and detects status change <tt>OL</
	/tt>-><tt>OB</tt>.	tt>-><tt>OB</tt>.</li>
	</li>	<li>The Management Daemon logs warning messages. The server is still operational
	<li>The Management Daemon logs warning messages. The server is still operational	,
	running on the UPS battery. -- <em>Minutes go by...</em>	running on the UPS battery. <em>Minutes go by...</em></li>
	</li>
	<li>The battery discharges below the level specified by variable	<li>The battery discharges below the level specified by variable
	<tt>battery.charge.low</tt>. The server remains operational, but the	<tt>battery.charge.low</tt>. The server remains operational, but the

	UPS battery will not last much longer. The Management Daemon polls the Attachme	UPS battery will not last much longer. The Management Daemon polls the Attachme
	nt Daemon, and	nt Daemon and
	detects status change <tt>OB</tt>-><tt>OB</tt>+<tt>LB</tt>.	detects status change <tt>OB</tt>-><tt>OB</tt>+<tt>LB</tt>.</li>
	</li>	<li>The Management Daemon logs the low battery event.</li>
	<li>The Management Daemon logs the low battery event.
	</li>
	<li anchor="setFSD">The Management Daemon decides to call for a system shutdown.	<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 to	It sets status <tt>FSD</tt> in the Attachment Daemon to call on any Secondaries to
	shut down and waits for command <tt>GET NUMATTACH</tt> to report one	shut down and waits for command <tt>GET NUMATTACH</tt> to report one

	single attachment, i.e. the Primary itself. The Management Daemon then issues th	single attachment, i.e., the Primary itself. The Management Daemon then issues t
	e	he
	system shutdown command for itself.	system shutdown command for itself.</li>
	</li>
	<li anchor="upsdrvctl">The operating system's shutdown process takes	<li anchor="upsdrvctl">The operating system's shutdown process takes

	over. During the system shutdown, a NUT Project specific script or an	over. During the system shutdown, a specific script to the NUT Project or an
	equivalent systemd service unit runs the command <tt>upsdrvctl	equivalent system service unit runs the command <tt>upsdrvctl
	shutdown</tt>. This tells the UPS that it is to shut down N seconds	shutdown</tt>. This tells the UPS that it is to shut down N seconds
	later where the default is N=20.	later where the default is N=20.
	Note that the "shutdown" of a UPS removes power	Note that the "shutdown" of a UPS removes power

	from the outlet sockets, but may not turn the UPS off completely.	from the outlet sockets but may not turn the UPS off completely.
	A delayed shutdown is sometimes audible, and the characteristic	A delayed shutdown is sometimes audible, and the characteristic

	beeping of the UPS stops.	beeping of the UPS stops.</li>
	</li>
	<li>The system shuts down and powers down, hopefully before the N=20	<li>The system shuts down and powers down, hopefully before the N=20

	seconds have passed.	seconds have passed.</li>
	</li>
	<li anchor="UPSshutdown"><t><em>N seconds after	<li anchor="UPSshutdown"><t><em>N seconds after

	item <xref target="upsdrvctl" format="counter"></xref></em> -- The UPS shuts	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	down, i.e., it turns off its outlet sockets when N=20 seconds have
	passed. With some UPS units, there is an audible "clunk".	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 UP S unit	</t><t>What if the public power supply returns before the UPS shuts down? The UP S unit
	should be able to wait a configurable time with default 30 seconds.	should be able to wait a configurable time with default 30 seconds.
	These two timers start from the moment the UPS receives the	These two timers start from the moment the UPS receives the

	<tt>upsdrvctl shutdown</tt> command. -- <em>Minutes, hours, days go	<tt>upsdrvctl shutdown</tt> command. <em>Minutes, hours, days go
	by...</em>	by...</em></t></li>
	</t></li>	<li><em>Some time later, maybe much later, the public power supply returns.</em>
	<li><em>Some time later, maybe much later, the public power supply returns</em>	The UPS reconnects its outlets to send power to the protected system.</li>
	--
	The UPS reconnects it's outlets to send power to the protected system.
	</li>
	<li anchor="UPSrestart">The system BIOS option "Restore power on AC	<li anchor="UPSrestart">The system BIOS option "Restore power on AC
	return" or "Restore to previous state" has hopefully been selected and	return" or "Restore to previous state" has hopefully been selected and
	the system powers up. The bootstrap process of the operating system	the system powers up. The bootstrap process of the operating system

	begins.	begins.</li>
	</li>
	<li>The operating system starts the Attachment Daemon and the Management Daemon. The Attachment Daemon	<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	starts the Driver and scans the UPS. The UPS status becomes

	<tt>OL</tt>+<tt>LB</tt>.	<tt>OL</tt>+<tt>LB</tt>.</li>
	</li>
	<li>After some time, the battery charges above	<li>After some time, the battery charges above

	the <tt>battery.charge.low</tt> threshold and the Attachment Daemon declares the	the <tt>battery.charge.low</tt> threshold, and the Attachment Daemon declares th e
	status change <tt>OL</tt>+<tt>LB</tt>-><tt>OL</tt>. We are now back in the sa me	status change <tt>OL</tt>+<tt>LB</tt>-><tt>OL</tt>. We are now back in the sa me

	situation as <xref target="start" format="counter"></xref> above.	situation as item <xref target="start" format="counter"></xref> above.</li>
	</li>
	</ol>	</ol>
	</section>	</section>
	<section anchor="differences">	<section anchor="differences">
	<name>Technical Terms: Historical Differences</name>	<name>Technical Terms: Historical Differences</name>
	<t>This appendix lists the major differences between the technical	<t>This appendix lists the major differences between the technical
	terms used in NUT software release 2.8.0 and documented in this text,	terms used in NUT software release 2.8.0 and documented in this text,

	and those used in previous version 2.7.4 of the NUT Project.	as well as those used in previous version 2.7.4 of the NUT Project.
	</t>	</t>
	<table>	<table>

		<name>Technical Terms: Historical Differences</name>
	<thead>	<thead>
	<tr>	<tr>

	<th>Term in previous<br/>release NUT 2.7.4	<th>Term in Previous<br/>Release NUT 2.7.4</th>
	</th>	<th>Term in this Document,<br/>Release NUT 2.8.0</th>
	<th>Term in this document,<br/>release NUT 2.8.0
	</th>
	<th>Reference	<th>Reference
	</th>	</th>
	</tr>	</tr>
	</thead>	</thead>
	<tbody>	<tbody>
	<tr>	<tr>

	<td>ALREADY-LOGGED-IN </td>	<td>ALREADY-LOGGED-IN</td>
	<td>ALREADY-ATTACHED </td>	<td>ALREADY-ATTACHED</td>
	<td><xref target="errors"></xref>	<td><xref target="errors"></xref></td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td>ALREADY-SSL-MODE </td>	<td>ALREADY-SSL-MODE</td>
	<td>TLS-ALREADY-ENABLED </td>	<td>TLS-ALREADY-ENABLED</td>
	<td><xref target="errors"></xref>	<td><xref target="errors"></xref></td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>LOGIN</tt> </td>	<td><tt>LOGIN</tt></td>
	<td><tt>ATTACH</tt> </td>	<td><tt>ATTACH</tt></td>
	<td><xref target="attach"></xref>	<td><xref target="attach"></xref></td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>LOGOUT</tt> </td>	<td><tt>LOGOUT</tt></td>
	<td><tt>DETACH</tt> </td>	<td><tt>DETACH</tt></td>
	<td><xref target="detach"></xref>	<td><xref target="detach"></xref></td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td>Master </td>	<td>Master</td>
	<td>Primary </td>	<td>Primary</td>
	<td><xref target="prim"></xref>	<td><xref target="prim"></xref></td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>NETVER</tt> </td>	<td><tt>NETVER</tt></td>
	<td><tt>PROTVER</tt> </td>	<td><tt>PROTVER</tt></td>
	<td><xref target="protver"></xref>	<td><xref target="protver"></xref></td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>NUMLOGINS</tt> </td>	<td><tt>NUMLOGINS</tt></td>
	<td><tt>NUMATTACH</tt> </td>	<td><tt>NUMATTACH</tt></td>
	<td><xref target="numattach"></xref>	<td><xref target="numattach"></xref></td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td>Slave </td>	<td>Slave</td>
	<td>Secondary </td>	<td>Secondary</td>
	<td><xref target="sec"></xref>	<td><xref target="sec"></xref></td>
	</td>
	</tr>	</tr>
	</tbody>	</tbody>
	</table>	</table>
	</section>	</section>
	<section anchor="AppendixEavesdropping">	<section anchor="AppendixEavesdropping">

	<name>Security Defences in Release 2.7.4</name>	<name>Security Defenses in Release 2.7.4</name>
	<t>Previous NUT version 2.7.4 did not provide support for TLS	<t>Previous NUT version 2.7.4 did not provide support for TLS
	1.3 <xref target="RFC8446"></xref>. The following subsections	1.3 <xref target="RFC8446"></xref>. The following subsections
	describe mitigating techniques.	describe mitigating techniques.
	</t>	</t>
	<section anchor="Shims">	<section anchor="Shims">
	<name>Shims</name>	<name>Shims</name>
	<t>Previous version 2.7.4 of NUT did not support TLS	<t>Previous version 2.7.4 of NUT did not support TLS
	1.3 <xref target="RFC8446"></xref>. Where such protection is needed	1.3 <xref target="RFC8446"></xref>. Where such protection is needed
	for version 2.7.4, a possible technique introduces shims between the	for version 2.7.4, a possible technique introduces shims between the

	Attachment Daemon and the network, and between the network and the Management Da	Attachment Daemon and the network and between the network and the Management Dae
	emon as shown	mon, as shown
	in figure <xref target="fig.shim" format="counter"></xref>. These shims	in <xref target="fig.shim"/>. These shims
	provide TLS 1.3 support, thus allowing the Attachment Daemon and Management Daem on to continue	provide TLS 1.3 support, thus allowing the Attachment Daemon and Management Daem on to continue

	temporarily without native TLS. The technique has been successfully	temporarily without having TLS implementations themselves. The technique has be en successfully
	tested.	tested.
	</t>	</t>
	<figure anchor="fig.shim">	<figure anchor="fig.shim">

	<name>Shims provide TLS support during migration	<name>Shims Provide TLS Support During Migration
	</name>	</name>

	<artwork align="center"> TLS shim listens TLS shim listens	<artwork align="center" type="ascii-art">
		TLS shim listens TLS shim listens
	on port TBD1/TCP on port 3493/TCP	on port TBD1/TCP on port 3493/TCP
	,-----,------------,----, ,----,--------------,	,-----,------------,----, ,----,--------------,
	\| UPS - Attachment \|TLS \| <-STARTTLS \| TLS\| Management \|	\| UPS - Attachment \|TLS \| <-STARTTLS \| TLS\| Management \|
	\| \| Daemon \|shim\| OK--> \|shim\| Daemon \|	\| \| Daemon \|shim\| OK--> \|shim\| Daemon \|
	/-----'------------'----\ '----'--------------'	/-----'------------'----\ '----'--------------'
	Listens on	Listens on

	port 3493/TCP</artwork>	port 3493/TCP
		</artwork>
	</figure>	</figure>
	<section>	<section>
	<name>Attachment Daemon Shim</name>	<name>Attachment Daemon Shim</name>
	<t>The shim in front of the Attachment Daemon listens to incoming traffic on por t	<t>The shim in front of the Attachment Daemon listens to incoming traffic on por t

	TBD1/TCP. When it receives the command <tt>STARTTLS</tt> it	TBD1/TCP. When it receives the command <tt>STARTTLS</tt>, it:
	</t>	</t>
	<ol spacing="compact" indent="adaptive">	<ol spacing="compact" indent="adaptive">

	<li>Returns <tt>OK</tt> to the client and sets up TLS encapsulation.	<li>returns <tt>OK</tt> to the client and sets up TLS encapsulation.</li>
	</li>	<li>does not send <tt>STARTTLS</tt> to the Attachment Daemon port 3493/TCP.</li>
	<li>Does not send <tt>STARTTLS</tt> to the Attachment Daemon port 3493/TCP.
	</li>
	</ol>	</ol>
	<t>All other commands and responses are passed through.	<t>All other commands and responses are passed through.
	</t>	</t>
	<t>Note: Port TBD1/TCP is not specified by this text.	<t>Note: Port TBD1/TCP is not specified by this text.
	</t>	</t>
	</section>	</section>
	<section>	<section>
	<name>Management Daemon Shim</name>	<name>Management Daemon Shim</name>
	<t>The shim in front of the Management Daemon listens for incoming traffic on po rt	<t>The shim in front of the Management Daemon listens for incoming traffic on po rt

	3493/TCP. When it receives the command <tt>STARTTLS</tt> it	3493/TCP. When it receives the command <tt>STARTTLS</tt>, it:
	</t>	</t>
	<ol spacing="compact" indent="adaptive">	<ol spacing="compact" indent="adaptive">

	<li>Returns <tt>FEATURE-NOT-CONFIGURED</tt> to the client.	<li>returns <tt>FEATURE-NOT-CONFIGURED</tt> to the client.</li>
	</li>	<li>sends <tt>STARTTLS</tt> to the Attachment Daemon on port TBD1/TCP.</li>
	<li>Sends <tt>STARTTLS</tt> to the Attachment Daemon on port TBD1/TCP.
	</li>
	</ol>	</ol>
	<t>All other commands and responses are passed through.	<t>All other commands and responses are passed through.
	</t>	</t>
	</section>	</section>
	</section>	</section>
	<section anchor="TLStunnel">	<section anchor="TLStunnel">
	<name>TLS Tunnels</name>	<name>TLS Tunnels</name>
	<t>Another technique is the use of <xref target="RFC8446">TLS	<t>Another technique is the use of <xref target="RFC8446">TLS

	tunnels</xref>, using a software such as	tunnels</xref>, using a software, such as
	stunnel <xref target="stunnel"></xref> which adds OpenSSL-based TLS	stunnel <xref target="stunnel"></xref>, which adds OpenSSL-based TLS
	support without modifying the Attachment Daemon or Management Daemon. The NUT P roject has no	support without modifying the Attachment Daemon or Management Daemon. The NUT P roject has no
	procedure to enforce this on sites.	procedure to enforce this on sites.
	</t>	</t>
	</section>	</section>
	<section anchor="VPN">	<section anchor="VPN">
	<name>VPN</name>	<name>VPN</name>
	<t>A further option to secure communications is very similar	<t>A further option to secure communications is very similar

	to <xref target="RFC8446">TLS tunnelling</xref> and consists of	to <xref target="RFC8446">TLS tunneling</xref> and consists of
	routing the NUT traffic through a Virtual Private Network, VPN.	routing the NUT traffic through a Virtual Private Network (VPN).
	</t>	</t>
	</section>	</section>
	<section anchor="VLAN">	<section anchor="VLAN">
	<name>VLAN</name>	<name>VLAN</name>
	<t>A fourth option is to isolate the UPS management traffic at the	<t>A fourth option is to isolate the UPS management traffic at the

	network switching level using a Virtual LAN, VLAN technique.	network switching level using a Virtual LAN (VLAN) technique.
	</t>	</t>
	<figure anchor="fig.VLAN">	<figure anchor="fig.VLAN">

	<name>UPS Management Protocol runs over its own VLAN	<name>UPS Management Protocol Runs over Its Own VLAN
	</name>	</name>

	<artwork align="center"> ,-------------, ,-------------,	<artwork align="center" type="ascii-art">
		,-------------, ,-------------,
	,-----, \| Attachment \| \| Management \|	,-----, \| Attachment \| \| Management \|
	\| UPS \|---\| Daemon \| \| Daemon \|	\| UPS \|---\| Daemon \| \| Daemon \|
	\| \| \|-------------\| UPS \|-------------\|	\| \| \|-------------\| UPS \|-------------\|
	\| \|===\| \| Management \| UPS \|	\| \|===\| \| Management \| UPS \|
	/-----\ \| Protected \|~~~~~~~~~~~~~~~\| Management \|	/-----\ \| Protected \|~~~~~~~~~~~~~~~\| Management \|
	\| Server \| VLAN \| Client \|	\| Server \| VLAN \| Client \|
	\| \| '-------------'	\| \| '-------------'
	'-------------'	'-------------'
	Production \| VLAN	Production \| VLAN
	,---\|-------,	,---\|-------,
	,-----------,\|	,-----------,\|
	,-----------,\|'	,-----------,\|'
	\| Clients \|'	\| Clients \|'

	'-----------'</artwork>	'-----------'
		</artwork>
	</figure>	</figure>

	<t>In <xref target="fig.VLAN"></xref> there are two VLANS: The main	<t>In <xref target="fig.VLAN"></xref>, there are two VLANS: the main
	traffic between the protected server and its clients uses the	traffic between the protected server and its clients using the
	production VLAN. The UPS management traffic between the Attachment and	production VLAN. The UPS management traffic between the Attachment and
	Management Daemons uses the UPS management VLAN marked as	Management Daemons uses the UPS management VLAN marked as
	~~~~~~~~~~~~~.	~~~~~~~~~~~~~.
	</t>	</t>
	</section>	</section>
	</section>	</section>
	<section anchor="adsec">	<section anchor="adsec">
	<name>Administrative Security</name>	<name>Administrative Security</name>

	<t>Administrative commands such as <tt>FSD</tt>, <tt>INSTCMD</tt>	<t>Administrative commands, such as <tt>FSD</tt>, <tt>INSTCMD</tt>,
	and <tt>SET</tt> are powerful and can have a deep effect on system	and <tt>SET</tt>, are powerful and can have a deep effect on system
	integrity, For example, the command <tt>FSD</tt> is involved in	integrity. For example, the command <tt>FSD</tt> is involved in
	mission critical system shutdown decisions. Access to them needs to	mission-critical system shutdown decisions. Access to them needs to
	be managed and restricted. This clause presents the current practice.	be managed and restricted. This section presents the current practice.
	</t>	</t>
	<section anchor="adminuser">	<section anchor="adminuser">
	<name>Management of Administrative Users</name>	<name>Management of Administrative Users</name>

	<t>The Attachment Daemon maintains a file (currently <tt>upsd.users</tt>) defini ng	<t>The Attachment Daemon maintains a file (currently <tt>upsd.users</tt>) that d efines
	each administrative user. Note that these users are independent of	each administrative user. Note that these users are independent of
	those recorded in file <tt>/etc/passwd</tt>. Each administrative user	those recorded in file <tt>/etc/passwd</tt>. Each administrative user
	gets its own section in file <tt>upsd.users</tt>. The declarations in	gets its own section in file <tt>upsd.users</tt>. The declarations in

	that section set the parameters which define that user's	that section set the parameters that define that user's
	privileges. The section begins with the name of the user enclosed in	privileges. The section begins with the name of the user enclosed in

	square brackets, OPENING BRACKET [	square brackets, opening bracket ([)
	and CLOSING BRACKET ], and continues until	and closing bracket (]), and continues until
	the next user name in brackets or EOF.	the next username in brackets or EOF.
	</t>	</t>

	<t>For example the following file declares two administrative users	<t>For example, the following file declares two administrative users,
	<tt>admin</tt> and <tt>pfy</tt>:</t>	<tt>admin</tt> and <tt>pfy</tt>:</t>

	<sourcecode> [admin]	<sourcecode name="" type="shell">
		[admin]
	password = sekret	password = sekret
	upsmon master	upsmon master
	actions = SET	actions = SET
	instcmds = ALL	instcmds = ALL
	[pfy]	[pfy]
	password = sekret	password = sekret
	instcmds = test.panel.start	instcmds = test.panel.start
	instcmds = test.panel.stop	instcmds = test.panel.stop
	</sourcecode>	</sourcecode>

	<t>Within each section the administrative user declarations are:	<t>Within each section, the administrative user declarations are:
	</t>	</t>
	<table>	<table>

	<name>Administrative user declarations	<name>Administrative User Declarations</name>
	</name>
	<thead>	<thead>
	<tr>	<tr>
	<th align="center">Declaration </th>	<th align="center">Declaration </th>

	<th align="center">Meaning	<th align="center">Meaning</th>
	</th>
	</tr>	</tr>
	</thead>	</thead>
	<tbody>	<tbody>
	<tr>	<tr>

	<td><tt>actions</tt>	<td><tt>actions</tt></td>
	</td>
	<td><t>Allow the user to do certain things in the Attachment Daemon. To	<td><t>Allow the user to do certain things in the Attachment Daemon. To
	specify multiple actions, use multiple instances of the	specify multiple actions, use multiple instances of the

	declaration. Valid actions are:	declaration. Valid actions are:</t>
	</t><ul>	<ul spacing="normal">
	<li><tt>FSD</tt> Set the "Forced Shutdown" flag for this UPS.	<li><tt>FSD</tt> Set the "Forced Shutdown" flag for this UPS.

	See <xref target="FSD"></xref>.	See <xref target="FSD"></xref>.</li>
	</li>	<li><tt>SET</tt> Change the value of a UPS variable. See <xref target="set"></x
	<li><tt>SET</tt> Change the value of a UPS variable. See <xref target="set"></x	ref>.</li>
	ref>.	</ul></td></tr>
	</li>
	</ul></td>
	</tr>
	<tr>	<tr>

	<td><tt>instcmds</tt>	<td><tt>instcmds</tt></td>
	</td>	<td>Let a user initiate specific Instant Commands. See
	<td>Let a user initiate specific instant commands. See
	<xref target="instcmd"></xref>. Use value <tt>ALL</tt> to grant all com mands	<xref target="instcmd"></xref>. Use value <tt>ALL</tt> to grant all com mands
	automatically. To specify multiple commands, use multiple	automatically. To specify multiple commands, use multiple
	instances of the instcmds field. For the full list of what a	instances of the instcmds field. For the full list of what a
	given UPS supports, use client <tt>upscmd -l</tt> supplied by	given UPS supports, use client <tt>upscmd -l</tt> supplied by
	the NUT Project. The <tt>LIST CMD</tt> command is issued within	the NUT Project. The <tt>LIST CMD</tt> command is issued within

	the client <tt>upscmd</tt>.	the client <tt>upscmd</tt>.</td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>password</tt>	<td><tt>password</tt></td>
	</td>
	<td>Set the password for this user. <em>Your password should be	<td>Set the password for this user. <em>Your password should be

	more secure than the examples shown.</em>	more secure than the examples shown.</em></td>
	</td>
	</tr>	</tr>
	<tr>	<tr>

	<td><tt>upsmon</tt>	<td><tt>upsmon</tt></td>
	</td>
	<td>Add the necessary actions for a Management Daemon to process a system	<td>Add the necessary actions for a Management Daemon to process a system

	shutdown. In current practice the value is still <tt>master</tt>	shutdown. In current practice, the value is still <tt>master</tt>
	or <tt>slave</tt>. Note that there is no	or <tt>slave</tt>. Note that there is no

	EQUALS =.	EQUALS =.</td>
	</td>
	</tr>	</tr>
	</tbody>	</tbody>
	</table>	</table>
	</section>	</section>
	<section anchor="adsecclient">	<section anchor="adsecclient">
	<name>An Administrative User of a Client Management Daemon</name>	<name>An Administrative User of a Client Management Daemon</name>
	<t>The following examples show the current security practices for	<t>The following examples show the current security practices for

	administrative users of a client Management Daemon They also illustrate the	administrative users of a client Management Daemon. They also illustrate the
	command pair <tt>USERNAME</tt> and <tt>PASSWORD</tt>. See <xref target="usernam	command pair <tt>USERNAME</tt> and <tt>PASSWORD</tt>. See Sections <xref target
	e"></xref>	="username" format="counter"></xref>
	and <xref target="password"></xref>.	and <xref target="password" format="counter"></xref>.
	</t>	</t>
	<section>	<section>
	<name>An Administrative User Logs into a Short Session</name>	<name>An Administrative User Logs into a Short Session</name>
	<t>In this simple example of current practice, the system	<t>In this simple example of current practice, the system
	administrator sets the battery level at which an Attachment Daemon will raise th e	administrator sets the battery level at which an Attachment Daemon will raise th e
	status <tt>LB</tt>, represented by variable <tt>battery.charge.low</tt>, to	status <tt>LB</tt>, represented by variable <tt>battery.charge.low</tt>, to
	35% of full charge. A system administrator types the following command	35% of full charge. A system administrator types the following command
	to call the client <tt>upsrw</tt> supplied by the	to call the client <tt>upsrw</tt> supplied by the
	NUT Project.</t>	NUT Project.</t>

	<sourcecode>upsrw -s battery.charge.low=35 -u admin -p sekret UPS-1@example.com	<sourcecode name="" type="shell">
		upsrw -s battery.charge.low=35 -u admin -p sekret UPS-1@example.com
	</sourcecode>	</sourcecode>
	<t>Option <tt>-s</tt> specifies the variable and the value,	<t>Option <tt>-s</tt> specifies the variable and the value,
	option <tt>-u</tt> specifies the <tt>USERNAME</tt>, option <tt>-p</tt>	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	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	UPS. The <tt>USERNAME</tt> and <tt>PASSWORD</tt> commands are issued

	within the client <tt>upsrw</tt> and the Session is of short duration.	within the client <tt>upsrw</tt>, and the session is of short duration.
	</t>	</t>
	<t>Note: Your password should be stronger than the example shown.	<t>Note: Your password should be stronger than the example shown.
	</t>	</t>
	</section>	</section>
	<section anchor="longsess">	<section anchor="longsess">
	<name>An Administrative User Logs into a Long Session</name>	<name>An Administrative User Logs into a Long Session</name>
	<t>In this second example of current practice, the long-running	<t>In this second example of current practice, the long-running

	Management Daemon <tt>upsmon</tt> which is responsible for initiating system	Management Daemon <tt>upsmon</tt>, which is responsible for initiating system
	shutdowns and which is provided by the NUT Project issues commands	shutdowns and which is provided by the NUT Project, issues commands
	<tt>USERNAME</tt> and <tt>PASSWORD</tt> when it starts up. The data	<tt>USERNAME</tt> and <tt>PASSWORD</tt> when it starts up. The data
	values needed for the	values needed for the
	<tt>USERNAME</tt> and <tt>PASSWORD</tt> commands are provided by a	<tt>USERNAME</tt> and <tt>PASSWORD</tt> commands are provided by a

	configuration file <tt>upsmon.conf</tt> which contains the	configuration file <tt>upsmon.conf</tt>, which contains the
	line</t>	line:</t>
	<sourcecode>MONITOR UPS-1@example.com 1 admin sekret master	<sourcecode name="" type="shell">
		MONITOR UPS-1@example.com 1 admin sekret master
	</sourcecode>	</sourcecode>
	<t> This says that the UPS to be monitored	<t> This says that the UPS to be monitored

	is <tt>UPS-1@example.com</tt>, it provides 1 single power supply, the	is <tt>UPS-1@example.com</tt>. It provides 1 single power supply. The
	administrative user is <tt>admin</tt> with	administrative user is <tt>admin</tt> with
	password <tt>sekret</tt>. The Management Daemon acts as a Primary, although	password <tt>sekret</tt>. The Management Daemon acts as a Primary, although
	current practice still uses the former term <tt>master</tt>.	current practice still uses the former term <tt>master</tt>.
	</t>	</t>
	<t>The <tt>USERNAME</tt> and <tt>PASSWORD</tt> commands are contained	<t>The <tt>USERNAME</tt> and <tt>PASSWORD</tt> commands are contained

	within the client <tt>upsmon</tt> and the Session is of long duration.	within the client <tt>upsmon</tt>, and the session is of long duration.
	</t>	</t>
	</section>	</section>
	</section>	</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 th
		e
		XML that was used as input to xml2rfc <xref target="RFC7991"/>, which then creat
		ed
		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>	</back>
	</rfc>	</rfc>

End of changes. 641 change blocks.
	1940 lines changed or deleted	1481 lines changed or added
This html diff was produced by rfcdiff 1.48.