Re: [auth48] AUTH48: RFC-to-be 9271 <draft-rprice-ups-management-protocol-15> for your review

[Roger Price <[e-mail]>]

On Fri, 22 Jul 2022, [e-mail] wrote:

> Approving for publication

> To approve your RFC for publication, please reply to this email
> stating that you approve this RFC for publication.  Please use REPLY
> ALL, as all the parties CCed on this message need to see your
> approval.

I approve the RFC-to-be 9271 for publication when subject to the
changes listed in this review response.

Roger Price, La Gaude, France, 2022-07-28, [e-mail]

---------------------------------------------------------------------
> While reviewing this document during AUTH48, please resolve (as
> necessary) the following questions, which are also in the XML file.

1) <!--[rfced] We note that "NUT Project" and "NUT Software Project"
were both used in this document. As "NUT Project" is more common,
we have made the updates shown below. Please review.

Original:
1.1.1.  NUT Software Project

    The primary goal of the NUT (Network UPS Tools) Software Project
    [NUT] is to provide support for Power Devices, such as
    Uninterruptible Power Supplies.

Current:
1.1.1.  NUT Project

    The primary goal of the Network UPS Tools (NUT) Project [NUT] is
    to provide support for power devices, such as UPSs.
-->

Resolution: I agree to your updates.

---------------------------------------------------------------------
2) <!--[rfced] Section 2.2: Because it may not be clear to the reader
whether the first or second edition is meant, please provide reference
information for "K&R C".

Original:
    The NUT Project has implemented an Attachment Daemon as program upsd
    and a set of hardware specific drivers, all written in K&R C.
-->

Resolution: Add a reference to the second edition as follows:

Change in section 2.2 3rd paragraph:
    The NUT Project has implemented an Attachment Daemon as program upsd
    and a set of hardware specific Drivers, all written in K&R C [C2ndEd].

New in section 9.2 Informative References:

[C2ndEd] Brian W. Kernighan, Dennis M. Ritchie, "The C Programming
Language", 2nd edition, 1988, Prentice Hall Software Series, ISBN
0-13-110362-8.

