Complete client bindings for NUT networked protocol

[jimklimov]

This PR follows up from #339 covers:

• improvements in Python and PERL bindings to cover all of docs/net-protocol.txt keywords as currently defined
• revision of TRACKING mode support (also in C++ library, follows up from Implement tracking commands in libnutclient #673 et al, and tests - implemented in Python, PERL, Java)
  • Closes: RFC: INSTCMD and SET VAR status tracking #656
  • Closes: INSTCMD and SET VAR status tracking implementation - perl #1348
  • Closes: INSTCMD and SET VAR status tracking implementation - python #1349
  • Closes: INSTCMD and SET VAR status tracking implementation - jNUT #1350
• enhanced test cases
  • Closes: CI: actively test SSL setups with NIT #1711
  • Addresses: (Python?) SSL handshake seems to be time-limited, CI tests rarely time out on busy workers #3401 (added retry looping upon timeout, not sure it works yet)
• transcribed Python test_nutclient into PERL and added it into NIT suite runs
  • Closes: Revise NIT to check PERL binding (UPS::Nut) #1613
• equivalent changes landed across several PRs into https://github.com/networkupstools/jNut leading to new releases; its GHA CI scripts now use the NIT script to test against a real (packaged, relatively old) NUT installation
• implemented the post-SSL-Handshake ping to ask the server for protocol version (C, C++, Python, PERL, Java)
  • Closes: Clients do not know STARTTLS setup actually failed until they send a query #3387
• tried to keep naming and behavior similar across the board
• AI did play a significant role on keeping stuff in sync, comparing code to docs, and generally remembering the moves; still, this work incurred numerous sleepless nights

[github-actions]

A ZIP file with standard source tarball and another tarball with pre-built docs for commit a654ba3 is temporarily available: NUT-tarballs-PR-3402.zip.

[jimklimov]

Various RedHat-derived distros on OBS disliked this. On the upside, from one PR to another these SSL errors are getting more legible. This also did catch certificate expectation mismatches (=>failed handshake) during the post-STRATTLS "OK" version query, as desired :)

