Merge branch 'master' into issue-1717

.github/workflows/PyNUTClient.yml

@@ -27,10 +27,10 @@ jobs:
       with:
         fetch-depth: 0
         fetch-tags: true
-    - name: Set up Python 3.10
+    - name: Set up Python 3.13
       uses: actions/setup-python@v3
       with:
-        python-version: '3.10'
+        python-version: '3.13'
     - name: Extract python interpreter path name
       id: pythoncmd
       run: >-

INSTALL.nut.adoc

@@ -99,7 +99,7 @@ ifndef::top_builddir[]
 endif::top_builddir[]
 //
 //
-// Address links on GitHub vs docs
+// Address links on GitHub vs. docs
 // (note: 'env-github' attribute is set on GitHub)
 //
 // - when generating docs:
@@ -306,11 +306,30 @@ Installation
 
 [NOTE]
 =====================================================================
+You should now gain privileges for installing software if necessary, e.g.:
 
-you should now gain privileges for installing software if necessary:
+	su -
 
-	su
+or prefix installation (not build/check!) commands with `sudo`, e.g.:
 
+	sudo make install ...
+=====================================================================
+
+[NOTE]
+=====================================================================
+If you install NUT for direct consumption on the system that has just
+built it from source, you might be aided for some of the steps listed
+and explained below by running (as `root`):
+
+	make install-as-root
+
+This should not only install the software, but also create directories
+such as the state path, assign ownership and access permissions to
+certain directories and sample configuration files which NUT user
+and/or group accounts should be able to read and/or write, and, on
+some platforms, also (re-)start the NUT daemons/services.
+
+See above "System User creation", that should be done first!
 =====================================================================
 
 Install the files to a system level directory:
@@ -328,7 +347,7 @@ have created.
 
 If you are packaging this software, then you will probably want to
 use the DESTDIR variable to redirect the build into another place,
-i.e.:
+also known as a "prototype directory" or a "staging area", i.e.:
 
 	make DESTDIR=/tmp/package install
 	make DESTDIR=/tmp/package install-conf
@@ -337,9 +356,12 @@ i.e.:
 State path creation
 ^^^^^^^^^^^^^^^^^^^
 
+NOTE: See above about `make install-as-root`, if you use that -- skip
+this step here.
+
 Create the state path directory for the driver(s) and server to use
 for storing UPS status data and other auxiliary files, and make it
-group-writable by the group of the system user you created.
+group-writable by the group of the system user you created, e.g.:
 
 	mkdir -p /var/state/ups
 	chmod 0770 /var/state/ups

Makefile.am

@@ -68,14 +68,16 @@ endif
 # tweak paths not using ${prefix} so `make distcheck` fails for it as
 # it does not play with a `DESTDIR` either.
 
-DISTCHECK_FLAGS = --with-all --with-ssl --with-doc=auto --with-pynut=app --with-nut_monitor=force
-DISTCHECK_LIGHT_FLAGS = --with-all=auto --with-ssl=auto --with-doc=auto --with-pynut=app --with-nut_monitor=force
-DISTCHECK_LIGHT_MAN_FLAGS = --with-all=auto --with-ssl=auto --with-doc=man --with-pynut=app --with-nut_monitor=force
-DISTCHECK_VALGRIND_FLAGS = --with-all=auto --with-ssl=auto --with-doc=skip --with-valgrind CXXFLAGS='$(CXXFLAGS) -g' CFLAGS='$(CFLAGS) -g' --with-pynut=app --with-nut_monitor=force
+DISTCHECK_FLAGS = --with-all --with-ssl --with-doc=auto --with-pynut=app --with-nut_monitor=force CXXFLAGS='@NUT_CONFIG_CXXFLAGS@' CFLAGS='@NUT_CONFIG_CFLAGS@' CPPFLAGS='@NUT_CONFIG_CPPFLAGS@' LDFLAGS='@NUT_CONFIG_LDFLAGS@'
+DISTCHECK_LIGHT_FLAGS = --with-all=auto --with-ssl=auto --with-doc=auto --with-pynut=app --with-nut_monitor=force CXXFLAGS='@NUT_CONFIG_CXXFLAGS@' CFLAGS='@NUT_CONFIG_CFLAGS@' CPPFLAGS='@NUT_CONFIG_CPPFLAGS@' LDFLAGS='@NUT_CONFIG_LDFLAGS@'
+DISTCHECK_LIGHT_MAN_FLAGS = --with-all=auto --with-ssl=auto --with-doc=man --with-pynut=app --with-nut_monitor=force CXXFLAGS='@NUT_CONFIG_CXXFLAGS@' CFLAGS='@NUT_CONFIG_CFLAGS@' CPPFLAGS='@NUT_CONFIG_CPPFLAGS@' LDFLAGS='@NUT_CONFIG_LDFLAGS@'
+DISTCHECK_VALGRIND_FLAGS = --with-all=auto --with-ssl=auto --with-doc=skip --with-valgrind CXXFLAGS='@NUT_CONFIG_CXXFLAGS@ -g' CFLAGS='@NUT_CONFIG_CFLAGS@ -g' CPPFLAGS='@NUT_CONFIG_CPPFLAGS@' LDFLAGS='@NUT_CONFIG_LDFLAGS@' --with-pynut=app --with-nut_monitor=force
 
 # Note: this rule uses envvar DISTCHECK_FLAGS expanded at run-time
 DISTCHECK_CONFIGURE_FLAGS = ${DISTCHECK_FLAGS}		\
