ifdef::txt[] Upgrading notes =============== endif::txt[] 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. Changes from 2.7.4 to 2.8.0 --------------------------- - Note to distribution packagers: this version hopefully learns from many past mistakes, so many custom patches may be no longer needed. If some remain, please consider making pull requests for upstream NUT codebase to share the fixes consistently across the ecosystem. Also note that some new types of drivers (so package groups with unique dependencies) could have appeared since your packaging was written (e.g. with modbus), as well as new features in systemd integration (`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. - Due to changes needed to resolve build warnings, mostly about mismatching data types for some variables, some structure definitions and API signatures of several routines had to be changed for argument types, return types, or both. Primarily this change concerns internal implementation details (may impact update of NUT forks with custom drivers using those), but a few changes also happened in header files installed for builds configured `--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. - libusb-1.0: NUT now defaults to building against libusb-1.0 API version if the configure script finds the development headers, falling back to libusb-0.1 if not. Please report any regressions. - apcupsd-ups: When monitoring a remote apcupsd server, interpret "SHUTTING DOWN" as a NUT "LB" status. If you were relying on the previous behavior (for instance, in a monitor-only situation), please adjust your upsmon settings. Reference: https://github.com/networkupstools/nut/issues/460 - Packagers: the AsciiDoc detection has been reworked to allow NUT to be built from source without requiring asciidoc/a2x (using pre-built man pages from the distribution tarball, for instance). Please double-check that we did not break anything (see docs/configure.txt for options). - Driver core: options added for standalone mode (scanning for devices without requiring ups.conf) - see docs/man/nutupsdrv.txt for details. - oldmge-shut has been removed, and replaced by mge-shut. - New drivers for devices with "Qx" (also known as "Megatec Q*") family of protocols should be developed as sub-drivers in the `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". - liebert-esp2: some multi-phase variable names have been updated to match the rest of NUT. - netxml-ups: if you have old firmware, or were relying on values being off by a factor of 10, consider the `do_convert_deci` flag. See docs/man/netxml-ups.txt for details. - snmp-ups: detection of Net-SNMP has been updated to use `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. - snmp-ups: bit mask values for flags in earlier codebase were defined in a way that caused logically different items to have same numeric values. This was fixed to surely use different definitions (so changing numbers behind some of those macro symbols), and testing with UPS, ePDU and ATS hardware which was available did not expose any practical differences. - usbhid-ups: numeric data conversion from wire protocol to CPU representation in GetValue() was completely reworked, aiming to be correct on all CPU types. That said, regressions are possible and feedback is welcome. - nut-scanner: Packagers, take note of the changes to the library search code in common/common.c. Please file an issue if this does not work with your platform. - 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] * Note this can break third-party test scripts which expected `*.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. * PyNUT module (protocol binding) supports both Python generations. * NUT-Monitor (desktop UI client) got separated into two projects: one with support for Python2 and GTK2, and another for Python3 and Qt5. On operating systems that serve both environments, either of these implementation should be usable. For distributions that deprecated and removed Python2 support, it is a point to consider in NUT packages and their build-time and installation dependencies. The historic filenames for desktop integration (`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). - apcsmart: updates to CS "hack" (see docs/man/apcsmart.txt for details) - upsdebugx(): added `[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 - upsdebugx() and related methods are now macros, optionally calling similarly named implementations like s_upsdebugx() as a slight optimization; this may show up in linking of binaries for some customized build scenarios - libraries, tools and protocol now support a `TRACKING` ID to be used with an `INSTCMD` or `SET VAR` requests; for details see docs/net-protocol.txt and docs/sock-protocol.txt - upsrw: display the variable type beside ENUM / RANGE - Augeas: new `--with-augeas-lenses-dir` configure option. Changes from 2.7.3 to 2.7.4 --------------------------- - scripts/systemd/nut-server.service.in: Restore systemd relationship since it was preventing upsd from starting whenever one or more drivers, among several, was failing to start - Fix UPower device matching for recent kernels, since hiddev* devices now have class "usbmisc", rather than "usb" - macosx-ups: the "port" driver option no longer has any effect - Network protocol information: default to type NUMBER for variables that are not flagged as STRING . This point is subject to improvements or change in the next release 2.7.5. Refer to docs/net-protocol.txt for more information Changes from 2.7.2 to 2.7.3 --------------------------- - The linkman:nutdrv_qx[8] driver will eventually supersede linkman:bestups[8]. It has been tested on a U-series Patriot Pro II. Please test the new driver on your hardware during your next maintenance window, and report any bugs. - If you are upgrading from a new install of 2.7.1 or 2.7.2, double-check the value of POWERDOWNFLAG in $prefix/etc/upsmon.conf - it has been restored to /etc/killpower as in 2.6.5 and earlier. - If you use upslog with a large sleep value, you may be interested in adding `killall -SIGUSR1 upslog` to any OB/OL script actions. This will force upslog to write a log entry to catch short power transients. - Be sure that your SSL keys are readable by the NUT system user. The SSL subsystem is now initialized after `upsd` forks, to work around issues in the NSS library. - The systemd nut-server.service does not Require nut-driver to be started successfully. This was previously preventing upsd startup, even for just one driver failure among many. This also matches the behavior of sysV initscripts. Changes from 2.7.1 to 2.7.2 --------------------------- - upsdrvctl is now installed to $prefix/sbin rather than $driverexec. This usually means moving from /bin to /sbin, apart from few exceptions. In all cases, please adapt your scripts. - FreeDesktop Hardware Abstraction Layer (HAL) support was removed. Please adapt your packaging files, if you used to distribute the nut-hal-drivers package. - 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. Changes from 2.6.5 to 2.7.1 --------------------------- - The linkman:apcsmart[8] driver has been replaced by a new implementation. There is a new parameter, 'ttymode', which may help if you have a non-standard serial port, or Windows. In case of issues with this new version, users can revert to apcsmart-old. - The linkman:nutdrv_qx[8] driver will eventually supersede blazer_ser and blazer_usb. Options are not exactly the same, but are documented in the nutdrv_qx man page. - Mozilla NSS support has been added. The OpenSSL configuration options should be unchanged, but please refer to the linkman:upsd.conf[5] and linkman:upsmon.conf[5] documentation in case we missed something. - linkman:upsrw[8] now prints out the maximum size of variables. Hopefully you are not parsing the output of upsrw - it would be easier to use one of the NUT libraries, or implement the network protocol yourself. - The jNut source is now here: https://github.com/networkupstools/jNut Changes from 2.6.4 to 2.6.5 --------------------------- - users are encouraged to update to NUT 2.6.5, to fix a regression in upssched. - mge-shut driver has been replaced by a new implementation (newmge-shut). In case of issue with this new version, users can revert to oldmge-shut. Changes from 2.6.3 to 2.6.4 --------------------------- - users are encouraged to update to NUT 2.6.4, to fix upsd vulnerability (CVE-2012-2944: upsd can be remotely crashed). - users of the bestups driver are encouraged to switch to blazer_ser, since bestups will soon be deprecated. Changes from 2.6.2 to 2.6.3 --------------------------- - nothing that affects upgraded systems. Changes from 2.6.1 to 2.6.2 --------------------------- - apcsmart driver has been replaced by a new implementation. In case of issue with this new version, users can revert to apcsmart-old. Changes from 2.6.0 to 2.6.1 --------------------------- - nothing that affects upgraded systems. Changes from 2.4.3 to 2.6.0 --------------------------- - users of the megatec and megatec_usb drivers must respectively switch to blazer_ser and blazer_usb. - users of the liebertgxt2 driver are advised that the driver name has changed to liebert-esp2. Changes from 2.4.2 to 2.4.3 --------------------------- - nothing that affects upgraded systems. Changes from 2.4.1 to 2.4.2 --------------------------- - The default subdriver for the blazer_usb driver USB id 06da:0003 has changed. If you use such a device and it is no longer working with this driver, override the 'subdriver' default in 'ups.conf' (see man 8 blazer). - NUT ACL and the allowfrom mechanism has been replaced in 2.4.0 by the LISTEN directive and tcp-wrappers respectively. This information was missing below, so a double note has been added. Changes from 2.4.0 to 2.4.1 --------------------------- - nothing that affects upgraded systems. Changes from 2.2.2 to 2.4.0 --------------------------- - The nut.conf file has been introduced to standardize startup configuration across the various systems. - The cpsups and nitram drivers have been replaced by the powerpanel driver, and removed from the tree. The cyberpower driver may suffer the same in the future. - The al175 and energizerups drivers have been removed from the tree, since these were tagged broken for a long time. - Developers of external client application using libupsclient must rename their "UPSCONN" client structure to "UPSCONN_t". - The upsd server will now disconnect clients that remain silent for more than 60 seconds. - The files under scripts/python/client are distributed under GPL 3+, whereas the rest of the files are distributed under GPL 2+. Refer to COPYING for more information. - The generated udev rules file has been renamed with dash only, no underscore anymore (ie 52-nut-usbups.rules instead of 52_nut-usbups.rules) Changes from 2.2.1 to 2.2.2 --------------------------- - The configure option "--with-lib" has been replaced by "--with-dev". This enable the additional build and distribution of the static version of libupsclient, along with the pkg-config helper and manual pages. The default configure option is to distribute only the shared version of libupsclient. This can be overridden by using the "--disable-shared" configure option (distribute static only binaries). - The UPS poweroff handling of the usbhid-ups driver has been reworked. Though regression is not expected, users of this driver are encouraged to test this feature by calling "upsmon -c fsd" and report any issue on the NUT mailing lists. Changes from 2.2.0 to 2.2.1 --------------------------- - nothing that affects upgraded systems. (The below message is repeated due to previous omission) - Developers of external client application using libupsclient are encouraged to rename their "UPSCONN" client structure to "UPSCONN_t" since the former will disappear by the release of NUT 2.4. Changes from 2.0.5 to 2.2.0 --------------------------- - users of the newhidups driver are advised that the driver name has changed to usbhid-ups. - users of the hidups driver must switch to usbhid-ups. - users of the following drivers (powermust, blazer, fentonups, mustek, esupssmart, ippon, sms) must switch to megatec, which replaces all these drivers. Please refer to doc/megatec.txt for details. - users of the mge-shut driver are encouraged to test newmge-shut, which is an alternate driver scheduled to replace mge-shut, - users of the cpsups driver are encouraged to switch to powerpanel which is scheduled to replace cpsups, - packagers will have to rework the whole nut packaging due to the major changes in the build system (completely modified, and now using automake). Refer to packaging/debian/ for an example of migration. - specifying '-a ' is now mandatory when starting a driver manually, ie not using upsdrvctl. - Developers of external client application using libupsclient are encouraged to rename the "UPSCONN" client structure to "UPSCONN_t" since the former will disappear by the release of NUT 2.4. Changes from 2.0.4 to 2.0.5 --------------------------- - users of the newhidups driver: the driver is now more strict about refusing to connect to unknown devices. If your device was previously supported, but fails to be recognized now, add 'productid=XXXX' to ups.conf. Please report the device to the NUT developer's mailing list. Changes from 2.0.3 to 2.0.4 --------------------------- - nothing that affects upgraded systems. - users of the following drivers (powermust, blazer, fentonups, mustek, esupssmart, ippon, sms, masterguard) are encouraged to switch to megatec, which should replace all these drivers by nut 2.2. For more information, please refer to doc/megatec.txt Changes from 2.0.2 to 2.0.3 --------------------------- - nothing that affects upgraded systems. - hidups users are encouraged to switch to newhidups, as hidups will be removed by nut 2.2. Changes from 2.0.1 to 2.0.2 --------------------------- - The newhidups driver, which is the long run USB support approach, needs hotplug files installed to setup the right permissions on device file to operate. Check newhidups manual page for more information. Changes from 2.0.0 to 2.0.1 --------------------------- - The cyberpower1100 driver is now called cpsups since it supports more than just one model. If you use this driver, be sure to remove the old binary and update your ups.conf 'driver=' setting with the new name. - The upsstats.html template page has been changed slightly to reflect better HTML compliance, so you may want to update your installed copy accordingly. If you've customized your file, don't just copy the new one over it, or your changes will be lost! Changes from 1.4.0 to 2.0.0 --------------------------- - The sample config files are no longer installed by default. If you want to install them, use 'make install-conf' for the main programs, and 'make install-cgi-conf' for the CGI programs. - 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 - The drivers no longer support sddelay in ups.conf or -d on the command line. If you need a delay after calling 'upsdrvctl shutdown', add a call to sleep in your shutdown script. - The templates used by upsstats have changed considerably to reflect the new variable names. If you use upsstats, you will need to install new copies or edit your existing files to use the new names. - Nobody needed UDP mode, so it has been removed. The only users seemed to be a few people like me with ancient asapm-ups binaries. If you really want to run asapm-ups again, bug me for the new patch which makes it work with upsclient. - 'make install-misc' is now 'make install-lib'. The misc directory has been gone for a long time, and the target was ambiguous. - The newapc driver has been renamed to apcsmart. If you previously used newapc, make sure you delete the old binary and fix your ups.conf. Otherwise, you may run the old driver from 1.4. *** File trimmed here on changes from 1.2.2 to 1.4.0 *** For information before this point, start with version 2.4.1 and work back.