---------------------------------------------------------------------
3) <!-- [rfced] We see that the <aside> element is used in Sections 3
and 4.2.  Please review whether any of the notes in other sections of
this document should be in the <aside> element. It is defined as "a
container for content that is semantically less important or
tangential to the content that surrounds it"
(https://xml2rfc.tools.ietf.org/xml2rfc-doc.html#name-aside-2).  -->

Resolution: I should be more consistent.  My historical notes should also
be tagged as <aside>.  I propose the following changes to the XML markup:

Section 2.7. Primary

OLD:
<t>Note: Historically, the Primary was known as the "Master".</t>
NEW:
<aside>
<t>Note: Historically, the Primary was known as the "Master".</t>
</aside>

Section 2.7. Secondary

OLD:
<t>Note: Historically, the Secondary was known as the "Slave".</t>
NEW:
<aside>
<t>Note: Historically, the Secondary was known as the "Slave".</t>
</aside>

Section 4.2.1 ATTACH

OLD:
<t>Note: Historically, this command was known as <tt>LOGIN</tt>.
However, because <tt>LOGIN</tt> was not the conventional user access to a
shell or program, the name was changed to avoid confusion.</t>
NEW:
<aside>
<t>Note: Historically, this command was known as <tt>LOGIN</tt>.
However, because <tt>LOGIN</tt> was not the conventional user access to a
shell or program, the name was changed to avoid confusion.</t>
</aside>

Section 4.2.2 DETACH

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

Section 4.2.4.3 GET ATTACH

OLD:
<t>Note: Historically, this subcommand was known
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
confusion.</t>
NEW:
<aside>
<t>Note: Historically, this subcommand was known
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
confusion.</t>
</aside>

Section 4.2.5 HELP

OLD:
<t>Note: Historically, this command also returned <tt>LOGIN</tt>
and <tt>LOGOUT</tt>.  Because <tt>LOGIN</tt> was not the conventional
user access to a shell or program, the command names were changed
to <tt>ATTACH</tt> and <tt>DETACH</tt> to avoid confusion.</t>
NEW:
<aside>
<t>Note: Historically, this command also returned <tt>LOGIN</tt>
and <tt>LOGOUT</tt>.  Because <tt>LOGIN</tt> was not the conventional
user access to a shell or program, the command names were changed
to <tt>ATTACH</tt> and <tt>DETACH</tt> to avoid confusion.</t>
</aside>

Section 4.2.9 PRIMARY

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

Section 4.3.2 Error Responses

OLD:
<td><tt>ALREADY-ATTACHED</tt></td>
<td><t>The client has already sent a
successful <tt>ATTACH</tt> command for a given UPS and can't do it again.</t>
<t>Note: Historically, this error response was <tt>ALREADY-LOGGED-IN</tt>.</t></td>
NEW:
<td><tt>ALREADY-ATTACHED</tt></td>
<td><t>The client has already sent a
successful <tt>ATTACH</tt> command for a given UPS and can't do it again.</t></td>

OLD:
</table>
</section>
NEW:
</table>
<aside>
<t>Note: Historically, the error response <tt>ALREADY-ATTACHED</tt> was known as
<tt>ALREADY-LOGGED-IN</tt>.</t>
</aside>
</section>


---------------------------------------------------------------------
4) <!-- [rfced] Please review the "type" attribute of each sourcecode
element in the XML file to ensure correctness. If the current list of
preferred values for "type"
(https://www.rfc-editor.org/materials/sourcecode-types.txt) does not
contain an applicable type, then feel free to let us know. Also, it is
acceptable to leave the "type" attribute not set.  -->

Resolution: I propose adding type="shell" attribute values as follows:

Section 4.2.5 HELP

   <sourcecode name="" type=""> becomes <sourcecode name="" type="shell">

Section 4.2.7.1 LIST CLIENT

   <sourcecode name="" type=""> becomes <sourcecode name="" type="shell"> twice

Section 4.2.7.2 LIST CMD

   <sourcecode name="" type=""> becomes <sourcecode name="" type="shell"> twice

Section 4.2.7.3 LIST ENUM

   <sourcecode name="" type=""> becomes <sourcecode name="" type="shell"> twice

Section 4.2.7.4 LIST RANGE

   <sourcecode name="" type=""> becomes <sourcecode name="" type="shell"> twice

Section 4.2.7.5 LIST RW

   <sourcecode name="" type=""> becomes <sourcecode name="" type="shell"> twice

Section 4.2.7.6 LIST UPS

   <sourcecode name="" type=""> becomes <sourcecode name="" type="shell"> twice

Section 4.2.7.7 LIST VAR

   <sourcecode name="" type=""> becomes <sourcecode name="" type="shell"> twice

Section 4.2.10 PROTVER

   <sourcecode name="" type=""> becomes <sourcecode name="" type="shell">

Section 4.2.14 VER

   <sourcecode name="" type=""> becomes <sourcecode name="" type="shell">

Section 4.3.2 Error Responses

   <sourcecode name="" type=""> becomes <sourcecode name="" type="shell">

Appendix E. Administrative Security

   <sourcecode name="" type=""> becomes <sourcecode name="" type="shell">

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

   <sourcecode name="" type=""> becomes <sourcecode name="" type="shell">

Appendix E.2.2 An Administrative User Logs into a Long Session

   <sourcecode name="" type=""> becomes <sourcecode name="" type="shell">

GLOBAL: In addition, please make the following GLOBAL change:

OLD:
<artwork align="center">
NEW:
<artwork align="center" type="ascii-art">


---------------------------------------------------------------------
5) <!-- [rfced] Section 4.2.12.1: The sentence below seems to imply
that the servers don't trust the CAs. Is this the case? Or can "for
some value of trust" be removed?

Current:
    The servers do not know
    who their clients will be, so they entrust the management of a Public
    Key Infrastructure (PKI) to Certificate Authorities that they trust,
    for some value of trust.   -->

Resolution: If you find it clearer without the "for some value of
trust", then let's remove those words.

IETF Style: In the 3rd paragraph of 4.2.12.1 you changed the sentence

    "This situation is totally different to the World Wide Web."

to

    "This situation is totally different than the World Wide Web."

The preposition "than" seems ill at ease to me, but if that's the IETF
style, then no problem.

---------------------------------------------------------------------
6) <!-- [rfced] Section 4.4: ABNF