[  170s] ================================
[  170s] Fri Apr 10 00:04:34 UTC 2026 [INFO] [testcase_sandbox_python_without_credentials] Call Python module test suite: PyNUT (NUT Python bindings) without login credentials
[  170s] Fri Apr 10 00:04:34 UTC 2026 [INFO] Adding client-side (Open)SSL config to python env to talk to our OpenSSL-capable upsd
[  170s] PyNUTClient test...
[  170s] [DEBUG] Class initialization...
[  170s] [DEBUG]  -> Host  = 127.0.0.1 (port 35027, timeout 5.0)
[  170s] [DEBUG]  -> Login = 'None' / 'None'
[  170s] [DEBUG]  -> SSL   = True (force: True, verify: True)
[  170s] [DEBUG] Creating SSL context
[  170s] [DEBUG] SSL context created
[  170s] [DEBUG] Connecting to host
[  170s] [DEBUG] Requesting STARTTLS
[  170s] [DEBUG] STARTTLS accepted, wrapping socket
[  170s] [DEBUG] STARTTLS setup claimed to succeed, but protocol version check in the secured session failed
[  170s] EXCEPTION during initialization: STARTTLS setup claimed to succeed, but protocol version check in the secured session failed, and SSL is required
[  170s] Traceback (most recent call last):
[  170s]   File "/home/abuild/rpmbuild/BUILD/nut-2.8.5.56+gc3b208ec/scripts/python/module/test_nutclient.py", line 35, in <module>
[  170s]     nut    = PyNUT.PyNUTClient( login=NUT_USER, password=NUT_PASS, debug=NUT_DEBUG, host=NUT_HOST, port=NUT_PORT,
[  170s]              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[  170s]   File "/home/abuild/rpmbuild/BUILD/nut-2.8.5.56+gc3b208ec/scripts/python/module/PyNUT.py", line 198, in __init__
[  170s]     self.__connect()
[  170s]   File "/home/abuild/rpmbuild/BUILD/nut-2.8.5.56+gc3b208ec/scripts/python/module/PyNUT.py", line 264, in __connect
[  170s]     raise PyNUTError("STARTTLS setup claimed to succeed, but protocol version check in the secured session failed, and SSL is required")
[  170s] PyNUT.PyNUTError: STARTTLS setup claimed to succeed, but protocol version check in the secured session failed, and SSL is required
[  170s] Fri Apr 10 00:04:34 UTC 2026 [ERROR] [testcase_sandbox_python_without_credentials] PyNUT complained, check above

[  170s] ================================
[  170s] Fri Apr 10 00:04:34 UTC 2026 [INFO] [testcase_sandbox_perl_with_credentials] Call Perl module test suite: UPS::Nut (NUT Perl bindings) with login credentials
[  170s] Fri Apr 10 00:04:34 UTC 2026 [INFO] Adding client-side (Open)SSL config to python env to talk to our OpenSSL-capable upsd
[  171s] net_starttls: SSL_accept failed (SSL_ERROR 1): Success
[  171s] Can't initialize: SSL setup failed but it is required at /home/abuild/rpmbuild/BUILD/nut-2.8.5.56+gc3b208ec/scripts/perl/test_nutclient.pl line 55.
[  171s] Can't call method "Error" on an undefined value at /home/abuild/rpmbuild/BUILD/nut-2.8.5.56+gc3b208ec/scripts/perl/test_nutclient.pl line 60.
[  171s] UPS::Nut test...
[  171s] DEBUG: STARTTLS accepted, upgrading socket.
[  171s] DEBUG: SSL upgrade failed: SSL connect attempt failed error:0A000086:SSL routines::certificate verify failed
[  171s] DEBUG: SSL setup failed but it is required
[  171s] DEBUG: Object destroyed.
[  171s] Fri Apr 10 00:04:35 UTC 2026 [ERROR] [testcase_sandbox_perl_with_credentials] UPS::Nut complained, check above

[AppVeyorBot]

❌ Build nut 2.8.5.4518-master failed (commit 0eba6f9d06 by @jimklimov)

• artifacts (if any)

[AppVeyorBot]

❌ Build nut 2.8.5.4518-master failed (commit 0eba6f9d06 by @jimklimov)

[AppVeyorBot]

❌ Build nut 2.8.5.4519-master failed (commit 06b0d37fdc by @jimklimov)

• artifacts (if any)

[AppVeyorBot]

✅ Build nut 2.8.5.4520-master completed (commit 3acbe35394 by @jimklimov)

• artifacts
• A 7-zip archive with built NUT for Windows debug binaries is temporarily available: NUT-for-Windows-x86_64-SNAPSHOT-2.8.5.4520-master.7z

[AppVeyorBot]

✅ Build nut 2.8.5.4520-master completed (commit 3acbe35394 by @jimklimov)

[jimklimov]

Python trouble was genuine; with Perl in more detail (on a Fedora 43 worker); it also seems that some specific constellation of options is relevant (a simple NUT_SSL_VARIANTS=nss CC=clang CXX=clang++ ./ci_build.sh docs=no did not evoke the problem, so I copied the line ultimately used by OBS packaging):

:; ./configure --disable-static --with-pic \
    --prefix=/usr --bindir=/usr/bin --sbindir=/usr/sbin --libdir=/usr/lib64 --libexecdir=/usr/libexec/ups \
    --sysconfdir=/etc/ups --datadir=/usr/share/nut --docdir=/usr/share/doc/nut \
    --with-ssl --with-openssl --with-libltdl=yes --with-cgi=auto --with-serial --with-usb \
    --with-snmp --with-neon --with-dev --with-ipmi=auto --with-powerman=auto \
    --with-doc=man=dist-auto --with-htmlpath=/usr/share/nut/htdocs \
    --with-cgipath=/usr/libexec/ups/cgi-bin --with-statepath=/var/lib/ups \
    --with-drvpath=/usr/libexec/ups/driver --with-user=upsd --with-group=daemon \
    --with-udev-dir=/usr/lib/udev --enable-option-checking=fatal \
    --with-systemdsystemunitdir --with-systemdshutdowndir \
    --with-augeas-lenses-dir=/usr/share/augeas/lenses/dist \
    --enable-keep_nut_report_feature --enable-strip --enable-check-NIT

UPDATE: Oh, it was using OpenSSL not NSS (faceplum)

:; make -ksj && NUT_DEBUG_LEVEL_UPSD=6 make check-NIT NIT_CASE=perl

...
   9.499026     [D5:3176458:upsd] mainloop: skip invalid SERVER listener [::1:35017, FD -1]: socket not bound
   9.499032     [D2:3176458:upsd] mainloop: polling 6 filedescriptors; some stats: considered 7 connections, wanted to actually poll 6 and was constrained by maxconn=1024 and chunked by sysmaxconn=1024
   9.535879     [D2:3176458:upsd] mainloop: polling returned 1 hits
   9.535896     [D3:3176458:upsd] mainloop: Incoming data from CLIENT [127.0.0.1, FD 8]
   9.535912     [D6:3176458:upsd] Entering check_command: STARTTLS
   9.535919     [D6:3176458:upsd] check_command: Calling command handler for STARTTLS
   9.535942     [D2:3176458:upsd] write: [destfd=8] [len=12] [OK STARTTLS]
DEBUG: STARTTLS accepted, upgrading socket.
DEBUG: SSL upgrade failed: SSL connect attempt failed error:0A000086:SSL routines::certificate verify failed
DEBUG: SSL setup failed but it is required
Can't initialize: SSL setup failed but it is required at /home/abuild/nut/scripts/perl/test_nutclient.pl line 55.
DEBUG: Object destroyed.
   9.585792     net_starttls: SSL_accept failed (SSL_ERROR 1): Success
   9.585812     [D1:3176458:upsd] ssl_error() ret=-1 SSL_ERROR 1
   9.585819     [D1:3176458:upsd] ssl_debug: error:0A000418:SSL routines::tlsv1 alert unknown ca
   9.585826     [D4:3176458:upsd] mainloop: adding FD handler #0 for DRIVER (1/1) [dummy, FD 5]
   9.585831     [D4:3176458:upsd] mainloop: adding FD handler #1 for DRIVER (2/2) [UPS1, FD 6]
   9.585836     [D4:3176458:upsd] mainloop: adding FD handler #2 for DRIVER (3/3) [UPS2, FD 7]
   9.585841     [D4:3176458:upsd] mainloop: adding FD handler #3 for CLIENT (1/1) [127.0.0.1 => (null), FD 8]
   9.585845     [D4:3176458:upsd] mainloop: adding FD handler #4 for SERVER listener (1/1) [localhost:35017, FD 3]
   9.585849     [D4:3176458:upsd] mainloop: adding FD handler #5 for SERVER listener (2/2) [127.0.0.1:35017, FD 4]
   9.585854     [D5:3176458:upsd] mainloop: skip invalid SERVER listener [::1:35017, FD -1]: socket not bound
   9.585858     [D2:3176458:upsd] mainloop: polling 6 filedescriptors; some stats: considered 7 connections, wanted to actually poll 6 and was constrained by maxconn=1024 and chunked by sysmaxconn=1024
   9.585973     [D2:3176458:upsd] mainloop: polling returned 1 hits
   9.585980     [D3:3176458:upsd] mainloop: Incoming data from CLIENT [127.0.0.1, FD 8]
   9.585990     [D2:3176458:upsd] Disconnect 127.0.0.1 (read failure): Success
   9.585993     [D3:3176458:upsd] client_disconnect: semi-initialised SSL on a client, sleep a bit to flush the buffers with possible error messages
Can't call method "Error" on an undefined value at /home/abuild/nut/scripts/perl/test_nutclient.pl line 60.
Fri Apr 10 07:35:11 UTC 2026 [ERROR] [testcase_sandbox_perl_with_credentials] UPS::Nut complained, check above

NOTE: Can't call method "Error" on an undefined value is not a problem, the $nut object is half-initialized and discarded, so post-mortem in test script can not print from it.

[AppVeyorBot]

✅ Build nut 2.8.5.4522-master completed (commit f8bc9a971e by @jimklimov)

• artifacts
• A 7-zip archive with built NUT for Windows debug binaries is temporarily available: NUT-for-Windows-x86_64-SNAPSHOT-2.8.5.4522-master.7z

[AppVeyorBot]

❌ Build nut 2.8.5.4523-master failed (commit 5269a2f752 by @jimklimov)

• artifacts (if any)

[AppVeyorBot]

❌ Build nut 2.8.5.4523-master failed (commit 5269a2f752 by @jimklimov)

[AppVeyorBot]

✅ Build nut 2.8.5.4524-master completed (commit bd5a7c4452 by @jimklimov)

• artifacts
• A 7-zip archive with built NUT for Windows debug binaries is temporarily available: NUT-for-Windows-x86_64-SNAPSHOT-2.8.5.4524-master.7z

[AppVeyorBot]

✅ Build nut 2.8.5.4524-master completed (commit bd5a7c4452 by @jimklimov)

[AppVeyorBot]

❌ Build nut 2.8.5.4525-master failed (commit 739ad38290 by @jimklimov)

• artifacts (if any)

[AppVeyorBot]

❌ Build nut 2.8.5.4525-master failed (commit 739ad38290 by @jimklimov)