+ PKG_CONFIG_PATH='@PKG_CONFIG_PATH@'			\
  --with-systemdsystemunitdir='$${prefix}/lib/systemd/system' \
+ --with-systemdsystempresetdir='$${prefix}/usr/lib/systemd/system-preset' \
  --with-systemdshutdowndir='$${prefix}/lib/systemd/system-shutdown' \
  --with-systemdtmpfilesdir='$${prefix}/usr/lib/tmpfiles.d' \
  --with-augeas-lenses-dir='$${prefix}/usr/share/augeas/lenses'		\
@@ -89,15 +91,26 @@ DISTCHECK_CONFIGURE_FLAGS = ${DISTCHECK_FLAGS}		\
 # that is meaningful for sub-make program (gets stripped away
 # otherwise and breaks custom distchecks).
 distcheck-light:
-	+prefix='$${prefix}'; $(MAKE) $(AM_MAKEFLAGS) DISTCHECK_CONFIGURE_FLAGS="$(DISTCHECK_CONFIGURE_FLAGS)" DISTCHECK_FLAGS="$(DISTCHECK_LIGHT_FLAGS)" distcheck
+	+prefix='$${prefix}'; $(MAKE) $(AM_MAKEFLAGS) DISTCHECK_FLAGS="$(DISTCHECK_LIGHT_FLAGS)" distcheck
 
 distcheck-light-man:
-	+prefix='$${prefix}'; $(MAKE) $(AM_MAKEFLAGS) DISTCHECK_CONFIGURE_FLAGS="$(DISTCHECK_CONFIGURE_FLAGS)" DISTCHECK_FLAGS="$(DISTCHECK_LIGHT_MAN_FLAGS)" distcheck
+	+prefix='$${prefix}'; $(MAKE) $(AM_MAKEFLAGS) DISTCHECK_FLAGS="$(DISTCHECK_LIGHT_MAN_FLAGS)" distcheck
+
+if HAVE_VALGRIND
+# Make the check in current build, if possible
+memcheck:
+	@echo "See also scripts/valgrind in NUT sources for a helper tool"
+	+@cd $(builddir)/tests && $(MAKE) $(AM_MAKEFLAGS) -s $@
 
 # Make a distcheck (and check in particular) with enabled valgrind and debug info
+distcheck-valgrind:
+	@echo "See also scripts/valgrind in NUT sources for a helper tool"
+	+prefix='$${prefix}'; $(MAKE) $(AM_MAKEFLAGS) DISTCHECK_FLAGS="$(DISTCHECK_VALGRIND_FLAGS)" distcheck
+else !HAVE_VALGRIND
 memcheck distcheck-valgrind:
 	@echo "See also scripts/valgrind in NUT sources for a helper tool"
