This file lists changes that affect users who installed older versions of this software. When upgrading from an older version, be sure to check this file to see if you need to make changes to your system.
For packaging (OS distribution or in-house) it is recommended to
primarily ./configure --with-all and then excise --without-something
explicitly for items not supported on your platform, so you do not miss
out on new NUT features as they come with new releases. Some may require
that you update your build environment with new third-party dependencies,
so a broken build of a new NUT release would let you know how to act.
This is a good time to point out that for stricter packaging systems, it may
be beneficial to add --enable-option-checking=fatal to the ./configure
command line, in order to quickly pick up any other removed option flags.
VERSION_DEFAULT file, so it can be used without git. Certain distros
can benefit from a VERSION_FORCED file or a NUT_VERSION_FORCED
environment variable exported from their build system, e.g. via
echo NUT_VERSION_FORCED=1.1.1 > VERSION_FORCED. Unfortunately, some
appliances tag all software the same with their firmware version;
if this is required, a (NUT_)VERSION_FORCED_SEMVER envvar or file can
help identify the actual NUT release version triplet used on the box.
Please use it, it immensely helps with community troubleshooting!
[issue #1949]
upsmon should now integrate natively with systemd-driven OS sleep events
(built with systemd version 221 or newer "inhibitor interface"), so various
hacks previously packaged into /usr/lib/systemd/system-sleep/ scripts or
units requiring/conflicting with the sleep.target may be obsolete.
For fallback with older systemd, a nut-sleep.service is provided now.
[#1070, #2596, #2597]
ALARM state was introduced to upsmon, allowing it
to optionally treat it as a factor in deciding that the device is in a
"critical" state (polled more often, assumed dead if communications are
lost). Since it is up to devices and their NUT drivers what they would
raise as an alarm (might be something as mundane as ECO mode being active),
some alarms can contribute to unwanted/early shutdowns. For this reason
a 0|1 setting ALARMCRITICAL was introduced into upsmon.conf (default
is 1), for such users to be able to prevent their upsmon from treating
the ALARM status as overly severe when it is not in fact. [#2658]
usbhid-ups subdriver PowerCOM HID subdriver sent UPS shutdown and
stayoff commands in wrong byte order, at least for devices currently
in the field. Driver now sends the commands in a way that satisfies new
devices; just in case a flag toggle powercom_sdcmd_byte_order_fallback
was added to set the old behavior (if some devices do need it). [PR #2480]
lbrb_log_delay_sec=N setting to delay propagation of
LB or LB+RB state (buggy with APC BXnnnnMI devices/firmwares issued
circa 2023-2024 which flood the logs with spurious LOWBATT and REPLACEBATT
events). This may work better for some devices when combined with flags
like onlinedischarge_calibration and lbrb_log_delay_without_calibrating.
[#2347]
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. [#2445]
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. [#2394]
CHANGELOG_REQUIRE_GROUP_BY_DATE_AUTHOR setting was added (for make
calls and used by tools/gitlog2changelog.py.in script), and it defaults
to true allowing for better ordered documents at the cost of some memory
during document generation. Resource-constrained builders (working from
a Git workspace, not tarball archives) may have to set it to false when
calling make for NUT. [#2510]
nut-scanner, which dynamically load shared libraries
at run-time without persistent pre-linking, should now know the library
file names that were present during build (likely encumbered with version
suffixes), and prefer them over plain libname.so patterns used previously
(which on some platforms are only delivered by development packages as
symlinks). Packaging recipes can likely be simplified now: some distros
certainly did patch NUT source to similar effect). [#2431]
nut-scanner and symbols that its libnutscan.so
delivers have caused a library version bump. New methods have been added
and one structure (nutscan_ipmi_t) updated in a (hopefully) backwards
compatible manner. [PR #2523, issue #2244 and numerous PRs for it]
sendsignalpid() and sendsignalfn() methods,
which can impact NUT forks which build using libcommon.la and similar
libraries. Added new last argument with const char *progname (may be
NULL) to check that we are signalling an expected program name when we
work with a PID. With the same effort, NUT programs which deal with PID
files to send signals (upsd, upsmon, drivers and upsdrvctl) would
now default to a safety precaution — checking that the running process
with that PID has the expected program name (on platforms where we can
determine one). This might introduce regressions for heavily customized
NUT builds (e.g. embedded in NAS or similar devices) whose binary file
names differ significantly from a progname defined in the respective
NUT source file, so a boolean NUT_IGNORE_CHECKPROCNAME environment
variable support was added to optionally disable this verification.
Also the NUT daemons should request to double-check against their
run-time process name (if it can be detected). [issue #2463]
More environment variable support was added to NUT programs, primarily
aimed at wrappers such as init scripts and service unit definitions,
allowing to tweak what (and whether) they write into debug traces, and
so "make noise" or "bring invaluable insights" to logs or terminal;
they can generally be used for services and init scripts via nut.conf:
configure script option to build --with-modbus+usb was added to
let the caller insist on the use of USB-capable libmodbus (or fail the
NUT build attempt). Certain build arguments can default this option to
become enabled (implicitly): configure --with-modbus --with-usb and
either --with-drivers=*apc_modbus* (actually implies --with-modbus)
or --with-modbus-includes=... --with-modbus-libs=...
as a way to avoid surprises with custom NUT builds aiming to have an
USB-capable apc_modbus driver (currently this requires a custom-built
libmodbus, can be a static build to avoid conflicts with OS). [#2666]
configure script option to --enable-NUT_STRARG-always was added
to enable the NUT_STRARG macro (to handle NULL string printing)
even if system libraries seem to safely support this behavior natively.
This should primarily help against overly zealous static analysis tools
in recent compiler generations. [#2585]
language standard revision via
CFLAGS and CXXFLAGS should again be honoured. There was a mishap
with the m4 scripting for autoconf which could have caused use of
C11/C11 if compiler supported it, regardless of a request. [PR #2306]
$datadir e.g. /usr/local/share/nut
and need to be pasted into your /boot/loader.conf.local). [#2159]
bus, busport and device
values when generating device configurations by default. They may
appear as comments, or enabled by specifying the -U command-line
option several times. [#2221]
tools/gitlog2changelog.py.in script was revised, in particular to
convert section titles (with contributor names) into plain ASCII character
set, for dblatex versions which do not allow diacritics and other kinds
of non-trivial characters in sections. A number of other projects seem to
use the NUT version of the script, and are encouraged to look at related
changes in configure.ac and Makefile.am recipes. [PR #2360, PR #2366]
*.adoc pattern. Newly, a release-notes.pdf and HTML
equivalents are generated. Packages which deliver documentation may need
to update the lists of files to ship. [#1953] Developers may be impacted
by new configure --enable-spellcheck toggle (should add spelling checks
to make check by default, if tools are available) to facilitate quicker
acceptance of contributions. Packaging systems may now want to explicitly
disable it, if it blocks package building (pull requests to update the
docs/nut.dict are a better and welcome solution). [#2067]
Several improvements regarding simultaneous support of USB devices that were previously deemed "identical" and so NUT driver instances did not start for all of them:
ups.conf options for that [#1763], and man pages were
updated to reflect that [#1766];
nut-scanner tool should suggest these options in its generated
device configuration [#1790]: hopefully these would now suffice for
sufficiently unique combinations;
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;
allow_duplicates
flag (caveat emptor!) which may help monitor several related no-name
devices on systems that do not discern "bus" and "device" values
(although without knowing reliably which one is which… sometimes it
is better than nothing) [#1756].
int type). Now such
entities are named TYPE_FD, TYPE_FD_SER or TYPE_FD_SOCK with some
helper macros to name and determine "invalid" values (closed file, etc.)
Some of these changes happened in NUT header files, and at this time it
was not investigated whether the set of files delivered for third-party
code integration (e.g. C/C++ projects binding with libnutclient or
`libupsclient) is consistent or requires additional definitions/files.
If something gets broken by this, it is a bug to address in future [#1556]
Further revision of public headers delivered by NUT was done, particularly
to address lack of common data types (size_t, ssize_t, uint16_t,
time_t etc.) in third-party client code that earlier sufficed to only
include NUT headers. Sort of regression by NUT 2.8.0 (note those consumers
still have to re-declare some numeric variable types used) [#1638]
make install of PyNUT module and NUT-Monitor desktop
application — such activity was earlier done by packages directly; now
the packaging recipes may use NUT source-code facilities and package just
symlinks as relevant for each distro separately [#1462, #1504]
upsd.conf listing of LISTEN addresses was previously inverted
(the last listed address was applied first), which was counter-intuitive
and fixed for this release. If user configurations somehow relied on this
order (e.g. to prioritize IPv6 vs IPv4 listeners), configuration changes
may be needed. [#2012]
upsd configured to listen on IPv6 addresses should handle only
IPv6 (and not IPv4-mappings like it might have done before) to avoid
surprises and insecurity — if user configurations somehow relied on
this dual support, configuration changes may be needed to specify both
desired IP addresses. Note that the daemon logs will now warn if a
host name resolves to several addresses (and will only listen on the
first hit, as it did before in such cases). [#2012]
LISTEN * directives became specified, to try
handling both IPv4 and IPv6 "any" address (subject to upsd CLI options
to only choose one, and to OS abilities). This use-case may be practically
implemented as a single IPv6 socket on systems with enabled and required
IPv4-mapped IPv6 address support, or as two separate listening sockets -
logged messages to this effect (e.g. inability to listen on IPv4 after
opening IPv6) are expected on some platforms. End-users may also want to
reconfigure their upsd.conf files to remove some now-redundant LISTEN
lines. [#2012]
make sockdebug for easier developer access to the tool;
also if configure --with-dev is in effect, it would now be installed to
the configured libexec location. A man page was also added. [#1936]
--with-gpio configure script option) -
this may impact packaging decisions on some (currently Linux released 2018+)
distributions going forward [#1855]
configure --with-nut-scanner toggle was added, specifically
so that build environments requesting --with-all but lacking libltdl
would abort and require the packager either to install the dependency
or explicitly forfeit building the tool (some distro packages missed it
quietly in the past) [#1560]
upsdebugx_report_search_paths() method in NUT common code was added,
and exposed in libnutscan.so builds in particular - API version for the
public library was bumped [#317]
Some environment variable support was added to NUT programs, primarily aimed at wrappers such as init scripts and service unit definitions, allowing to tweak what (and whether) they write into debug traces, and so "make noise" or "bring invaluable insights" to logs or terminal:
NUT_DEBUG_LEVEL=NUM envvar allows to temporarily boost debugging
of many daemons (upsd, upsmon, drivers, upsdrvctl, upssched)
without changes to configuration files or scripted command lines. [#1915]
NUT_DEBUG_PID envvar (presence) support was added to add current
process ID to tags with debug-level identifiers. This may be useful
when many NUT daemons write to the same console or log file, such as
in containers/plugins for Home Assistant, storage appliances, etc. [#2118]
NUT_QUIET_INIT_SSL envvar (presence or "true" value) prevents
libupsclient consumers (notoriously upsc) from reporting whether
they have initialized SSL support. [#1662]
NUT_QUIET_INIT_UPSNOTIFY envvar (presence or "true" value)
prevents daemons which can notify service management frameworks (such
as systemd) about passing their lifecycle milestones, to not report
loudly if they could not do so (e.g. running on a system without a
framework, or misconfigured so they could not report and the OS would
restart the false-positively "unresponsive" service). [#2136]
configure script, reference init-script and packaging templates updated
to eradicate @PIDPATH@/nut ambiguity in favor of @ALTPIDPATH@ for the
unprivileged processes vs. @PIDPATH@ for those running as root [#1719]
configure script can now be retained and installed by using the
--enable-keep_nut_report_feature option; packagers are welcome to make
use of this, to better keep track of their deliveries [#1826, #1708]
Renamed generated nut-common.tmpfiles(.in) ⇒ nut-common-tmpfiles.conf(.in) to install a /usr/lib/systemd-tmpfiles/*.conf pattern [#1755]
WatchdogSec= values are currently NOT pre-set into systemd
unit file templates provided by NUT, this is an exercise for end-users
based on sizing of their deployments and performance of monitoring station
[#1590, #1777]
mibs)
were renamed: pw is now eaton_pw_nm2, and pxgx_ups is eaton_pxg_ups
[#1715]
tools/gitlog2changelog.py.in script was revised, in particular to
generate the ChangeLog file more consistently with different versions
of Python interpreter, and without breaking the long file paths in the
resulting mark-up text. Due to this, a copy of this file distributed with
NUT release archives is expected to considerably differ on first glance
from its earlier released versions (not just adding lines for the new
release, but changing lines in the older releases too) [#1945, #1955]
nut-driver@instances
and the nut-driver-enumerator to manage their population), as well as
updated Python 2 and Python 3 support (again, maybe dictating different
package groups) as detailed below.
--with-dev and so may impact upsclient and nutclient (C++) consumers.
At the very least, binaries for those consumers should be rebuilt to remain
stable with NUT 2.8.0 and not mismatch int-type sizes and other arguments.
nutdrv_qx framework
for USB and Serial connected devices, not as updates/clones of older e.g.
blazer family and bestups. Sources, man pages and start-up messages
of such older drivers were marked with "OBSOLETION WARNING".
do_convert_deci flag. See
docs/man/netxml-ups.txt for details.
pkg-config by
default (if present), rather than net-snmp-config(-32|-64) script(s) as
the only option available previously. The scripts tend to specify a lot
of options (sometimes platform-specific) in suggested CFLAGS and LIBS
compared to the packaged pkg-config information which also works and is
more portable. If this change bites your distribution, please bring it up
in https://github.com/networkupstools/nut/issues or better yet, post a PR.
Also note that ./configure --with-netsnmp-config(=yes) should set up the
preference of the detected script over pkg-config information, if both
are available, and --with-netsnmp-config=/path/name would as well.
dummy-ups can now specify mode as a driver argument, and separates the
notion of dummy-once (new default for \*.dev files that do not change)
vs. dummy-loop (legacy default for *.seq and others) [issue #1385]
*.dev
files to work as a looping sequence with a TIMER keywords to change
values slowly; now such files should get processed to the end once.
Specify mode=dummy-loop driver option or rename the data file used
in the port option for legacy behavior.
Use/Test-cases which modified such files content externally should
not be impacted.
Python: scripts have been updated to work with Python 3 as well as 2.
NUT-Monitor script
and nut-monitor.desktop) are still delivered, but now cover a wrapper
script which detects the environment capabilities and launches the best
suitable UI implementation (if both are available).
[D#] prefix to log entries with level > 0
so if any scripts or other tools relied on parsing those messages
making some assumptions, they should be updated
TRACKING ID to be used with
an INSTCMD or SET VAR requests; for details see docs/net-protocol.txt
and docs/sock-protocol.txt
--with-augeas-lenses-dir configure option.
killall -SIGUSR1 upslog to any OB/OL script actions. This will force
upslog to write a log entry to catch short power transients.
upsd forks, to work around issues in the
NSS library.
ACCESS is no longer supported in upsd.conf. Use ACCEPT and REJECT.
Old way:
ACCESS grant all adminbox ACCESS grant all webserver ACCESS deny all all
New way:
ACCEPT adminbox ACCEPT webserver REJECT all
Note that ACCEPT and REJECT can take multiple arguments, so this will also work:
ACCEPT adminbox webserver REJECT all