[Nut-upsuser] NUT command LOGIN is not a login

Roger Price
Thu, 24 Jun 2021 12:48:38 -0000

During the ISE review of the proposed RFC, the IETF editor has asked for
clarification of the LOGIN command, since he, like most people, assumes that
"LOGIN" means something like "login to a shell".

The Developer Guide Chapter 9
https://networkupstools.org/docs/developer-guide.chunked/ar01s09.html
"Network
Protocol Information" says

  9.9. LOGIN

  LOGIN <upsname>    Response: OK (upon success) or various errors

  Note This requires "upsmon slave" or "upsmon master" in
upsd.users

  Use this to log the fact that a system is drawing power from this UPS. The
  upsmon master will wait until the count of attached systems reaches 1 -
itself.
  This allows the slaves to shut down first.

  Note You probably shouldn?t send this command unless you are upsmon, or a
  upsmon replacement.

  9.4 GET NUMLOGINS <upsname>
  Response: NUMLOGINS <UPSNAME> <VALUE>

  where <value> is the number of clients which have done LOGIN for this
UPS. This
  is used by the master upsmon to determine how many clients are still connected
  when starting the shutdown process.

I propose saying:

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

LOGIN is not the conventional user access to a shell. In a configuration such as
Figure 4 in which a UPS protects more than one system, the Primary (2.8)
Management Daemon (2.6), upsmon, needs to know how many Secondaries (2.9) are
currently "active", i.e. powered by the UPS, either on wall or battery
power.
The Attachment Daemon (2.1), upsd, supports this by keeping a count of all the
"active" systems powered by a UPS. The count is initialised, one
secondary at a
time by the LOGIN command, which should be understood as "count this
secondary
as active". LOGIN is one of a trio of commands for Secondary (2.9)
counting:
command LOGOUT (4.2.7) decrements the count and a Management Daemon (2.6),
upsmon, may read the count at any time using command NUMLOGINS (4.2.2.3).

The LOGIN command is also sent to the Attachment Daemon (2.1), upsd, for the
Primary (2.8) so during normal, fully protected operation, the count is 1 (the
Primary (2.8)) + the number of Secondaries (2.9). During a full system shutdown,
the count drops as each Secondary (2.9) Management Daemon (2.6), upsmon,
executes command LOGOUT (4.2.7) during its own shutdown. When the count drops to
1, only the Primary (2.8) is "active" and it knows that all the
Secondaries
(2.9) have shut down.

Is that correct?

Comment: had the command LOGIN been called SETACTIVE, with the upsmon flag
ST_LOGIN changed to ST_ACTIVE, and NUMLOGINS changed to NUMACTIVE this mechanism
would probably be easier to understand.  LOGOUT might be NOTACTIVE.

   Current   Proposed
   LOGIN     SETACTIVE
   LOGOUT    NOTACTIVE
   NUMLOGINS NUMACTIVE
   ST_LOGIN  ST_ACTIVE

Roger