a) We adjusted the spacing of some of the comments and one definition
so that the ABNF fit within our column limits. Please let us know if
any updates are necessary:

Original:
                                 ; E.g. HB:[e-mail]:3493
Current:
                                 ; E.g.,
                                 ; HB:[e-mail]:3493

b) When we attempted to validate the ABNF using
<https://tools.ietf.org/tools/bap/abnf.cgi>, we received the following
error. Please let us know how we may fix this.

stdin(87:0): error: Rule username was already defined on line 28 of stdin
28:                                 ; E.g., HB:[e-mail]:3493
29:    username = ups               ; E.g., Power-Dept.6
30:    varname = 1*LC *62( DOT 1*(DIGIT / LC) )
31:                                 ; E.g., outlet.1.status
-->

a) Resolution: Ok for me.

b) Resolution: I propose changing the names used in the two rules
       password = "PASSWORD" SP *63VCHAR
       username = "USERNAME" SP username
which become
       session-password = "PASSWORD" SP *63VCHAR
       session-username = "USERNAME" SP username
This requires the following changes:

Section 4.2.8. PASSWORD

OLD:
<t>ABNF: See variable <tt>password</tt> in <xref target="fig.ABNF"></xref>.
NEW:
<t>ABNF: See variable <tt>session-password</tt> in <xref target="fig.ABNF"></xref>.

Section 4.2.13. USERNAME

OLD:
<t>ABNF: See variable <tt>username</tt> in <xref target="fig.ABNF"></xref>.
NEW:
<t>ABNF: See variable <tt>session-username</tt> in <xref target="fig.ABNF"></xref>.

---------------------------------------------------------------------
7) <!-- [rfced] Section 6.2.1: The following sentence seems to be missing something:

Current:

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

Perhaps (splitting the sentence into two and highlighting that the
expiration times should be specified):

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

-->

Agreed, the split sentence is much better.

---------------------------------------------------------------------
8) <!--[rfced] Per the suggestion of RFC 7942 ("Improving Awareness
of Running Code: The Implementation Status Section"), may we remove
the Implementation Status section of this document?
-->

RFC 7942 says "I-Ds published on the Independent Stream are explicitly
out of scope.", but if you prefer to remove the Implementation Status
section, then let's do it.  I would like to keep 8.2 Recommended
Minimum Support with three subsections 8.2.1, 8.2.2 and 8.2.3.  This
could be done either by making them a new section 8 Recommended
Minimum Support as follows:

OLD: 8.2 Recommended Minimum Support
NEW: 8 Recommended Minimum Support

OLD: 8.2.1 Desktop PC Variables
NEW: 8.2 Desktop PC Variables

OLD: 8.2.2 Unattended Servers and Additional Variables
NEW: 8.2 Unattended Servers and Additional Variables

OLD: 8.2.3 Commands and Other Technical Terms
NEW: 8.2 Commands and Other Technical Terms

or alternatively, if you prefer to remove section 8 entirely, then 8.2
(8.2.1 + 8.2.2 + 8.2.3) could be moved to Appendix A to become
Appendix A.4 as follows:

OLD: 8.2 Recommended Minimum Support
NEW: A.4 Recommended Minimum Support

OLD: 8.2.1 Desktop PC Variables
NEW: A.4.1 Desktop PC Variables

OLD: 8.2.2 Unattended Servers and Additional Variables
NEW: A.4.2 Unattended Servers and Additional Variables

OLD: 8.2.3 Commands and Other Technical Terms
NEW: A.4.3 Commands and Other Technical Terms


---------------------------------------------------------------------
9) <!--[rfced] The following URL appears to be to a personal webpage. If
possible, please provide a more stable URL.

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

A more permanent reference might be the OpenJade Project which
maintains sgmlnorm, so I propose the following resolution:

OLD: <http://www.jclark.com/sp/sgmlnorm.htm>
NEW: Maintained by the OpenJade Project
<http://openjade.sourceforge.net/> and included in many distributions
<https://linux.die.net/man/1/sgmlnorm>.

---------------------------------------------------------------------
10) <!-- [rfced] The following reference is not cited in the text.
Please let us know where it should be cited or if this reference can
be deleted from the References section.

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

-->

Please delete this reference.

