NUT v2.8.3

NOTE: Currently tagged as v2.8.3-rc2; if it passes CI - will be additionally/re- tagged as THE release.

For MANY more details 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

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 by upscli_set_default_connect_timeout(), retrieved by upscli_get_default_connect_timeout(), and initialized from various sources by priority, including: libupsclient or program built-in defaults, config-file settings, a NUT_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.
  • 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 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.

• Driver changes:

  • WARNING: apc_modbus - known issues remain with RTU USB support, does not work reliably
  • 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 r...

NUT v2.8.2, is it here, is it not?

While trying to set up some semblance of a proper release cadence, as well as hoping to tag a new NUT release at this or that "pretty date" time and again, something urgent kept popping up to delay the release. Still, looking month-to-month, this release is 2 years after v2.8.0, so we're on track to yearlies. Maybe quarterlies would not be impossible - just gotta manage expectations and the number of planned milestones :)

As a fun fact, some development work for this release was done directly on an Android phone (Termux app sufficiently delivers a native-architectured Debian/Linux environment), and the release is being cut from a storm in the Northern (Icy) Ocean, enchanted by the ethereal shine of the Polar lights... Interesting times, indeed...

The NUT v2.8.2 release ties up more loose ends from earlier development branches and forks, complete with warnings clean-up and Windows portability where possible/easy, bringing in nutconf (a C++ library to interact with NUT configs and more, and the frontend tool for it), an interactive CLI installer contributed from a vendor's bundling of NUT, more features for the nut-driver-enumerator (NDE), several improvements for the nut-scanner, as well as refinement, enhancements and bug-fixing for features (and odd regressions) added in the recent releases.

Some user-reported issues between their devices and such drivers as riello_usb and usbhid-ups subdriver for Belkin/Liebert support, were also added. It is always pleasant to note the collaborations which happen online, with NUT community members addressing many issues by themselves.

Much non-functional activity revolved around CI-related improvements, including migration of the NUT CI farm from Fosshost (RIP) to Digital Ocean, and revised build recipes with improved portability (especially for documentation builds).

As usual, for more details, see the NEWS.adoc and UPGRADING.adoc files, or even peruse the ChangeLog document.

The next treat on the menu in a future release can be the remainder of the 42ity fork, such as DMF technology support - it finally passed the new strict quality gates of NUT CI that appeared for v2.8.0 release and have evolved ever since. This work informed many pointed fixes for the upstream project, which are included in this release.

NOTE: The initially posted tarball signature file did not pass checks on some systems and was replaced by one made on a different maintainer workstation after a week.

NUT v2.8.1, now with Windows support (again) 🎃

NUT v2.8.1 release: TLDR version

Generally you can preview the live list of notable changes since 2.8.0 release at https://networkupstools.org/historic/v2.8.1/docs/release-notes.chunked/NUT_Release_Notes.html#_release_notes_for_nut_2_8_1_what_8217_s_new_since_2_8_0 and for things that are expected to impact packaging and upgrades (whether by some possibly breaking disruption, or by adding new ways to automate things more efficiently that the audience could benefit from) - at https://networkupstools.org/historic/v2.8.1/docs/release-notes.chunked/NUT_Upgrading_Notes.html#_changes_from_2_8_0_to_2_8_1 - with such release notes publication also being a recent addition.

NUT for Windows is back!

Older development of NUT for Windows was modernized over the past 15 months or so, and was merged as part of main codebase (in 2022, post-v2.8.0). Still, caveat emptor!

Better read up in comments to #5 and #1611 and #1050 to an extent. The short of it is that syntactically NUT builds pass without warnings, and survive integration tests (upsd data server and some dummy-ups driver setups). The binaries can be executed on the platform, drivers can see physical UPS devices and upsd represents them on the network; deeper integration was not tested much yet.

Builds are doable in linux+mingw (using an older build script to arrange configure options) and in Windows+MSYS2 with plain configure or same ci_build.sh as CI builds on other platforms use to arrange it. Prerequisites are listed in scripts/Windows/README and docs/config-prereqs.txt respectively (or now also actionably wrapped by appveyor.yml). Parts of serial driver codebases are ifdef-ed away.

