Clarify the value of POWERDOWNFLAG in upsmon -h and document that it must be set

[jimklimov]

Part of findings from investigation for issue #321

[jimklimov]

Example "screenshots" from upsmon -h:

• Original status:

~/nut$ ./clients/upsmon -h
Network UPS Tools upsmon 2.8.1-994-gbff0c6bc9
Monitors UPS servers and may initiate shutdown if necessary.

usage: /home/jim/nut/clients/.libs/upsmon [OPTIONS]

  -c <cmd>      send command to running process
                commands:
                 - fsd: shutdown all primary-mode UPSes (use with caution)
                 - reload: reread configuration
                 - stop: stop monitoring and exit
  -P <pid>      send the signal above to specified PID (bypassing PID file)
  -D            raise debugging level (and stay foreground by default)
  -F            stay foregrounded even if no debugging is enabled
  -B            stay backgrounded even if debugging is bumped
  -V            display the version of this software
  -h            display this help
  -K            checks POWERDOWNFLAG, sets exit code to 0 if set
  -p            always run privileged (disable privileged parent)
  -u <user>     run child as user <user> (ignored when using -p)
  -4            IPv4 only
  -6            IPv6 only

• With added logging of which config file is used (before hushing that):

Network UPS Tools upsmon 2.8.1-994-gbff0c6bc9
   0.000000     [D1] loadconfig: Reloading /usr/local/ups/etc/upsmon.conf
   0.000045     UPS: x (monitoring only)
   0.000079     Applying debug level 6 from original command line arguments
Monitors UPS servers and may initiate shutdown if necessary.
...

• With hushing of most loadconfig() messages (when debug level is negative) and a warning about absent POWERDOWNFLAG line in upsmon.conf:

Network UPS Tools upsmon 2.8.1-994-gbff0c6bc9
No POWERDOWNFLAG value was configured in /usr/local/ups/etc/upsmon.conf!
Should be a path to file that is normally writeable for root user, and remains at least readable late in shutdown after all unmounting completes.
Monitors UPS servers and may initiate shutdown if necessary.

usage: /home/jim/nut/clients/.libs/upsmon [OPTIONS]

  -c <cmd>      send command to running process
...
  -K            checks POWERDOWNFLAG (***NOT CONFIGURED***), sets exit code to 0 if set
...

• ...and with a value defined in config (huh, TODO hush the "redefined" message):

Network UPS Tools upsmon 2.8.1-994-gbff0c6bc9
Warning: POWERDOWNFLAG redefined in split-process mode!
You must restart upsmon for this change to work
Monitors UPS servers and may initiate shutdown if necessary.

usage: /home/jim/nut/clients/.libs/upsmon [OPTIONS]

...
  -K            checks POWERDOWNFLAG (/run/nut/killpower), sets exit code to 0 if set
...

• UPDATE: with a value defined in config after a later commit below):

Network UPS Tools upsmon 2.8.1-994-gbff0c6bc9
Monitors UPS servers and may initiate shutdown if necessary.

usage: /home/jim/nut/clients/.libs/upsmon [OPTIONS]

...
  -K            checks POWERDOWNFLAG (/run/nut/killpower), sets exit code to 0 if set
...

[jimklimov]

Some upsmon -DDDDDD -K && echo KILLPOWER tests:

• No file:

Network UPS Tools upsmon 2.8.1-994-gbff0c6bc9
   0.000000     fopen /run/upsmon.pid: No such file or directory
   0.000046     Could not find PID file to see if previous upsmon instance is already running!
   0.000063     [D1] loadconfig: Loading /usr/local/ups/etc/upsmon.conf
   0.000095     UPS: x (monitoring only)
   0.000129     Using power down flag file /run/nut/killpower
   0.000151     [D1] debug level is '6'
   0.000158     Power down flag is not set

• Empty file (just touched):

Network UPS Tools upsmon 2.8.1-994-gbff0c6bc9
   0.000000     fopen /run/upsmon.pid: No such file or directory
   0.000048     Could not find PID file to see if previous upsmon instance is already running!
   0.000084     [D1] loadconfig: Loading /usr/local/ups/etc/upsmon.conf
   0.000139     UPS: x (monitoring only)
   0.000174     Using power down flag file /run/nut/killpower
   0.000198     [D1] debug level is '6'
   0.000246     '/run/nut/killpower' exists, but we can't read from it: No such file or directory
   0.000270     POWERDOWNFLAG (/run/nut/killpower) does not contain the upsmon magic string

• NOTE: No such file or directory seems odd above

• With magic string:

Network UPS Tools upsmon 2.8.1-994-gbff0c6bc9
   0.000000     fopen /run/upsmon.pid: No such file or directory
   0.000021     Could not find PID file to see if previous upsmon instance is already running!
   0.000043     [D1] loadconfig: Loading /usr/local/ups/etc/upsmon.conf
   0.000097     UPS: x (monitoring only)
   0.000144     Using power down flag file /run/nut/killpower
   0.000169     [D1] debug level is '6'
   0.000228     Power down flag is set
KILLPOWER

[jimklimov]

upsmon -K without debug verbosity args (some might argue this is a bit too talkative for the use-case where it is not going to signal an existing sibling nor monitor the UPSes - perhaps the new negative verbosity support from this PR can help -- PRs pending):

:; ./clients/upsmon -K && echo KILLPOWER
Network UPS Tools upsmon 2.8.1-994-gbff0c6bc9
fopen /run/upsmon.pid: No such file or directory
Could not find PID file to see if previous upsmon instance is already running!
UPS: x (monitoring only)
Using power down flag file /run/nut/killpower
Power down flag is set
KILLPOWER

:; rm /run/nut/killpower
:; ./clients/upsmon -K && echo KILLPOWER
Network UPS Tools upsmon 2.8.1-994-gbff0c6bc9
fopen /run/upsmon.pid: No such file or directory
Could not find PID file to see if previous upsmon instance is already running!
UPS: x (monitoring only)
Using power down flag file /run/nut/killpower
Power down flag is not set