drivers/main.{c,h}, docs/man/ups.conf.txt, conf/ups.conf.sample, NEWS.adoc: introduce reconnect_max_tries setting for NUT drivers [#3541]

Signed-off-by: Jim Klimov <jimklimov+nut@gmail.com>

Author: jimklimov

NEWS.adoc

@@ -156,6 +156,10 @@ https://github.com/networkupstools/nut/milestone/13
       chunks populated only partially with bytes we intended. These buffers are
       now more diligently pre-zeroed as their siblings were in other code paths,
       to avoid sending host stack garbage to a device. [#3529]
+    * Introduced a `reconnect_max_tries` setting for NUT drivers, so they can
+      be configured to exit after the specified number of reconnection attempts
+      (so that the OS service management facility can completely recycle the
+      driver program). [#3541]
 
  - NUT client libraries:
     * Complete support for actions documented in `docs/net-protocol.txt`

conf/ups.conf.sample

@@ -112,6 +112,18 @@ maxretry = 3
 #
 #                The default is 75 seconds.
 #
+# reconnect_max_tries: OPTIONAL. This can be set as a global variable above
+#              your first UPS definition and it can also be set in a
+#              UPS section. If a driver loses connection to the device,
+#              try reconnecting for the specified number of iterations and
+#              exit (so some OS service management facility or an alerted
+#              sysadmin can restart the driver program "from scratch").
+#              A zero value (unreasonable but possible) means to exit as
+#              soon as the device connection was lost.
+#              A negative value (default) means to try reconnecting
+#              indefinitely (e.g. data cable fell out, or the data path
+#              to a networked UPS was lost for a significant time).
+#
 #   debug_min: OPTIONAL.  Specify a minimum debug level for all driver daemons
 #              and for the upsdrvctl tool (when specified at global level),
 #              or for this driver daemon (when specified in a driver section),

docs/man/ups.conf.txt

@@ -100,6 +100,19 @@ its own in `upsd.conf`.
 +
 Environment variable `NUT_STATEPATH` set by caller can override this setting.
 
+*reconnect_max_tries*::
+
+Optional. If a driver loses connection to the device, try reconnecting for
+the specified number of iterations and exit (so some OS service management
+facility or an alerted sysadmin can restart the driver program "from scratch").
++
+A zero value (unreasonable but possible) means to exit as soon as the device
+connection was lost.
++
+A negative value (default) means to try reconnecting indefinitely (e.g. data
+cable fell out, or the data path to a networked UPS was lost for a significant
+time).
+
 *maxstartdelay*::
 
 Optional.  Same as the UPS field of the same name, but this is the
@@ -340,6 +353,11 @@ They would not be actively killed by `upsdrvctl` after this timeout expires.
 +
 The default is 75 seconds.
 
+*reconnect_max_tries*::
+Optional.  This can be set as a global variable above your first UPS
+definition and it can also be set in a UPS section.  See explanation
+above, in the global section.
+
 *maxretry*::
 Optional.  This can be set as a global variable above your first UPS
 definition and it can also be set in a UPS section.  See explanation

drivers/main.c

@@ -101,7 +101,8 @@ vartab_t	*vartab_h = NULL;
  */
 time_t	poll_interval = 2;
 static char	*chroot_path = NULL, *user = NULL, *group = NULL;
-static int	user_from_cmdline = 0, group_from_cmdline = 0;
+static int	user_from_cmdline = 0, group_from_cmdline = 0,
+		reconnect_max_tries = -1, reconnect_count = 0;
 
 /* signal handling */
 int	exit_flag = 0;
@@ -1397,6 +1398,18 @@ static int main_arg(char *var, char *val)
 		return 1;	/* handled */
 	}
 
+	/* Allow per-driver overrides of the global setting
+	 * and allow to reload this, why not. */
+	if (!strcmp(var, "reconnect_max_tries")) {
+		int	intval = -1;
+		if ( str_to_int (val, &intval, 10) ) {
+			reconnect_max_tries = intval;
+			reconnect_count = 0;
+		} else {
+			upslogx(LOG_INFO, "WARNING : Invalid reconnect_max_tries value found in ups.conf global settings");
+		}
+	}
+
 	/* only for upsdrvctl - ignored here */
 	if (!strcmp(var, "sdorder"))
 		return 1;	/* handled */
@@ -1571,6 +1584,18 @@ static void do_global_args(const char *var, const char *val)
 		return;
 	}
 
+	if (!strcmp(var, "reconnect_max_tries")) {
+		int	intval = -1;
+		if ( str_to_int (val, &intval, 10) ) {
+			reconnect_max_tries = intval;
+			reconnect_count = 0;
+		} else {
+			upslogx(LOG_INFO, "WARNING : Invalid reconnect_max_tries value found in ups.conf global settings");
+		}
+
+		return;
+	}
+
 	/* Allow to specify its minimal debugging level for all drivers -
 	 * admins can set more with command-line args, but can't set
 	 * less without changing config. Should help debug of services.
@@ -2169,6 +2194,77 @@ void setup_signals(void)
 }
 #endif /* !WIN32*/
 
+/* Called by a driver to enter/continue a reconnection loop (trying=1,
+ * with certain configuration can activate exit_flag) or to end it (0).
+ * Sets the driver.state to "reconnect.trying" or "quiet" respectively.
+ * Returns how many attempts remain before driver exits (-1 if it won't).
+ */
+int reconnect_trying(int trying)
+{
+	if (!trying) {
+		if (reconnect_count > 0)
+			upslogx(LOG_INFO, "Driver reconnected "
+				"to the device [%s] after %d attempts",
+				upsname, reconnect_count);
+		reconnect_count = 0;
+		dstate_setinfo("driver.state", "quiet");
+		return -1;
+	}
+
+	if (reconnect_max_tries == 0) {
+		upslogx(LOG_WARNING, "Driver lost connection "
+			"to the device [%s] and will exit immediately",
+			upsname);
+		exit_flag = 1;
+		return 0;
+	}
+
+	dstate_setinfo("driver.state", "reconnect.trying");
+
+	if (reconnect_count == 0) {
+		if (reconnect_max_tries < 0) {
+			upslogx(LOG_INFO, "Driver reconnecting "
+				"to the device [%s], will try "
+				"indefinitely",
+				upsname);
+		} else {
+			upslogx(LOG_INFO, "Driver reconnecting "
+				"to the device [%s], will try for "
+				"max %d attempts, then will exit",
+				upsname, reconnect_max_tries);
+		}
+	}
+
+	if (reconnect_count < INT_MAX) {
+		reconnect_count++;
+	} else {
+		upsdebugx(1, "%s: reconnect counter overflowed", __func__);
+		if (reconnect_max_tries > 0) {
+			upslogx(LOG_WARNING, "Driver lost connection "
+				"to the device [%s] and reconnect "
+				"counter overflowed, will exit immediately",
+				upsname);
+			exit_flag = 1;
+			return 0;
+		}
+	}
+
+	if (reconnect_max_tries > 0) {
+		if (reconnect_max_tries < reconnect_count) {
+			upslogx(LOG_WARNING, "Driver lost connection "
+				"to the device [%s] and tried to "
+				"reconnect for %d times, "
+				"now will exit as configured",
+				upsname, reconnect_count);
+			exit_flag = 1;
+			return 0;
+		}
+		return reconnect_max_tries - reconnect_count + 1;
+	}
+
+	return -1;
+}
+
 /* This source file is used in some unit tests to mock realistic driver
  * behavior - using a production driver skeleton, but their own main().
  * It is called from main-stub.c in shared-mode builds.
@@ -3301,6 +3397,11 @@ int main(int argc, char **argv)
 		gettimeofday(&timeout, NULL);
 		timeout.tv_sec += poll_interval;
 
+		if (reconnect_count > 0) {
+			dstate_setinfo("driver.reconnect_count", "%d", reconnect_count);
+			dstate_setinfo("driver.reconnect_max_tries", "%d", reconnect_max_tries);
+		}
+
 		/* Drivers can now choose to track changes of current battery
 		 * charge vs. its previous value to e.g. report "CHRG" status.
 		 * TODO: Eventually provide a common `runtimecal` fallback to all?

drivers/main.h

@@ -112,6 +112,13 @@ typedef struct vartab_s {
 void addvar(int vartype, const char *name, const char *desc);
 void addvar_reloadable(int vartype, const char *name, const char *desc);
 
+/* Called by a driver to enter/continue a reconnection loop (trying=1,
+ * with certain configuration can activate exit_flag) or to end it (0).
+ * Sets the driver.state to "reconnect.trying" or "quiet" respectively.
+ * Returns how many attempts remain before driver exits (-1 if it won't).
+ */
+int reconnect_trying(int trying);
+
 /* Several helpers for driver configuration reloading follow:
  * * testval_reloadable() checks if we are currently reloading (or initially
  *   loading) the configuration, and if strings oldval==newval or not,