upssched: Introduce passing of NOTIFYMSG to a CMDSCRIPT

NEWS.adoc

@@ -100,6 +100,17 @@ https://github.com/networkupstools/nut/milestone/12
    * Introduced a `SHUTDOWN_HOSTSYNC` notification message, to report that
      the primary `upsmon` initiated the shutdown and has some secondaries
      to wait for first. [#3084]
+   * Make sure an `FSD` notification is issued for each UPS when this primary
+     `upsmon` instance sets it (and does not return to usual data processing
+     loop to see and report it like secondaries do). This allows a `NOTIFYCMD`
+     such as `upssched` on the primary to handle the pending power outage
+     (e.g. begin stopping heavy services) even while `upsmon` waits for the
+     secondaries to complete their shutdowns and log out of the `upsd` data
+     server. [issue #3003, PR #3110]
++
+NOTE: If using `upssched` and monitoring multiple UPSes, consider setting up
+a `START-TIMER-SHARED` rule with a short (approx. 1 second) timeout to group
+several `FSD` notifications into one executed action. [PR #3097]
 
  - `upssched` tool updates:
    * Previously in PR #2896 (NUT releases v2.8.3 and v2.8.4) the `UPSNAME` and
@@ -120,6 +131,9 @@ https://github.com/networkupstools/nut/milestone/12
    * Introduced `upssched -l` mode to list currently tracked timers. [#3097]
    * Make use of `setproctag()` and `getproctag()` to report parent/child
      process names. [#3084]
+   * Introduced optional passing of `NOTIFYMSG` text (normally originating
+     from `upsmon` which calls `upssched`) as an environment variable into
+     the ultimately executed `CMDSCRIPT` processes. [#3105]
 
  - `configure` script options:
    * Introduced `--with-python{,2,3}-modules-dir` to specify PyNUT(Client)

clients/upsmon.c

@@ -280,6 +280,7 @@ static unsigned __stdcall async_notify(LPVOID param)
 		if (notifycmd != NULL) {
 			snprintf(exec, sizeof(exec), "%s \"%s\"", notifycmd, data->notice);
 
+			upsdebugx(6, "%s: Calling NOTIFYCMD: %s", __func__, exec);
 			if (data->upsname)
 				setenv("UPSNAME", data->upsname, 1);
 			else
@@ -1132,8 +1133,20 @@ static void setfsd(utype_t *ups)
 		return;
 	}
 
-	if (!strncmp(buf, "OK", 2))
+	if (!strncmp(buf, "OK", 2)) {
+		upsdebugx(1, "%s: data server confirmed setting FSD for UPS [%s]", __func__, ups->sys);
+
+		/* Let NOTIFYCMD (if any) know, and have a chance to react */
+		if (ups->lastfsdnotify) {
+			/* e.g. upsd was still alive with a latched FSD
+			 * status when this upsmon instance started */
+			upsdebugx(2, "%s: not notifying about FSD for UPS [%s] because it was recently reported already", __func__, ups->sys);
+		} else {
+			time(&(ups->lastfsdnotify));
+			do_notify(ups, NOTIFY_FSD, NULL);
+		}
 		return;
+	}
 
 	/* protocol error: upsd said something other than "OK" */
 	upslogx(LOG_ERR, "FSD set on UPS %s failed: %s", ups->sys, buf);
@@ -1842,9 +1855,12 @@ static void ups_fsd(utype_t *ups)
 
 	upsdebugx(3, "%s: %s (first time)", __func__, ups->sys);
 
-	/* must have changed from !FSD to FSD, so notify */
+	/* must have changed from !FSD to FSD, so notify; avoid duplicates though */
 
-	do_notify(ups, NOTIFY_FSD, NULL);
+	if (!(ups->lastfsdnotify)) {
+		time(&(ups->lastfsdnotify));
+		do_notify(ups, NOTIFY_FSD, NULL);
+	}
 	setflag(&ups->status, ST_FSD);
 }
 
@@ -2112,6 +2128,8 @@ static void addups(int reloading, const char *sys, const char *pvs,
 	tmp->lastrbwarn = 0;
 	tmp->lastncwarn = 0;
 
+	tmp->lastfsdnotify = 0;
+
 	tmp->offsince = 0;
 	tmp->oblbsince = 0;
 	tmp->oversince = 0;
@@ -2867,8 +2885,10 @@ static void parse_status(utype_t *ups, char *status, char *buzzword, char *buzzw
 	/* clear these out early if they disappear */
 	if (!strstr(status, "LB"))
 		clearflag(&ups->status, ST_LOWBATT);
-	if (!strstr(status, "FSD"))
+	if (!strstr(status, "FSD")) {
 		clearflag(&ups->status, ST_FSD);
+		ups->lastfsdnotify = 0;
+	}
 
 	/* similar to above - clear these flags and send notifications */
 	if (!strstr(status, "CAL"))

clients/upsmon.h

@@ -92,10 +92,12 @@ typedef struct {
 	int	pollfail_log_throttle_count;	/* How many pollfreq loops this UPS was in this state since last logged report? */
 
 	time_t	lastpoll;		/* time of last successful poll	*/
-	time_t  lastnoncrit;		/* time of last non-crit poll	*/
+	time_t	lastnoncrit;		/* time of last non-crit poll	*/
 	time_t	lastrbwarn;		/* time of last REPLBATT warning*/
 	time_t	lastncwarn;		/* time of last NOCOMM warning	*/
 
+	time_t	lastfsdnotify;		/* time of last FSD notification (when first discovering the state, or setting it - avoid duplicate notification); 0 initially or if that state clears	*/
+
 	time_t	offsince;		/* time of recent entry into OFF state	*/
 	time_t	oblbsince;		/* time of recent entry into OB LB state (normally this causes immediate shutdown alert, unless we are configured to delay it)	*/
 	time_t	oversince;		/* time of recent entry into OVER state	*/

clients/upssched-cmd

@@ -17,8 +17,8 @@
 echo "`date -u`: $0: THIS IS A SAMPLE SCRIPT, PLEASE TAILOR IT FOR YOUR DEPLOYMENT OF NUT!" >&2
 logger -t upssched-cmd "THIS IS A SAMPLE SCRIPT, PLEASE TAILOR IT FOR YOUR DEPLOYMENT OF NUT!"
 
-printf "`date -u`: UPSNAME='%s'\tNOTIFYTYPE='%s'\targs=%s\n" "$UPSNAME" "$NOTIFYTYPE" "$@" >&2
-printf "UPSNAME='%s' NOTIFYTYPE='%s' args=%s\n" "$UPSNAME" "$NOTIFYTYPE" "$@" | logger -t upssched-cmd-received-NOTIFYTYPE
+printf "`date -u`: UPSNAME='%s'\tNOTIFYTYPE='%s'\tNOTIFYMSG='%s'\targs=%s\n" "$UPSNAME" "$NOTIFYTYPE" "$NOTIFYMSG" "$*" >&2
+printf "UPSNAME='%s' NOTIFYTYPE='%s' NOTIFYMSG='%s' args=%s\n" "$UPSNAME" "$NOTIFYTYPE" "$NOTIFYMSG" "$*" | logger -t upssched-cmd-received-NOTIFYTYPE
 
 #set