-	+prefix='$${prefix}'; $(MAKE) $(AM_MAKEFLAGS) DISTCHECK_CONFIGURE_FLAGS="$(DISTCHECK_CONFIGURE_FLAGS)" DISTCHECK_FLAGS="$(DISTCHECK_VALGRIND_FLAGS)" distcheck
+	@echo "SKIPPED $@ : valgrind was not detected on this system by configure script" >&2
+endif !HAVE_VALGRIND
 
 # workaround the dist generated files that are also part of the distribution
 # Note that distcleancheck is disabled for now, while waiting for a proper
@@ -492,9 +505,9 @@ install-bin:
 install-man: install-data-recursive
 	@echo $(WARN)
 	@echo "Warning: 'make install-man' is deprecated."
-	@echo "Use 'cd man; make install' instead."
+	@echo "Use 'cd docs/man; make install' instead."
 	@echo $(WARN)
-	+cd man; $(MAKE) $(AM_MAKEFLAGS) install
+	+cd docs/man; $(MAKE) $(AM_MAKEFLAGS) install
 install-conf:
 	@echo $(WARN)
 	@echo "Warning: 'make install-conf' is deprecated."
@@ -525,16 +538,211 @@ setver:
 	@echo "Error: 'make setver' no longer exists."
 	@echo "Edit configure.ac to set version number."
 
