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

[Roger Price]

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