nut-scanner: report bogus and duplicate serial numbers [#1810]

NEWS

@@ -184,6 +184,10 @@ https://github.com/networkupstools/nut/milestone/8
    abort and require either to install the dependency or explicitly forfeit
    the tool (some distro packages missed it quietly in the past) [#1560]
 
+ - The `nut-scanner` program should now by default warn about serial numbers
+   which do not make much sense (are duplicate, empty, all same character, etc)
+   [#1810]
+
  - Existing openssl-1.1.0 support added for NUT v2.8.0 release was tested to
    be sufficient without deprecation warnings for builds against openssl-3.0.x
    (but no real-time testing was done yet) [#1547]

UPGRADING

@@ -31,6 +31,10 @@ Changes from 2.8.0 to 2.8.1
     device configuration [#1790]: hopefully these would now suffice for
     sufficiently unique combinations;
 
+  * The `nut-scanner` tool should also suggest sanity-check violations
+    as comments in its generated device configuration [#1810], e.g. bogus
+    or duplicate serial number values;
+
   * The common USB matching logic was updated with an `allow_duplicates`
     flag (caveat emptor!) which may help monitor several related no-name
     devices on systems that do not discern "bus" and "device" values

docs/man/Makefile.am

@@ -177,6 +177,9 @@ SRC_DEV_PAGES = \
 	nutscan_scan_avahi.txt \
 	nutscan_scan_ipmi.txt \
 	nutscan_scan_eaton_serial.txt \
+	nutscan_display_sanity_check.txt \
+	nutscan_display_sanity_check_serial.txt \
+	nutscan_display_ups_conf_with_sanity_check.txt \
 	nutscan_display_ups_conf.txt \
 	nutscan_display_parsable.txt \
 	nutscan_cidr_to_ip.txt \
@@ -290,6 +293,9 @@ MAN3_DEV_PAGES = \
 	nutscan_scan_avahi.3 \
 	nutscan_scan_ipmi.3 \
 	nutscan_scan_eaton_serial.3 \
+	nutscan_display_sanity_check.3 \
+	nutscan_display_sanity_check_serial.3 \
+	nutscan_display_ups_conf_with_sanity_check.3 \
 	nutscan_display_ups_conf.3 \
 	nutscan_display_parsable.3 \
 	nutscan_cidr_to_ip.3 \
@@ -352,6 +358,9 @@ HTML_DEV_MANS = \
 	nutscan_scan_avahi.html \
 	nutscan_scan_ipmi.html \
 	nutscan_scan_eaton_serial.html \
+	nutscan_display_sanity_check.html \
+	nutscan_display_sanity_check_serial.html \
+	nutscan_display_ups_conf_with_sanity_check.html \
 	nutscan_display_ups_conf.html \
 	nutscan_display_parsable.html \
 	nutscan_cidr_to_ip.html \

docs/man/nut-scanner.txt

@@ -37,6 +37,10 @@ Display the help text.
 DISPLAY OPTIONS
 ---------------
 
+*-Q* | *--disp_nut_conf_with_sanity_check*::
+Display result in the 'ups.conf' format with sanity-check warnings (if any)
+as comments (default).
+
 *-N* | *--disp_nut_conf*::
 Display result in the 'ups.conf' format.
 

docs/man/nutscan.txt

@@ -43,7 +43,9 @@ linkman:nutscan_add_device_to_device[3].
 Helper functions are also provided to output data using standard formats:
 
 - linkman:nutscan_display_parsable[3] for parsable output,
-- linkman:nutscan_display_ups_conf[3] for ups.conf style.
+- linkman:nutscan_display_ups_conf[3] for ups.conf style,
+- linkman:nutscan_display_ups_conf_with_sanity_check[3] for ups.conf style
+  with comments for warnings about possible configuration problems (if any).
 
 
 ERROR HANDLING
@@ -59,6 +61,9 @@ linkman:nut-scanner[8],
 linkman:nutscan_scan_usb[3], linkman:nutscan_scan_snmp[3],
 linkman:nutscan_scan_xml_http_range[3], linkman:nutscan_scan_nut[3],
 linkman:nutscan_scan_avahi[3], linkman:nutscan_scan_ipmi[3],
+linkman:nutscan_display_sanity_check[3],
+linkman:nutscan_display_sanity_check_serial[3],
+linkman:nutscan_display_ups_conf_with_sanity_check[3],
 linkman:nutscan_display_parsable[3], linkman:nutscan_display_ups_conf[3],
 linkman:nutscan_new_device[3], linkman:nutscan_free_device[3],
 linkman:nutscan_add_device_to_device[3],

docs/man/nutscan_add_option_to_device.txt

@@ -38,6 +38,12 @@ associated 'value'. Copies of 'option_name' and 'value' are stored
 in the device, so the caller can safely free both of the original
 strings used as arguments.
 
+Such options and their values may be further sanity-checked and reported
+as warnings by *nutscan_display_sanity_check()* dispatcher and its related
+methods which implement the logic of particular checks. This is used for
+example when generating 'ups.conf' file content suggestions with
+*nutscan_display_ups_conf_with_sanity_check()* method.
+
 NOTES
 -----
 
@@ -49,6 +55,9 @@ SEE ALSO
 linkman:nutscan_scan_usb[3], linkman:nutscan_scan_xml_http_range[3],
 linkman:nutscan_scan_nut[3], linkman:nutscan_scan_avahi[3],
 linkman:nutscan_scan_ipmi[3], linkman:nutscan_scan_snmp[3],
+linkman:nutscan_display_sanity_check[3],
+linkman:nutscan_display_sanity_check_serial[3],
+linkman:nutscan_display_ups_conf_with_sanity_check[3],
 linkman:nutscan_display_ups_conf[3], linkman:nutscan_display_parsable[3],
 linkman:nutscan_new_device[3], linkman:nutscan_free_device[3],
 linkman:nutscan_add_device_to_device[3]

docs/man/nutscan_cidr_to_ip.txt

@@ -40,4 +40,5 @@ SEE ALSO
 linkman:nutscan_scan_usb[3], linkman:nutscan_scan_xml_http_range[3],
 linkman:nutscan_scan_nut[3], linkman:nutscan_scan_avahi[3],
 linkman:nutscan_scan_ipmi[3], linkman:nutscan_scan_snmp[3],
+linkman:nutscan_display_ups_conf_with_sanity_check[3],
 linkman:nutscan_display_parsable[3], linkman:nutscan_display_ups_conf[3]

docs/man/nutscan_display_parsable.txt

@@ -29,12 +29,19 @@ which is:
 * <port type> and <optional parameter X> depend on <driver name>,
   see the corresponding driver's man page.
 
+Note that this format is for machine consumption, so is not associated
+with sanity checks that may be used along with display method for the
+'ups.conf' file format.
+
 SEE ALSO
 --------
 
 linkman:nutscan_scan_usb[3], linkman:nutscan_scan_xml_http_range[3],
 linkman:nutscan_scan_nut[3], linkman:nutscan_scan_avahi[3],
 linkman:nutscan_scan_ipmi[3], linkman:nutscan_scan_snmp[3],
+linkman:nutscan_display_sanity_check[3],
+linkman:nutscan_display_sanity_check_serial[3],
+linkman:nutscan_display_ups_conf_with_sanity_check[3],
 linkman:nutscan_display_ups_conf[3], linkman:nutscan_new_device[3],
 linkman:nutscan_free_device[3], linkman:nutscan_add_option_to_device[3],
 linkman:nutscan_add_device_to_device[3], linkman:nutscan_cidr_to_ip[3]

docs/man/nutscan_display_sanity_check.txt

@@ -0,0 +1,39 @@
+NUTSCAN_DISPLAY_SANITY_CHECK(3)
+===============================
+
+NAME
+----
+
+nutscan_display_sanity_check - Display sanity check warnings about
+the specified `nutscan_device_t` structure on stdout.
+
+SYNOPSIS
+--------
+
+ #include <nut-scan.h>
+
+ void nutscan_display_sanity_check(nutscan_device_t * device);
+
+DESCRIPTION
+-----------
+
+The *nutscan_display_sanity_check()* function calls all sanity-check
+analyzers against displays all NUT devices in 'device', and they may
+print comments to stdout. It displays them in a way that it can be
+directly copied into the 'ups.conf' file.
+
+It is called from *nutscan_display_ups_conf_with_sanity_check()* to
+provide an aggregate content for 'ups.conf' file in one shot.
+
+SEE ALSO
+--------
+
+linkman:nutscan_display_ups_conf_with_sanity_check[3],
+linkman:nutscan_display_sanity_check_serial[3],
+linkman:nutscan_scan_usb[3], linkman:nutscan_scan_xml_http_range[3],
+linkman:nutscan_scan_nut[3], linkman:nutscan_scan_avahi[3],
+linkman:nutscan_scan_ipmi[3], linkman:nutscan_scan_snmp[3],
+linkman:nutscan_display_ups_conf[3],
+linkman:nutscan_display_parsable[3], linkman:nutscan_new_device[3],
+linkman:nutscan_free_device[3], linkman:nutscan_add_option_to_device[3],
+linkman:nutscan_add_device_to_device[3], linkman:nutscan_cidr_to_ip[3]

docs/man/nutscan_display_sanity_check_serial.txt

@@ -0,0 +1,43 @@
+NUTSCAN_DISPLAY_SANITY_CHECK_SERIAL(3)
+======================================
+
+NAME
+----
+
+nutscan_display_sanity_check_serial - Display sanity check warnings
+about "serial" (serial number/code string) optional values in the
+specified `nutscan_device_t` structure on stdout.
+
+SYNOPSIS
+--------
+
+ #include <nut-scan.h>
+
+ void nutscan_display_sanity_check_serial(nutscan_device_t * device);
+
+DESCRIPTION
+-----------
+
+The *nutscan_display_sanity_check_serial()* function analyzes "serial"
+optional field in all NUT devices in 'device', and in case of duplicate
+or otherwise seemingly invalid values, prints comments to stdout.
+It displays them in a way that it can be directly copied into the
+'ups.conf' file.
+
+It is called from *nutscan_display_ups_conf_with_sanity_check()* to
+provide an aggregate content for 'ups.conf' file in one shot.
+
+SEE ALSO
+--------
+
+linkman:nutscan_display_ups_conf_with_sanity_check[3],
+linkman:nutscan_display_sanity_check_serial[3],
+linkman:nutscan_scan_usb[3], linkman:nutscan_scan_xml_http_range[3],
+linkman:nutscan_scan_nut[3], linkman:nutscan_scan_avahi[3],
+linkman:nutscan_scan_ipmi[3], linkman:nutscan_scan_snmp[3],
+linkman:nutscan_display_sanity_check[3],
+linkman:nutscan_display_ups_conf_with_sanity_check[3],
+linkman:nutscan_display_ups_conf[3],
+linkman:nutscan_display_parsable[3], linkman:nutscan_new_device[3],
+linkman:nutscan_free_device[3], linkman:nutscan_add_option_to_device[3],
+linkman:nutscan_add_device_to_device[3], linkman:nutscan_cidr_to_ip[3]

docs/man/nutscan_display_ups_conf.txt

@@ -21,12 +21,18 @@ The *nutscan_display_ups_conf()* function displays all NUT devices in
 'device' to stdout. It displays them in a way that it can be directly
 copied into the 'ups.conf' file.
 
+It is called from *nutscan_display_ups_conf_with_sanity_check()* to
+provide an aggregate content for 'ups.conf' file in one shot.
+
 SEE ALSO
 --------
 
 linkman:nutscan_scan_usb[3], linkman:nutscan_scan_xml_http_range[3],
 linkman:nutscan_scan_nut[3], linkman:nutscan_scan_avahi[3],
 linkman:nutscan_scan_ipmi[3], linkman:nutscan_scan_snmp[3],
+linkman:nutscan_display_ups_conf_with_sanity_check[3],
+linkman:nutscan_display_sanity_check[3],
+linkman:nutscan_display_sanity_check_serial[3],
 linkman:nutscan_display_parsable[3], linkman:nutscan_new_device[3],
 linkman:nutscan_free_device[3], linkman:nutscan_add_option_to_device[3],
 linkman:nutscan_add_device_to_device[3], linkman:nutscan_cidr_to_ip[3]

docs/man/nutscan_display_ups_conf_with_sanity_check.txt

@@ -0,0 +1,36 @@
+NUTSCAN_DISPLAY_UPS_CONF_WITH_SANITY_CHECK(3)
+=============================================
+
+NAME
+----
+
+nutscan_display_ups_conf_with_sanity_check - Display the specified
+`nutscan_device_t` structure and sanity-check warnings on stdout.
+
+SYNOPSIS
+--------
+
+ #include <nut-scan.h>
+
+ void nutscan_display_ups_conf_with_sanity_check(nutscan_device_t * device);
+
+DESCRIPTION
+-----------
+
+The *nutscan_display_ups_conf_with_sanity_check()* function displays
+all NUT devices in 'device' to stdout, and follows up with comments
+about sanity-check violations (if any). It displays them in a way that
+it can be directly copied into the 'ups.conf' file.
+
+SEE ALSO
+--------
+
+linkman:nutscan_scan_usb[3], linkman:nutscan_scan_xml_http_range[3],
+linkman:nutscan_scan_nut[3], linkman:nutscan_scan_avahi[3],
+linkman:nutscan_scan_ipmi[3], linkman:nutscan_scan_snmp[3],
+linkman:nutscan_display_sanity_check[3],
+linkman:nutscan_display_sanity_check_serial[3],
+linkman:nutscan_display_ups_conf[3],
+linkman:nutscan_display_parsable[3], linkman:nutscan_new_device[3],
+linkman:nutscan_free_device[3], linkman:nutscan_add_option_to_device[3],
+linkman:nutscan_add_device_to_device[3], linkman:nutscan_cidr_to_ip[3]

docs/man/nutscan_free_device.txt

@@ -32,6 +32,7 @@ SEE ALSO
 linkman:nutscan_scan_usb[3], linkman:nutscan_scan_xml_http_range[3],
 linkman:nutscan_scan_nut[3], linkman:nutscan_scan_avahi[3],
 linkman:nutscan_scan_ipmi[3], linkman:nutscan_scan_snmp[3],
+linkman:nutscan_display_ups_conf_with_sanity_check[3],
 linkman:nutscan_display_ups_conf[3], linkman:nutscan_display_parsable[3],
 linkman:nutscan_new_device[3], linkman:nutscan_add_option_to_device[3],
 linkman:nutscan_add_device_to_device[3]

docs/man/nutscan_get_serial_ports_list.txt

@@ -56,4 +56,5 @@ linkman:nutscan_scan_usb[3], linkman:nutscan_scan_xml_http_range[3],
 linkman:nutscan_scan_nut[3], linkman:nutscan_scan_avahi[3],
 linkman:nutscan_scan_ipmi[3], linkman:nutscan_scan_snmp[3],
 linkman:nutscan_scan_eaton_serial[3],
+linkman:nutscan_display_ups_conf_with_sanity_check[3],
 linkman:nutscan_display_parsable[3], linkman:nutscan_display_ups_conf[3]

docs/man/nutscan_init.txt

@@ -46,6 +46,9 @@ linkman:nutscan_init[3], linkman:nutscan_scan_usb[3],
 linkman:nutscan_scan_snmp[3], linkman:nutscan_scan_xml_http_range[3],
 linkman:nutscan_scan_nut[3], linkman:nutscan_scan_avahi[3],
 linkman:nutscan_scan_ipmi[3], linkman:nutscan_display_ups_conf[3],
+linkman:nutscan_display_sanity_check[3],
+linkman:nutscan_display_sanity_check_serial[3],
+linkman:nutscan_display_ups_conf_with_sanity_check[3],
 linkman:nutscan_display_parsable[3], linkman:nutscan_new_device[3],
 linkman:nutscan_free_device[3], linkman:nutscan_add_option_to_device[3],
 linkman:nutscan_add_device_to_device[3]

docs/man/nutscan_new_device.txt

@@ -37,5 +37,8 @@ linkman:nutscan_scan_usb[3], linkman:nutscan_scan_xml_http_range[3],
 linkman:nutscan_scan_nut[3], linkman:nutscan_scan_avahi[3],
 linkman:nutscan_scan_ipmi[3], linkman:nutscan_scan_snmp[3]
 linkman:nutscan_display_ups_conf[3], linkman:nutscan_display_parsable[3]
+linkman:nutscan_display_sanity_check[3],
+linkman:nutscan_display_sanity_check_serial[3],
+linkman:nutscan_display_ups_conf_with_sanity_check[3],
 linkman:nutscan_free_device[3], linkman:nutscan_add_option_to_device[3]
 linkman:nutscan_add_device_to_device[3]

docs/man/nutscan_scan_avahi.txt

@@ -41,6 +41,9 @@ linkman:nutscan_init[3],
 linkman:nutscan_scan_usb[3], linkman:nutscan_scan_xml_http_range[3],
 linkman:nutscan_scan_nut[3], linkman:nutscan_scan_snmp[3],
 linkman:nutscan_scan_ipmi[3], linkman:nutscan_display_ups_conf[3],
+linkman:nutscan_display_sanity_check[3],
+linkman:nutscan_display_sanity_check_serial[3],
+linkman:nutscan_display_ups_conf_with_sanity_check[3],
 linkman:nutscan_display_parsable[3], linkman:nutscan_new_device[3],
 linkman:nutscan_free_device[3], linkman:nutscan_add_option_to_device[3],
 linkman:nutscan_add_device_to_device[3], linkman:nutscan_cidr_to_ip[3],

docs/man/nutscan_scan_eaton_serial.txt

@@ -40,6 +40,9 @@ linkman:nutscan_init[3],
 linkman:nutscan_scan_usb[3], linkman:nutscan_scan_xml_http_range[3],
 linkman:nutscan_scan_snmp[3], linkman:nutscan_scan_avahi[3],
 linkman:nutscan_scan_ipmi[3], linkman:nutscan_display_ups_conf[3],
+linkman:nutscan_display_sanity_check[3],
+linkman:nutscan_display_sanity_check_serial[3],
+linkman:nutscan_display_ups_conf_with_sanity_check[3],
 linkman:nutscan_display_parsable[3], linkman:nutscan_new_device[3],
 linkman:nutscan_free_device[3], linkman:nutscan_add_option_to_device[3],
 linkman:nutscan_add_device_to_device[3],

docs/man/nutscan_scan_ipmi.txt

@@ -50,7 +50,11 @@ SEE ALSO
 linkman:nutscan_init[3],
 linkman:nutscan_scan_usb[3], linkman:nutscan_scan_xml_http_range[3],
 linkman:nutscan_scan_nut[3], linkman:nutscan_scan_avahi[3],
-linkman:nutscan_scan_snmp[3], linkman:nutscan_display_ups_conf[3],
+linkman:nutscan_scan_snmp[3],
+linkman:nutscan_display_sanity_check[3],
+linkman:nutscan_display_sanity_check_serial[3],
+linkman:nutscan_display_ups_conf_with_sanity_check[3],
+linkman:nutscan_display_ups_conf[3],
 linkman:nutscan_display_parsable[3], linkman:nutscan_new_device[3],
 linkman:nutscan_free_device[3], linkman:nutscan_add_option_to_device[3],
 linkman:nutscan_add_device_to_device[3], linkman:nutscan_scan_eaton_serial[3],

docs/man/nutscan_scan_nut.txt

@@ -46,7 +46,11 @@ SEE ALSO
 linkman:nutscan_init[3],
 linkman:nutscan_scan_usb[3], linkman:nutscan_scan_xml_http_range[3],
 linkman:nutscan_scan_snmp[3], linkman:nutscan_scan_avahi[3],
-linkman:nutscan_scan_ipmi[3], linkman:nutscan_display_ups_conf[3],
+linkman:nutscan_scan_ipmi[3],
+linkman:nutscan_display_sanity_check[3],
+linkman:nutscan_display_sanity_check_serial[3],
+linkman:nutscan_display_ups_conf_with_sanity_check[3],
+linkman:nutscan_display_ups_conf[3],
 linkman:nutscan_display_parsable[3], linkman:nutscan_new_device[3],
 linkman:nutscan_free_device[3], linkman:nutscan_add_option_to_device[3],
 linkman:nutscan_add_device_to_device[3], linkman:nutscan_scan_eaton_serial[3],

docs/man/nutscan_scan_snmp.txt

@@ -82,7 +82,11 @@ SEE ALSO
 linkman:nutscan_init[3],
 linkman:nutscan_scan_usb[3], linkman:nutscan_scan_xml_http_range[3],
 linkman:nutscan_scan_nut[3], linkman:nutscan_scan_avahi[3],
-linkman:nutscan_scan_ipmi[3], linkman:nutscan_display_ups_conf[3],
+linkman:nutscan_scan_ipmi[3],
+linkman:nutscan_display_sanity_check[3],
+linkman:nutscan_display_sanity_check_serial[3],
+linkman:nutscan_display_ups_conf_with_sanity_check[3],
+linkman:nutscan_display_ups_conf[3],
 linkman:nutscan_display_parsable[3], linkman:nutscan_new_device[3],
 linkman:nutscan_free_device[3], linkman:nutscan_add_option_to_device[3],
 linkman:nutscan_add_device_to_device[3], linkman:nutscan_scan_eaton_serial[3],

docs/man/nutscan_scan_usb.txt

@@ -33,7 +33,11 @@ SEE ALSO
 linkman:nutscan_init[3],
 linkman:nutscan_scan_snmp[3], linkman:nutscan_scan_xml_http_range[3],
 linkman:nutscan_scan_nut[3], linkman:nutscan_scan_avahi[3],
-linkman:nutscan_scan_ipmi[3], linkman:nutscan_display_ups_conf[3],
+linkman:nutscan_scan_ipmi[3],
+linkman:nutscan_display_sanity_check[3],
+linkman:nutscan_display_sanity_check_serial[3],
+linkman:nutscan_display_ups_conf_with_sanity_check[3],
+linkman:nutscan_display_ups_conf[3],
 linkman:nutscan_display_parsable[3], linkman:nutscan_new_device[3],
 linkman:nutscan_free_device[3], linkman:nutscan_add_option_to_device[3],
 linkman:nutscan_add_device_to_device[3], linkman:nutscan_scan_eaton_serial[3]

docs/man/nutscan_scan_xml_http_range.txt

@@ -48,7 +48,11 @@ SEE ALSO
 linkman:nutscan_init[3],
 linkman:nutscan_scan_usb[3], linkman:nutscan_scan_snmp[3],
 linkman:nutscan_scan_nut[3], linkman:nutscan_scan_avahi[3],
-linkman:nutscan_scan_ipmi[3], linkman:nutscan_display_ups_conf[3],
+linkman:nutscan_scan_ipmi[3],
+linkman:nutscan_display_sanity_check[3],
+linkman:nutscan_display_sanity_check_serial[3],
+linkman:nutscan_display_ups_conf_with_sanity_check[3],
+linkman:nutscan_display_ups_conf[3],
 linkman:nutscan_display_parsable[3], linkman:nutscan_new_device[3],
 linkman:nutscan_free_device[3], linkman:nutscan_add_option_to_device[3],
 linkman:nutscan_add_device_to_device[3], linkman:nutscan_scan_eaton_serial[3]