+# Adjust permissions when installing as `root` into the actual system.
+# We honour DESTDIR anyway, as someone can install into a chroot etc.
+# NOTE: Might be an 'install-data-hook' (for dirs) and/or 'install-exec-hook'
+# (for service restart) but better not force this on everyone?
+# It is also up to the end-user making such an installation to remove (or not)
+# dirs and files made below.
+# To err on the safe side in cross builds, we ignore Windows builds and those
+# not built for the same system as the build host.
+install-data-hook:
+	@case "@target_os@" in *mingw*) exit 0;; esac ; \
+	 if [ x"@host_os@" != x"@build_os@" ]; then exit 0 ; fi ; \
+	 if [ x"@target_os@" != x"@build_os@" ]; then exit 0 ; fi ; \
+	 if (command -v id) && [ x"`id -u`" = x0 ] && [ x"$(DESTDIR)" = x -o x"$(DESTDIR)" = x/ ] ; then \
+		echo "================================================================================" >&2 ; \
+		echo "| NUT data files have been installed into the system, now consider running     |" >&2 ; \
+		echo "| '(sudo) make install-as-root' to apply permissions and service state changes |" >&2 ; \
+		echo "================================================================================" >&2 ; \
+	 fi
+
+if HAVE_SYSTEMD
+HAVE_SYSTEMD = true
+else
+HAVE_SYSTEMD = false
+endif
+
+if WITH_SYSTEMD_TMPFILES
+WITH_SYSTEMD_TMPFILES = true
+else
+WITH_SYSTEMD_TMPFILES = false
+endif
+
+if WITH_SYSTEMD_PRESET
+WITH_SYSTEMD_PRESET = true
+else
+WITH_SYSTEMD_PRESET = false
+endif
+
+if WITH_CGI
+WITH_CGI = true
+else
+WITH_CGI = false
+endif
+
+if WITH_SOLARIS_SMF
+WITH_SOLARIS_SMF = true
+else
+WITH_SOLARIS_SMF = false
+endif
+
+if WITH_SOLARIS_INIT
+WITH_SOLARIS_INIT = true
+else
+WITH_SOLARIS_INIT = false
+endif
+
+# TODO: Actually move this into scripts like Solaris/postinstall
+# using OS-specific `useradd`/`groupadd`, etc.
+# Note that as we stop services, we may be dealing with (older)
+# distros that do not follow current naming in NUT code base.
+install-as-root:
+	@+echo "$@: starting (no-op if not root)" >&2 ; \
+	 case "@target_os@" in *mingw*) exit 0;; esac ; \
+	 if [ x"@host_os@" != x"@build_os@" ]; then exit 0 ; fi ; \
+	 if [ x"@target_os@" != x"@build_os@" ]; then exit 0 ; fi ; \
+	 prefix="@prefix@"; \
+	 if (command -v id) && [ x"`id -u`" = x0 ] ; then \
+		if [ x"$(DESTDIR)" = x -o x"$(DESTDIR)" = x/ ] ; then \
+			if $(HAVE_SYSTEMD) ; then \
+				echo "$@: Stop NUT services, if any" >&2 ; \
+				@SYSTEMD_SYSTEMCTL_PROGRAM@ stop nut-monitor.service nut-server.service || true ; \
+				@SYSTEMD_SYSTEMCTL_PROGRAM@ stop nut-driver.service || true ; \
+				@SYSTEMD_SYSTEMCTL_PROGRAM@ stop nut-driver.target || true ; \
+				@SYSTEMD_SYSTEMCTL_PROGRAM@ stop nut.target || true ; \
+			fi ; \
+			if $(WITH_SOLARIS_SMF) || $(WITH_SOLARIS_INIT) ; then \
+				if $(WITH_SOLARIS_SMF) ; then \
+					echo "$@: Stop NUT services, if any" >&2 ; \
+					SMF_ACTIVE="`/usr/bin/svcs -a -Hostate,fmri | grep svc:/system/power/ | grep -v disabled | awk '{print $$2}'`" ; \
+					for S in $$SMF_ACTIVE ; do \
+						/usr/sbin/svcadm disable -ts $$S || true ; \
+					done ; \
+				fi ; \
+				$(top_builddir)/scripts/Solaris/preremove \
+				|| exit ; \
+			fi ; \
+		fi ; \
+		$(MAKE) $(AM_FLAGS) DESTDIR="$(DESTDIR)" install || exit ; \
+		if [ x"$(DESTDIR)" = x -o x"$(DESTDIR)" = x/ ] ; then \
+			if $(WITH_SOLARIS_SMF) || $(WITH_SOLARIS_INIT) ; then \
+				$(top_builddir)/scripts/Solaris/preinstall && \
+				$(top_builddir)/scripts/Solaris/postinstall ; \
+				exit ; \
+			fi ; \
+		fi ; \
+		echo "  MKDIR   $(DESTDIR)/@STATEPATH@ $(DESTDIR)/@STATEPATH@/upssched" >&2 ; \
+		$(MKDIR_P) "$(DESTDIR)/@STATEPATH@/upssched" && \
+		for D in "@PIDPATH@" "@ALTPIDPATH@" "@ALTSTATEPATH@" "@CONFPATH@" ; do \
+			case x"$$D" in \
+			x|x@*) ;; \
+			*)	echo "  MKDIR   $(DESTDIR)/$$D" >&2 ; \
+				$(MKDIR_P) "$(DESTDIR)/$$D" \
+				|| exit ;; \
+			esac ; \
+		done ; \
+		if (command -v chmod) ; then \
+			echo "  CHMOD(0770)   $(DESTDIR)/@STATEPATH@/upssched" >&2 ; \
+			chmod 0770 "$(DESTDIR)/@STATEPATH@/upssched" \
+			|| exit ; \
+			for D in "@STATEPATH@" "@PIDPATH@" "@ALTPIDPATH@" "@ALTSTATEPATH@" ; do \
+				case x"$$D" in \
+				x|x@*|x/run|x/var/run|x/tmp|x/var/tmp|x/dev/shm|x/etc|x/var|x/usr|x/usr/local|x/usr/local/etc|x/usr/etc) ;; \
+				*)	echo "  CHMOD(0770)   $(DESTDIR)/$$D" >&2 ; \
+					chmod 0770 "$(DESTDIR)/$$D" \
+					|| exit ;; \
+				esac ; \
+			done ; \
+			case x"@CONFPATH@" in \
+				x|x@*|x/run|x/var/run|x/tmp|x/var/tmp|x/dev/shm|x/etc|x/var|x/usr|x/usr/local|x/usr/local/etc|x/usr/etc) ;; \
+				*)	echo "  CHMOD(0751)   $(DESTDIR)/@CONFPATH@" >&2 ; \
+					chmod 0751 "$(DESTDIR)/@CONFPATH@" \
+					|| exit ;; \
+			esac ; \
+			for F in hosts.conf.sample upsstats-single.html.sample upsstats.html.sample upsset.conf.sample ; do \
+				echo "  CHMOD(0644)   CGI: $(DESTDIR)/@CONFPATH@/$$F" >&2 ; \
+				chmod 0644 "$(DESTDIR)/@CONFPATH@/$$F" \
+				|| { if $(WITH_CGI) ; then exit 1 ; else true ; fi ; } ; \
+			done ; \
+			for F in nut.conf.sample ups.conf.sample upsd.conf.sample upsd.users.sample upsmon.conf.sample upssched.conf.sample ; do \
+				echo "  CHMOD(0640)   $(DESTDIR)/@CONFPATH@/$$F" >&2 ; \
+				chmod 0640 "$(DESTDIR)/@CONFPATH@/$$F" \
+				|| exit ; \
+			done ; \
+		else \
+			echo "$@: WARNING: Can not CHMOD created locations!" >&2 ; \
+		fi ; \
+		if (command -v chown) && test 0 -lt "`id -u '@RUN_AS_USER@'`" \
+		&& ( test 0 -lt "`getent group '@RUN_AS_GROUP@' | awk -F: '{print $$3}'`" || test 0 -lt "`id -g '@RUN_AS_GROUP@'`" ) \
+		; then \
+			echo "  CHOWN(@RUN_AS_USER@:@RUN_AS_GROUP@)   $(DESTDIR)/@STATEPATH@/upssched" >&2 ; \
+			chown "@RUN_AS_USER@:@RUN_AS_GROUP@" "$(DESTDIR)/@STATEPATH@/upssched" \
+			|| exit ; \
+			for D in "@STATEPATH@" "@PIDPATH@" "@ALTPIDPATH@" "@ALTSTATEPATH@" ; do \
+				case x"$$D" in \
+				x|x@*|x/run|x/var/run|x/tmp|x/var/tmp|x/dev/shm|x/etc|x/var|x/usr|x/usr/local|x/usr/local/etc|x/usr/etc) ;; \
+				*)	echo "  CHOWN(@RUN_AS_USER@:@RUN_AS_GROUP@)   $(DESTDIR)/$$D" >&2 ; \
+					chown "@RUN_AS_USER@:@RUN_AS_GROUP@" "$(DESTDIR)/$$D" \
+					|| exit ;; \
+				esac ; \
+			done ; \
+			case x"@CONFPATH@" in \
+				x|x@*|x/run|x/var/run|x/tmp|x/var/tmp|x/dev/shm|x/etc|x/var|x/usr|x/usr/local|x/usr/local/etc|x/usr/etc) ;; \
+				*)	echo "  CHOWN(root:@RUN_AS_GROUP@)   $(DESTDIR)/@CONFPATH@" >&2 ; \
+					chown "root:@RUN_AS_GROUP@" "$(DESTDIR)/@CONFPATH@" \
+					|| exit ;; \
+			esac ; \
+			for F in hosts.conf.sample upsstats-single.html.sample upsstats.html.sample upsset.conf.sample ; do \
+				echo "  CHOWN(root:@RUN_AS_GROUP@)   CGI: $(DESTDIR)/@CONFPATH@/$$F" >&2 ; \
+				chown "root:@RUN_AS_GROUP@" "$(DESTDIR)/@CONFPATH@/$$F" \
+				|| { if $(WITH_CGI) ; then exit 1 ; else true ; fi ; } ; \
+			done ; \
+			for F in nut.conf.sample ups.conf.sample upsd.conf.sample upsd.users.sample upsmon.conf.sample upssched.conf.sample ; do \
+				echo "  CHOWN(root:@RUN_AS_GROUP@)   $(DESTDIR)/@CONFPATH@/$$F" >&2 ; \
+				chown "root:@RUN_AS_GROUP@" "$(DESTDIR)/@CONFPATH@/$$F" \
+				|| exit ; \
+			done ; \
+		else \
+			echo "$@: WARNING: Can not CHOWN created locations!" >&2 ; \
+		fi ; \
+		if [ x"$(DESTDIR)" = x -o x"$(DESTDIR)" = x/ ] ; then \
+			if $(HAVE_SYSTEMD) ; then \
+				echo "$@: Activate default systemd layout, restart services:" >&2 ; \
+				if $(WITH_SYSTEMD_TMPFILES) ; then \
+					echo "$@: Apply systemd-tmpfiles presets" >&2 ; \
+					@SYSTEMD_TMPFILES_PROGRAM@ --create || exit ; \
+				fi ; \
+				echo "$@: Learn systemd definition changes" >&2 ; \
+				@SYSTEMD_SYSTEMCTL_PROGRAM@ daemon-reload || exit ; \
+				if $(WITH_SYSTEMD_PRESET) ; then \
+					echo "$@: Apply systemd enabled/disabled service presets" >&2 ; \
+					@SYSTEMD_SYSTEMCTL_PROGRAM@ preset-all || exit ; \
+				else \
+					echo "$@: Apply systemd enabled/disabled service defaults" >&2 ; \
+					@SYSTEMD_SYSTEMCTL_PROGRAM@ disable nut.target nut-driver.target nut-monitor nut-server nut-driver-enumerator.path nut-driver-enumerator.service || exit ; \
+					@SYSTEMD_SYSTEMCTL_PROGRAM@ enable  nut.target nut-driver.target nut-monitor nut-server nut-driver-enumerator.path nut-driver-enumerator.service || exit ; \
+				fi ; \
+				echo "$@: Reconfigure nut-driver-enumerator (service instance wrapping)" >&2 ; \
+				@SYSTEMD_SYSTEMCTL_PROGRAM@ restart udev || true ; \
+				$(top_builddir)/scripts/upsdrvsvcctl/nut-driver-enumerator.sh --reconfigure || { RES=$$?; if [ $$RES != 42 ] ; then exit $$RES ; fi ; } ; \
+				echo "$@: Restart NUT services" >&2 ; \
+				@SYSTEMD_SYSTEMCTL_PROGRAM@ restart nut-driver-enumerator.service nut-monitor.service nut-server.service || exit ; \
+			fi ; \
+		fi ; \
+		echo "$@: finished" >&2 ; \
+	 fi
+
 # Clean the dist tarball and packages
 MAINTAINERCLEANFILES_DISTBALL = nut-*.tar.gz
 # HP-UX:
-MAINTAINERCLEANFILES_PACKAGES = NUT_HPUX_package@PACKAGE_VERSION@.depot
+MAINTAINERCLEANFILES_PACKAGES = NUT_HPUX_package@PACKAGE_VERSION@.depot NUT_HPUX_package-@PACKAGE_VERSION@.depot
 # AIX as below, and RedHat-compatible (cover binary and source packages):
 MAINTAINERCLEANFILES_PACKAGES += nut*rpm
 # Debian-compatible (cover binary and source packages):
 MAINTAINERCLEANFILES_PACKAGES += nut*deb
 # Solaris SVR4 package archives:
-MAINTAINERCLEANFILES_PACKAGES += NUT_solaris_*_package@PACKAGE_VERSION@.local.gz
+MAINTAINERCLEANFILES_PACKAGES += NUT_solaris_*_package@PACKAGE_VERSION@.local.gz NUT_solaris_*_package-@PACKAGE_VERSION@.local.gz
 # Newer Solaris IPS (aka "pkg(5)" format archives)
 MAINTAINERCLEANFILES_PACKAGES += *.p5p
 
@@ -548,7 +756,7 @@ package: dist
 	"HP-UX") \
 		( cd scripts/HP-UX && \
 		  $(MAKE) $(AM_MAKEFLAGS) DESTDIR="$$DESTDIR" package && \
-		  mv NUT_HPUX_package.depot $(abs_top_builddir)/NUT_HPUX_package@PACKAGE_VERSION@.depot ) ;; \
+		  mv NUT_HPUX_package.depot $(abs_top_builddir)/NUT_HPUX_package-@PACKAGE_VERSION@.depot ) ;; \
 	"SunOS") \
 		$(MAKE) $(AM_MAKEFLAGS) && \
 		$(MAKE) $(AM_MAKEFLAGS) DESTDIR="$$DESTDIR" install && \