In particular, "purely native" builds (e.g. with Visual Studio) were not attempted yet, not that I know of. The goal was to have something usable first, so first winners were even two - GCC builds with mingw (on linux and in MSYS2), with ccache recommended for faster iterations, with x86_64 and i686 targets. Probably clang is doable, but was not tried yet. Passing in custom CFLAGS into MSYS2 builds (as pre-set envvars or configure argument) caused issues for that build of gcc itself (somehow became part of path it is trying to build in). There are more variants of standard library to juggle too (UCRT etc.) for portability across Windows releases vs. modernity.

Due to availability/easy-buildability of third-party dependencies, these build scenarios currently have some non-overlapping results (notably libgd/cgi, snmp and neon/xml are known inconsistencies).

USB HID may need more work, possibly installing a low-level driver in OS, to see devices in detail. See one practical success story at #1690 (comment)

Maybe that was solved by predecessors in MSI packaging, not re-investigated yet with recent effort. The need for that research is tracked as #1485

These and other known caveats can be seen in NUT for Windows project as open tickets in https://github.com/orgs/networkupstools/projects/2/views/1 project.

Happy Halloween!

NUT v2.8.0+, now with Windows support

Older development of NUT for Windows was modernized over past months, and now merged as part of main codebase (post-v2.8.0). Caveat emptor!

Better read up in comments to #5 and #1611 and #1050 to an extent. The short of it is that syntactically NUT builds pass without warnings, and survive integration tests (upsd and some dummy-ups setups).

Doable in linux+mingw (using an older build script to arrange configure options) and in Windows+MSYS2 with plain configure or same ci_build.sh as CI builds on other platforms use to arrange it. Prerequisites are listed in scripts/Windows/README and docs/config-prereqs.txt respectively (or now also actionably wrapped by appveyor.yml). Known caveats are in NUT for Windows project as open tickets in https://github.com/orgs/networkupstools/projects/2/views/1 project.

In particular, "purely native" builds (e.g. with Visual Studio) were not attempted yet, not that I know of. The goal was to have something usable first, so first winners were even two - GCC builds with mingw (on linux and in MSYS2), with ccache recommended for faster iterations, with x86_64 and i686 targets. Probably clang is doable, but was not tried yet. Passing in custom CFLAGS into MSYS2 builds (as pre-set envvars or configure argument) caused issues for that build of gcc itself (somehow became part of path it is trying to build in). There are more variants of standard library to juggle too (UCRT etc.) for portability across Windows releases vs. modernity.

Due to availability/easy-buildability of third-party dependencies, these build scenarios currently have some non-overlapping results (notably libgd/cgi, snmp and neon/xml are known inconsistencies).

USB HID may need more work, possibly installing a low-level driver in OS, to see devices in detail. Maybe that was solved by predecessors in MSI packaging, not re-investigated yet with recent effort.

Parts of serial driver codebases are ifdef-ed away.

v2.6.5-8-Windows

Old(!!!) NUT-for-Windows effort recently attempted with (partially) modern dependencies, cross-built on Ubuntu per instructions in code, published more as a proof of concept for progressing on issue #5 than for production use.

NUT v2.8.0 (un-signed)

This is a re-post of the release artifacts to keep download URLs based on original vX.Y.Z git tag pattern, as used by distro recipes, intact. Such URLs got broken after addressing issue #1410, as reported later in issue #1971.

For release details, please see https://github.com/networkupstools/nut/releases/tag/v2.8.0-signed

NUT v2.8.0-rc3

A third and hopefully final rehearsal for a pending NUT release, initially focused on updating sources for the documentation published on the nut-website and API to match the large changes, and also fixing a few bugs noted with the intensified testing after v2.8.0-rc1 and v2.8.0-rc2 - especially some found while integrating the new NIT (NUT Integration Testing) suite.

Welcome NUT-EEE (the Easter Egg Edition, because why not - it sounds cute?) ;)