---------------------------------------------------------------------
11) <!-- [rfced] Table 9 does not have a title. Please review, and
provide the title if desired.  -->

Proposed change in Appendix C:
OLD:
<table>
<thead>
NEW:
<table>
<name>Technical Terms: Historical Differences</name>
<thead>

---------------------------------------------------------------------
12) <!-- [rfced] Acknowledgments: As the source for this document is
now in RFCXML, how may the following paragraph be updated?

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

Perhaps:
    Earlier drafts of this document were prepared using an SGML DTD [SGML]
    and an XML meta-DTD defined by HyTime Annex A [HyTimeA].  Unlike
    XML, SGML offers markup minimization, and the earlier drafts took
    advantage of this.  The osgmlnorm [sgmlnorm] program generated the
    XML that was used as input to xml2rfc [RFC7991], which then created
    the document's current source. The editor acknowledges the help received
    from Carsten Bormann and Julian Reschke in the xml2rfc mailing list.
-->

Excellent!  I was concerned that you might remove all reference to
SGML now that it is no longer fashionable.  I'm glad you kept it.


---------------------------------------------------------------------
13) <!-- [rfced] Formatting: May we update the formatting to use just
one type of text styling?

Current (Section 4.2.1, for example):

    ...the Primary Management Daemon needs to
    know how many Secondaries are currently "_active_"

Perhaps (using <em> tags only):

    ...the Primary Management Daemon needs to
    know how many Secondaries are currently _active_

or (using quotes only)

    ...the Primary Management Daemon needs to
    know how many Secondaries are currently "active"


Current (Appendix B. Note that the double dash cannot be represented in XML comments):

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

Perhaps (removing the dashes):

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

or (removing the <em> tags):

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

-->

Agreed.  One type of text styling is sufficient.  Perhaps its better
to use <em> since the markup will allow rendering in different styles
in different circumstances.

---------------------------------------------------------------------
14) <!--[rfced] Terminology:

a) We've made the following terms lowercase because typically they are
presented in all caps only when following Unicode hex values (e.g.,
"U+0022 QUOTATION MARK"). Please let us know if any updates are
necessary:

    QUOTATION MARK / quotation mark
    REVERSE SLANT / reverse slant
    LINE FEED / line feed
    SPACE / space
    HYPHEN / hyphen

b) The following terms were used inconsistently. We've chosen the latter form. Please let us know if any updates are necessary:

    instant command / Instant Command
    sub command / subcommand
    US-ASCII / ASCII

c) The following terms are used inconsistently. Please let us know how we can make these consistent:

    Driver (23 instances) / driver (24 instances)
    Event (21 instances) / event (17 instances)
    Session (13 instances) / session (3 instances)

