upsmon: clarify warning about lack of POWERDOWNFLAG configuration

NEWS.adoc

@@ -382,6 +382,7 @@ but the `nutshutdown` script would bail out quickly and quietly. [PR #3008]
      long delays did not happen in practice. [issues #2133 and #3084, PR #3086]
    * Make use of `setproctag()` and `getproctag()` to report parent/child
      process names. [#3084]
+   * Clarify the warning about lack of `POWERDOWNFLAG` in configuration. [#3391]
    * Introduced a `SHUTDOWN_HOSTSYNC` notification message, to report that
      the primary `upsmon` initiated the shutdown and has some secondaries
      to wait for first. [#3084]

clients/upsmon.c

@@ -2694,12 +2694,40 @@ static void loadconfig(void)
 
 	/* TOTHINK: Should this warning be limited to non-WIN32 builds? */
 	if (!powerdownflag) {
+		int	is_primary = 0, is_fed = 0;
+		utype_t	*ups;
+
+		for (ups = firstups; ups != NULL; ups = (utype_t *)ups->next) {
+			if (flag_isset(ups->status, ST_PRIMARY)) {
+				is_primary = 1;
+				if (ups->pv > 0) {
+					is_fed = 1;
+					break;
+				}
+			}
+		}
+
 		upslogx(LOG_WARNING, "No POWERDOWNFLAG value was configured in %s!",
 			configfile);
 		upslogx(LOG_INFO,
 			"POWERDOWNFLAG 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.");
+
+		if (is_primary)
+			upslogx(LOG_WARNING, "This upsmon instance is PRIMARY "
+				"for at least one device%s, but would not be able "
+				"to arrange its power-cycling when needed, "
+				"in the end of handling a power outage.\n"
+				"In case of a power-race condition, this can "
+				"leave your computer(s) indefinitely halted.",
+				is_fed ? " that feeds it" : "");
+		else
+			upslogx(LOG_WARNING, "This upsmon instance is not a "
+				"PRIMARY for any device, so this can be of "
+				"little concern unless other shutdown routines "
+				"on your system also consult it to act fast "
+				"during an outage.");
 	}
 }
 

docs/config-notes.txt

@@ -675,8 +675,24 @@ during a power failure when low battery is reached.
 
 We will test for the presence of this file in a later step.
 
+It is recommended to use a volatile file system, which is re-created
+during boot, like `/run` or `/var/run` on many OSes. Historic default
+was under `/etc` where unprivileged users could not write, but a
+persistent file could confuse the later shutdowns if it was not removed.
+
 	POWERDOWNFLAG /etc/killpower
 
+As far as NUT is concerned, this should be configured on any `upsmon`
+instance which is "primary" for any device that may be commanded to
+shut down, and is powered by same device.
+
+Other shutdown scripts, on "primary" or "secondary" systems are however
+welcome to check for the time-constrained shutdown due to power outage,
+in case they need to balance graceful vs. urgent activities (e.g. how
+long to wait for their client-server disconnection).
+
+The `upsmon -K` command should be used for such check.
+
 References: man pages: linkman:upsmon[8],
 linkman:upsmon.conf[5]