NUT v2.8.0-rc2

A second rehearsal for a pending NUT release, fixing a few bugs noted with the intensified testing after v2.8.0-rc1, and landing some more old pull requests.

Again, production-like testing on as many platforms as possible (including proposed service management integration for systemd and SMF) would be very welcome!

UPDATE: Attached tarball was re-published due to corruption of initially uploaded one.

NUT v2.8.0 (signed)

After a long and windy trip since the last official release v2.7.4 half a dozen years ago, we the community, contributors and maintainers are proud to announce at last the general availability of NUT v2.8.0!

As always, the new release includes numerous new drivers, sub-drivers, protocols and bug-fixes, with many companies and individuals chipping in with contributions of code.Thanks to everyone involved in making this happen, inspiring the changes, and providing the open-source friendly infrastructure.

This release also culminates a significant effort in improvements of NUT QA and CI, and as a result -- in codebase quality and portability across a decade or two of recent platforms, third-party tools and other dependencies. As a side effect, public API (in headers and libraries) has changed a bit, hence a new semantic "minor" number is claimed for this major body of work.

During this time, the https://networkupstools.org/ web site has changed to a rolling-release model to serve current information to match the evolving codebase. There are now special Sub-sites for historic releases to keep documentation snapshots relevant for users of packages which are typically based on official NUT releases.

We recognize that NUT is an important piece of infrastructure which gets built into all sorts of devices, projects and operating systems -- some of which the team never heard of until they pop up in a question, and others we haven't heard of for years -- so we take a seriously omnivorous stance towards covering many versions and implementations of compiler suites, C/C++ revisions, make programs, shell and other scripted language interpreters, OSes and CPUs, and other similar variables tamed with our new NUT CI farm test matrix dynamically driven by currently registered build agents and their declared capabilities.

Sections in the NEWS and UPGRADING files about changes since last release are several pages long, so would not all be repeated here. A few important highlights for distribution packagers and custom builders follow, however:

• NUT now supports more i2c and modbus devices, as well as libusb-1.0 support as an alternative to earlier libusb-0.1 (so new dependency-based categories of packages for drivers may be due);
• NUT Python modules and scripts (e.g. NUT-Monitor variants) should work with python-2.7 and with python-3.x, so covering historic distro releases as well as new ones (and so your distro can deliver one or both, probably in several packages with different dependencies in the latter case);
• NUT provides revised reference systemd and SMF service unit definitions, including support of drivers wrapped into individual service instances with varying dependencies based on different media required (networked stack, USB stack, etc.), and many daemons include -F option for running "in foreground" to avoid extra forking after one already done by a service framework - you may want to use those in your packaged deliverables;
• NUT newly provides the "nut-driver-enumerator" script and service, which allows it to follow edition of ups.conf and dynamically define+(re)start and stop+undefine service instances for drivers - there are several ways it can be integrated for different use-cases;
• there are several new configuration keywords and CLI options - so while new NUT builds should work with old configs and scripts, the opposite is not necessarily true (old binaries may reject configurations taking advantage of new features);
• there are several new protocol keywords - but old and new NUT daemons (data server and clients) should be able to communicate both ways;
• it is assumed that API/ABI changes may require third-party NUT clients (library consumers of libnutclient, libupsclient, libnutscan... -- their version info was bumped accordingly) to get rebuilt, in order to work with the new NUT release in a stable fashion;
• the dummy-ups driver used in automated testing now processes *.dev filename patterns once and does not loop, like it still does for *.seq and other files (by default);
• USB code is now more strict about logical minimum/maximum ranges for data reported from devices, and some devices were already found to make mistakes - so there is also a mechanism for turning a blind eye to known issues and fix-up such report descriptors to produce intended sane values;
• new documentation page docs/config-prereqs.txt highlights packaged dependencies installable on a large range of platforms to build as much of NUT as possible (incidentally, ones NUT CI farm uses to test every iteration);
• finally, we hope that NUT codebase might be able to cater for everyone "out of the box" (it also simplifies local builds from GitHub sources on any systems, for troubleshooting and checking pre-release enhancements): if you as a packager have to apply patches for your distribution, give it a thought -- whether they address a common issue best solved upstream once and behave similarly for everyone (and conversely, if your platform can do with existing solutions already tracked in the NUT version du-jour). PRs welcome! Or at least Wiki entries to list all the distro efforts for cross-pollination :)

