diff --git a/Makefile.am b/Makefile.am index c367c904a2..cf055eaf5b 100644 --- a/Makefile.am +++ b/Makefile.am @@ -134,6 +134,17 @@ spellcheck spellcheck-interactive: (cd $(builddir)/docs/man && $(MAKE) -s $@) || RES=$$? ; \ (cd $(builddir)/conf && $(MAKE) -s $@) || RES=$$? ; \ (cd $(builddir)/data && $(MAKE) -s $@) || RES=$$? ; \ + (cd $(builddir)/data/html && $(MAKE) -s $@) || RES=$$? ; \ + (cd $(builddir)/scripts && $(MAKE) -s $@) || RES=$$? ; \ + (cd $(builddir)/scripts/Solaris && $(MAKE) -s $@) || RES=$$? ; \ + (cd $(builddir)/scripts/Windows && $(MAKE) -s $@) || RES=$$? ; \ + (cd $(builddir)/scripts/devd && $(MAKE) -s $@) || RES=$$? ; \ + (cd $(builddir)/scripts/hotplug && $(MAKE) -s $@) || RES=$$? ; \ + (cd $(builddir)/scripts/python && $(MAKE) -s $@) || RES=$$? ; \ + (cd $(builddir)/scripts/systemd && $(MAKE) -s $@) || RES=$$? ; \ + (cd $(builddir)/scripts/udev && $(MAKE) -s $@) || RES=$$? ; \ + (cd $(builddir)/scripts/upsdrvsvcctl && $(MAKE) -s $@) || RES=$$? ; \ + (cd $(builddir)/tests/NIT && $(MAKE) -s $@) || RES=$$? ; \ exit $$RES # Note: the "all-docs" and "check-docs" targets may require tools not diff --git a/data/html/Makefile.am b/data/html/Makefile.am index 4d0620ac68..90fa56fa28 100644 --- a/data/html/Makefile.am +++ b/data/html/Makefile.am @@ -4,7 +4,28 @@ if WITH_CGI dist_html_DATA = index.html bottom.html nut-banner.png nodist_html_DATA = header.html endif -EXTRA_DIST = README +EXTRA_DIST = README.adoc + +SPELLCHECK_SRC = README.adoc + +# NOTE: Due to portability, we do not use a GNU percent-wildcard extension: +#%-spellchecked: % Makefile.am $(top_srcdir)/docs/Makefile.am $(abs_srcdir)/$(NUT_SPELL_DICT) +# $(MAKE) -s -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC_ONE="$<" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + +# NOTE: Portable suffix rules do not allow prerequisites, so we shim them here +# by a wildcard target in case the make implementation can put the two together. +*-spellchecked: Makefile.am $(top_srcdir)/docs/Makefile.am $(abs_srcdir)/$(NUT_SPELL_DICT) + +.sample.sample-spellchecked: + $(MAKE) -s -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC_ONE="$<" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + +.in.in-spellchecked: + $(MAKE) -s -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC_ONE="$<" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + +spellcheck spellcheck-interactive spellcheck-sortdict: + $(MAKE) -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC="$(SPELLCHECK_SRC)" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + +CLEANFILES = *-spellchecked MAINTAINERCLEANFILES = Makefile.in .dirstamp # Generated by configure script: diff --git a/data/html/README b/data/html/README deleted file mode 100644 index ccaf070fc8..0000000000 --- a/data/html/README +++ /dev/null @@ -1,97 +0,0 @@ -Desc: NUT HTML complementary information -File: README -Date: 27 Jul 2005 -Auth: Arnaud Quette - Dave Breiland - -This file provides some complementary information -about the use and integration of NUT HTML pages. - -1) Introduction ---------------- - -NUT HTML pages have been created as a central point -that ease the access to the various CGI scripts -providing the NUT web interface. - -It consists of three .html files: -- index.html: defines the two container frames, -topFrame and mainFrame -- header.html: contain the header including links -to NUT website, and upsstat.cgi/upsset.cgi -- bottom.html: empty frame that will be replaced -with the content of upsstat.cgi or upsset.cgi. - -2) Integration --------------- - -You first need to install NUT CGI (ie using ./configure --with-cgi). -Refer to the README file for more information - -There are two ways to integrate NUT HTML with your -webserver, with the same results: - -a) take advantage of the existing tree -====================================== - -- the cgi are for example installed in /usr/lib/cgi-bin, -which is already configured in your webserver as the -default CGI path - -- in the same spirit, we will use the existing DocumentRoot -and create a "nut" subdirectory, and copy the three .html -files (index, header and bottom) - -Note that the links to cgi scripts in header.html are -pre configured to work in this situation, which ease -the packagers work. - -b) configure manually -===================== - -- copy the data/html directory to somepath (ie /usr/local/nut -for a standard installation from source) - --Now edit your webserver configuration file, adding for -example (for Apache): - -#Begin Section -ScriptAlias /nut/cgi-bin/ /usr/local/nut/cgi-bin/ - - AllowOverride AuthConfig - Options ExecCGI - Order allow,deny - Allow from all - - -Alias /nut/ /usr/local/nut/html/ - - Options None - AllowOverride AuthConfig - Order allow,deny - Allow from all - -#End Section - --Make sure to change the links path in header.html according to your -configuration and installation. - -3) Conclusion -============= - -- Make sure to restart your webserver. - --Configure the CGI scripts. Manpages can be found from: ---prompt> man -M /usr/local/nut/man/ upsstats.cgi ---prompt> man -M /usr/local/nut/man/ upsset.cgi ---prompt> man -M /usr/local/nut/man/ upsimage.cgi ---prompt> man -M /usr/local/nut/man/ hosts.conf - --It is recommended that you use .htaccess files in the cgi-bin folder and the -html folder. Please reference: -http://httpd.apache.org/docs/howto/htaccess.html - -- You will then be able to access the NUT HTML page at: -http://localhost/nut - - diff --git a/data/html/README.adoc b/data/html/README.adoc new file mode 100644 index 0000000000..fdd6659885 --- /dev/null +++ b/data/html/README.adoc @@ -0,0 +1,103 @@ +NUT HTML complementary information +================================== +Arnaud Quette , Dave Breiland +v1.0, 27 Jul 2005 (start date) + +This file provides some complementary information +about the use and integration of NUT HTML pages. + +1) Introduction +--------------- + +NUT HTML pages have been created as a central point +that ease the access to the various CGI scripts +providing the NUT web interface. + +It consists of three HTML files: + +* `index.html`: defines the two container frames, + `topFrame` and `mainFrame` +* `header.html`: contains the header including links + to NUT website, and `upsstats.cgi`/`upsset.cgi` +* `bottom.html`: empty frame that will be replaced + with the content of `upsstats.cgi` or `upsset.cgi`. + +2) Integration +-------------- + +You first need to install NUT CGI, i.e. using +---- +:; ./configure --with-cgi +---- + +Refer to the NUT documentation for more information. + +There are two ways to integrate NUT HTML with your +webserver, with the same results: + +a) take advantage of the existing tree +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- the cgi programs are (for example) installed in `/usr/lib/cgi-bin`, + which is already configured in your webserver as the default CGI path + +- in the same spirit, we will use the existing `DocumentRoot` (in terms + of Apache webserver) and create a `nut` subdirectory, and copy the + three `.html` files (`index`, `header` and `bottom`) + +Note that the links to cgi programs in `header.html` are pre-configured +to work in this situation, which eases the packagers' work. + +b) configure manually +~~~~~~~~~~~~~~~~~~~~~ + +- copy the `data/html` directory to some path (i.e. `/usr/local/nut` + for a standard installation from source) + +- Now edit your webserver configuration file, adding for + example (for Apache): +---- +#Begin Section +ScriptAlias /nut/cgi-bin/ /usr/local/nut/cgi-bin/ + + AllowOverride AuthConfig + Options ExecCGI + Order allow,deny + Allow from all + + +Alias /nut/ /usr/local/nut/html/ + + Options None + AllowOverride AuthConfig + Order allow,deny + Allow from all + +#End Section +---- + +- Make sure to change the links path in `header.html` according to your + configuration and installation. + +3) Conclusion +------------- + +- Make sure to restart your webserver. + +- Configure the CGI scripts. Manpages can be found from: +---- +:; man -M /usr/local/nut/man/ upsstats.cgi +:; man -M /usr/local/nut/man/ upsset.cgi +:; man -M /usr/local/nut/man/ upsimage.cgi +:; man -M /usr/local/nut/man/ hosts.conf +---- + +- It is recommended that you use `.htaccess` files in the `cgi-bin` folder + and the `html` folder. Please reference: + http://httpd.apache.org/docs/howto/htaccess.html + +- You will then be able to access the NUT HTML page at: + http://localhost/nut + +- Further protection with HTTPS is recommended, especially for installations + on networks accessible by someone other than yourself. diff --git a/docs/Makefile.am b/docs/Makefile.am index 3abaf26c6f..9e7b8eba50 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -420,12 +420,43 @@ ASPELL_OUT_NOTERRORS = (^[ \t]*[\*\@]|^$$) # # NOTE: This portable rule RELIES on just one SPELLCHECK_SRC defined # at a time, with an outer Makefile caller ensuring the looping: + +SPELLCHECK_RECIPE_DEBUG_STREAM = /dev/null +#SPELLCHECK_RECIPE_DEBUG_STREAM = &2 + $(SPELLCHECK_BUILDDIR)/$(SPELLCHECK_SRC_ONE)-spellchecked: $(SPELLCHECK_SRCDIR)/$(SPELLCHECK_SRC_ONE) $(abs_top_srcdir)/docs/Makefile.am $(abs_srcdir)/$(NUT_SPELL_DICT) @LANG=C; LC_ALL=C; export LANG; export LC_ALL; \ if test x"$(SPELLCHECK_SRC_ONE)" = x ; then echo "SKIP: Bogus spellcheck call for empty target filename (with make target $@)" >&2 ; exit 0; fi; \ case "$@" in *-spellchecked) ;; *) echo "SKIP: Bogus spellcheck call for non '*-spellchecked' target filename (with make target $@)" >&2 ; exit 0;; esac; \ rm -f "$@" || true ; \ - echo " ASPELL Spell checking on $(SPELLCHECK_SRCDIR)/$(SPELLCHECK_SRC_ONE)"; \ + REPORT_SRCDIR="$(SPELLCHECK_SRCDIR)"; \ + REPORT_SRC_ONE="$(SPELLCHECK_SRC_ONE)"; \ + REPORT_PREFIX="" ; \ + case "$(SPELLCHECK_SRC_ONE)" in \ + /*) ;; \ + */*) if [ x"$${REPORT_SRCDIR}" = x ] ; then \ + echo EMPTY >$(SPELLCHECK_RECIPE_DEBUG_STREAM) ; \ + REPORT_SRCDIR="`dirname "$(SPELLCHECK_SRC_ONE)"`"; \ + else \ + echo "APPEND: SPELLCHECK_SRCDIR='$(SPELLCHECK_SRCDIR)' SPELLCHECK_SRC_ONE='$(SPELLCHECK_SRC_ONE)' dirname='`dirname "$(SPELLCHECK_SRC_ONE)"`'" >$(SPELLCHECK_RECIPE_DEBUG_STREAM) ; \ + REPORT_SRCDIR="$${REPORT_SRCDIR}/`dirname "$(SPELLCHECK_SRC_ONE)"`"; \ + fi ; \ + REPORT_SRC_ONE="`basename "$(SPELLCHECK_SRC_ONE)"`"; \ + ;; \ + *) ;; \ + esac; \ + if [ x"$${REPORT_SRCDIR}" != x ] ; then \ + tmpREPORT_PREFIX="NUT source root :: $${REPORT_SRCDIR} :: " ; \ + REPORT_SRCDIR="`cd "$${REPORT_SRCDIR}" && { pwd >$(SPELLCHECK_RECIPE_DEBUG_STREAM) ; pwd | sed 's|^'"$(abs_top_srcdir)"'/*||' ; }`" \ + || { REPORT_SRCDIR="$(SPELLCHECK_SRCDIR)" ; REPORT_SRC_ONE="$(SPELLCHECK_SRC_ONE)" ; REPORT_PREFIX="" ; } ; \ + fi ; \ + echo "=== Got REPORT_SRCDIR='$${REPORT_SRCDIR}'" >$(SPELLCHECK_RECIPE_DEBUG_STREAM) ; \ + case "$${REPORT_SRCDIR}" in \ + "") ;; \ + */) ;; \ + *) REPORT_SRCDIR="$${REPORT_SRCDIR}/" ;; \ + esac ; \ + echo " ASPELL Spell checking on $${REPORT_PREFIX}$${REPORT_SRCDIR}$${REPORT_SRC_ONE}"; \ OUT="`(sed 's,^\(.*\)$$, \1,' | $(ASPELL) -a $(ASPELL_NUT_TEXMODE_ARGS) $(ASPELL_NUT_COMMON_ARGS) 2>&1) < "$(SPELLCHECK_SRCDIR)/$(SPELLCHECK_SRC_ONE)"`" \ && { if test -n "$$OUT" ; then OUT="`echo "$$OUT" | $(EGREP) -b -v '$(ASPELL_OUT_NOTERRORS)' `" ; fi; \ test -z "$$OUT" ; } \ diff --git a/docs/nut.dict b/docs/nut.dict index fa9b46d7cb..f58ce86758 100644 --- a/docs/nut.dict +++ b/docs/nut.dict @@ -1,4 +1,4 @@ -personal_ws-1.1 en 3283 utf-8 +personal_ws-1.1 en 3410 utf-8 AAC AAS ABI @@ -79,6 +79,7 @@ AsciiDoc Asium Ates AudibleAlarmControl +AuthConfig AutoFrq AutoMsg AutoRst @@ -174,6 +175,7 @@ CERTIDENT CERTREQUEST CERTVERIF CEST +CHOST CHRG CL CLANGVER @@ -215,6 +217,7 @@ ChangeLog ChargdV Chatziathanassiou CheckUPS +CheckUPSAvailable Checksum Chiou Chu @@ -264,6 +267,7 @@ DF DHEA DIGYS DISCHRG +DLDIR DLLs DMF DN @@ -271,26 +275,32 @@ DNS DOCTYPE DOMAINs DPC +DPURIFY DRIVERLIST DS DSA DSHUTD DSL DTE +DTrace DUMPALL DUMPDONE DWAKE DWITH DX Daniele +Dashjr DataRoom Dbnc +Ddtrace DeepTstFail Defensor DeltaUPSv DeviceID DeviceKit DeviceLogin +DeviceLogout +Dgtk Dharm DiSplay Diehl @@ -298,11 +308,17 @@ Dietze Digitus Digys Dimitris +Dinstalled Disassembly +Dlibelf Dly +Dman Dmitry DocBook +DocumentRoot Doxygen +DriverInstaller +Dsystemtap Dynamix Dynex EAGAIN @@ -354,6 +370,7 @@ Eriksson Evgeny Exar ExecCGI +ExecStartPre FD FEMEA FFF @@ -401,12 +418,15 @@ FreqSens Frolov FullLoad Fuß +GC GCCVER GES GETADDRINFO GID GKrellM GND +GNUmakefile +GObject GPIO GPIOCHIP GPL @@ -414,6 +434,7 @@ GPSER GRs GTK GUESSTIMATION +GUID GUIs GWD GXE @@ -427,6 +448,10 @@ Gathman Gembe GenTestFail Gert +GetRWVars +GetUPSCommands +GetUPSList +GetUPSNames GetUPSVars Ghali Giese @@ -435,6 +460,7 @@ GitHub GitHub's Gnd Gnomovision +GnuTLS Goebl Golang Gomes @@ -490,6 +516,7 @@ Homebrew Homebridge Hoogervorst Hough +Hrusecky Hunnox Hurd Håvard @@ -527,6 +554,7 @@ ITEMP ITy IVT IZ +ImageFiles Infosec Innova Integrators @@ -557,6 +585,7 @@ Javadoc Javascript Jenkinsfile JoinControllers +Jong Joon Jumpered KNutClient @@ -596,6 +625,8 @@ LDADD LDFLAGS LDLC LDRIVER +LDSHARED +LDSHAREDLIBC LEDs LGTM LH @@ -799,6 +830,7 @@ NaturalDocs Necedah NetBSD NetBeans +NetInvent NetPro NetServer NetUps @@ -816,6 +848,7 @@ NomVOut NotePad Novell NrLoBatt +NuGet NutException Nxx OAH @@ -867,6 +900,7 @@ Opengear's Opensource Opti OptiUPS +Orsiris Orvaldi Orzechowski OutletSystem @@ -901,6 +935,7 @@ POSIX POWERDOWNFLAG POWEREX POWERLINE +PPA PPD PPDn PPDnnn @@ -927,6 +962,7 @@ PV PWLv PWR PXG +PYTHONPATH PaaS Pac PackageRequired @@ -994,9 +1030,12 @@ Proxmox Prynych Pulizzi PwrOut +PyDOC PyGTK PyNUT PyNUTClient +PyNUTError +PyPI PyQt QBDR QBT @@ -1086,11 +1125,13 @@ Rodríguez Rouben Rozman Rucelf +RunUPSCommand RuntimeWarning RxD RxHs Ryabov SAI +SASU SCM SCO SCR @@ -1146,6 +1187,7 @@ SOFF SOLA SOLA's SOMECO +SOURCEMODE SOV SPARC SPC @@ -1156,6 +1198,7 @@ SRC SSSS STARTTLS STB +STDCALL STESTI STI STIME @@ -1166,6 +1209,7 @@ SUNWugen SUNWusb SURTD SUSE +SVR SX SXI SXL @@ -1189,12 +1233,15 @@ Sep Sequentializing SerialNumber Serv +Serveur +SetRWVar Shara ShareAlike Shaul ShdnDbnc ShdnDly ShdnPol +ShutDown Shutdn Sibbald Sicon @@ -1299,6 +1346,7 @@ Tigra Tnn ToddGreenfield Tomek +Toolset TopGuard Toth Traceback @@ -1333,6 +1381,7 @@ UPSHOST UPSIMAGEPATH UPSLC UPSNOTIFY +UPSName UPSOutletSystemOutletDelayBeforeReboot UPSOutletSystemOutletDelayBeforeShutdown UPSOutletSystemOutletDelayBeforeStartup @@ -1403,10 +1452,13 @@ WARNOPT WCH WELI WHAD +WIP WIPO WMNut WS +WSDIR WSE +WSL WTU Waldie WantedBy @@ -1416,11 +1468,13 @@ Werror Weverything Wextra WhizBang +WiX Wikipedia WinMerge WinNUT WinPower Wireshark +Wl WordFmt Wrede XAU @@ -1437,10 +1491,12 @@ XSL XT XUPS XXXX +XXXXXXXXXXXX XYZ Xfer XferDly XfmrRes +Xlinker Xpert Xups Xymon @@ -1476,6 +1532,7 @@ acpi acquisited acvoltsin acvoltsout +acx adb addcmd addenum @@ -1528,8 +1585,10 @@ apcsmart apctest apcupsd aphel +apinames appveyor ar +architecting archlinux arduino arg @@ -1573,6 +1632,7 @@ autogen automagically automake automessage +autopoint autoreconf autorestart autosaving @@ -1586,7 +1646,10 @@ avahi avr awd awk +b'some +b'string bAlternateSetting +bUps backend backends backgrounding @@ -1645,6 +1708,7 @@ bootable bp br brazil +brotli bsd bsv bt @@ -1660,6 +1724,7 @@ bugfix bugfixes buildbots builddir +buildtype bullseye busport busybox @@ -1806,6 +1871,7 @@ cx cyberpower d'un da +daemonized daisychain daisychained databits @@ -1819,6 +1885,7 @@ dayofweek dblatex dcd dcn +ddk ddl de deUNV @@ -1831,6 +1898,7 @@ decrypt dedb dedup deduplication +defs defun dep dephasing @@ -1874,6 +1942,7 @@ dockapp docs dod domxml +dotnet downloadable dpkg dq @@ -1917,6 +1986,7 @@ ei el emacs emptor +emptyDir endchar enddate endian @@ -1957,6 +2027,7 @@ executables executeCommand execve extendedhistory +extern externalConsole extradata fabula @@ -1989,14 +2060,18 @@ firewalling firmwares flts fmt +fno +fontconfig footnoteref forceshutdown forcessl formatconfig formatparam +formatstring fp freebsd freeipmi +freetype freqsensitivity frob frontends @@ -2036,11 +2111,13 @@ getent getenv getopt gettext +gettextize getvar gitcache github gitignore gitk +gitlab gmail gmake gnuplot @@ -2048,6 +2125,7 @@ gnutls google goto gotos +gperf gpg gpgsign gpio @@ -2109,7 +2187,9 @@ iUSB ib ibattery icd +iconv icp +icu idProduct idVendor ident @@ -2145,14 +2225,17 @@ initinfo initscripts initups inline +inlined innotech inode inplace +installable installcheck installpkg installurl instcmd instcmds +integrations intel intelliSenseMode intercharacter @@ -2163,6 +2246,7 @@ interoperating interprocess interruptonly interruptsize +intltool invcontdelay invcontpolarity inverter @@ -2199,6 +2283,7 @@ jenkins jessie jimklimov journalctl +jpeg jpg jpgraph jre @@ -2252,10 +2337,14 @@ libgpiod libhid libhidups libi +libiconv +libintl libipmimonitoring libltdl +liblzma libmodbus libneon +libnetsnmp libnss libnut libnutclient @@ -2279,9 +2368,12 @@ libusb's libusbugen libusbx libvirt +libwdi libwrap +libxml libxslt libxxx +libz licensor licensors liebert @@ -2302,6 +2394,7 @@ lldb llvm lm ln +lnetsnmp loadPercentage localhost localtime @@ -2323,6 +2416,7 @@ lowruntime lowvoltsout lposix lr +lregex lsd lsusb lt @@ -2331,6 +2425,7 @@ lu lua lv lvo +lws lxc lxcbr lxccontainer @@ -2343,6 +2438,7 @@ mS macaddr macosx mailx +mainFrame maintainer's maintainership maj @@ -2352,6 +2448,7 @@ mandir manpage manpages masterguard +matcher maxacvi maxacvo maxd @@ -2483,6 +2580,7 @@ nitram nl nlb nlogic +nls nm nn nnn @@ -2490,6 +2588,7 @@ noAuthNoPriv nobody's nobt nodev +nodownload nodtk noexec noflag @@ -2519,6 +2618,7 @@ nowarn np nss ntUPSd +nuget num numOfBytesFromUPS numa @@ -2598,6 +2698,7 @@ pathnames pbzip pc pconf +pcre pcs pdf pdu @@ -2620,6 +2721,7 @@ pijuice pinout pinouts pipename +pixmaps pkg pkgconf pkgconfig @@ -2639,6 +2741,7 @@ pollonly popa portname porttype +posix powercom powerdev powerdown @@ -2685,6 +2788,8 @@ prog prtconf ps psu +pthread +pthreads pts pty pulizzi @@ -2700,6 +2805,7 @@ pycparser pydoc pygments pynut +qDEB qa qemu qfs @@ -2781,6 +2887,7 @@ rqt rsa rsync rts +ru rubygem runlevel runtime @@ -2795,6 +2902,7 @@ salicru sbin sbindir scd +sched scm screenshot screenshots @@ -2802,6 +2910,7 @@ scriptname sd sdb sddelay +sdk sdl sdorder sdtime @@ -2886,6 +2995,7 @@ socomec solaris solibs solis +somename somepass something's sp @@ -2920,6 +3030,7 @@ stopAtEntry stopIP stopbits str +strUps strace strarr strcasecmp @@ -2963,6 +3074,7 @@ svcs svn sw symlink +symlinked symlinking symlinks symmetrathreephase @@ -3026,6 +3138,8 @@ tmpfs tmpring toolchain toolkits +toolset +topFrame topbot tport transmitxhs @@ -3068,6 +3182,7 @@ udev udevadm ufw ugen +ui uid uint ukUNV @@ -3081,11 +3196,13 @@ undefine undervoltage unescaped unicast +unicode uninstall uninterruptible uniq unistd unitidentify +unix unmapped unmounts unpowered @@ -3101,6 +3218,7 @@ upsIdent upsIdentModel upsMIB upsObjects +upsadmin upsc upscli upsclient @@ -3132,6 +3250,7 @@ upsmon's upsmonuser upsname upsonbatt +upspass upspasswd upsrw upssched @@ -3210,6 +3329,7 @@ waitbeforereconnect wakeup wc wchar +wdi webNUT webnut webserver @@ -3219,8 +3339,10 @@ wget whitespace wiki wildcards +wininit winnutclient winpthreads +wix wmNUT wmnut wordformat @@ -3253,10 +3375,13 @@ xfmrresistance xh xhci xhtml +xjf xmalloc xml xmllint +xmlto xpg +xpm xr xrealloc xsl @@ -3267,6 +3392,8 @@ xu xxxAP xxxx xxxxAP +xz +xzf yaml yml youruid diff --git a/scripts/Makefile.am b/scripts/Makefile.am index 6113a2b3f5..e90db0bc54 100644 --- a/scripts/Makefile.am +++ b/scripts/Makefile.am @@ -1,4 +1,7 @@ -EXTRA_DIST = README \ +# Network UPS Tools: scripts (root) + +EXTRA_DIST = \ + README.adoc \ avahi/nut.service.in \ HP-UX/nut-drvctl \ HP-UX/nut-drvctl.sh \ @@ -11,7 +14,7 @@ EXTRA_DIST = README \ misc/osd-notify \ perl/Nut.pm \ RedHat/halt.patch \ - RedHat/README \ + RedHat/README.adoc \ RedHat/ups.in \ RedHat/upsd.in \ RedHat/upsmon.in \ @@ -20,9 +23,32 @@ EXTRA_DIST = README \ subdriver/gen-snmp-subdriver.sh \ upower/95-upower-hid.hwdb \ upower/95-upower-hid.rules \ + usb_resetter/README.adoc \ + usb_resetter/nut-driver.service \ Windows/halt.c \ Windows/Makefile SUBDIRS = augeas devd hotplug python systemd udev ufw Solaris Windows upsdrvsvcctl +SPELLCHECK_SRC = README.adoc RedHat/README.adoc usb_resetter/README.adoc + +# NOTE: Due to portability, we do not use a GNU percent-wildcard extension: +#%-spellchecked: % Makefile.am $(top_srcdir)/docs/Makefile.am $(abs_srcdir)/$(NUT_SPELL_DICT) +# $(MAKE) -s -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC_ONE="$<" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + +# NOTE: Portable suffix rules do not allow prerequisites, so we shim them here +# by a wildcard target in case the make implementation can put the two together. +*-spellchecked: Makefile.am $(top_srcdir)/docs/Makefile.am $(abs_srcdir)/$(NUT_SPELL_DICT) + +.sample.sample-spellchecked: + $(MAKE) -s -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC_ONE="$<" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + +.in.in-spellchecked: + $(MAKE) -s -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC_ONE="$<" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + +spellcheck spellcheck-interactive spellcheck-sortdict: + $(MAKE) -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC="$(SPELLCHECK_SRC)" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + +CLEANFILES = *-spellchecked RedHat/*-spellchecked usb_resetter/*-spellchecked + MAINTAINERCLEANFILES = Makefile.in .dirstamp diff --git a/scripts/README b/scripts/README deleted file mode 100644 index f31e10312c..0000000000 --- a/scripts/README +++ /dev/null @@ -1,12 +0,0 @@ -These directories hold various scripts: -- example startup and shutdown scripts for various operating systems and -distributions, -- hotplug and udev integration for on the fly privileges settings (Linux only), -- UPower (previously DeviceKit-power) rules file, -- Python Client module and application, -- Perl client module, -- Augeas support lenses and modules for NUT, -- systemd support files. - -They have either been contributed by users of the software, or by the NUT Team -itself. diff --git a/scripts/README.adoc b/scripts/README.adoc new file mode 100644 index 0000000000..8125b1771c --- /dev/null +++ b/scripts/README.adoc @@ -0,0 +1,25 @@ +NUT contributed and integration scripts +======================================= + +These directories hold various scripts and resources needed for systems +integration, and other non-core functionality, which were contributed +over time by the NUT Team, side projects and/or general community members +(users of the software), including: + +- example startup and shutdown scripts for various operating systems and + distributions, +- `hotplug` and `udev` integration for on the fly privileges settings + (Linux only), +- `UPower` (previously `DeviceKit-power`) rules file, +- Python Client module and application, +- Perl client module, +- Augeas support lenses and modules for NUT, +- support to run NUT components as service unit instances: + * shared `nut-driver-enumerator` and `upsdrvsvcctl` logic, + * `systemd` support files, + * SMF (Solaris/illumos Service Management Framework) support files, +- init-scripts and/or packaging elements for several Unix operating systems, +- Windows build helpers and information, +- software-driven USB reset suggestions and helpers (for stuck devices), +- `logrotate` integration, +- and many others. diff --git a/scripts/RedHat/README b/scripts/RedHat/README deleted file mode 100644 index d6023d1295..0000000000 --- a/scripts/RedHat/README +++ /dev/null @@ -1,3 +0,0 @@ -Install ups in /etc/rc.d/init.d - -/etc/sysconfig/ups is used only to store the POWERDOWNFLAG variable diff --git a/scripts/RedHat/README.adoc b/scripts/RedHat/README.adoc new file mode 100644 index 0000000000..8de3b7be46 --- /dev/null +++ b/scripts/RedHat/README.adoc @@ -0,0 +1,6 @@ +NUT integration files for older RedHat based Linux distributions +================================================================ + +Install `ups` in `/etc/rc.d/init.d` + +The `/etc/sysconfig/ups` is used only to store the `POWERDOWNFLAG` variable diff --git a/scripts/Solaris/Makefile.am b/scripts/Solaris/Makefile.am index 678b4eb8e6..bd7c6ad84e 100644 --- a/scripts/Solaris/Makefile.am +++ b/scripts/Solaris/Makefile.am @@ -1,4 +1,6 @@ -EXTRA_DIST = makelocal.sh precheck.py.in preproto.pl.in README +# Network UPS Tools: scripts/Solaris + +EXTRA_DIST = makelocal.sh precheck.py.in preproto.pl.in README.adoc PROTOTYPE_DIR = $(DESTDIR)@prefix@ SOLARIS_CHECK_TARGETS = PYTHON = @PYTHON@ @@ -89,4 +91,25 @@ check-local-solaris-smf: $(SOLARIS_SMF_MANIFESTS) /usr/sbin/svccfg validate "$$F" || RES=$$? ; \ done; exit $$RES +SPELLCHECK_SRC = README.adoc + +# NOTE: Due to portability, we do not use a GNU percent-wildcard extension: +#%-spellchecked: % Makefile.am $(top_srcdir)/docs/Makefile.am $(abs_srcdir)/$(NUT_SPELL_DICT) +# $(MAKE) -s -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC_ONE="$<" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + +# NOTE: Portable suffix rules do not allow prerequisites, so we shim them here +# by a wildcard target in case the make implementation can put the two together. +*-spellchecked: Makefile.am $(top_srcdir)/docs/Makefile.am $(abs_srcdir)/$(NUT_SPELL_DICT) + +.sample.sample-spellchecked: + $(MAKE) -s -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC_ONE="$<" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + +.in.in-spellchecked: + $(MAKE) -s -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC_ONE="$<" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + +spellcheck spellcheck-interactive spellcheck-sortdict: + $(MAKE) -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC="$(SPELLCHECK_SRC)" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + +CLEANFILES = *-spellchecked + MAINTAINERCLEANFILES = Makefile.in .dirstamp diff --git a/scripts/Solaris/README b/scripts/Solaris/README deleted file mode 100644 index adb305efdc..0000000000 --- a/scripts/Solaris/README +++ /dev/null @@ -1,38 +0,0 @@ -This directory contains init-scripts and SMF manifests and methods -for integration of NUT services with Solaris and descendant OSes. - -This also includes the nut-driver-enumerator.sh (service and implementation -method) and upsdrvsvcctl (tool) to manage NUT drivers as service instances, -which are stored in ../upsdrvsvcctl/ subdirectory (portable codebase shared -with Linux systemd). - -The default implementation (runs once) can be enabled with: - - svcadm enable nut-driver-enumerator:default - -Note that at the moment there is no out-of-the-box integration for triggering -a restart/refresh of the nut-driver-enumerator SMF service at the very instant -when the `ups.conf` file is modified, like there is with systemd path unit type. -Due to this, the systems administrator is expected to either invoke -`svcadm refresh nut-driver-enumerator` after changing the NUT configuration -or wait until the daemonized mode, if enabled, picks up the change (should do -so within a minute by default). However, a DTrace script or a tool like -https://github.com/emcrisostomo/fswatch wrapped into a service might be used -for equivalent effect. - -Alternatively, but somewhat more expensively, the same `nut-driver-enumerator.sh` -script can be executed in a loop as the payload of the SMF service to keep -inspecting the configuration and apply changes to the running system. It is -not a common use-case to keep changing device setups, so this solution is not -enforced by default ;) although a service variant is provided... - -Note that only one of these can be enabled at the same time: - - svcadm disable nut-driver-enumerator:default - svcadm enable nut-driver-enumerator:daemon - -Init-script solution contributed by numerous authors -SMF solution contributed by Jim Klimov - -For special notes about USB-connected device monitoring with NUT under Solaris -and related operating systems, see docs/solaris-usb.txt diff --git a/scripts/Solaris/README.adoc b/scripts/Solaris/README.adoc new file mode 100644 index 0000000000..ffb84adcd5 --- /dev/null +++ b/scripts/Solaris/README.adoc @@ -0,0 +1,69 @@ +Solaris/illumos helper scripts and resources +============================================ + +Overview +-------- + +This directory contains init-scripts and SMF manifests and methods for better +integration of NUT services with Solaris and descendant operating systems, +covering SVR4 packaging with init scripts and/or SMF services (as called from +`make package` in the source root). + +NOTE: IPS (`pkg(5)`) packaging is not currently provided here, but is a concern +of particular distributions. See for example the OpenIndiana userland recipe at +https://github.com/OpenIndiana/oi-userland/tree/oi/hipster/components/sysutils/nut + +This also includes the `nut-driver-enumerator.sh` (service and implementation +method) and `upsdrvsvcctl` (tool) to manage NUT drivers as service instances, +which are stored in `../upsdrvsvcctl/` subdirectory (portable codebase shared +with Linux systemd). + +SMF integration +--------------- + +The default implementation (which runs once per invocation) can be enabled +with: +---- +:; svcadm enable nut-driver-enumerator:default +---- + +Note that at the moment there is no out-of-the-box integration for triggering +a restart/refresh of the `nut-driver-enumerator` SMF service at the very instant +when the `ups.conf` file is modified, like there is with systemd path unit type. +Due to this, the systems administrator is expected to either invoke +`svcadm refresh nut-driver-enumerator` after changing the NUT configuration, +or wait until the daemonized mode, if enabled, picks up the change (should do +so within a minute by default). However, a DTrace script or a tool like +https://github.com/emcrisostomo/fswatch wrapped into a service might be used +for equivalent effect. + +Alternatively, but in a potentially more computationally expensive fashion, the +same `nut-driver-enumerator.sh` script can be executed in a loop as the payload +of the SMF service to keep inspecting the configuration regularly and so apply +changes to the running system. It is not a common use-case to keep changing +device setups, so this solution is not enforced by default ;) although an SMF +service variant for this is provided... + +Note that only one of these implementations can be enabled at the same time: +---- +:; svcadm disable nut-driver-enumerator:default +:; svcadm enable nut-driver-enumerator:daemon +---- + +Other +----- + +For special notes about USB-connected device monitoring with NUT under Solaris +and related operating systems, see also `docs/solaris-usb.txt`. The example +`reset-ups-usb-solaris.sh.sample` script can be used to reset USB connections +if a driver (or UPS controller) gets stuck -- but it needs to be adapted to +*your* system first. + +Credits +------- + +* Init-script solution and SVR4 packaging contributed by numerous authors + over the years + +* SMF solution and OpenIndiana packaging contributed by Jim Klimov + diff --git a/scripts/Windows/DriverInstaller/README.txt b/scripts/Windows/DriverInstaller/README.adoc similarity index 100% rename from scripts/Windows/DriverInstaller/README.txt rename to scripts/Windows/DriverInstaller/README.adoc diff --git a/scripts/Windows/Installer/README.adoc b/scripts/Windows/Installer/README.adoc index 21f16d7712..fdf377fedd 100644 --- a/scripts/Windows/Installer/README.adoc +++ b/scripts/Windows/Installer/README.adoc @@ -54,7 +54,7 @@ NUT for Windows uses the WiX Toolset to codify and implement the installer: * https://github.com/wixtoolset/ * https://github.com/wixtoolset/wix/ -The toolset in turn reqires the .NET framework (and the related NuGet tool) +The toolset in turn requires the .NET framework (and the related NuGet tool) which is available on Windows and Linux platforms, at least. In case of the latter (for cross-builds) note that many of the newer distribution releases should include dotnet packages in their repositories; for earlier releases @@ -96,11 +96,11 @@ likely need deeper investigation and update to be useful. Findings so far: or older) and the XML file which describes the installer actions and the file/directory structures it would deliver. * It would be helpful to find how to generate the filesystem structure - (names, GUIDs, what else?) based on the prototype area prepared by + (names, `GUID`s, what else?) based on the prototype area prepared by `make install DESTDIR=...` during a NUT build. It does not have to be part of *every* build (e.g. we can want this separated by driver types to allow end-users to install just a subset of NUT, similar - to how this happends with multi-package approach on Unix/Linux) but + to how this happens with multi-package approach on Unix/Linux) but an automated process which makes maintenance easier would be great: let a human sort where different filenames are categorized, and let automation discover that some installed files are not mentioned or diff --git a/scripts/Windows/Makefile.am b/scripts/Windows/Makefile.am index 972e823966..efc555de1f 100644 --- a/scripts/Windows/Makefile.am +++ b/scripts/Windows/Makefile.am @@ -1,11 +1,45 @@ -# Network UPS Tools: script/Windows +# Network UPS Tools: scripts/Windows AM_CFLAGS = -I$(top_srcdir)/include ../include/nut_version.h: FORCE (cd ../include/ && $(MAKE) $(AM_MAKEFLAGS) nut_version.h) -EXTRA_DIST = winevent.mc build-mingw-nut.sh README.adoc +EXTRA_DIST = \ + winevent.mc \ + build-mingw-nut.sh \ + build-mingw-prereqs.sh \ + dllldd.sh \ + README.adoc \ + DriverInstaller/wdi-simple.c \ + DriverInstaller/README.adoc \ + Installer/README.adoc \ + Installer/BuildInstaller.bat \ + Installer/NUT-Installer.xml.in \ + Installer/ImageFiles/icons/completi.ico \ + Installer/ImageFiles/icons/info.ico \ + Installer/ImageFiles/icons/custicon.ico \ + Installer/ImageFiles/icons/Up.ico \ + Installer/ImageFiles/icons/exclamic.ico \ + Installer/ImageFiles/icons/powernut_Stop.ico \ + Installer/ImageFiles/icons/repairic.ico \ + Installer/ImageFiles/icons/New.ico \ + Installer/ImageFiles/icons/removico.ico \ + Installer/ImageFiles/icons/powernut_logo.ico \ + Installer/ImageFiles/icons/insticon.ico \ + Installer/ImageFiles/Images/NUT_wix_vertical.bmp \ + Installer/ImageFiles/Images/NUT_wix_horizontal.bmp \ + Installer/ImageFiles/Others/StopService.bat \ + Installer/ImageFiles/Others/StartService.bat \ + Installer/ImageFiles/emptyDir/man1/temp.txt \ + Installer/ImageFiles/emptyDir/cgi-bin/temp.txt \ + Installer/ImageFiles/emptyDir/pkgconfig/temp.txt \ + Installer/ImageFiles/emptyDir/include/temp.txt \ + Installer/ImageFiles/emptyDir/html/temp.txt \ + Installer/ImageFiles/emptyDir/man3/temp.txt \ + Installer/ImageFiles/emptyDir/run/temp.txt + +CLEANFILES = *-spellchecked */*-spellchecked bin_PROGRAMS = @@ -34,8 +68,27 @@ nut_LDADD = ../../common/libcommon.la winevent.o halt_SOURCES = halt.c endif HAVE_WINDOWS -CLEANFILES = winevent.rc winevent.o winevent.h +CLEANFILES += winevent.rc winevent.o winevent.h endif HAVE_MINGW_RESGEN +SPELLCHECK_SRC = README.adoc DriverInstaller/README.adoc Installer/README.adoc + +# NOTE: Due to portability, we do not use a GNU percent-wildcard extension: +#%-spellchecked: % Makefile.am $(top_srcdir)/docs/Makefile.am $(abs_srcdir)/$(NUT_SPELL_DICT) +# $(MAKE) -s -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC_ONE="$<" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + +# NOTE: Portable suffix rules do not allow prerequisites, so we shim them here +# by a wildcard target in case the make implementation can put the two together. +*-spellchecked: Makefile.am $(top_srcdir)/docs/Makefile.am $(abs_srcdir)/$(NUT_SPELL_DICT) + +.sample.sample-spellchecked: + $(MAKE) -s -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC_ONE="$<" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + +.in.in-spellchecked: + $(MAKE) -s -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC_ONE="$<" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + +spellcheck spellcheck-interactive spellcheck-sortdict: + $(MAKE) -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC="$(SPELLCHECK_SRC)" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + MAINTAINERCLEANFILES = Makefile.in .dirstamp diff --git a/scripts/Windows/README.adoc b/scripts/Windows/README.adoc index 3349ed38a9..a3ad9e67a0 100644 --- a/scripts/Windows/README.adoc +++ b/scripts/Windows/README.adoc @@ -8,7 +8,7 @@ NUT is now also available for the Microsoft Windows platform. This methodology (and Windows support in general) are currently experimental, so pull requests are welcome to tie up some loose ends (add more prerequisites, -test and fix programs, re-enable some code just commented away by ifdefs...) +test and fix programs, re-enable some code just commented away by `ifdef`s...) NOTE: It is possible to prepare a Windows machine with tools and prerequisites for building NUT natively, as detailed in `docs/config-prereqs.txt` and easily @@ -98,6 +98,7 @@ or (it can help to open two terminals and copy one ARCH into each and then the lines below into both of them; be sure to use separate directory trees for the unpacked build workspaces) + - for either-ARCH build environment further set: ------ :; export HOST_FLAG="--host=$ARCH" @@ -549,7 +550,7 @@ NOTE: Ability to `make docs` here relies on presence of `xmlto` program. In NUT CI workers prepared according to `docs/config-prereqs.txt` this should be among dependencies for `asciidoc`; beware that with prerequisites it has quite a large installation footprint. Alternately check PR #69, or consult -the makefiles for current `install` target definition to run its job without +the Makefiles for current `install` target definition to run its job without `install-docs` part (example posted below). #:; ( cd "$DLDIR" && git clone -b fix-mingw-cross https://github.com/jimklimov/neon neon-git ) diff --git a/scripts/augeas/Makefile.am b/scripts/augeas/Makefile.am index b93033ee5b..dc5e924dee 100644 --- a/scripts/augeas/Makefile.am +++ b/scripts/augeas/Makefile.am @@ -1,7 +1,12 @@ +# Network UPS Tools: scripts/augeas EXTRA_DIST = gen-nutupsconf-aug.py.in nutupsconf.aug.tpl \ README.adoc tests/test_nut.aug +# Note: spellchecking is currently ensured by docs/Makefile.am +# due to inclusion into docs/developer-guide.txt, and the heading +# level may be also dictated by that. + PYTHON = @PYTHON@ # only call the script to generate Augeas ups.conf lens upon "make dist", diff --git a/scripts/augeas/README.adoc b/scripts/augeas/README.adoc index 9919ab798b..d70eada59f 100644 --- a/scripts/augeas/README.adoc +++ b/scripts/augeas/README.adoc @@ -12,11 +12,14 @@ In order to address this point, NUT now provides configuration tools and manipulation abstraction, to anybody who want to manipulate NUT configuration, through Augeas lenses and modules. -From link:http://augeas.net[Augeas homepage]: - -"Augeas is a configuration editing tool. It parses configuration files in their -native formats and transforms them into a tree. Configuration changes are made -by manipulating this tree and saving it back into native config files." +.From link:http://augeas.net[Augeas homepage]: +[quote] +____ +_Augeas is a configuration editing tool. It parses configuration files +in their native formats and transforms them into a tree. Configuration +changes are made by manipulating this tree and saving it back into +native config files._ +____ In other words, Augeas is the dreamed Registry, with all the advantages (such as a uniform interface and tools), and the added bonus of being @@ -39,11 +42,11 @@ are welcome). As an example, on Debian and derivatives, do the following: - $ apt-get install augeas-lenses augeas-tools + :; apt-get install augeas-lenses augeas-tools And optionally: - $ apt-get install libaugeas0 libaugeas-dev python-augeas + :; apt-get install libaugeas0 libaugeas-dev python-augeas On RedHat and derivatives, you have to install the packages 'augeas' and 'augeas-libs'. @@ -53,23 +56,23 @@ On RedHat and derivatives, you have to install the packages 'augeas' and NUT lenses and modules for Augeas ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -These are the *.aug files in the present directory. +These are the `*.aug` files in the present directory. You can either install the files to the right location on your system, -generally in '/usr/share/augeas/lenses/', or use these from NUT -source directory ('nut/scripts/augeas'). The latter is to be preferred for +generally in `/usr/share/augeas/lenses/`, or use these from NUT +source directory (`nut/scripts/augeas`). The latter is to be preferred for the time being. Create a test sandbox --------------------- -NOTE: for now, it's easier to include an existing /etc/nut/ directory. +NOTE: For now, it is easier to include an existing `/etc/nut/` directory. - $ export AUGEAS_ROOT=./augeas-sandbox - $ mkdir $AUGEAS_ROOT - $ sudo cp -pr /etc/nut $AUGEAS_ROOT - $ sudo chown -R $(id -nu):$(id -ng) $AUGEAS_ROOT + :; export AUGEAS_ROOT=./augeas-sandbox + :; mkdir $AUGEAS_ROOT + :; sudo cp -pr /etc/nut $AUGEAS_ROOT + :; sudo chown -R $(id -nu):$(id -ng) $AUGEAS_ROOT Start testing and using @@ -89,13 +92,13 @@ Shell Start an augeas shell using: - $ augtool -b + :; augtool -b -NOTE: if you have not installed NUT lenses, add '-I/path/to/nut/scripts/augeas'. +NOTE: If you have not installed NUT lenses, add `-I/path/to/nut/scripts/augeas`. From there, you can perform different actions like: -- list existing nut related files: +- list existing NUT-related files: augtool> ls /files/etc/nut/ nut.conf/ = (none) @@ -104,7 +107,7 @@ From there, you can perform different actions like: ups.conf/ = (none) upsd.conf/ = (none + -or using: +or using the matcher: + augtool> match /files/etc/nut/* /files/etc/nut/nut.conf = (none) @@ -112,21 +115,26 @@ or using: /files/etc/nut/upsmon.conf = (none) /files/etc/nut/ups.conf = (none) /files/etc/nut/upsd.conf = (none) - -NOTE: if you don't see anything, you may search for error messages by using: + +[NOTE] +====== +If you don't see anything, you may search for error messages by using: + augtool> ls /augeas/files/etc/nut/*/errors + and + augtool> get /augeas/files/etc/nut/ups.conf/error/message /augeas/files/etc/nut/ups.conf/error/message = Permission denied +====== -- create a new device entry (in ups.conf), called 'augtest': +- create a new device entry (in `ups.conf`), called `augtest`: augtool> set /files/etc/nut/ups.conf/augtest/driver dummy-ups augtool> set /files/etc/nut/ups.conf/augtest/port auto augtool> save -- list the devices using the 'usbhid-ups' driver: +- list the devices currently using the `usbhid-ups` driver: augtool> match /files/etc/nut/ups.conf/*/driver dummy-ups @@ -134,15 +142,15 @@ and C ~ -A library is available for C programs, along with pkg-config support. +A library is available for C programs, along with `pkg-config` support. You can get the compilation and link flags using the following code -in your configure script or Makefile: +in your program's `configure` script or `Makefile`: CFLAGS="`pkg-config --silence-errors --cflags augeas`" LDFLAGS="`pkg-config --silence-errors --libs augeas`" -Here is an code sample using this library for NUT configuration: +Here is a code sample using this library for NUT configuration: -------------------------------------------------------------------------------- augeas *a = aug_init(NULL, NULL, AUG_NONE); diff --git a/scripts/devd/Makefile.am b/scripts/devd/Makefile.am index 72a9031aab..e363a66d39 100644 --- a/scripts/devd/Makefile.am +++ b/scripts/devd/Makefile.am @@ -1,3 +1,4 @@ +# Network UPS Tools: scripts/devd if WITH_DEVD devdconfdir = $(devddir) @@ -7,7 +8,7 @@ if WITH_USB endif endif -EXTRA_DIST = README +EXTRA_DIST = README.adoc MAINTAINERCLEANFILES = Makefile.in .dirstamp @@ -24,3 +25,24 @@ MAINTAINERCLEANFILES += nut-usb.conf.in.AUTOGEN_WITHOUT # Part of dist tarball, regardless of use for current build: EXTRA_DIST += nut-usb.conf.in + +SPELLCHECK_SRC = README.adoc + +# NOTE: Due to portability, we do not use a GNU percent-wildcard extension: +#%-spellchecked: % Makefile.am $(top_srcdir)/docs/Makefile.am $(abs_srcdir)/$(NUT_SPELL_DICT) +# $(MAKE) -s -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC_ONE="$<" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + +# NOTE: Portable suffix rules do not allow prerequisites, so we shim them here +# by a wildcard target in case the make implementation can put the two together. +*-spellchecked: Makefile.am $(top_srcdir)/docs/Makefile.am $(abs_srcdir)/$(NUT_SPELL_DICT) + +.sample.sample-spellchecked: + $(MAKE) -s -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC_ONE="$<" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + +.in.in-spellchecked: + $(MAKE) -s -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC_ONE="$<" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + +spellcheck spellcheck-interactive spellcheck-sortdict: + $(MAKE) -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC="$(SPELLCHECK_SRC)" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + +CLEANFILES = *-spellchecked diff --git a/scripts/devd/README b/scripts/devd/README deleted file mode 100644 index 71381dce49..0000000000 --- a/scripts/devd/README +++ /dev/null @@ -1,12 +0,0 @@ -On FreeBSD, devd has a similar role to udev on Linux. - -The devd.conf file defines actions to perform when devices are plugged in. - -The tools/nut-usbinfo.pl script generates nut-usb.conf.in by processing USB -macros in all of the drivers. In this case, the defined action for each -matching UPS is to change the permissions such that the NUT drivers can -access the devices without requiring root privileges. You may need to -restart devd and re-plug in the UPS to trigger the actions. - -The format of this configuration file should work with devd on FreeBSD 9.0 -and 9.1, at the very least. diff --git a/scripts/devd/README.adoc b/scripts/devd/README.adoc new file mode 100644 index 0000000000..baefb3a9fa --- /dev/null +++ b/scripts/devd/README.adoc @@ -0,0 +1,20 @@ +NUT USB integration resources for FreeBSD devd +============================================== + +On FreeBSD, the `devd` subsystem has a similar role to `udev` on Linux. + +NOTE: Some FreeBSD based systems rely on "quirks" instead. + +The `devd.conf` file defines actions to perform when devices are plugged in. + +The `tools/nut-usbinfo.pl` script (under NUT source tree root) generates +the `nut-usb.conf.in` here by processing USB macros in all of the drivers. +In this case, the defined action for each matching UPS is to change the +permissions such that the NUT drivers can access the USB device nodes +without requiring root privileges. + +You may need to restart `devd` and re-plug in the UPS (or reboot) after +installation of the file in order to trigger the actions. + +The format of this configuration file should work with `devd` on FreeBSD 9.0 +and 9.1, at the very least. diff --git a/scripts/hotplug/Makefile.am b/scripts/hotplug/Makefile.am index 6595084913..7666ab93d5 100644 --- a/scripts/hotplug/Makefile.am +++ b/scripts/hotplug/Makefile.am @@ -1,4 +1,6 @@ -EXTRA_DIST = README +# Network UPS Tools: scripts/hotplug + +EXTRA_DIST = README.adoc if WITH_HOTPLUG hotplugusbdir = $(hotplugdir)/usb @@ -20,3 +22,24 @@ DISTCLEANFILES = libhidups # (technically, generated by tools/nut-usbinfo.pl script among # GENERATED_USB_OS_FILES): MAINTAINERCLEANFILES += libhid.usermap + +SPELLCHECK_SRC = README.adoc + +# NOTE: Due to portability, we do not use a GNU percent-wildcard extension: +#%-spellchecked: % Makefile.am $(top_srcdir)/docs/Makefile.am $(abs_srcdir)/$(NUT_SPELL_DICT) +# $(MAKE) -s -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC_ONE="$<" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + +# NOTE: Portable suffix rules do not allow prerequisites, so we shim them here +# by a wildcard target in case the make implementation can put the two together. +*-spellchecked: Makefile.am $(top_srcdir)/docs/Makefile.am $(abs_srcdir)/$(NUT_SPELL_DICT) + +.sample.sample-spellchecked: + $(MAKE) -s -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC_ONE="$<" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + +.in.in-spellchecked: + $(MAKE) -s -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC_ONE="$<" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + +spellcheck spellcheck-interactive spellcheck-sortdict: + $(MAKE) -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC="$(SPELLCHECK_SRC)" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + +CLEANFILES = *-spellchecked diff --git a/scripts/hotplug/README b/scripts/hotplug/README deleted file mode 100644 index aa036e72a9..0000000000 --- a/scripts/hotplug/README +++ /dev/null @@ -1,38 +0,0 @@ -Desc: Hotplug script for NUT USB drivers -File: scripts/hotplug/README -Date: 8 January 2007 -Auth: Arnaud Quette - -This document introduces Linux Hotplug script for NUT USB -drivers (usbhid-ups, bcmxcp_usb and tripplite_usb). - -These are needed, on older Linux systems, to ensure the right -privileges are set on the usb files (i.e. allowing nut user -to read AND write to the UPS device). - -Alternative ------------ - -For newer 2.6 kernels with the udev mechanism, you should use the -scripts in scripts/udev instead of this one. - -Installation ------------- - -For most users, these files will be automatically installed in -/etc/hotplug upon "make install", if that directory exists. -You can specify an alternate directory by running: - - ./configure --with-hotplug-dir=DIR - -Manual installation -------------------- -These scripts can be used with Linux 2.4 to 2.6.13. - -- possibly change libhidups to match NUT user -- copy libhidups and libhid.usermap to /etc/hotplug/usb/ -- make libhidups executable with: - chmod a+x /etc/hotplug/usb/libhidups -- call update-usb.usermap or equivalent if needed - -You can then plug your UPS, and start NUT. diff --git a/scripts/hotplug/README.adoc b/scripts/hotplug/README.adoc new file mode 100644 index 0000000000..a53b6dac46 --- /dev/null +++ b/scripts/hotplug/README.adoc @@ -0,0 +1,46 @@ +Hotplug script for NUT USB drivers +================================== +Arnaud Quette +v1.0, 8 January 2007 (start date) + +This document introduces Linux Hotplug script for NUT USB +drivers (`usbhid-ups`, `bcmxcp_usb` and `tripplite_usb`). + +These are needed, on older Linux systems, to ensure the right +privileges are set on the USB device node files (i.e. allowing +`nut` user to read AND write to the UPS device). + + +Alternative +----------- + +For newer 2.6 kernels with the `udev` mechanism, you should use +the scripts in `scripts/udev` instead of this one. + + +Installation +------------ + +For most users, these files will be automatically installed in +`/etc/hotplug` upon `make install`, if that directory exists. + +You can specify an alternate directory by running: +---- +:; ./configure --with-hotplug-dir=DIR +---- + + +Manual installation +------------------- + +These scripts can be used with Linux 2.4 to 2.6.13. + +- possibly change `libhidups` to match NUT user +- copy `libhidups` and `libhid.usermap` to `/etc/hotplug/usb/` +- make `libhidups` executable with: +---- +:; chmod a+x /etc/hotplug/usb/libhidups +---- +- call `update-usb.usermap` or equivalent if needed + +You can then plug your UPS, and start NUT. diff --git a/scripts/python/Makefile.am b/scripts/python/Makefile.am index e65512e774..7003c62ef7 100644 --- a/scripts/python/Makefile.am +++ b/scripts/python/Makefile.am @@ -191,6 +191,32 @@ endif ################################################################# +SPELLCHECK_SRC = \ + README.adoc \ + app/README.adoc \ + module/README.adoc + +# NOTE: Due to portability, we do not use a GNU percent-wildcard extension: +#%-spellchecked: % Makefile.am $(top_srcdir)/docs/Makefile.am $(abs_srcdir)/$(NUT_SPELL_DICT) +# $(MAKE) -s -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC_ONE="$<" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + +# NOTE: Portable suffix rules do not allow prerequisites, so we shim them here +# by a wildcard target in case the make implementation can put the two together. +*-spellchecked: Makefile.am $(top_srcdir)/docs/Makefile.am $(abs_srcdir)/$(NUT_SPELL_DICT) + +.sample.sample-spellchecked: + $(MAKE) -s -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC_ONE="$<" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + +.in.in-spellchecked: + $(MAKE) -s -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC_ONE="$<" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + +spellcheck spellcheck-interactive spellcheck-sortdict: + $(MAKE) -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC="$(SPELLCHECK_SRC)" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + +CLEANFILES = *-spellchecked */*-spellchecked + +################################################################# + MAINTAINERCLEANFILES = Makefile.in .dirstamp clean-local: diff --git a/scripts/python/README.adoc b/scripts/python/README.adoc index 4c18bedb36..72e268063b 100644 --- a/scripts/python/README.adoc +++ b/scripts/python/README.adoc @@ -7,44 +7,55 @@ by David Goncalves, and released under GPL v3. module ~~~~~~ -This directory contains PyNUT.py, which is a Python abstraction class to +This directory contains `PyNUT.py`, which is a Python abstraction class to access NUT data server(s). You can use it in Python programs to access NUT's -upsd data server in a simple way, without having to know the NUT protocol. +`upsd` data server in a simple way, without having to know the NUT protocol. The same module should work for Python 2 and Python 3. -To import it on Python programs you have to use the following (case sensitive): +To import it into Python programs you have to use the following line (case +sensitive): import PyNUT -This module provides a 'PyNUTClient' class that can be used to connect and -get data from an upsd data server. +This module provides a `PyNUTClient` class that can be used to connect and +get data from an `upsd` data server. -To install the PyNUT module on Debian/Ubuntu, copy it to: -/usr/share/python-support/python-pynut/ +To install the `PyNUT` module on Debian/Ubuntu, copy it to: +`/usr/share/python-support/python-pynut/` For quick tests, just make sure its directory is exported in `PYTHONPATH` environment variable. -This directory also contains test_nutclient.py, which is a PyNUT test program. -For this to be fully functional, you will need to adapt the login, password and -upsname to fit your configuration. A NUT data server should be running for the -test program to verify connection and protocol support. +This directory also contains `test_nutclient.py`, which is a `PyNUT` test program +and it also serves as a code example. For this to be fully functional, you will +need to adapt the login, password and upsname to fit your configuration. +A NUT data server should be running for the test program to verify connection +and protocol support. For one practical example, you can research `tests/NIT/nit.sh` in NUT sources. app ~~~ -This directory contains the NUT-Monitor application, which uses the -PyNUT class, along with its resources. +This directory contains the `NUT-Monitor` UI application, which uses the +`PyNUT` class, along with its own resources. + +There are two closely related separate implementations, for Python 2 with GTK2 +and for Python 3 with Qt5. Both can be installed at the same time, if your +distribution has not yet outlawed the obsolete Python 2 interpreters. To install it, you will either need to keep the files together, or to install: -- Depending on the Python version(s) your system has, put NUT-Monitor-py2gtk2 - or NUT-Monitor-py3qt5 to /usr/bin/, /usr/X11R6/bin/ or something like that - (optionally making a simple NUT-Monitor symlink to the preferred version), -- ui/*.glade (for NUT-Monitor-py2gtk2) or ui/*.ui (for NUT-Monitor-py3qt5) - to /usr/share/nut-monitor/, -- nut-monitor.png to something like /usr/share/pixmaps/ -- finally, nut-monitor-py2gtk2.desktop and/or nut-monitor-py3qt5.desktop - (optionally symlinked as nut-monitor.desktop) to /usr/share/applications/ + +- Depending on the Python version(s) your system has, put `NUT-Monitor-py2gtk2` + and/or `NUT-Monitor-py3qt5` to `/usr/bin/`, `/usr/X11R6/bin/` or something + like that (optionally making a simple `NUT-Monitor` symlink to the preferred + implementation version or using the provided wrapper script), +- `ui/*.glade` (for `NUT-Monitor-py2gtk2`) or `ui/*.ui` (for `NUT-Monitor-py3qt5`) + files to `/usr/share/nut-monitor/`, +- `nut-monitor.png` to something like `/usr/share/pixmaps/`, +- finally, `nut-monitor-py2gtk2.desktop` and/or `nut-monitor-py3qt5.desktop` + (optionally symlinked as `nut-monitor.desktop`) to `/usr/share/applications/` + +The `PyNUT` module can be kept nearby, or must be installed as a "site" or "vendor" +provided script into your Python modules location. See the wrapper script for more technical details. diff --git a/scripts/python/app/README.adoc b/scripts/python/app/README.adoc index 2f8482211b..f2d31afb96 100644 --- a/scripts/python/app/README.adoc +++ b/scripts/python/app/README.adoc @@ -12,19 +12,22 @@ uses the python-pynut class (available at http://www.lestat.st), delivered as PyNUT in the NUT source tree. Refer to your OS packaging and/or install custom modules with `pip` (or `pip3`) -to get required dependencies (GTK + GObject or QT5). +to get required dependencies (GTK + GObject or Qt5). Path to PyNUT module -------------------- For quick tests (e.g. during development), you can run the clients like this: -```` + +---- :; PYTHONPATH=../module/ python2 ./NUT-Monitor-py2gtk2.in -```` +---- + or: -```` + +---- :; PYTHONPATH=../module/ python3 ./NUT-Monitor-py3qt5.in -```` +---- Localization ------------ @@ -50,7 +53,7 @@ image::screenshots/nut-monitor-1.png[Example of device status overview] image::screenshots/nut-monitor-2.png[Example report of device variables] -image::screenshots/nut-monitor-3.png[Example modification of a writeable variable] +image::screenshots/nut-monitor-3.png[Example modification of a writable variable] Kudos ----- @@ -58,7 +61,7 @@ Kudos NUT-Monitor and PyNUT (for Python 2 syntax) were originally authored by David Goncalves -NUT-Monitor was converted to Python 3 + QT5 by Luke Dashjr +NUT-Monitor was converted to Python 3 + Qt5 by Luke Dashjr PyNUT was extended, and two variants of NUT-Monitor converged and wrapped for Python 2+3 dual support by Jim Klimov diff --git a/scripts/python/module/README.adoc b/scripts/python/module/README.adoc index 87c7b6114d..8397806dce 100644 --- a/scripts/python/module/README.adoc +++ b/scripts/python/module/README.adoc @@ -99,7 +99,7 @@ Although the original project was written in French, for the reasons of general distribution with NUT, all of its code is commented in English. While this file contains the description from https://www.lestat.st/informatique/projets/pynut the class `PyNUTClient` is compatible with the Python module PyDOC, so you can -type `pydoc PyNUT` to obtain succint documentation on your current version of +type `pydoc PyNUT` to obtain succinct documentation on your current version of the module. For more examples see the provided test script and the NUT-Monitor application @@ -126,7 +126,7 @@ ver ~~~ Sends the `VER` command to the NUT data server and returns its self-reported -identification such as version, product or distribution it may be bunded with. +identification such as version, product or distribution it may be bundied with. Note that the NUT client interactions should not rely on reported versions, but follow the protocol as defined. @@ -168,7 +168,7 @@ evaluates the server response. ----- import PyNUT - ups = PyNUT.PyNUTClient( host='serveur', login='upsadmin', password='upspass' ) + ups = PyNUT.PyNUTClient( host='server', login='upsadmin', password='upspass' ) result = ups.CheckUPSAvailable( ups='ups1' ) print( result ) @@ -188,7 +188,7 @@ of "variable"-"current value" pairs. ----- import PyNUT - ups = PyNUT.PyNUTClient( host='serveur', login='upsadmin', password='upspass' ) + ups = PyNUT.PyNUTClient( host='server', login='upsadmin', password='upspass' ) result = ups.GetRWVars( ups='ups1' ) print( result ) @@ -213,7 +213,7 @@ pairs. ----- import PyNUT - ups = PyNUT.PyNUTClient( host='serveur', login='upsadmin', password='upspass' ) + ups = PyNUT.PyNUTClient( host='server', login='upsadmin', password='upspass' ) result = ups.GetRWVars( ups='ups1' ) print( result ) @@ -241,7 +241,7 @@ Returns the list of UPSes represented by the NUT server, as a dictionary of ----- import PyNUT - ups = PyNUT.PyNUTClient( host='serveur', login='upsadmin', password='upspass' ) + ups = PyNUT.PyNUTClient( host='server', login='upsadmin', password='upspass' ) result = ups.GetUPSList() print( result ) @@ -265,7 +265,7 @@ methods. ----- import PyNUT - ups = PyNUT.PyNUTClient( host='serveur', login='upsadmin', password='upspass' ) + ups = PyNUT.PyNUTClient( host='Serveur', login='upsadmin', password='upspass' ) result = ups.GetUPSNames() print( result ) @@ -283,7 +283,7 @@ of "variable"-"current value" pairs. ----- import PyNUT - ups = PyNUT.PyNUTClient( host='serveur', login='upsadmin', password='upspass' ) + ups = PyNUT.PyNUTClient( host='Serveur', login='upsadmin', password='upspass' ) result = ups.GetUPSVars( ups='UPS1' ) print( result ) @@ -356,7 +356,7 @@ in case of failure. ----- import PyNUT - ups = PyNUT.PyNUTClient( host='serveur', login='upsadmin', password='upspass' ) + ups = PyNUT.PyNUTClient( host='Serveur', login='upsadmin', password='upspass' ) result = ups.RunUPSCommand( ups='UPS1', command='test.panel.start' ) print( result ) @@ -381,7 +381,7 @@ in case of failure. ----- import PyNUT - ups = PyNUT.PyNUTClient( host='serveur', login='upsadmin', password='upspass' ) + ups = PyNUT.PyNUTClient( host='Serveur', login='upsadmin', password='upspass' ) result = ups.SetRWVar( ups='UPS1', var='battery.date', value='06/17/08' ) print( result ) diff --git a/scripts/systemd/Makefile.am b/scripts/systemd/Makefile.am index dafdd5ae99..18b49492ce 100644 --- a/scripts/systemd/Makefile.am +++ b/scripts/systemd/Makefile.am @@ -1,4 +1,6 @@ -EXTRA_DIST = README +# Network UPS Tools: scripts/systemd + +EXTRA_DIST = README.adoc if HAVE_SYSTEMD @@ -31,6 +33,27 @@ EXTRA_DIST += \ # NOTE: Do not EXTRA_DIST nut-common-tmpfiles.conf.in - it is generated per build endif +SPELLCHECK_SRC = README.adoc + +# NOTE: Due to portability, we do not use a GNU percent-wildcard extension: +#%-spellchecked: % Makefile.am $(top_srcdir)/docs/Makefile.am $(abs_srcdir)/$(NUT_SPELL_DICT) +# $(MAKE) -s -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC_ONE="$<" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + +# NOTE: Portable suffix rules do not allow prerequisites, so we shim them here +# by a wildcard target in case the make implementation can put the two together. +*-spellchecked: Makefile.am $(top_srcdir)/docs/Makefile.am $(abs_srcdir)/$(NUT_SPELL_DICT) + +.sample.sample-spellchecked: + $(MAKE) -s -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC_ONE="$<" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + +.in.in-spellchecked: + $(MAKE) -s -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC_ONE="$<" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + +spellcheck spellcheck-interactive spellcheck-sortdict: + $(MAKE) -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC="$(SPELLCHECK_SRC)" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + +CLEANFILES = *-spellchecked + MAINTAINERCLEANFILES = Makefile.in .dirstamp # Generated by autogen.sh and needed to run the configure script: diff --git a/scripts/systemd/README b/scripts/systemd/README deleted file mode 100644 index 5b3ee5812e..0000000000 --- a/scripts/systemd/README +++ /dev/null @@ -1,12 +0,0 @@ -This directory contains the NUT support files for systemd, the System and -Service Manager. - -These files are automatically installed, upon detection (at configure time) -of a systemd enabled system. - -This also uses the nut-driver-enumerator.sh (service and implementation -method) and upsdrvsvcctl (tool) to manage NUT drivers as service instances -located in ../upsdrvsvcctl/ source subdirectory. - -Contributed by Michal Hlavinka -Updated 2016-2018 by Michal Hrusecky and Jim Klimov diff --git a/scripts/systemd/README.adoc b/scripts/systemd/README.adoc new file mode 100644 index 0000000000..6b24286c37 --- /dev/null +++ b/scripts/systemd/README.adoc @@ -0,0 +1,23 @@ +NUT resources for systemd integration +===================================== + +Overview +-------- + +This directory contains the NUT support files for `systemd`, the System and +Service Manager used in many Linux distributions. + +These files are automatically installed, upon detection (at `configure` time) +of a systemd enabled target system, or if corresponding configuration options +were requested. + +This also uses the `nut-driver-enumerator.sh` (service and implementation +method) and `upsdrvsvcctl` (tool) to manage NUT drivers as service instances +located in `../upsdrvsvcctl/` source subdirectory. + +Credits +------- + +* Contributed by Michal Hlavinka +* Updated 2016-2018 by Michal Hrusecky and Jim Klimov +* Maintained since 2020 by Jim Klimov diff --git a/scripts/udev/Makefile.am b/scripts/udev/Makefile.am index f84e4c1fe5..2c7df88abc 100644 --- a/scripts/udev/Makefile.am +++ b/scripts/udev/Makefile.am @@ -1,3 +1,4 @@ +# Network UPS Tools: scripts/udev if WITH_UDEV udevrulesdir = $(udevdir)/rules.d @@ -10,7 +11,7 @@ if WITH_IPMI endif endif -EXTRA_DIST = README +EXTRA_DIST = README.adoc 62-nut-usbups.rules: nut-usbups.rules cp nut-usbups.rules $@ @@ -34,3 +35,24 @@ MAINTAINERCLEANFILES += nut-usbups.rules.in nut-usbups.rules.in.AUTOGEN_WITHOUT # Part of dist tarball, regardless of use for current build: EXTRA_DIST += nut-usbups.rules.in + +SPELLCHECK_SRC = README.adoc + +# NOTE: Due to portability, we do not use a GNU percent-wildcard extension: +#%-spellchecked: % Makefile.am $(top_srcdir)/docs/Makefile.am $(abs_srcdir)/$(NUT_SPELL_DICT) +# $(MAKE) -s -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC_ONE="$<" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + +# NOTE: Portable suffix rules do not allow prerequisites, so we shim them here +# by a wildcard target in case the make implementation can put the two together. +*-spellchecked: Makefile.am $(top_srcdir)/docs/Makefile.am $(abs_srcdir)/$(NUT_SPELL_DICT) + +.sample.sample-spellchecked: + $(MAKE) -s -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC_ONE="$<" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + +.in.in-spellchecked: + $(MAKE) -s -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC_ONE="$<" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + +spellcheck spellcheck-interactive spellcheck-sortdict: + $(MAKE) -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC="$(SPELLCHECK_SRC)" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + +CLEANFILES += *-spellchecked diff --git a/scripts/udev/README b/scripts/udev/README deleted file mode 100644 index c94f834779..0000000000 --- a/scripts/udev/README +++ /dev/null @@ -1,46 +0,0 @@ -Desc: Udev script for NUT USB and IPMI drivers -File: scripts/udev/README -Date: 31 July 2014 -Auth: Arnaud Quette - -This document introduces the Linux udev script for NUT USB -drivers (usbhid-ups, bcmxcp_usb, tripplite_usb, ...) and IPMI driver -(nut-ipmipsu). - -These are needed on Linux systems running udev (recommended -as of kernel 2.6.3, and mandatory as of 2.6.14 and higher). - -This script ensure that the right privileges are set on the -USB and IPMI devices files to allow the NUT driver to operate (ie -allowing the nut user to read AND write to the device). - -Note that the old style hotplug files, available in the -scripts/hotplug directory, are not needed if your kernel supports -udev. - -Installation ------------- - -For most users, these files will be automatically installed in -/etc/udev (or /lib/udev) upon "make install", if that directory -exists and if the feature (USB and / or IPMI) has been enabled -at configure time. You can specify an alternate directory with: - - ./configure --with-udev-dir=DIR - -Manual installation -------------------- - -To install them manually, copy the rules file(s) to /etc/udev/rules.d -(or /lib/udev/rules.d on newer systems) using the command(s): - - :; cp -f nut-usbups.rules /etc/udev/rules.d/62-nut-usbups.rules - :; cp -f nut-ipmipsu.rules /etc/udev/rules.d/52-nut-ipmipsu.rules - -You will need to refresh the bus to avoid a reboot for these rules to be -active. You can do so using: - - :; udevadm trigger --subsystem-match=usb_device - -For USB devices, you can then plug your UPS USB cord, or unplug / replug -it to refresh the device permission, and start NUT. diff --git a/scripts/udev/README.adoc b/scripts/udev/README.adoc new file mode 100644 index 0000000000..62b503b003 --- /dev/null +++ b/scripts/udev/README.adoc @@ -0,0 +1,49 @@ +Udev script for NUT USB and IPMI drivers +======================================== +Arnaud Quette +v1.0, 31 July 2014 (start date) + +This document introduces the Linux `udev` script for NUT USB drivers +(`usbhid-ups`, `nutdrv_qx`, `bcmxcp_usb`, `tripplite_usb`, ...) and +IPMI driver (`nut-ipmipsu`). + +These are needed on Linux systems running `udev` (recommended as of Linux +kernel 2.6.3, and mandatory as of 2.6.14 and higher). + +This script ensures that the right privileges are set on the USB and IPMI +device nodes to allow the NUT driver to operate (i.e. allowing the `nut` +user to read AND write to the hardware device). + +Note that the old style `hotplug` files, available in the `scripts/hotplug` +directory, are not needed anymore if your kernel supports `udev`. + +Installation +------------ + +For most users, these files will be automatically installed in `/etc/udev` +(or `/lib/udev`) upon `make install`, if that directory exists and if the +feature (USB and/or IPMI driver support) has been enabled at `configure` time. + +You can specify an alternate directory with: +---- +:; ./configure --with-udev-dir=DIR +---- + +Manual installation +------------------- + +To install them manually, copy the rules file(s) to `/etc/udev/rules.d` +(or `/lib/udev/rules.d` on newer systems) using the following command(s): +---- +:; cp -f nut-usbups.rules /etc/udev/rules.d/62-nut-usbups.rules +:; cp -f nut-ipmipsu.rules /etc/udev/rules.d/52-nut-ipmipsu.rules +---- + +You will need to refresh the bus to avoid a reboot for these rules to be +active. You can do so using: +---- +:; udevadm trigger --subsystem-match=usb_device +---- + +For USB devices, you can then plug your UPS USB cord, or unplug/re-plug +it to refresh the device permission, and start NUT. diff --git a/scripts/ufw/Makefile.am b/scripts/ufw/Makefile.am index eb6476c94c..24cc6e15bb 100644 --- a/scripts/ufw/Makefile.am +++ b/scripts/ufw/Makefile.am @@ -1,4 +1,10 @@ +# Network UPS Tools: scripts/ufw + EXTRA_DIST = README.adoc nut.ufw.profile.in +# Note: spellchecking is currently ensured by docs/Makefile.am +# due to inclusion into docs/security.txt, and the heading level +# is also dictated by that. + MAINTAINERCLEANFILES = Makefile.in .dirstamp CLEANFILES = *-spellchecked README diff --git a/scripts/upsdrvsvcctl/Makefile.am b/scripts/upsdrvsvcctl/Makefile.am index 77313cae94..43bb633b1b 100644 --- a/scripts/upsdrvsvcctl/Makefile.am +++ b/scripts/upsdrvsvcctl/Makefile.am @@ -1,4 +1,6 @@ -EXTRA_DIST = README +# Network UPS Tools: scripts/upsdrvsvcctl + +EXTRA_DIST = README.adoc if HAVE_SYSTEMD EXTRA_DIST += nut-driver-enumerator.sh upsdrvsvcctl @@ -10,4 +12,25 @@ endif EXTRA_DIST += nut-driver-enumerator.sh.in upsdrvsvcctl.in +SPELLCHECK_SRC = README.adoc + +# NOTE: Due to portability, we do not use a GNU percent-wildcard extension: +#%-spellchecked: % Makefile.am $(top_srcdir)/docs/Makefile.am $(abs_srcdir)/$(NUT_SPELL_DICT) +# $(MAKE) -s -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC_ONE="$<" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + +# NOTE: Portable suffix rules do not allow prerequisites, so we shim them here +# by a wildcard target in case the make implementation can put the two together. +*-spellchecked: Makefile.am $(top_srcdir)/docs/Makefile.am $(abs_srcdir)/$(NUT_SPELL_DICT) + +.sample.sample-spellchecked: + $(MAKE) -s -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC_ONE="$<" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + +.in.in-spellchecked: + $(MAKE) -s -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC_ONE="$<" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + +spellcheck spellcheck-interactive spellcheck-sortdict: + $(MAKE) -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC="$(SPELLCHECK_SRC)" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + +CLEANFILES = *-spellchecked + MAINTAINERCLEANFILES = Makefile.in .dirstamp diff --git a/scripts/upsdrvsvcctl/README b/scripts/upsdrvsvcctl/README deleted file mode 100644 index b2a9db64a8..0000000000 --- a/scripts/upsdrvsvcctl/README +++ /dev/null @@ -1,11 +0,0 @@ -This directory contains the shared NUT support files for Linux systemd (the -System and Service Manager) and Solaris SMF (Service Management Framework). -It includes the nut-driver-enumerator.sh (service and implementation method) -and upsdrvsvcctl (tool) to manage NUT drivers as service instances. - -These files are automatically installed into SBINDIR/upsdrvsvcctl and -LIBEXECDIR/nut-driver-enumerator.sh, upon detection (at configure time) -of a systemd or SMF enabled system, with Makefiles of the ../systemd/ and -../Solaris/ source directories respectively. - -Contributed 2016-2018 by Jim Klimov diff --git a/scripts/upsdrvsvcctl/README.adoc b/scripts/upsdrvsvcctl/README.adoc new file mode 100644 index 0000000000..cd596428ad --- /dev/null +++ b/scripts/upsdrvsvcctl/README.adoc @@ -0,0 +1,16 @@ +Shared resources for NUT service unit integrations +================================================== + +This directory contains the shared NUT support files for Linux systemd (the +System and Service Manager) and Solaris SMF (Service Management Framework). +It includes the `nut-driver-enumerator.sh` (service and implementation method) +and `upsdrvsvcctl` (tool) to manage NUT drivers as service instances. + +These files are automatically installed into `SBINDIR/upsdrvsvcctl` and +`LIBEXECDIR/nut-driver-enumerator.sh`, upon detection (at `configure` time) +of a systemd or SMF enabled system, with Makefiles of the `../systemd/` and +`../Solaris/` source directories respectively. + +Contributed 2016-2018 by Jim Klimov + +Maintained since 2020 by Jim Klimov diff --git a/scripts/usb_resetter/README.md b/scripts/usb_resetter/README.adoc similarity index 80% rename from scripts/usb_resetter/README.md rename to scripts/usb_resetter/README.adoc index f1c226e255..56a65127fe 100644 --- a/scripts/usb_resetter/README.md +++ b/scripts/usb_resetter/README.adoc @@ -1,12 +1,12 @@ -Desc: Method for resetting unreliable USB UPS interfaces -File: scripts/usb_resetter/README -Date: 30 Mar 2023 -Auth: Orsiris de Jong - NetInvent SASU +Method for resetting unreliable USB UPS interfaces (on Linux) +============================================================= +Orsiris de Jong - NetInvent SASU +v1.0, 30 Mar 2023 (start date) Some cheaper USB UPS have the same kind of unreliable USB to serial interface, -being a "Cypress Semiconductor USB to Serial" or "INNO TECH USB to Serial" -(often with the `0665:5161` VendorID/ProductId seen in examples below). -Most of them use `blazer_usb` or `nutdrv_qx` driver, and sometimes the +often being a "Cypress Semiconductor USB to Serial" or "INNO TECH USB to Serial" +(often with the `0665:5161` VendorID/ProductID seen in examples below). +Most of them use `blazer_usb` or `nutdrv_qx` NUT driver, and sometimes the driver can't start because it can't communicate with the UPS. NOTE: It is believed that in some cases the chip on UPS side can go into @@ -23,23 +23,24 @@ to Linux platforms as of this writing. Grab a copy via `pip` with `pip install usb_resetter`, or make a plain install directly from GitHub with e.g.: -```` +---- :; curl -o /usr/local/bin/usb_resetter -L \ https://raw.githubusercontent.com/netinvent/usb_resetter/main/usb_resetter/usb_resetter.py \ - && chmod +x /usr/local/bin/usb_resetter -```` + && chmod +x /usr/local/bin/usb_resetter +---- Once you have got the script, identify the USB UPS with: -``` +---- :; usb_resetter --list -``` +---- In our case, we could see something like: -```` +---- Found device 0665:5161 at /dev/bus/usb/001/002 Manufacturer=INNO TECH, Product=USB to Serial -```` +---- The `usb_resetter` can work in three different ways: + - Reset device itself - Reset the hub the device is attached to - Reset all USB controllers @@ -48,30 +49,30 @@ A simple USB device reset typically isn't sufficient for those UPS devices, so we would need to reset the hub it's attached to. The command for doing that is: -``` +---- :; usb_resetter --reset-hub --device 0665:5161 -``` +---- Bear in mind that this will reset other devices connected to the same hub. -While this isn't a problem for a keyboard / mouse, it might be for a USB -storage device. On some hardware, each USB plug gets it's own hub. -On others, two or more USB plus share one hub. +While this isn't a problem for a keyboard/mouse, it might be for a USB +storage device. On some hardware, each USB plug gets its own hub. +On others, two or more USB plugs share one hub. A good practice would be to isolate the USB UPS on a hub without any other device in order to not interfere with other hardware, or to associate it on a hub where a non-critical device is already plugged. Getting the hub your device is attached to can be done with: -```` +---- :; usb_resetter --list-hubs --device 0665:5161 -```` +---- The easiest way to integrate this activity with the `nut-driver` service is to modify the systemd service file (or ideally use a separate "drop-in" snippet file) with the following line: -```` +---- ExecStartPre=/usr/local/bin/usb_reset.py --reset-hub --device 0665:5161 -```` +---- An example modified `nut-driver.service` file which may be applicable to a NUT v2.7.4 or older release (modulo the paths and the particular VID:PID) @@ -83,7 +84,7 @@ to run each driver in a dedicated instance, declared manually or often by the `nut-driver-enumerator` script or service (tracking `ups.conf` sections). The added call to `usb_resetter` can then be a systemd drop-in file tailored for that particular device and named like -`/etc/systemd/system/nut-driver@myups.service.d/dropin.conf`, +`/etc/systemd/system/nut-driver@myups.service.d/usbreset.conf`, so it does not impact others (unless they use the same USB hub). This way, every time the nut-driver service is restarted, the USB UPS link diff --git a/tests/NIT/Makefile.am b/tests/NIT/Makefile.am index cf69699664..7fb3dff492 100644 --- a/tests/NIT/Makefile.am +++ b/tests/NIT/Makefile.am @@ -1,4 +1,4 @@ -EXTRA_DIST = nit.sh README +EXTRA_DIST = nit.sh README.adoc if WITH_CHECK_NIT check: check-NIT @@ -20,6 +20,27 @@ check-NIT-devel: $(abs_srcdir)/nit.sh @cd "$(top_builddir)/drivers" && $(MAKE) -s dummy-ups$(EXEEXT) @$(MAKE) check-NIT +SPELLCHECK_SRC = README.adoc + +# NOTE: Due to portability, we do not use a GNU percent-wildcard extension: +#%-spellchecked: % Makefile.am $(top_srcdir)/docs/Makefile.am $(abs_srcdir)/$(NUT_SPELL_DICT) +# $(MAKE) -s -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC_ONE="$<" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + +# NOTE: Portable suffix rules do not allow prerequisites, so we shim them here +# by a wildcard target in case the make implementation can put the two together. +*-spellchecked: Makefile.am $(top_srcdir)/docs/Makefile.am $(abs_srcdir)/$(NUT_SPELL_DICT) + +.sample.sample-spellchecked: + $(MAKE) -s -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC_ONE="$<" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + +.in.in-spellchecked: + $(MAKE) -s -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC_ONE="$<" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + +spellcheck spellcheck-interactive spellcheck-sortdict: + $(MAKE) -f $(top_builddir)/docs/Makefile SPELLCHECK_SRC="$(SPELLCHECK_SRC)" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@ + +CLEANFILES = *-spellchecked + MAINTAINERCLEANFILES = Makefile.in .dirstamp clean-local: diff --git a/tests/NIT/README b/tests/NIT/README.adoc similarity index 83% rename from tests/NIT/README rename to tests/NIT/README.adoc index 729e8a560d..b442f27434 100644 --- a/tests/NIT/README +++ b/tests/NIT/README.adoc @@ -1,5 +1,5 @@ -NUT Integration Testing suite -============================= +NUT Integration Testing suite (aka NIT) +======================================= This suite aims to simplify running `upsd`, a `dummy-ups` driver and a few clients to query them, as part of regular `make check` routine @@ -7,7 +7,7 @@ or separately with existing binaries (should not impact any existing installation data, processes or communications). WARNING: Current working directory when starting the script should be -the location where it may create temporary data (e.g. the BUILDDIR). +the location where it may create temporary data (e.g. the `BUILDDIR`). See also link:https://git.launchpad.net/ubuntu/+source/nut/tree/debian/tests/test-nut.py[The NUT testing script]