-->

  a) OK for lower case.  I was deliberately following Unicode usage,
  but if you prefer lower case, that's OK.

  b) instant command -> Instant Command  OK

     sub command -> subcommand OK

     US-ASCII -> ASCII ????? IANA says that US-ASCII is the "Preferred
     MIME Name" and as such is the first entry at
     https://www.iana.org/assignments/character-sets/character-sets.xhtml
     so I propose to continue using US-ASCII.

  c) Driver: I distinguish between Driver as a component of NUT and
     driver as a generic piece of software but I was not consistent.
     Here are all the instances of driver in your file rfc9271.xml that
     need changing.  The other instances do not need to change.  The
     line numbers start at 1.

    189 : and a set of hardware-specific drivers, all written in K&amp;R C.    [Change drivers -> Drivers]
    199 : driver for each hardware interface type it supports.  Although this  [Change driver -> Driver]
    200 : document considers the driver to be part of the Attachment Daemon,   [Change driver -> Driver]
    217 : is passed to the driver and                                          [Change driver -> Driver]
    263 : one system, the computer running the driver is known as the Primary. [Change driver -> Driver]
   1159 : design of the UPS or its driver.                                     [Change driver -> Driver]
   1461 : Driver for the UPS, but that driver isn't providing regular updates  [Change driver -> Driver]
   1474 : connected. This usually means that the driver is not running or,     [Change driver -> Driver]
   1495 : driver.</td>                                                         [Change driver -> Driver]
   2384 : <li>June 1999 Code rewrite with a UPS driver <tt>smartups</tt>, an   [Change driver -> Driver]
   2388 : <li>June 2001 Common core for multiple drivers.</li>                 [Change drivers -> Drivers]

     Event: Again I was not consistent.  Here are all the instances of
     Event in your file rfc9271.xml that need changing.  The other
     instances do not need to change.  The line numbers start at 1.

   209 : <t>A UPS Event occurs in the Management Daemon when a change in       [Change Event -> event]
   475 : response to an Event, which is taken as the basis for Management      [Change Event -> event]
   609 : <t>Note: The symbol "<tt>FSD</tt>" is also used for an Event.         [Change Event -> event]
  1900 : <t>A Management Daemon detects the occurrence of a UPS Event from     [Change Event -> event]
  1979 : <td>UPS communicating<br/>(Event <tt>COMMOK</tt>)</td>                [Change Event -> event]
  1997 : <td>System shutdown<br/>(Events <tt>FSD</tt>, <tt>SHUTDOWN</tt>)      [Change Events -> events]
  2006 : <xref target="BBB" format="counter"></xref> (Event <tt>LOWBATT</tt>)  [Change Event -> event]
  2015 : (Events <tt>COMMBAD</tt>, <tt>NOCOMM</tt>)</td>                       [Change Events -> events]
  2033 : <td>Receiving power<br/>(Event <tt>ONLINE</tt>)</td>                  [Change Event -> event]
  2037 : <td>Power lost<br/>(Event <tt>ONBATT</tt>)</td>                       [Change Event -> event]
  2051 : <td>Replace battery<br/>(Event <tt>REPLBATT</tt>)</td>                [Change Event -> event]
  2107 : (Event <tt>NOCOMM</tt>), and if the last known <tt>OL</tt>/           [Change Event -> event]

     Session: Once again I was not consistent.  Here are all the
     instances of Session in your file rfc9271.xml that need changing.
     The other instances do not need to change.  The line numbers start
     at 1.

  1086 : to specify the password required to enter a Session with the          [Change Session -> session]
  1106 : starts up and opens a Session with the Attachment Daemon, it lays     [Change Session -> session]
  1252 : command <tt>PASSWORD</tt> to open a Session with the Attachment       [Change Session -> session]
  1445 : in the same Session.</td>                                             [Change Session -> session]
  1451 : within the same Session.</td>                                         [Change Session -> session]
  3479 : within the client <tt>upsrw</tt>, and the Session is of short         [Change Session -> session]
  3504 : within the client <tt>upsmon</tt>, and the Session is of long         [Change Session -> session]


---------------------------------------------------------------------
15) <!-- [rfced] Please review the "Inclusive Language" portion of the
online Style Guide
<https://www.rfc-editor.org/styleguide/part2/#inclusive_language> and
let us know if any changes are needed.

For example, please consider whether the following should be updated: 
native, man in the middle, whitespace
-->

I read the reference in the style guide, but didn't find the specific
example needed.

  1) native TLS: one instance, section D.1.  I don't know of any new
term which replaces "native TLS" but if there is one then let's use
it.

  2) man in the middle: Sections 6.1 and 6.3.2.  I propose keeping this
term since it is a technical term taken from IEC 62351-1.

  3) whitespace: two instances to mean some combination of space and
tab, section 4.1.  Is there some new word which is generally
understood?  If so, let's use it, otherwise let's stay with the
wellknown term.

---------------------------------------------------------------------
---------------------------------------------------------------------

ISE Eliot Lear has called for more levity.
https://www.ietf.org/blog/new-ise-eliot-lear/
  Q IETF Blog: What are your publication priorities?
  A I cannot stress enough how much I value levity.

So here in a general spirit of levity is a limerick about a UPS:

  Our servers will still be alright
  If power drops off in the night.
    That 10 year old pack
    of battery back
  up will easily...(communication lost)

And another about the IETF process:

  The IETF takes the line
  That agreement be sought every time
    But if code's working good
    As the doc says it should
  Then rougher consensus is fine.

But whether or not such levity is acceptable in an Informational RFC,
I do not know.

---------------------------------------------------------------------
>> Thank you.
>> RFC Editor/ap/jm

My thanks to you for such a detailed review.

------------------End of reply to AUTH48 comments--------------------
---------------------------------------------------------------------