A lot of effort and several rounds of community testing have gone into making sure that all these new features and bug-fixes and addressed warnings did not break anything severely, but... things might happen.

Still, there is always room for improvement and many known efforts that did not make it into this release got queued into the next. Likewise, there are some open issues about device/model/firmware-specific behaviors that are known but were not even addressed - we would always welcome help and PRs from community members with devices, debugging/coding skills, and time to spare.

In any case, we hope the next NUT releases will happen in a more manageable cadence ;)

Managing power can be fun, but mis-managing power can be dangerous. While we hope that new NUT release would not have fallout as spectacular and dramatic as from a certain other power monitoring and management system that failed 36 years ago today, please do take care with your electric experiments, and do secure your installations!

NOTE: After this release was cut, it was found that a late-coming feature did not let dummy-ups build on MacOS. A fix and ways to avoid such mishap from repeating are investigated under issue #1415 and would be part of next NUT release. Until then, you may have to build from master branch.

NUT v2.8.0-rc1

Hello, fellow NUTs!

It is with a [happy] heart that I must proclaim today, that the long reign of NUT v2.7.4 is coming to an end. Its anticipated successor of half a dozen years, release-in-waiting NUT v2.7.5 has also quietly expired, and [won't] be sorely missed. They were survived by the next name in line, NUT v2.8.0(-rc1). Le NUT est mort, long live the NUT!

Along just this leg of the journey, NUT codebase survived at least four separate CI farms and technologies to make its builds easier and more reliable, all while succeeding on a wide range of CPU and OS platforms, ranging from current distros to the dawn of millenium (nearly-immutable appliances and sturdy reliable servers matter too!), as well as multiple generations and implementations of compiler toolkits, "make" and scripted code interpreters involved.

We are grateful to the many freely available projects, services and communities who helped us in particular (maybe unwittingly) and the FOSS ecosystem in general (intentionally), such as (and not limited to) Asciidoc, Autotools and family, BuildBot, CCache, Clang/LLVM, FossHost, GCC, GitHub, Google, illumos, Jenkins, LiberaChat, Proxmox, QEMU, StackExchange, Travis, ZeroMQ... bits here, swathes there - it would have been much harder without the likes of them (and many others).

Advances in compiler code analysis in particular, as is seen on a daily basis with CI non-regression builds across the range of 10 major releases of clang and 7 of gcc, are immense. At times annoying, yes, but they led to a great cleansing of the codebase from questionable code (and indeed some potential bugs). And it was possible to do so in a way that all those regularly tested systems are satisfied, so the codebase stays clean and green and portable as we iterate new contributions, and merged with peace of mind many ports and features from long-awaited branches (such as libusb-1.0+0.1 support finally), or forks (notably 42ity/nut).

Let me take a moment to tender our special thanks from both the maintainer team and countless users of UPS, ePDU, solar panel and similar hardware, to numerous personal and corporate contributors of new drivers and features or fixes for existing ones, as well as to community members who ask and answer questions, and who log github issues with their ideas, experiences or grievances.

As always we would welcome people willing to regularly share their expertise in certain areas and tools (such as solving many practical mysteries around USB), or protocols (more active experts on prolific Qx family would be great for PR reviews), or packaging, service and distro integrations, or HCL/DDL maintenance based on reports trickling in... just about anything!

While we have a lot of features queued to complete or port for the next releases (hopefully with a healthier cadence), we expect to see more feedback by exposing the release, and hope for little fallout from the many changes made while cleaning up the warnings.

Handing over to community last-minute testers, and hereby alerting creative packagers now...

Jim Klimov,
on behalf of the Network UPS Tools Project