Network UPS Tools Files

For MANY more details please see release notes in NEWS.adoc or rendered as https://networkupstools.org/docs/release-notes.chunked/NUT_Release_Notes.html#_release_notes_for_nut_2_8_3_what_8217_s_new_since_2_8_2 and UPGRADING.adoc or rendered as https://networkupstools.org/docs/release-notes.chunked/NUT_Upgrading_Notes.html#_changes_from_2_8_2_to_2_8_3

Some errata already applies:

• https://github.com/networkupstools/nut/pull/2921 (or for hot-fixes, commit https://github.com/networkupstools/nut/pull/2921/commits/2b7e1e56129e2b31b5a681b2ad6b9a070c689de2) : Used a wrong variable name in script, so did not detect that the document types we want are not in fact buildable; the resulting builds did succeed (but without the requested documentation), misleading the builders on half-capable build environments.
• https://github.com/networkupstools/nut/pull/2916 : portability problems with the helpful warning from upsd about "further (ignored) addresses resolved for this name", and a potential (not practically reachable) buffer overflow, both actually introduced in release v2.8.2 but only found and fixed after v2.8.3.

A binary build of NUT for Windows, fetched and renamed from NUT-for-Windows-x86_64-SNAPSHOT-2.8.3.3028-master.7z at AppVeyor CI, is attached (in lieu of a real installer so far).

Highlights of this release:

• New documentation book on NUT Quality Assurance and Build Automation, assimilated a few chapters from Developer Guide and User Manual and introduced a lot of new text.

• API changes:

• Methods to handle strings with unique tokens like ups.status were refactored and exposed in libupsclient library (so stock and third-party NUT clients can parse status with identical approach): upscli_str_add_unique_token() and upscli_str_contains_token()
• For ages, upscli_connect() was a blocking request which waited until interrupted by the system. Now there is a built-in timeout (defaults to 0 for legacy-compatible blocking behavior) which can be modified byupscli_set_default_connect_timeout(), retrieved byupscli_get_default_connect_timeout(), and initialized from various sources by priority, including: libupsclient or program built-in defaults, config-file settings, aNUT_DEFAULT_CONNECT_TIMEOUT` envvar, or CLI options,
• Symbols exported from libupsclient now include nut_debug_level* so that NUT clients can be usefully debugged (e.g. using NUT_DEBUG_LEVEL environment variable).
• "Libs" linker options exposed by pkg-config files for public NUT libraries may now contain RUNPATH settings, when NUT libraries are installed into uncommon locations (not the system-default search path for libraries).
• A NUT SEMVER format was defined, complete with documentation and scripting. It builds upon the common three-number SEMVER, adding a few components with certain meanings, which can be populated for non-release iterations. In same bundle of changes, the variables for NUT_WEBSITE_BASE can be set for rolling-development or historic release snapshot URLs.
• Some work was done in documentation and code to streamline handling of "ECO" concept (or Green, or High Efficiency, or Smart, or...) which every vendor defines differently - and some of their models/firmwares might have varying opinions about as well - balancing such vague buzzwords with general vendor-neutrality of NUT reported data points or commands. This work is likely to continue in future releases, but some practical results may be tried on certain series of MGE/Eaton USB devices already.
• More symblols exposed by libnutscan
• Newly optionally delivering libnutconf, just in case someone would want to use it rather than command-line nutconf tool (arguably the tool's API may be more stable, as that project is slowly getting assimilated into NUT code base). Note: if build of the shared libnutconf is enabled, it would be required packaged along with the tool (otherwise it is statically built into the tool program).
• The PyNUTClient no longer relies on telnetlib (was part of Python "batteries included" core since forever until 3.13)

• Added many man pages

• Various NUT program changes:

• The new ability to modify default connection timeout is used by a number of stock NUT clients, including upsc, upscmd, upsrw, upslog, upsmon, upsimage, upsset and upsstats (so they only try 10 seconds by default). Some have added a command-line option -W NUM to modify this timeout, all can rely on envvar handling.
• The NUT_WEBSITE_BASE is used to provide links to rendered documentation from tools' help/usage messages, systemd/SMF service definitions, etc.
• The NUT-Monitor Python GUI localization and About dialog message (with links to NUT Website) were revised.
• The pynutclient tarball for PyPI repository was renamed (lower-cased) per their updated requirements. Python class naming remains camel-cased as PyNUTClient.
• Man page section numbers/names are not same on all operating systems, so some packaging recipes had to patch their build areas to fix generated files; now NUT recipes and configure file support such rewrites to be done as part of vanilla build.
• SystemD "presets" are now delivered to automatically enable/disable an opinionated selection of NUT service units (there are many variants for different use-cases, as documented in that file and elsewhere, but here one size fits most cases - others can customize theirs).
• The upslog client got some feature revision, and became an optional nut-logger service (systemd/SMF).
• For some platforms, upsmon should better handle system sleep/hibernation; more on this may be done in later releases for other platforms.
• The upsmon client now reports the UPSes entering/exiting a lot more states, including OVER(load), TRIM, BOOST and ALARM, as well as logging of unsupported (non-standard) tokens. The ALARMCRITICAL setting controls whether presence of alarms can impact decisions about shutting down the system. Similarly it can now manage overload notifications and criticality with OVERDURATION setting.
• Improved search for dynamically loaded shared libraries, notably by nut-scanner - it previously looked for short symlinks like libname.so or libname.so.1 on most platforms - and these are only delivered by additional (development) packages on some; now it should also check the exact library file name it was built against (e.g. libname.so.1.2.3) among the options it tries.
• Programs which can signal their earlier instances (e.g. to reload configs or to kill off a stale driver) now should try to check the file name associated with the PID, in order to not signal unrelated programs (e.g. system rebooted, PID file remained on a persistent file system).
• A NUT_DEBUG_SYSLOG environment variable was introduced to tweak activation of syslog message emission (and related detachment of stderr when daemons are backgrounding), which can be useful for systemd service units. It can be set via nut.conf file for all standard consumers, or patched/dropped-in to systemd unit definitions specifically (less recommended, but may be easier to package). The positive effect would be avoiding duplicate logging as both syslog and stderr ending up in the same journal.
• Extended upsdrvctl with a list operation (or -l option) to report manageable device configuration names (possible <ups> arguments to start, stop etc. operations), or to confirm a single name that it is known, and a status operation for more information.
• The upsdrvctl should now warn if executed on systems where NUT was built with support for service management frameworks like systemd or SMF, so nut-driver service units prepared by nut-driver-enumerator would conflict with manually-executed driver programs.
• Demon messages about failing to notify an absent service subsystem should now be less cryptic (report names not numbers of respective data points)
• Reduce "scary noise" about failure to fopen() the PID file
• upsd failure to LISTEN on an invalid host name (e.g. localhost:3493 or 1.2.3.4/24) is now logged in a more actionable manner.
• Many (envvar-driven) options added to reduce noise when starting NUT programs (banner, SSL, notification subsystem...); legacy behaviors mostly left in place by default
• Drivers would now report the socket they are listening on, and server would report full path to the driver socket it tries to connect to.
• Revised nut.exe (the NUT for Windows wrapper for all-in-one service) to be more helpful with command-line use
• Introduced a simple experiment to expose NUT client readings as filesystem objects via FUSE, in scripts/fuse/execfuse-nut now. Not production-ready nor efficient, rather a PoC of possible future work.

• Revise some messages from CLI tools

• Driver changes:

• WARNING: apc_modbus - known issues remain with RTU USB support, does not work reliably
• Report libmodbus linking type in drivers with it;
• Troubleshooting of USB drivers with LIBUSB_DEBUG=INTEGER setting in ups.conf (as well as an environment variable)
• All drivers should now support the optional sdcommands setting with a site-local list of instant commands to handle upsdrv_shutdown(), which may be useful in cases when the driver’s built-in commands (or their order) do not meet the goals of particular NUT deployment. This can also help with shutdown endgame testing, using a mock command like starting the beeper (where supported) to verify that the UPS communications happen as expected, without compromising the load connected to the UPS. During this overhaul, many older drivers got their first ever supported INSTCMD such as shutdown.return, shutdown.stayoff or load.off. Default logic that was previously the content of upsdrv_shutdown() methods was often relocated into new shutdown.default INSTCMD definitions.
• usbhid-ups
  • APC BXnnnnMI devices built cca 2023-2024 send spurious updates about going offline/online and lowbatt/replacebatt and back, sometimes several times an hour; this is likely internal detail of their calibration, so options were added to suppress such events if they are short-lived (lbrb_log_delay_sec, see also onlinedischarge_calibration and lbrb_log_delay_without_calibrating)
  • CPS HID - changed some timings; more data from some cps-hid devices and revised broken USB descriptor fix-up
  • PowerCom HID - sent shutdown/stayoff commands wrong, at least as current models see that byte stream. If older devices did want the bytes inverted, a fallback config option is provided.
• snmp-ups - updated Netvision MIB
• GPIO drivers - support old and new libgpiod (v1.x vs. v2.x)
• riello_ser - added localcalculation option to compute battery.runtime and battery.charge if the device provides bogus values (similar to runtimecal in some other drivers, may be refactored to that configuration and logic model in later NUT releases)
• apcsmart - should try fully reconnecting upon getting into a prolonged data stale condition

New drivers/devices: * usbhid-ups - added new subdrivers (EcoFlow River 3 Plus and Delta 3 Plus; KSTAR now found also on new VID:PID combo; updated detection of some PhoenixTec devices on a different VID:PID; more MGE/Eaton models) * nutdrv_qx - added many protocols (innovart31, q2, q6, gtec...) and fixed some older issues * snmp-ups - added Baytech RPC3-NC PDU MIB * bicker_ser - added new driver for Bicker 12/24Vdc UPS via RS-232 serial communication protocol, which supports any UPS shipped with the PSZ-1053 extension module. * liebert-gxe - added new driver with support for Liebert GXE Series UPS (serial or USB posing as a serial port). * nhs_ser - added new driver for numerous NHS Nobreaks, senoidal line — UPS models with serial port, made by NHS Sistemas Eletronicos LTDA and popular in Brazil. Currently this driver only builds on Linux. * Introduced a new driver concept for interaction with OS-reported hardware monitoring readings. Currently instantiated as hwmon_ina219 specifically made for Texas Instruments INA219 chip as exposed in the Linux "hwmon" subsystem of its "sysfs" interface. * phoenixcontact_modbus driver: Introduced Phoenix Contact QUINT4-UPS/24DC management (only new modbus addresses). * added scripts/external_apis with an example script integrating a non-native protocol with NUT via dummy-ups; that example can be installed using configure --enable-extapi-enphase.

• Recipe/CI changes:
• Lines in first section of NUT configuration report are now better grouped as miscellaneous features and detection results, then drivers and programs/tools. The report can optionally remain as config.nut_report_feature.log and be installed into shared documentation of a NUT package.
• Faster parallel (re-)builds and spell-checks, notably with make spellcheck-interactive-quick for developers
• Fixed custom make distcheck-something processing
• Stricter make dist operations, so all man page files must be pre-populated for the archive (whether inherited, generated, or explicitly faked with placeholders for testing)
• Enabled installation of built PDF and HTML (including man page renditions) files under the configured docdir. It seems previously they were only built (if requested) but not installed via make, unlike the common man pages which are delivered automatically. Packaging recipes can likely be simplified now.
• Improved out-of-the-box integration with valgrind
• Revised the scripts/Windows/build-mingw-nut.sh helper script for the different ARCH values to be built in dedicated subdirs
• Cross-builds using only a host implementation of pkg-config program should now ignore host *.pc files and avoid confusion.
• Introduced make install-as-root to create directories not directly populated by make install and NUT build artifacts, apply permissions and (on some platforms) restart services involved with NUT.