From e0bc4af3ee3a1a0a4ef1dae755d9c4410312d047 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Wed, 5 Feb 2025 10:26:12 +0100 Subject: [PATCH 01/67] AUTHORS, MAINTAINERS, docs/nut.dict: add Jim Klimov Just half a decade as maintainer; better late than never :) Signed-off-by: Jim Klimov --- AUTHORS | 12 +++++++++++- MAINTAINERS | 9 +++++++++ docs/nut.dict | 3 ++- 3 files changed, 22 insertions(+), 2 deletions(-) diff --git a/AUTHORS b/AUTHORS index 3eaff4f4ef..3cbfd83846 100644 --- a/AUTHORS +++ b/AUTHORS @@ -86,12 +86,22 @@ N: Mark Powell E: medp@primagraphics.co.uk D: Ported to SunOS4 +N: Evgeny "Jim" Klimov +E: jimklimov+nut@gmail.com +D: Primary coordinator ; author of numerous CI recipes, tests and OS +D: integration scripts - including NDE (NUT Driver Enumerator), NIT +D: (NUT Integration Test suite) and Jenkins-Dynamatrix, to name a few. +D: Also automake/autoconf/m4 scripting, asciidoc documentation. +D: More of a bug-fixer, warnings-squasher and portability maintainer, +D: rather than e.g. specifically a driver developer. +P: 4096R/7043DCF7 B834 59F7 76B9 0224 988F 36C0 DE01 84DA 7043 DCF7 + N: Arnaud Quette E: aquette.dev@gmail.com E: arnaud.quette@mgeups.com E: aquette@debian.org W: http://arnaud.quette.free.fr/ -D: Primary coordinator ; author of snmp-ups, mge-shut, usbhid-ups ; +D: Previous primary coordinator ; author of snmp-ups, mge-shut, usbhid-ups ; D: co author of mge-utalk, hidups, SNMP UPS Agent ; contributor to blazer, D: bestferrups, nut core, and many others ; coordination with MGE UPS D: SYSTEMS, linux-usb developers (for hidups), Net SNMP and packagers diff --git a/MAINTAINERS b/MAINTAINERS index 87b03d11c5..7ac162858d 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -64,6 +64,15 @@ P: Greg Troxel M: gdt@lexort.com S: Maintained: pkgsrc (sysutils/ups-nut) +CI, tests and recipes +===================== + +P: Evgeny "Jim" Klimov +M: jimklimov+nut@gmail.com +S: Maintained or Supported: numerous CI recipes, tests and OS integration +S: scripts: NDE (NUT Driver Enumerator), NIT (NUT Integration Test suite), +S: Jenkins-Dynamatrix, automake/autoconf/m4 scripting, asciidoc documentation. + Everything else =============== diff --git a/docs/nut.dict b/docs/nut.dict index 87a49d98ed..1dc9775088 100644 --- a/docs/nut.dict +++ b/docs/nut.dict @@ -1,4 +1,4 @@ -personal_ws-1.1 en 3281 utf-8 +personal_ws-1.1 en 3282 utf-8 AAC AAS ABI @@ -2878,6 +2878,7 @@ spectype spellcheck splitaddr splitname +squasher sr src srcdir From d4238e98e053c9daaf2539478151a9abaf22d848 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Wed, 5 Feb 2025 10:29:44 +0100 Subject: [PATCH 02/67] docs/man/sockdebug.txt, docs/nut.dict: clarify the two separate sources of the program (POSIX/WIN32) Signed-off-by: Jim Klimov --- docs/man/sockdebug.txt | 12 ++++++++---- docs/nut.dict | 3 ++- 2 files changed, 10 insertions(+), 5 deletions(-) diff --git a/docs/man/sockdebug.txt b/docs/man/sockdebug.txt index f79bde71be..6bcd6e4017 100644 --- a/docs/man/sockdebug.txt +++ b/docs/man/sockdebug.txt @@ -4,7 +4,7 @@ SOCKDEBUG(8) NAME ---- -sockdebug - simple developer/troubleshooting aid utility to communicate +sockdebug - Simple developer/troubleshooting aid utility to communicate with a NUT driver using the socket protocol SYNOPSIS @@ -68,9 +68,13 @@ AUTHORS This manual page was written by Jim Klimov . -The program was originally written by -Russell Kroll (POSIX version), and by -Frederic Bohe (Windows version). +The program is currently maintained as two separate sources, with one +of them used for a build depending on the target platform: + +* `server/sockdebug.c` (POSIX version) was originally written by + Russell Kroll , and +* `server/pipedebug.c` (Windows version) was originally written by + Frederic Bohe . SEE ALSO -------- diff --git a/docs/nut.dict b/docs/nut.dict index 1dc9775088..798d255269 100644 --- a/docs/nut.dict +++ b/docs/nut.dict @@ -1,4 +1,4 @@ -personal_ws-1.1 en 3282 utf-8 +personal_ws-1.1 en 3283 utf-8 AAC AAS ABI @@ -2596,6 +2596,7 @@ pigz pijuice pinout pinouts +pipedebug pipename pixmaps pkg From 4efebb4e051d4e1b1580f6b8600c303b475462d1 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Wed, 5 Feb 2025 11:27:40 +0100 Subject: [PATCH 03/67] docs/man/clone.txt, docs/man/clone-outlet.txt, docs/man/dummy-ups.txt: update wording and cross-links of the virtual device drivers Signed-off-by: Jim Klimov --- docs/man/clone-outlet.txt | 31 ++++++++++-------- docs/man/clone.txt | 35 +++++++++++--------- docs/man/dummy-ups.txt | 69 ++++++++++++++++++++++++--------------- 3 files changed, 79 insertions(+), 56 deletions(-) diff --git a/docs/man/clone-outlet.txt b/docs/man/clone-outlet.txt index b26d778f34..890a75df2b 100644 --- a/docs/man/clone-outlet.txt +++ b/docs/man/clone-outlet.txt @@ -4,7 +4,8 @@ CLONE-OUTLET(8) NAME ---- -clone-outlet - clone an UPS, treating its outlet as if it were an UPS (monitoring only) +clone-outlet - Clone an UPS, treating its outlet as if it were an UPS + (monitoring only) SYNOPSIS -------- @@ -20,16 +21,18 @@ linkman:nutupsdrv[8]. DESCRIPTION ----------- -This driver, which sits on top of another driver socket, allows users to group -clients to a particular outlet of a device and deal with this output as if it -were a normal UPS. Unlike the linkman:clone[8] driver or linkman:dummy-ups[8] +This driver, which sits on top of another driver's local UNIX socket file +(or Windows named pipe), allows users to group clients to a particular +outlet of a device and deal with this output as if it were a normal UPS. + +Unlike the linkman:clone[8] driver or linkman:dummy-ups[8] driver running in repeater mode, this driver represents a read-only device for monitoring and shutdowns (it does not accept setting any values or sending instant commands during run time). -Unlike linkman:dummy-ups[8], this driver does not require a running `upsd` -data server nor use the networked NUT protocol to talk to the "real" driver -(which may be remote in case of `dummy-ups` repeater mode). +Unlike linkman:dummy-ups[8] generally, this driver does not require a running +`upsd` data server nor use the networked NUT protocol to talk to the "real" +driver (which may be remote in case of `dummy-ups` repeater mode). This driver does not create a completely new virtual device, but replaces or extends some of the original readings reported by the "real" driver using @@ -134,15 +137,15 @@ IMPORTANT --------- Unlike a real UPS, you should *not* configure a upsmon primary mode for this -driver. When a upsmon primary sees the OB LB flags and tells the upsd server -it is OK to initiate the shutdown sequence, the server will latch the FSD -status and it will not be possible to restart the systems connected without -restarting the upsd server. +driver. When a linkman:upsmon[8] primary sees the OB LB flags and tells the +linkman:upsd[8] server it is OK to initiate the shutdown sequence, the server +will latch the FSD status, and it will not be possible to restart the systems +connected without restarting the `upsd` server. This will be a problem if the power returns after the clone UPS initiated -the shutdown sequence on it's outlet, but returns before the real UPS begins -shutting down. The solution is in the clone driver, that will insert the -FSD flag if needed without the help of a upsmon primary. +the shutdown sequence on its outlet, but returns before the real UPS begins +shutting down. The solution is in the `clone` driver, that will insert the +FSD flag if needed without the help of an `upsmon` primary. CAVEATS ------- diff --git a/docs/man/clone.txt b/docs/man/clone.txt index bd27128057..8a9d975995 100644 --- a/docs/man/clone.txt +++ b/docs/man/clone.txt @@ -4,7 +4,8 @@ CLONE(8) NAME ---- -clone - clone an UPS, treating its outlet as if it were an UPS (with shutdown INSTCMD support) +clone - Clone an UPS, treating its outlet as if it were an UPS + (with shutdown INSTCMD support) SYNOPSIS -------- @@ -20,12 +21,14 @@ linkman:nutupsdrv[8]. DESCRIPTION ----------- -This driver, which sits on top of another driver socket, allows users to group -clients to a particular outlet of a device and deal with this output as if it -were a normal UPS. Unlike the linkman:clone-outlet[8] driver, this driver -represents a manageable device for that can be used both for monitoring and -for client computer and UPS/ePDU outlet shutdowns (it supports sending -relevant instant commands during run time). +This driver, which sits on top of another driver's local UNIX socket file +(or Windows named pipe), allows users to group clients to a particular +outlet of a device and deal with this output as if it were a normal UPS. + +Unlike the linkman:clone-outlet[8] driver, this driver represents a +manageable device that can be used both for monitoring and for client +computer and UPS/ePDU outlet shutdowns (it supports sending relevant +instant commands during run time). Unlike linkman:dummy-ups[8], this driver does not require a running `upsd` data server nor use the networked NUT protocol to talk to the "real" driver @@ -74,8 +77,8 @@ This driver supports the following settings: *port*='drivername-devicename':: Required. The standard NUT driver `port` setting, here it provides the name -of the local Unix socket (or named Windows pipe) for connection to the "real" -driver. +of the local Unix socket file (or Windows named pipe) for connection to the +"real" device driver. *load.off*='command':: Recommended. Set the command on the "real" UPS driver that will be used to @@ -172,15 +175,15 @@ IMPORTANT --------- Unlike a real UPS, you should *not* configure a upsmon primary mode for this -driver. When a upsmon primary sees the OB LB flags and tells the upsd server -it is OK to initiate the shutdown sequence, the server will latch the FSD -status and it will not be possible to restart the systems connected without -restarting the upsd server. +driver. When a linkman:upsmon[8] primary sees the `OB LB` flags and tells the +linkman:upsd[8] data server that it is OK to initiate the shutdown sequence, +the server will latch the FSD status, and it will not be possible to restart +the systems connected without restarting the `upsd` server. This will be a problem if the power returns after the clone UPS initiated -the shutdown sequence on it's outlet, but returns before the real UPS begins -shutting down. The solution is in the clone driver, that will insert the -FSD flag if needed without the help of a upsmon primary. +the shutdown sequence on its outlet, but returns before the real UPS begins +shutting down. The solution is in the `clone` driver itself, that will insert +the FSD flag if needed without the help of an upsmon primary. CAVEATS ------- diff --git a/docs/man/dummy-ups.txt b/docs/man/dummy-ups.txt index d51f42e56e..5d4532a45d 100644 --- a/docs/man/dummy-ups.txt +++ b/docs/man/dummy-ups.txt @@ -4,7 +4,7 @@ DUMMY-UPS(8) NAME ---- -dummy-ups - Driver for multi-purpose UPS emulation +dummy-ups - Driver for multi-purpose UPS emulation or relay SYNOPSIS -------- @@ -32,11 +32,13 @@ Dummy Mode In this mode, *dummy-ups* looks like a standard NUT device driver to linkman:upsd[8] and allows one to change any value for testing purposes. + It is both interactive, controllable through the linkman:upsrw[1] and linkman:upscmd[1] commands (or equivalent graphical tool), and batchable -through script files. It can be configured, launched and used as any other -"real" NUT driver. This mode is mostly useful for development and testing -purposes. +through script files. + +It can be configured, launched and used as any other "real" NUT driver. +This mode is mostly useful for development and testing purposes. NOTE: See below about the differences of `dummy-once` vs. `dummy-loop` modes -- the former may be more suitable for "interactive" uses and tests. @@ -45,12 +47,15 @@ Repeater Mode ~~~~~~~~~~~~~ In this mode, *dummy-ups* acts as a NUT client, simply forwarding data. + This can be useful for supervision purposes. This mode can also allow some load sharing between several `upsd` instances communicating with ultimate NUT clients, with a "central" one using a point-to-point communication with -the UPS. This arrangement can also help with networked UPSes, whose network -management cards can be overwhelmed with a farm of servers directly polling -SNMP or other protocols every few seconds. +the actual UPS or ePDU device. + +This arrangement can also help with networked UPSes, whose network management +cards can be overwhelmed with a whole farm of servers directly polling SNMP or +other networked protocols every few seconds. //////////////////////////////////////// Future intention: Meta mode to aggregate several drivers as one device @@ -70,10 +75,15 @@ override the mode of operation which would be otherwise guessed by the driver. Dummy Mode ~~~~~~~~~~ -In this context, `port` in the `ups.conf` block defines a file name for the -*dummy-ups* to read data from. This can either be an absolute or a relative -path name. In the latter case the NUT sysconfig directory (i.e. `/etc/nut`, -`/usr/local/ups/etc`, ...) is prepended. +In this context, `port` in the `ups.conf` block specifies a "definition file" +name for the *dummy-ups* to read data from. This can either be an absolute or +a relative path name. In the latter case the NUT sysconfig directory (i.e. +`/etc/nut`, `/usr/local/ups/etc`, ...) is prepended. + +NOTE: The "sysconfig" location is built-in according to `configure` script +arguments, but can be tuned at run time by `NUT_CONFPATH` environment variable. +See the `tests/NIT/nit.sh` script in NUT sources, which heavily relies on this +driver, for more examples. Since NUT v2.8.0 two aspects of this mode are differentiated: @@ -115,6 +125,7 @@ not be impacted. For instance: +---- [dummy1] driver = dummy-ups port = evolution500.seq @@ -124,12 +135,14 @@ For instance: driver = dummy-ups port = epdu-managed.dev desc = "dummy-ups in dummy-once mode" +---- -This file is generally named `something.dev` or `something.seq`. It contains -a list of all valid variables and associated values (you can later use `upsrw` +This definition file, specified by the `port` argument in the example above, +is generally named `something.dev` or `something.seq`. It contains a list of +all valid variables and associated values (you can later use `upsrw` only to modify values of these variables), and has the same format as an -linkman:upsc[8] dump (`: `). So you can easily create -definition files from an existing UPS using `upsc > file.dev`. +linkman:upsc[8] data dump (`: `). This means you can easily +create definition files from an existing UPS using `upsc > file.dev`. Note that the Network UPS project provides an extensive link:https://www.networkupstools.org/ddl/index.html[DDL (Devices Dumps Library)] @@ -144,8 +157,8 @@ available: `device.*`, `driver.*`, `ups.mfr`, `ups.model`, `ups.status` as filled by the driver itself. Some sample definition files are available in the `data` directory of the -NUT source tree, and generally in the sysconfig or share directory of your -system distribution. +NUT source tree, and generally in the "sysconfig" or "share" directory of +your system distribution. Since *dummy-ups* will usually loop on reading this file, you can dynamically modify it with some external process to "interact" with the driver. @@ -173,7 +186,8 @@ and, in particular, forget any values you could have just set with `upsrw`. Note that to avoid CPU overload with an infinite loop, the driver "sleeps" a bit between file-reading cycles (currently this delay is hardcoded to one -second), independently of (and/or in addition to) any `TIMER` keywords. +second), independently of (and/or in addition to) any `TIMER` keywords and +possibly the common `pollinterval` setting. Repeater Mode ~~~~~~~~~~~~~ @@ -191,7 +205,7 @@ For instance: desc = "dummy-ups in repeater mode" Unlike UPS specifications in the rest of NUT, the `@hostname` portion is not -optional - it is the `@` character which enables Repeater Mode. To refer to an +optional -- it is the `@` character which enables Repeater Mode. To refer to an UPS on the same host as *dummy-ups*, use `port = upsname@localhost`. Note that to avoid CPU overload with an infinite loop, the driver "sleeps" a @@ -199,10 +213,11 @@ bit between data-requesting cycles (currently this delay is hardcoded to one second), so propagation of data updates available to a remote `upsd` may lag by this much. -Beware that any error encountered at repeater mode startup (e.g. when not all -target UPS to be repeated or `upsd` instances are connectable yet) will cause -*dummy-ups* driver to terminate prematurely. This behaviour can be changed by -setting the `repeater_disable_strict_start` flag, making such errors non-fatal. +Beware that any error encountered at repeater mode startup (e.g. when not +all target UPS to be repeated or their `upsd` instances are connectable +yet) will by default cause the *dummy-ups* driver to terminate prematurely. +This behaviour can be changed by setting the `repeater_disable_strict_start` +flag, making such errors non-fatal. INTERACTION ----------- @@ -233,7 +248,9 @@ for interaction. *dummy-ups* is useful for NUT client development, and other testing purposes. It also helps the NUT Quality Assurance effort, by automating some tests on -the NUT framework. +the NUT framework and the NIT (NUT Integration Test suite). See the +`tests/NIT/nit.sh` script in NUT sources, which heavily relies on this +driver, for more examples. It now offers a repeater mode. This will help in building the Meta UPS approach, which allows one to build a virtual device, composed of several other devices @@ -278,8 +295,8 @@ linkman:upsrw[1], linkman:ups.conf[5], linkman:nutupsdrv[8] -Clone driver: -~~~~~~~~~~~~~ +Clone drivers: +~~~~~~~~~~~~~~ The "repeater" mode of 'dummy-ups' driver is in some ways similar to the 'clone' and 'clone-outlet' drivers, which sit on top of another driver From 7c60382e5dd73608920f1596982b233a595d0aaf Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Wed, 5 Feb 2025 12:02:39 +0100 Subject: [PATCH 04/67] docs/man/libupsclient-config.txt: note the pkg-config alternative to the older-style script Signed-off-by: Jim Klimov --- docs/man/libupsclient-config.txt | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/man/libupsclient-config.txt b/docs/man/libupsclient-config.txt index 1e496c7645..28b45fd139 100644 --- a/docs/man/libupsclient-config.txt +++ b/docs/man/libupsclient-config.txt @@ -4,7 +4,7 @@ LIBUPSCLIENT-CONFIG(1) NAME ---- -libupsclient-config - script to get information about the installed +libupsclient-config - Script to get information about the installed version of libupsclient SYNOPSIS @@ -19,6 +19,10 @@ DESCRIPTION linker flags that should be used to compile and link programs that use *libupsclient* from the Network UPS Tools project. +It allows to simplify build automation for systems without a `pkg-config` +implementation which would instead use the `libupsclient.pc` file installed +with the NUT development files. + OPTIONS ------- From c0ff5a08bccfd31c418b8ea2e3073ffa461c8c14 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Wed, 5 Feb 2025 12:15:11 +0100 Subject: [PATCH 05/67] docs/man/microsol-apc.txt: use standard markup for "Extra Arguments" and "Supported Commands"; refer to "See also" the solis driver Signed-off-by: Jim Klimov --- docs/man/microsol-apc.txt | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/docs/man/microsol-apc.txt b/docs/man/microsol-apc.txt index 096602f0c6..1de0b0e159 100644 --- a/docs/man/microsol-apc.txt +++ b/docs/man/microsol-apc.txt @@ -36,16 +36,20 @@ EXTRA ARGUMENTS This driver support the following extra optional settings in the linkman:ups.conf[5]. -*battext = n* - (default = 0, no extra battery, where n = Ampere*hour ) +*battext=*'n':: +Default = 0, no extra battery, where `n` = Ampere*hour. -*prgshut = 1* - (default = 0, no programmable shutdown ) +*prgshut=*'n':: +Default = 0, no programmable shutdown; `1` to enable one. COMMANDS -------- - * shutdown.return - Shut down in .3 minutes and restart in .3 minutes +*shutdown.return*:: +Shut down in .3 minutes and restart in .3 minutes after that. - * shutdown.stayoff - Shut down in .3 minutes and do not return +*shutdown.stayoff*:: +Shut down in .3 minutes and do not return. ISSUES ------ @@ -71,6 +75,11 @@ The core driver: linkman:nutupsdrv[8] +Driver for older devices under same brand: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +linkman:solis[8] + Internet resources: ~~~~~~~~~~~~~~~~~~~ From 9a62ff9f36e0bdc14f04fc4102a8f9e56886aff8 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Wed, 5 Feb 2025 12:20:18 +0100 Subject: [PATCH 06/67] docs/man/rhino.txt: use standard markup for "Extra Arguments" and "Supported Commands" Signed-off-by: Jim Klimov --- docs/man/rhino.txt | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/docs/man/rhino.txt b/docs/man/rhino.txt index ed97f717ec..34ba351a30 100644 --- a/docs/man/rhino.txt +++ b/docs/man/rhino.txt @@ -35,20 +35,26 @@ EXTRA ARGUMENTS This driver support the following extra optional settings in linkman:ups.conf[5]: -*battext = n* - (default = 0, no extra battery, where n = Ampere*hour ) +*battext=*'n':: +Default = 0, no extra battery, where `n` = Ampere*hour. COMMANDS -------- - * load.on - Turn on the load immediately +*load.on*:: +Turn on the load immediately. - * load.off - Turn off the load immediately +*load.off*:: +Turn off the load immediately. - * bypass.start - Put the UPS in bypass mode +*bypass.start*:: +Put the UPS in bypass mode. - * bypass.stop - Put the UPS out of bypass mode +*bypass.stop*:: +Put the UPS out of bypass mode. - * shutdown.stayoff - Shut down in 3 minutes and do not return +*shutdown.stayoff*:: +Shut down in 3 minutes and do not return. AUTHOR ------ From 7d09ce5f3156a45e9fb50401288be600ca3a77e3 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Wed, 5 Feb 2025 12:28:37 +0100 Subject: [PATCH 07/67] docs/man/solis.txt: use standard markup for "Extra Arguments" and "Supported Commands"; refer to "See also" the microsol-apc driver Signed-off-by: Jim Klimov --- docs/man/solis.txt | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/docs/man/solis.txt b/docs/man/solis.txt index 7c1bf016e8..bbbbb23ad0 100644 --- a/docs/man/solis.txt +++ b/docs/man/solis.txt @@ -32,7 +32,8 @@ This driver has been tested with: All Solis models are sinusoidal on-line. In 2009, Schneider Electric acquired Microsol Technologies, and by 2012, the -entire Microsol line of equipment was being sold under the APC brand. +entire Microsol line of equipment was being sold under the APC brand. Newer +devices may be better supported by linkman:microsol-apc[8] driver instead. EXTRA ARGUMENTS --------------- @@ -40,16 +41,20 @@ EXTRA ARGUMENTS This driver support the following extra optional settings in the linkman:ups.conf[5]. -*battext = n* - (default = 0, no extra battery, where n = Ampere*hour ) +*battext=*'n':: +Default = 0, no extra battery, where `n` = Ampere*hour. -*prgshut = 1* - (default = 0, no programmable shutdown ) +*prgshut=*'n':: +Default = 0, no programmable shutdown; `1` to enable one. COMMANDS -------- - * shutdown.return - Shut down in .3 minutes and restart in .3 minutes +*shutdown.return*:: +Shut down in .3 minutes and restart in .3 minutes after that. - * shutdown.stayoff - Shut down in .3 minutes and do not return +*shutdown.stayoff*:: +Shut down in .3 minutes and do not return. ISSUES ------ @@ -71,6 +76,11 @@ The core driver: linkman:nutupsdrv[8] +Driver for newer devices under same brand: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +linkman:microsol-apc[8] + Internet resources: ~~~~~~~~~~~~~~~~~~~ From aa39d3738870571d2e620cdd4e8906dad9a71b1d Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Wed, 5 Feb 2025 12:32:03 +0100 Subject: [PATCH 08/67] docs/man/upsc.txt: refer to "See also" the upslog client and ups.conf man pages; revise markup Signed-off-by: Jim Klimov --- docs/man/upsc.txt | 27 +++++++++++++++------------ 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/docs/man/upsc.txt b/docs/man/upsc.txt index 1d4c8e4bda..91e16965e0 100644 --- a/docs/man/upsc.txt +++ b/docs/man/upsc.txt @@ -4,7 +4,7 @@ UPSC(8) NAME ---- -upsc - example lightweight UPS client +upsc - Lightweight read-only NUT client SYNOPSIS -------- @@ -33,9 +33,9 @@ OPTIONS *-L* 'host':: As above, list all UPS names configured at 'host', including their description - provided by the remote upsd(8) from ups.conf(5). The hostname defaults to - "localhost". You may optionally add a colon and a port number to override the - default port. + provided by the remote linkman:upsd[8] from its linkman:ups.conf[5]. + The hostname defaults to "localhost". You may optionally add a colon and + a port number to override the default port. *-c* 'ups':: @@ -48,9 +48,10 @@ OPTIONS 'variable':: - Display the value of this variable only. By default, upsc retrieves the list - of variables from the server and then displays the value for each. This may - be useful in shell scripts to save an additional pipe into grep. + Display the value of this variable only. By default, `upsc` retrieves the + list of variables from the server and then displays the value for each. + This option may be useful in shell scripts to save an additional pipe into + `grep`. EXAMPLES -------- @@ -90,17 +91,17 @@ SCRIPTED MODE ------------- If you run this program inside a shell script or similar to get the list of -devices and variables, you should only consider using output from stdout, -not stderr. +devices and variables, you should only consider using output from `stdout`, +not `stderr`. DIAGNOSTICS ----------- -upsc will either print a list of UPS names, a list of all supported variables -and their values on the UPS, or an error message. If you receive an error, +`upsc` will either print a list of UPS names, a list of all supported variables +and their values on the UPS, or an error message. If you do receive an error, make sure you have specified a valid UPS on the command line, that -linkman:upsd[8] is really running on the other host and that no firewalls are +linkman:upsd[8] is really running on the other host, and that no firewalls are blocking you. HISTORY @@ -113,6 +114,8 @@ only talks TCP. This is why 'upsct' no longer exists. SEE ALSO -------- +linkman:upslog[8], +linkman:ups.conf[5], linkman:upsd[8] Internet resources: From ea80b2b37ce0db79f13480d723202f9cc3f51dc0 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Wed, 5 Feb 2025 16:00:47 +0100 Subject: [PATCH 09/67] docs/man/upscli_splitaddr.txt: fix description of the method Signed-off-by: Jim Klimov --- docs/man/upscli_splitaddr.txt | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/man/upscli_splitaddr.txt b/docs/man/upscli_splitaddr.txt index b7054939f6..a3f2c34aa0 100644 --- a/docs/man/upscli_splitaddr.txt +++ b/docs/man/upscli_splitaddr.txt @@ -17,10 +17,9 @@ SYNOPSIS DESCRIPTION ----------- -The *upscli_splitaddr()* function takes a pointer to the raw UPS -definition 'buf' and returns pointers to dynamically allocated -memory in 'upsname' and 'hostname'. It also copies the port -number into 'port'. +The *upscli_splitaddr()* function takes a pointer to the listening address +definition 'buf' and returns the pointer to dynamically allocated +memory in 'hostname'. It also copies the port number into 'port'. FORMATTING ---------- From 2bf9a13bb00e79dab085572187de9d738172092e Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Wed, 5 Feb 2025 16:12:22 +0100 Subject: [PATCH 10/67] docs/man/{lib,nutscan,upscli}*: update markup of API docs to be consistent * Block-quoting and indentation of SYNOPSIS * Bullet-lists for numerous methods and args * Slight wording changes * Single-quote integer return values * Backtick-quote program and config file names * Cross-link to some other pages with linkman macro Signed-off-by: Jim Klimov --- docs/man/libnutclient.txt | 8 ++- docs/man/libnutclient_commands.txt | 7 ++- docs/man/libnutclient_devices.txt | 7 ++- docs/man/libnutclient_general.txt | 24 +++++--- docs/man/libnutclient_misc.txt | 32 +++++----- docs/man/libnutclient_tcp.txt | 37 ++++++------ docs/man/libnutclient_variables.txt | 60 +++++++++++-------- docs/man/libupsclient-config.txt | 8 ++- docs/man/nutscan.txt | 2 +- docs/man/nutscan_add_device_to_device.txt | 11 ++-- docs/man/nutscan_add_ip_range.txt | 49 +++++++-------- docs/man/nutscan_add_option_to_device.txt | 47 ++++++++------- docs/man/nutscan_cidr_to_ip.txt | 13 ++-- docs/man/nutscan_display_parsable.txt | 10 ++-- docs/man/nutscan_display_sanity_check.txt | 12 ++-- .../nutscan_display_sanity_check_serial.txt | 12 ++-- docs/man/nutscan_display_ups_conf.txt | 12 ++-- ...can_display_ups_conf_with_sanity_check.txt | 10 ++-- docs/man/nutscan_free_device.txt | 6 +- docs/man/nutscan_free_ip_ranges.txt | 10 ++-- docs/man/nutscan_get_serial_ports_list.txt | 42 +++++++------ docs/man/nutscan_init.txt | 23 +++---- docs/man/nutscan_init_ip_ranges.txt | 8 ++- docs/man/nutscan_ip_ranges_iter_inc.txt | 15 +++-- docs/man/nutscan_ip_ranges_iter_init.txt | 11 ++-- docs/man/nutscan_new_device.txt | 6 +- docs/man/nutscan_scan_avahi.txt | 8 ++- docs/man/nutscan_scan_eaton_serial.txt | 12 ++-- docs/man/nutscan_scan_ipmi.txt | 26 ++++---- docs/man/nutscan_scan_nut.txt | 32 +++++----- docs/man/nutscan_scan_nut_simulation.txt | 21 +++++-- docs/man/nutscan_scan_snmp.txt | 38 ++++++------ docs/man/nutscan_scan_usb.txt | 12 ++-- docs/man/nutscan_scan_xml_http_range.txt | 34 ++++++----- docs/man/nutscan_stringify_ip_ranges.txt | 8 ++- docs/man/upscli_add_host_cert.txt | 15 +++-- docs/man/upscli_cleanup.txt | 8 ++- docs/man/upscli_connect.txt | 10 ++-- docs/man/upscli_disconnect.txt | 10 ++-- docs/man/upscli_fd.txt | 8 ++- docs/man/upscli_get.txt | 38 +++++++----- docs/man/upscli_init.txt | 54 ++++++++++------- docs/man/upscli_list_next.txt | 28 +++++---- docs/man/upscli_list_start.txt | 10 ++-- docs/man/upscli_readline.txt | 18 +++--- docs/man/upscli_sendline.txt | 16 ++--- docs/man/upscli_splitaddr.txt | 16 ++--- docs/man/upscli_splitname.txt | 20 ++++--- docs/man/upscli_ssl.txt | 13 ++-- docs/man/upscli_strerror.txt | 10 ++-- docs/man/upscli_upserror.txt | 8 ++- docs/man/upsclient.txt | 9 +-- 52 files changed, 563 insertions(+), 401 deletions(-) diff --git a/docs/man/libnutclient.txt b/docs/man/libnutclient.txt index 668eb8349a..60fcb7c4a4 100644 --- a/docs/man/libnutclient.txt +++ b/docs/man/libnutclient.txt @@ -9,9 +9,11 @@ libnutclient - Network UPS Tools high-level client access library SYNOPSIS -------- +------ #include +------ - Refer to this file for more information. +Refer to this file for more information. DESCRIPTION @@ -21,8 +23,8 @@ The Network UPS Tools (NUT) *nutclient* library provides a number of useful functions for programs to use when communicating with linkman:upsd[8]. It provides high-level representation of NUT data through client connection, devices, variables and commands. -Unlike linkman:upsclient[3], all low-level protocol details are -hidden. +Unlike linkman:upsclient[3] (also known as "upscli" API), here all +low-level protocol details are hidden. State is maintained across calls in an opaque structure called `NUTCLIENT_t`. Callers are expected to create one per client connection. These will be diff --git a/docs/man/libnutclient_commands.txt b/docs/man/libnutclient_commands.txt index 33a90ca559..676d35e48a 100644 --- a/docs/man/libnutclient_commands.txt +++ b/docs/man/libnutclient_commands.txt @@ -13,6 +13,7 @@ access library SYNOPSIS -------- +------ #include typedef void* NUTCLIENT_t; @@ -35,6 +36,7 @@ SYNOPSIS NUTCLIENT_t client, const char* dev, const char* cmd, const char* param=""); +------ DESCRIPTION ----------- @@ -49,12 +51,13 @@ The returned strarr must be freed by 'strarr_free'. * The *nutclient_has_device_command* function tests if the specified command is supported by the device. + -Return 1 is supported and 0 if not. +Return '1' if supported and '0' if not. * The *nutclient_get_device_command_description* function retrieves the command description, if any. + -The returned string must be freed. +The returned string must be freed by linkman:free[3] +(see linkman:libnutclient_general[3]). * The *nutclient_execute_device_command* intends to execute the instant command, with an optional parameter. diff --git a/docs/man/libnutclient_devices.txt b/docs/man/libnutclient_devices.txt index 700673f04a..d0fd5e0b51 100644 --- a/docs/man/libnutclient_devices.txt +++ b/docs/man/libnutclient_devices.txt @@ -12,6 +12,7 @@ library SYNOPSIS -------- +------ #include typedef void* NUTCLIENT_t; @@ -23,6 +24,7 @@ SYNOPSIS int nutclient_has_device(NUTCLIENT_t client, const char* dev); char* nutclient_get_device_description(NUTCLIENT_t client, const char* dev); +------ DESCRIPTION ----------- @@ -32,7 +34,8 @@ These functions allow to manage devices. * The *nutclient_get_devices()* function retrieves the list of devices monitored by a client. + -The returned strarr must be freed by 'strarr_free'. +The returned strarr must be freed by 'strarr_free' +(see linkman:libnutclient_general[3]). * The *nutclient_has_device()* function tests if a device is monitored by a client. @@ -40,7 +43,7 @@ The returned strarr must be freed by 'strarr_free'. * The *nutclient_get_device_description()* function retrieves the device description. + -The returned description string must be freed. +The returned description string must be freed by linkman:free[3]. Common arguments: diff --git a/docs/man/libnutclient_general.txt b/docs/man/libnutclient_general.txt index 7d41acf136..0725ab623c 100644 --- a/docs/man/libnutclient_general.txt +++ b/docs/man/libnutclient_general.txt @@ -11,6 +11,7 @@ access library SYNOPSIS -------- +------ #include typedef void* NUTCLIENT_t; @@ -22,6 +23,7 @@ SYNOPSIS strarr strarr_alloc(unsigned short count); void strarr_free(strarr arr); +------ DESCRIPTION ----------- @@ -29,18 +31,22 @@ DESCRIPTION The *nutclient_destroy()* function destroys a 'NUTCLIENT_t' or derived (like 'NUTCLIENT_TCP_t') connection object, and frees allocated memory. -The *strarr* type represents an array of C strings (array of char pointer). -The array must always be terminated by a NULL pointer. -Pointed strings must be allocated by (x)calloc or (x)strdup. +* The *strarr* type represents an array of C strings (array of char pointer). + The array must always be terminated by a NULL pointer. ++ +Pointed strings must be allocated by `(x)calloc` or `(x)strdup`. -The *strarr_alloc()* function allocates a 'strarr' array with the specified -number of (non-initialized) string pointers. -Another additional pointer set to 0 is added at the end of the array. +* The *strarr_alloc()* function allocates a 'strarr' array with the specified + number of (non-initialized) string pointers. ++ +Another additional pointer set to NULL is added at the end of the array. -The *strarr_free* function frees a 'strarr' array. -It also frees all pointed strings. +* The *strarr_free* function frees a 'strarr' array. + It also frees all pointed strings. -'dev' is the device name. +Common arguments: + +* 'dev' is the device name. SEE ALSO -------- diff --git a/docs/man/libnutclient_misc.txt b/docs/man/libnutclient_misc.txt index 2635db4722..871db2cca7 100644 --- a/docs/man/libnutclient_misc.txt +++ b/docs/man/libnutclient_misc.txt @@ -12,6 +12,7 @@ Miscellaneous functions in Network UPS Tools high-level client access library SYNOPSIS -------- +------ #include typedef void* NUTCLIENT_t; @@ -31,32 +32,35 @@ SYNOPSIS void nutclient_device_master(NUTCLIENT_t client, const char* dev); void nutclient_device_forced_shutdown(NUTCLIENT_t client, const char* dev); +------ DESCRIPTION ----------- -The *nutclient_authenticate()* function authenticates the user. +* The *nutclient_authenticate()* function authenticates the user. -* 'login' is the user name. + - 'login' is the user name. -* 'passwd' is the user password. + - 'passwd' is the user password. -The *nutclient_logout()* function disconnects gracefully from the server. +* The *nutclient_logout()* function disconnects gracefully from the server. -The *nutclient_device_login()* function logs the fact that a system -is drawing power from this UPS. +* The *nutclient_device_login()* function logs the fact that a system + is drawing power from this UPS. -The *nutclient_get_device_num_logins()* function retrieves the number of -clients which have been logged for this device. +* The *nutclient_get_device_num_logins()* function retrieves the number of + clients which have been logged for this device. -The *nutclient_device_master()* and *nutclient_device_primary()* (note: -the former is obsoleted since NUT v2.8.0 in favor of the latter) functions -make sure that primary-mode functions like FSD are available if necessary. +* The *nutclient_device_master()* and *nutclient_device_primary()* (note: + the former is obsoleted since NUT v2.8.0 in favor of the latter) functions + make sure that primary-mode functions like FSD are available if necessary. -The *nutclient_device_forced_shutdown()* function sets the "forced shutdown" -flag on the device. +* The *nutclient_device_forced_shutdown()* function sets the "forced shutdown" + (FSD) flag on the device. -'dev' is the device name. +Common arguments: + +* 'dev' is the device name. SEE ALSO -------- diff --git a/docs/man/libnutclient_tcp.txt b/docs/man/libnutclient_tcp.txt index 299fce22b9..5e227ae095 100644 --- a/docs/man/libnutclient_tcp.txt +++ b/docs/man/libnutclient_tcp.txt @@ -13,6 +13,7 @@ access library SYNOPSIS -------- +------ #include #include /* uint16_t */ #include /* time_t */ @@ -31,6 +32,7 @@ SYNOPSIS void nutclient_tcp_set_timeout(NUTCLIENT_TCP_t client, time_t timeout); time_t nutclient_tcp_get_timeout(NUTCLIENT_TCP_t client); +------ DESCRIPTION ----------- @@ -38,30 +40,31 @@ DESCRIPTION These functions allow to manage connections to linkman:upsd[8] using NUT TCP protocol. -The *nutclient_tcp_create_client()* function create the 'NUTCLIENT_TCP_t' -context and intend to connect to upsd at 'host' and 'port'. -The context must be freed by 'nutclient_destroy()' +* The *nutclient_tcp_create_client()* function create the 'NUTCLIENT_TCP_t' + context and intend to connect to upsd at 'host' and 'port'. ++ +The context must be freed by 'nutclient_destroy()'. -* 'host' can be a sever name or a valid IPv4 or IPv6 address like -"localhost", "127.0.0.1" or "::1". + - 'host' can be a sever name or a valid IPv4 or IPv6 address like + "localhost", "127.0.0.1" or "::1". -* 'port' is a valid TCP port, generally 3493. + - 'port' is a valid TCP port, generally '3493'. -The *nutclient_tcp_is_connected()* function test if the connection is valid. +* The *nutclient_tcp_is_connected()* function test if the connection is valid. -The *nutclient_tcp_disconnect()* function force to disconnect the specified -connection. +* The *nutclient_tcp_disconnect()* function force to disconnect the specified + connection. -The *nutclient_tcp_reconnect()* function force to reconnect a connection, -disconnecting it if needed. +* The *nutclient_tcp_reconnect()* function force to reconnect a connection, + disconnecting it if needed. -The *nutclient_tcp_set_timeout()* function set the timeout duration -for I/O operations. +* The *nutclient_tcp_set_timeout()* function set the timeout duration + for I/O operations. -The *nutclient_tcp_get_timeout()* function retrieve the timeout duration -for I/O operations. - -'timeout' values are specified in seconds, negatives values for blocking. +* The *nutclient_tcp_get_timeout()* function retrieve the timeout duration + for I/O operations. ++ +'timeout' values are specified in seconds, use negative values for blocking. SEE ALSO -------- diff --git a/docs/man/libnutclient_variables.txt b/docs/man/libnutclient_variables.txt index fbeeb3d981..28f5efbc8d 100644 --- a/docs/man/libnutclient_variables.txt +++ b/docs/man/libnutclient_variables.txt @@ -15,6 +15,7 @@ library SYNOPSIS -------- +------ #include typedef void* NUTCLIENT_t; @@ -41,37 +42,46 @@ SYNOPSIS void nutclient_set_device_variable_values(NUTCLIENT_t client, const char* dev, const char* var, const strarr values); +------ DESCRIPTION ----------- These functions allow to manage variables of devices. -The *nutclient_get_device_variables()* function retrieves the list -of variables names for a device. -The returned strarr must be freed by 'strarr_free'. - -The *nutclient_get_device_rw_variables* function retrieves the list -of read-write variables names for a device. -The returned strarr must be freed by 'strarr_free'. - -The *nutclient_has_device_variable* function tests if the specified -variable is supported by the device. -Return 1 is supported and 0 if not. - -The *nutclient_get_device_variable_description* function retrieves -the variable description, if any. -The returned string must be freed. - -The *nutclient_get_device_variable_values* returns variable values -(generally only one). -The returned strarr must be freed by 'strarr_free'. - -The *nutclient_set_device_variable_value* intends to set the value -of the specified variable. - -The *nutclient_set_device_variable_values* intends to set multiple -values of the specified variable. +* The *nutclient_get_device_variables()* function retrieves the list + of variables names for a device. ++ +The returned strarr must be freed by 'strarr_free' +(see linkman:libnutclient_general[3]). + +* The *nutclient_get_device_rw_variables* function retrieves the list + of read-write variables names for a device. ++ +The returned strarr must be freed by 'strarr_free' +(see linkman:libnutclient_general[3]). + +* The *nutclient_has_device_variable* function tests if the specified + variable is supported by the device. ++ +Return '1' if supported and '0' if not. + +* The *nutclient_get_device_variable_description* function retrieves + the variable description, if any. ++ +The returned string must be freed by linkman:free[3]. + +* The *nutclient_get_device_variable_values* returns variable values + (generally only one). ++ +The returned strarr must be freed by 'strarr_free' +(see linkman:libnutclient_general[3]). + +* The *nutclient_set_device_variable_value* intends to set the value + of the specified variable. + +* The *nutclient_set_device_variable_values* intends to set multiple + values of the specified variable. Common arguments: diff --git a/docs/man/libupsclient-config.txt b/docs/man/libupsclient-config.txt index 28b45fd139..1a4e21e7f1 100644 --- a/docs/man/libupsclient-config.txt +++ b/docs/man/libupsclient-config.txt @@ -16,8 +16,9 @@ DESCRIPTION ----------- *libupsclient-config* is a tool that is used to determine the compiler and -linker flags that should be used to compile and link programs that use -*libupsclient* from the Network UPS Tools project. +linker flags that should be used to compile and link programs that use the +*libupsclient* from the Network UPS Tools project (also known as the "upscli" +API). It allows to simplify build automation for systems without a `pkg-config` implementation which would instead use the `libupsclient.pc` file installed @@ -45,7 +46,8 @@ This manual page was written by Arnaud Quette . SEE ALSO -------- -linkman:upsclient[3] +linkman:upsclient[3], +linkman:nutclient[3] Internet resources: ~~~~~~~~~~~~~~~~~~~ diff --git a/docs/man/nutscan.txt b/docs/man/nutscan.txt index 7f3390d026..6340ab1c9d 100644 --- a/docs/man/nutscan.txt +++ b/docs/man/nutscan.txt @@ -22,7 +22,7 @@ DISCOVERY FUNCTIONS First, include the required header file: - #include + #include Then, to discover new devices, use the appropriate function: diff --git a/docs/man/nutscan_add_device_to_device.txt b/docs/man/nutscan_add_device_to_device.txt index 2cde5523f8..903bf87f62 100644 --- a/docs/man/nutscan_add_device_to_device.txt +++ b/docs/man/nutscan_add_device_to_device.txt @@ -9,12 +9,13 @@ nutscan_add_device_to_device - Concatenate two devices structure. SYNOPSIS -------- - #include - - nutscan_device_t * nutscan_add_device_to_device( - nutscan_device_t * first, - nutscan_device_t * second); +------ + #include + nutscan_device_t * nutscan_add_device_to_device( + nutscan_device_t * first, + nutscan_device_t * second); +------ DESCRIPTION ----------- diff --git a/docs/man/nutscan_add_ip_range.txt b/docs/man/nutscan_add_ip_range.txt index 8270c6cc69..cca8084bc6 100644 --- a/docs/man/nutscan_add_ip_range.txt +++ b/docs/man/nutscan_add_ip_range.txt @@ -10,27 +10,28 @@ and ending addresses) to a `nutscan_ip_range_list_t` structure. SYNOPSIS -------- - #include - - /* One IP address range: */ - typedef struct nutscan_ip_range_s { - char * start_ip; - char * end_ip; - struct nutscan_ip_range_s * next; - } nutscan_ip_range_t; - - /* List of IP address ranges and helper data: */ - typedef struct nutscan_ip_range_list_s { - nutscan_ip_range_t * ip_ranges; /* Actual linked list of entries, first entry */ - nutscan_ip_range_t * ip_ranges_last; /* Pointer to end of list for quicker additions */ - size_t ip_ranges_count; /* Counter of added entries */ - } nutscan_ip_range_list_t; - - - size_t nutscan_add_ip_range( - nutscan_ip_range_list_t *irl, - char * start_ip, - char * end_ip); +------ + #include + + /* One IP address range: */ + typedef struct nutscan_ip_range_s { + char * start_ip; + char * end_ip; + struct nutscan_ip_range_s * next; + } nutscan_ip_range_t; + + /* List of IP address ranges and helper data: */ + typedef struct nutscan_ip_range_list_s { + nutscan_ip_range_t * ip_ranges; /* Actual linked list of entries, first entry */ + nutscan_ip_range_t * ip_ranges_last; /* Pointer to end of list for quicker additions */ + size_t ip_ranges_count; /* Counter of added entries */ + } nutscan_ip_range_list_t; + + size_t nutscan_add_ip_range( + nutscan_ip_range_list_t *irl, + char * start_ip, + char * end_ip); +------ DESCRIPTION ----------- @@ -42,9 +43,9 @@ or 0 in case of non-fatal errors. This function skips work if: -* the structure pointer is `NULL` (0 is returned); -* neither `start_ip` nor `end_ip` were provided, i.e. they have `NULL` values - (current list length from the structure is returned); +* the structure pointer is `NULL` ('0' is returned); +* neither `start_ip` nor `end_ip` were provided, i.e. they both have `NULL` + values (current list length from the structure is returned); * failed to allocate the entry (fatal). If only one of `start_ip` or `end_ip` values was provided (not `NULL`), a diff --git a/docs/man/nutscan_add_option_to_device.txt b/docs/man/nutscan_add_option_to_device.txt index b24ff8e3a7..bed9a087f5 100644 --- a/docs/man/nutscan_add_option_to_device.txt +++ b/docs/man/nutscan_add_option_to_device.txt @@ -11,23 +11,24 @@ option data to the specified device. SYNOPSIS -------- - #include - - /* Add enabled option data to the specified device. */ - void nutscan_add_option_to_device( - nutscan_device_t * device, - char * option_name, - char * value); - - /* Since libnutscan version 2.5.0: - * Add option data to the specified device with an optional comment tag - * for options suggested, but not currently enabled for actual use. */ - void nutscan_add_commented_option_to_device( - nutscan_device_t * device, - char * option_name, - char * value, - char * comment_tag); - +------ + #include + + /* Add enabled option data to the specified device. */ + void nutscan_add_option_to_device( + nutscan_device_t * device, + char * option_name, + char * value); + + /* Since libnutscan version 2.5.0: + * Add option data to the specified device with an optional comment tag + * for options suggested, but not currently enabled for actual use. */ + void nutscan_add_commented_option_to_device( + nutscan_device_t * device, + char * option_name, + char * value, + char * comment_tag); +------ DESCRIPTION ----------- @@ -42,15 +43,15 @@ The `nutscan_device_t` contains the following variables: struct nutscan_device * prev; struct nutscan_device * next; -This is a double linked list of device. Each device is described by +This is a double linked list of devices. Each 'device' is described by its `type`, its `driver` name, its `port` and any number of optional data. The *nutscan_add_option_to_device()* adds an optional data in the -given device. Optional data are made of an 'option_name' and an +given 'device'. Optional data are made of an 'option_name' and an associated 'value', and optionally a 'comment_tag'. Copies of the -'option_name', 'value' and 'comment_tag' are stored in the device, -so the caller can safely free all of the original strings used as -arguments. +'option_name', 'value' and 'comment_tag' are stored in the 'device', +so the caller can safely linkman:free[3] all of the original strings +used as arguments. NOTE: A non-`NULL` value of the 'comment_tag' makes the option not-enabled for current use. Depending on the output format, it may be either completely @@ -60,7 +61,7 @@ string `"\0"` may be passed to have no prefix). Such options and their values may be further sanity-checked and reported as warnings by *nutscan_display_sanity_check()* dispatcher and its related methods which implement the logic of particular checks. This is used for -example when generating 'ups.conf' file content suggestions with +example when generating an `ups.conf` file content suggestions with *nutscan_display_ups_conf_with_sanity_check()* method. NOTES diff --git a/docs/man/nutscan_cidr_to_ip.txt b/docs/man/nutscan_cidr_to_ip.txt index ef7c9a9c1a..f631431140 100644 --- a/docs/man/nutscan_cidr_to_ip.txt +++ b/docs/man/nutscan_cidr_to_ip.txt @@ -9,9 +9,11 @@ nutscan_cidr_to_ip - Convert a CIDR IP to a range of IP address. SYNOPSIS -------- - #include +------ + #include - int nutscan_cidr_to_ip(const char * cidr, char ** start_ip, char ** stop_ip); + int nutscan_cidr_to_ip(const char * cidr, char ** start_ip, char ** stop_ip); +------ DESCRIPTION ----------- @@ -21,13 +23,14 @@ the CIDR format given as a string in 'cidr', to two IPs in strings pointed by 'start_ip' and 'stop_ip' which can be used as input parameters in the scanning functions of the libnutscan API. -It is the caller's responsibility to free 'start_ip' and 'stop_ip' strings. +It is the caller's responsibility to linkman:free[3] the 'start_ip' +and 'stop_ip' strings. RETURN VALUE ------------ -The *nutscan_cidr_to_ip()* function returns 0 if an error occurred -(invalid 'cidr' address) or 1 if successful. +The *nutscan_cidr_to_ip()* function returns '0' if an error occurred +(invalid 'cidr' address) or '1' if successful. NOTES ----- diff --git a/docs/man/nutscan_display_parsable.txt b/docs/man/nutscan_display_parsable.txt index aa2cc76e4b..fb07bb73bf 100644 --- a/docs/man/nutscan_display_parsable.txt +++ b/docs/man/nutscan_display_parsable.txt @@ -10,15 +10,17 @@ structure on stdout. SYNOPSIS -------- - #include +------ + #include - void nutscan_display_parsable(nutscan_device_t * device); + void nutscan_display_parsable(nutscan_device_t * device); +------ DESCRIPTION ----------- The *nutscan_display_parsable()* function displays all NUT devices in -'device' to stdout. It displays them in a way that can be easily parsed +'device' to `stdout`. It displays them in a way that can be easily parsed, which is: :driver="",port=""[,="",="",...] @@ -31,7 +33,7 @@ which is: Note that this format is for machine consumption, so is not associated with sanity checks that may be used along with display method for the -'ups.conf' file format. +`ups.conf` file format. SEE ALSO -------- diff --git a/docs/man/nutscan_display_sanity_check.txt b/docs/man/nutscan_display_sanity_check.txt index f0e6ce4eb0..2a089c3726 100644 --- a/docs/man/nutscan_display_sanity_check.txt +++ b/docs/man/nutscan_display_sanity_check.txt @@ -10,20 +10,22 @@ the specified `nutscan_device_t` structure on stdout. SYNOPSIS -------- - #include +------ + #include - void nutscan_display_sanity_check(nutscan_device_t * device); + void nutscan_display_sanity_check(nutscan_device_t * device); +------ DESCRIPTION ----------- The *nutscan_display_sanity_check()* function calls all sanity-check analyzers against displays all NUT devices in 'device', and they may -print comments to stdout. It displays them in a way that it can be -directly copied into the 'ups.conf' file. +print comments to `stdout`. It displays them in a way that it can be +directly copied into the `ups.conf` file. It is called from *nutscan_display_ups_conf_with_sanity_check()* to -provide an aggregate content for 'ups.conf' file in one shot. +provide an aggregate content for `ups.conf` file in one shot. SEE ALSO -------- diff --git a/docs/man/nutscan_display_sanity_check_serial.txt b/docs/man/nutscan_display_sanity_check_serial.txt index 243b15a341..d26d3354e6 100644 --- a/docs/man/nutscan_display_sanity_check_serial.txt +++ b/docs/man/nutscan_display_sanity_check_serial.txt @@ -11,21 +11,23 @@ specified `nutscan_device_t` structure on stdout. SYNOPSIS -------- - #include +------ + #include - void nutscan_display_sanity_check_serial(nutscan_device_t * device); + void nutscan_display_sanity_check_serial(nutscan_device_t * device); +------ DESCRIPTION ----------- The *nutscan_display_sanity_check_serial()* function analyzes "serial" optional field in all NUT devices in 'device', and in case of duplicate -or otherwise seemingly invalid values, prints comments to stdout. +or otherwise seemingly invalid values, prints comments to `stdout`. It displays them in a way that it can be directly copied into the -'ups.conf' file. +`ups.conf` file. It is called from *nutscan_display_ups_conf_with_sanity_check()* to -provide an aggregate content for 'ups.conf' file in one shot. +provide an aggregate content for `ups.conf` file in one shot. SEE ALSO -------- diff --git a/docs/man/nutscan_display_ups_conf.txt b/docs/man/nutscan_display_ups_conf.txt index 3b6233ac9d..fbf00fc52b 100644 --- a/docs/man/nutscan_display_ups_conf.txt +++ b/docs/man/nutscan_display_ups_conf.txt @@ -10,19 +10,21 @@ structure on stdout. SYNOPSIS -------- - #include +------ + #include - void nutscan_display_ups_conf(nutscan_device_t * device); + void nutscan_display_ups_conf(nutscan_device_t * device); +------ DESCRIPTION ----------- The *nutscan_display_ups_conf()* function displays all NUT devices in -'device' to stdout. It displays them in a way that it can be directly -copied into the 'ups.conf' file. +'device' to `stdout`. It displays them in a way that it can be directly +copied into the `ups.conf` file. It is called from *nutscan_display_ups_conf_with_sanity_check()* to -provide an aggregate content for 'ups.conf' file in one shot. +provide an aggregate content for `ups.conf` file in one shot. SEE ALSO -------- diff --git a/docs/man/nutscan_display_ups_conf_with_sanity_check.txt b/docs/man/nutscan_display_ups_conf_with_sanity_check.txt index 838375eb36..8daf5d1d08 100644 --- a/docs/man/nutscan_display_ups_conf_with_sanity_check.txt +++ b/docs/man/nutscan_display_ups_conf_with_sanity_check.txt @@ -10,17 +10,19 @@ nutscan_display_ups_conf_with_sanity_check - Display the specified SYNOPSIS -------- - #include +------ + #include - void nutscan_display_ups_conf_with_sanity_check(nutscan_device_t * device); + void nutscan_display_ups_conf_with_sanity_check(nutscan_device_t * device); +------ DESCRIPTION ----------- The *nutscan_display_ups_conf_with_sanity_check()* function displays -all NUT devices in 'device' to stdout, and follows up with comments +all NUT devices in 'device' to `stdout`, and follows up with comments about sanity-check violations (if any). It displays them in a way that -it can be directly copied into the 'ups.conf' file. +it can be directly copied into the `ups.conf` file. SEE ALSO -------- diff --git a/docs/man/nutscan_free_device.txt b/docs/man/nutscan_free_device.txt index 7ef10cc3ad..2bff433223 100644 --- a/docs/man/nutscan_free_device.txt +++ b/docs/man/nutscan_free_device.txt @@ -10,9 +10,11 @@ nutscan_free_device - Free a `nutscan_device_t` structure created by SYNOPSIS -------- - #include +------ + #include - void nutscan_free_device(nutscan_device_t * device); + void nutscan_free_device(nutscan_device_t * device); +------ DESCRIPTION ----------- diff --git a/docs/man/nutscan_free_ip_ranges.txt b/docs/man/nutscan_free_ip_ranges.txt index 567e89dcfe..77bf85403e 100644 --- a/docs/man/nutscan_free_ip_ranges.txt +++ b/docs/man/nutscan_free_ip_ranges.txt @@ -11,9 +11,11 @@ and, more importantly, filled by a series of `nutscan_add_ip_range()` calls. SYNOPSIS -------- - #include +------ + #include - void nutscan_free_ip_ranges(nutscan_ip_range_list_t *irl); + void nutscan_free_ip_ranges(nutscan_ip_range_list_t *irl); +------ DESCRIPTION ----------- @@ -25,8 +27,8 @@ entries, and zeroes out helper properties. The structure itself is not freed (as it can be a statically allocated variable on the stack), and can be re-used for a new list if needed. -The caller must free the structure object if it was allocated dynamically -(e.g. by calling `nutscan_init_ip_ranges(NULL)`). +The caller must ultimately free the structure object if it was allocated +dynamically (e.g. by originally calling `nutscan_init_ip_ranges(NULL)`). NOTES ----- diff --git a/docs/man/nutscan_get_serial_ports_list.txt b/docs/man/nutscan_get_serial_ports_list.txt index bf8aa26d89..0cea2d7610 100644 --- a/docs/man/nutscan_get_serial_ports_list.txt +++ b/docs/man/nutscan_get_serial_ports_list.txt @@ -9,39 +9,43 @@ nutscan_get_serial_ports_list - Get a port list name from a range of port. SYNOPSIS -------- - #include +------ + #include - char ** nutscan_get_serial_ports_list(const char *ports_range); + char ** nutscan_get_serial_ports_list(const char *ports_range); +------ DESCRIPTION ----------- The *nutscan_get_serial_ports_list()* function returns a null terminated array of strings generated from a port range. -'ports_range' may be one of: - - - a single character from 0 to 9 or a to z representing a serial - communication port depending on the operating system. For instance - "0" is converted to /dev/ttyS0 and /dev/ttyUSB0 on Linux; - "1" is converted to COM1 on Windows; - "c" is converted to /dev/ttyc on Solaris... - - a range of character in the form "X-Y". For instance - "0-1" will be converted to /dev/ttyS0, /dev/ttyS1, /dev/ttyUSB0 - and /dev/ttyUSB1 on Linux; - "1-3" will be converted to COM1, COM2 and COM3 on Windows; - "a-c" will be converted to /dev/ttya, /dev/ttyb and /dev/ttyc on Solaris. - - a single port name (/dev/ttyS5, COM4...). - - a list of port names separated with commas: - "/dev/ttyS0,/dev/ttyS2,/dev/ttyS4" or "COM1,COM3"... + +The 'ports_range' may be one of: + +* a single character from `0` to `9` or `a` to `z`, representing a serial + communication port depending on the operating system. For instance: + - `0` is converted to `/dev/ttyS0` and `/dev/ttyUSB0` on Linux; + - `1` is converted to `COM1` on Windows; + - `c` is converted to `/dev/ttyc` on Solaris... +* a range of character in the form `X-Y`. For instance + - `0-1` will be converted to `/dev/ttyS0`, `/dev/ttyS1`, `/dev/ttyUSB0` + and `/dev/ttyUSB1` on Linux; + - `1-3` will be converted to `COM1`, `COM2` and `COM3` on Windows; + - `a-c` will be converted to `/dev/ttya`, `/dev/ttyb` and `/dev/ttyc` + on Solaris. +* a single port name (`/dev/ttyS5`, `COM4`...). +* a list of port names separated with commas: + `/dev/ttyS0,/dev/ttyS2,/dev/ttyS4` or `COM1,COM3`... The returned array can be used in a call to *nutscan_scan_eaton_serial* -to get the serial device on a system. +to get the serial-port device on a system. RETURN VALUE ------------ The *nutscan_get_serial_ports_list()* function returns NULL if an error -occurred (invalid port range) or a pointer to a null terminated array +occurred (invalid port range) or a pointer to a NULL-terminated array of strings on success. NOTES diff --git a/docs/man/nutscan_init.txt b/docs/man/nutscan_init.txt index 27768d270b..96ad345e87 100644 --- a/docs/man/nutscan_init.txt +++ b/docs/man/nutscan_init.txt @@ -9,9 +9,11 @@ nutscan_init - Initialize the nutscan library. SYNOPSIS -------- - #include +------ + #include - void nutscan_init(void); + void nutscan_init(void); +------ DESCRIPTION ----------- @@ -22,15 +24,16 @@ any other function of the nutscan library. It updates the following global variables which can be used by nutscan library user to know which scan methods are available at run-time. -This depends on the libraries installed on the system: +This depends on further libraries installed on the system: - nutscan_avail_avahi = 1 : AVAHI scan is available - nutscan_avail_ipmi = 1 : IPMI scan is available - nutscan_avail_nut = 1 : Old NUT method is available - nutscan_avail_nut_simulation = 1 : NUT simulation devices method is available - nutscan_avail_snmp = 1 : SNMP method is available - nutscan_avail_usb = 1 : USB method is available - nutscan_avail_xml_http = 1 : XML HTTP method is available +* `nutscan_avail_avahi = 1`: AVAHI NUT scan is available +* `nutscan_avail_ipmi = 1`: IPMI scan is available +* `nutscan_avail_nut = 1`: "Old" NUT method is available +* `nutscan_avail_nut_simulation = 1`: NUT simulation devices method + is available +* `nutscan_avail_snmp = 1`: SNMP method is available +* `nutscan_avail_usb = 1`: USB method is available +* `nutscan_avail_xml_http = 1`: XML HTTP method is available Note that if a method is reported as unavailable by those variables, the call to the corresponding `nutscan_scan_*` function will always return NULL. diff --git a/docs/man/nutscan_init_ip_ranges.txt b/docs/man/nutscan_init_ip_ranges.txt index 73094aaefc..9049c99f80 100644 --- a/docs/man/nutscan_init_ip_ranges.txt +++ b/docs/man/nutscan_init_ip_ranges.txt @@ -10,9 +10,11 @@ structure (and optionally create one in the first place). SYNOPSIS -------- - #include +------ + #include - nutscan_ip_range_list_t * nutscan_init_ip_ranges(nutscan_ip_range_list_t *irl); + nutscan_ip_range_list_t * nutscan_init_ip_ranges(nutscan_ip_range_list_t *irl); +------ DESCRIPTION ----------- @@ -27,7 +29,7 @@ as it may have garbage from stack after allocation. The caller must free the contents of the structure after completing its use by calling `nutscan_free_ip_ranges` (after which the structure can be re-used), and explicitly `free()` the structure object itself if it was allocated -dynamically (e.g. by calling `nutscan_init_ip_ranges(NULL)`). +dynamically (e.g. by originally calling `nutscan_init_ip_ranges(NULL)`). NOTES ----- diff --git a/docs/man/nutscan_ip_ranges_iter_inc.txt b/docs/man/nutscan_ip_ranges_iter_inc.txt index abbd12aa0c..f02cf98c7e 100644 --- a/docs/man/nutscan_ip_ranges_iter_inc.txt +++ b/docs/man/nutscan_ip_ranges_iter_inc.txt @@ -10,15 +10,19 @@ using a `nutscan_ip_range_list_iter_t` structure. SYNOPSIS -------- - #include +------ + #include - char * nutscan_ip_ranges_iter_inc(nutscan_ip_range_list_iter_t *irliter); + char * nutscan_ip_ranges_iter_inc(nutscan_ip_range_list_iter_t *irliter); +------ DESCRIPTION ----------- -The *nutscan_ip_ranges_iter_inc()* function can prepare an iterator from -the specified `nutscan_ip_range_list_t` structure. +The *nutscan_ip_ranges_iter_inc()* function can walk an iterator from +the specified `nutscan_ip_range_list_iter_t` helper object, prepared by +linkman:nutscan_ip_ranges_iter_init[3] from a `nutscan_ip_range_list_t` +structure. This function skips work if: @@ -29,7 +33,8 @@ This function skips work if: Returns the next IP address from the currently iterated registered IP address range, or switches iteration to the next range if no addresses -remained in the current one. +remained in the current one. The caller SHOULD NOT free this string +while iterating. NOTES ----- diff --git a/docs/man/nutscan_ip_ranges_iter_init.txt b/docs/man/nutscan_ip_ranges_iter_init.txt index 4c871c8e9b..d154ac2b64 100644 --- a/docs/man/nutscan_ip_ranges_iter_init.txt +++ b/docs/man/nutscan_ip_ranges_iter_init.txt @@ -10,11 +10,13 @@ a `nutscan_ip_range_list_iter_t` structure. SYNOPSIS -------- - #include +------ + #include - char * nutscan_ip_ranges_iter_init( - nutscan_ip_range_list_iter_t *irliter, - const nutscan_ip_range_list_t *irl); + char * nutscan_ip_ranges_iter_init( + nutscan_ip_range_list_iter_t *irliter, + const nutscan_ip_range_list_t *irl); +------ DESCRIPTION ----------- @@ -34,6 +36,7 @@ This function skips work if: Returns the first IP address from the first registered IP address range. Subsequent addresses can be returned by `nutscan_ip_ranges_iter_inc()`. +The caller SHOULD NOT free this string while iterating. NOTES ----- diff --git a/docs/man/nutscan_new_device.txt b/docs/man/nutscan_new_device.txt index 43581599ec..e6c86fbf2e 100644 --- a/docs/man/nutscan_new_device.txt +++ b/docs/man/nutscan_new_device.txt @@ -9,9 +9,11 @@ nutscan_new_device - Create a new nutscan_device_t structure. SYNOPSIS -------- - #include +------ + #include - nutscan_device_t * nutscan_new_device(void); + nutscan_device_t * nutscan_new_device(void); +------ DESCRIPTION ----------- diff --git a/docs/man/nutscan_scan_avahi.txt b/docs/man/nutscan_scan_avahi.txt index 5c407d3d7b..1d50ef83e9 100644 --- a/docs/man/nutscan_scan_avahi.txt +++ b/docs/man/nutscan_scan_avahi.txt @@ -9,10 +9,12 @@ nutscan_scan_avahi - Scan network for NUT services via mDNS SYNOPSIS -------- - #include - #include /* useconds_t */ +------ + #include + #include /* useconds_t */ - nutscan_device_t * nutscan_scan_avahi(useconds_t usec_timeout); + nutscan_device_t * nutscan_scan_avahi(useconds_t usec_timeout); +------ DESCRIPTION ----------- diff --git a/docs/man/nutscan_scan_eaton_serial.txt b/docs/man/nutscan_scan_eaton_serial.txt index 42e2a826ec..be97566458 100644 --- a/docs/man/nutscan_scan_eaton_serial.txt +++ b/docs/man/nutscan_scan_eaton_serial.txt @@ -10,19 +10,21 @@ and Q1). SYNOPSIS -------- - #include +------ + #include - nutscan_device_t * nutscan_scan_eaton_serial(const char* ports_list); + nutscan_device_t * nutscan_scan_eaton_serial(const char* ports_list); +------ DESCRIPTION ----------- The *nutscan_scan_eaton_serial()* function tries to detect NUT devices which are compatible with Eaton's serial device protocols (SHUT, XCP -and Q1 (aka blazer)). +and Q1 (aka blazer or megatec)). -'ports_list' is a NULL terminated array of pointers to strings containing -serial device name (/dev/ttyS0, COM1, /dev/ttya...) +'ports_list' is a NULL-terminated array of pointers to strings containing +serial device name (`/dev/ttyS0`, `COM1`, `/dev/ttya`...) You MUST call linkman:nutscan_init[3] before using this function. diff --git a/docs/man/nutscan_scan_ipmi.txt b/docs/man/nutscan_scan_ipmi.txt index 9d43210f68..93f08f760c 100644 --- a/docs/man/nutscan_scan_ipmi.txt +++ b/docs/man/nutscan_scan_ipmi.txt @@ -9,16 +9,18 @@ nutscan_scan_ipmi - Scan local IPMI devices. SYNOPSIS -------- - #include +------ + #include - nutscan_device_t * nutscan_scan_ipmi( - const char * startIP, - const char * stopIP, - nutscan_ipmi_t * sec); + nutscan_device_t * nutscan_scan_ipmi( + const char * startIP, + const char * stopIP, + nutscan_ipmi_t * sec); - nutscan_device_t * nutscan_scan_ip_range_ipmi( - nutscan_ip_range_list_t * irl, - nutscan_ipmi_t * sec); + nutscan_device_t * nutscan_scan_ip_range_ipmi( + nutscan_ip_range_list_t * irl, + nutscan_ipmi_t * sec); +------ DESCRIPTION ----------- @@ -31,9 +33,13 @@ respective function searches for a local PSU. Otherwise, it searches for remote hosts that would serve IPMI protocols, and would try to authenticate using the data in 'sec' structure. + The former issues an IPMI request on every IP ranging from 'startIP' to -'stopIP', where 'stopIP' is optional; the latter can walk several IP -address ranges represented by a `nutscan_ip_range_list_t` structure. +'stopIP', where 'startIP' is mandatory and 'stopIP' is optional (one +'startIP' address is scanned if 'stopIP' is NULL); while the latter can +walk several IP address ranges represented by a `nutscan_ip_range_list_t` +structure. + Those IP arguments may be either IPv4 or IPv6 addresses or host names. You MUST call linkman:nutscan_init[3] before using this function. diff --git a/docs/man/nutscan_scan_nut.txt b/docs/man/nutscan_scan_nut.txt index 1263a6be23..88e11735ca 100644 --- a/docs/man/nutscan_scan_nut.txt +++ b/docs/man/nutscan_scan_nut.txt @@ -9,19 +9,21 @@ nutscan_scan_nut - Scan network for available NUT services. SYNOPSIS -------- - #include - #include /* useconds_t */ +------ + #include + #include /* useconds_t */ - nutscan_device_t * nutscan_scan_nut( - const char * startIP, - const char * stopIP, - const char * port, - useconds_t usec_timeout); + nutscan_device_t * nutscan_scan_nut( + const char * startIP, + const char * stopIP, + const char * port, + useconds_t usec_timeout); - nutscan_device_t * nutscan_scan_ip_range_nut( - nutscan_ip_range_list_t * irl, - const char * port, - useconds_t usec_timeout); + nutscan_device_t * nutscan_scan_ip_range_nut( + nutscan_ip_range_list_t * irl, + const char * port, + useconds_t usec_timeout); +------ DESCRIPTION ----------- @@ -29,10 +31,12 @@ DESCRIPTION The *nutscan_scan_nut()* and *nutscan_scan_ip_range_nut()* functions try to detect available NUT services and their associated devices. The former issues a NUT request on every IP ranging from 'startIP' -to 'stopIP' (where 'startIP' is mandatory, 'stopIP' is optional); +to 'stopIP', where 'startIP' is mandatory and 'stopIP' is optional +(one 'startIP' address is scanned if 'stopIP' is NULL); while the latter can walk several IP address ranges represented by a -`nutscan_ip_range_list_t` structure. Those IP arguments may be -either IPv4 or IPv6 addresses or host names. +`nutscan_ip_range_list_t` structure. + +Those IP arguments may be either IPv4 or IPv6 addresses or host names. You MUST call linkman:nutscan_init[3] before using this function. diff --git a/docs/man/nutscan_scan_nut_simulation.txt b/docs/man/nutscan_scan_nut_simulation.txt index 8e7ba1999c..10c5faec5b 100644 --- a/docs/man/nutscan_scan_nut_simulation.txt +++ b/docs/man/nutscan_scan_nut_simulation.txt @@ -9,20 +9,29 @@ nutscan_scan_nut_simulation - Scan your sysconfig directory for NUT simulation d SYNOPSIS -------- - #include - #include /* useconds_t */ +------ + #include + #include /* useconds_t */ - nutscan_device_t * nutscan_scan_nut_simulation(); + nutscan_device_t * nutscan_scan_nut_simulation(); +------ DESCRIPTION ----------- -The *nutscan_scan_nut_simulation()* function try to detect available NUT -simulation devices, by finding .dev and .seq files in your sysconfig +The *nutscan_scan_nut_simulation()* function tries to detect available NUT +simulation devices, by finding `*.dev` and `*.seq` files in your "sysconfig" directory. You MUST call linkman:nutscan_init[3] before using this function. +BUGS +---- + +This function currently uses the built-in location of the "sysconfig" +directory, and does not consider an override with `NUT_CONFPATH` environment +variable accepted by most of the NUT code base. + RETURN VALUE ------------ @@ -36,7 +45,7 @@ SEE ALSO linkman:nutscan_init[3], linkman:nutscan_scan_usb[3], linkman:nutscan_scan_xml_http_range[3], linkman:nutscan_scan_snmp[3], linkman:nutscan_scan_avahi[3], -linkman:nutscan_scan_ipmi[3], linkman:nutscan_scan_nut[3], +linkman:nutscan_scan_ipmi[3], linkman:nutscan_scan_nut[3], linkman:nutscan_display_sanity_check[3], linkman:nutscan_display_sanity_check_serial[3], linkman:nutscan_display_ups_conf_with_sanity_check[3], diff --git a/docs/man/nutscan_scan_snmp.txt b/docs/man/nutscan_scan_snmp.txt index f89aebdde1..8fb183a5ed 100644 --- a/docs/man/nutscan_scan_snmp.txt +++ b/docs/man/nutscan_scan_snmp.txt @@ -9,29 +9,33 @@ nutscan_scan_snmp - Scan network for SNMP devices. SYNOPSIS -------- - #include - #include /* useconds_t */ - - nutscan_device_t * nutscan_scan_snmp( - const char * start_ip, - const char * stop_ip, - useconds_t timeout, - nutscan_snmp_t * sec); - - nutscan_device_t * nutscan_scan_ip_range_snmp( - nutscan_ip_range_list_t * irl, - useconds_t usec_timeout, - nutscan_snmp_t * sec); +------ + #include + #include /* useconds_t */ + + nutscan_device_t * nutscan_scan_snmp( + const char * start_ip, + const char * stop_ip, + useconds_t timeout, + nutscan_snmp_t * sec); + + nutscan_device_t * nutscan_scan_ip_range_snmp( + nutscan_ip_range_list_t * irl, + useconds_t usec_timeout, + nutscan_snmp_t * sec); +------ DESCRIPTION ----------- The *nutscan_scan_snmp()* and *nutscan_scan_ip_range_snmp()* functions try to detect NUT compatible SNMP devices. The former tries SNMP queries -on every IP ranging from 'start_ip' to 'stop_ip'; the latter can walk -several IP address ranges represented by a `nutscan_ip_range_list_t` -structure. Those IP arguments may be either IPv4 or IPv6 addresses or -host names. +on every IP ranging from 'start_ip' to 'stop_ip', where 'startIP' is +mandatory and 'stopIP' is optional (one 'startIP' address is scanned +if 'stopIP' is NULL); while the latter can walk several IP address +ranges represented by a `nutscan_ip_range_list_t` structure. + +Those IP arguments may be either IPv4 or IPv6 addresses or host names. You MUST call linkman:nutscan_init[3] before using this function. diff --git a/docs/man/nutscan_scan_usb.txt b/docs/man/nutscan_scan_usb.txt index f9632bdd00..bc74e52bfa 100644 --- a/docs/man/nutscan_scan_usb.txt +++ b/docs/man/nutscan_scan_usb.txt @@ -9,19 +9,21 @@ nutscan_scan_usb - Scan NUT compatible USB devices. SYNOPSIS -------- - #include +------ + #include - nutscan_device_t * nutscan_scan_usb(nutscan_usb_t * scanopts); - -NOTE ----- + nutscan_device_t * nutscan_scan_usb(nutscan_usb_t * scanopts); +------ +[NOTE] +====== Before `libnutscan` version 2.5.0 there was no argument: nutscan_device_t * nutscan_scan_usb(void); After the API update to have an argument, equivalent default activity can be achieved by passing `NULL` value for the argument. +====== DESCRIPTION ----------- diff --git a/docs/man/nutscan_scan_xml_http_range.txt b/docs/man/nutscan_scan_xml_http_range.txt index 1c9b667c81..75ea3caca6 100644 --- a/docs/man/nutscan_scan_xml_http_range.txt +++ b/docs/man/nutscan_scan_xml_http_range.txt @@ -9,19 +9,21 @@ nutscan_scan_xml_http_range - Scan network for XML/HTTP devices. SYNOPSIS -------- - #include - #include /* useconds_t */ - - nutscan_device_t * nutscan_scan_xml_http_range( - const char * start_ip, - const char * end_ip, - useconds_t usec_timeout, - nutscan_xml_t * sec) - - nutscan_device_t * nutscan_scan_ip_range_xml_http( - nutscan_ip_range_list_t * irl, - useconds_t usec_timeout, - nutscan_xml_t * sec) +------ + #include + #include /* useconds_t */ + + nutscan_device_t * nutscan_scan_xml_http_range( + const char * start_ip, + const char * end_ip, + useconds_t usec_timeout, + nutscan_xml_t * sec) + + nutscan_device_t * nutscan_scan_ip_range_xml_http( + nutscan_ip_range_list_t * irl, + useconds_t usec_timeout, + nutscan_xml_t * sec) +------ DESCRIPTION ----------- @@ -34,8 +36,10 @@ respective function does this by issuing a broadcast message on all currently configured network interfaces. Otherwise, the former queries every IP ranging from 'start_ip' to 'stop_ip', -where 'stopIP' is optional; the latter can walk several IP address ranges -represented by a `nutscan_ip_range_list_t` structure. +, where 'startIP' is mandatory and 'stopIP' is optional (one 'startIP' address +is scanned if 'stopIP' is NULL); while the latter can walk several IP address +ranges represented by a `nutscan_ip_range_list_t` structure. + Those IP arguments may be either IPv4 or IPv6 addresses or host names. It waits up to 'usec_timeout' microseconds for a response from potential diff --git a/docs/man/nutscan_stringify_ip_ranges.txt b/docs/man/nutscan_stringify_ip_ranges.txt index cc14793f10..e6fd49ba87 100644 --- a/docs/man/nutscan_stringify_ip_ranges.txt +++ b/docs/man/nutscan_stringify_ip_ranges.txt @@ -10,9 +10,11 @@ structure into a string buffer that can be further printed into logs. SYNOPSIS -------- - #include +------ + #include - const char * nutscan_stringify_ip_ranges(nutscan_ip_range_list_t *irl); + const char * nutscan_stringify_ip_ranges(nutscan_ip_range_list_t *irl); +------ DESCRIPTION ----------- @@ -25,6 +27,8 @@ or a range as `start_ip .. end_ip`. Returns a pointer to internal statically allocated buffer which would be overwritten by subsequent calls, but does not have to be freed by caller. +WARNING: Callers should use semaphores if accessing this function in multi-thread context! + NOTES ----- diff --git a/docs/man/upscli_add_host_cert.txt b/docs/man/upscli_add_host_cert.txt index 6d9050d3c1..10192b6688 100644 --- a/docs/man/upscli_add_host_cert.txt +++ b/docs/man/upscli_add_host_cert.txt @@ -9,18 +9,23 @@ upscli_add_host_cert - Register a security rule for an host. SYNOPSIS -------- - #include +------ + #include - void upscli_add_host_cert(const char* hostname, const char* certname, - int certverify, int forcessl); + void upscli_add_host_cert( + const char* hostname, + const char* certname, + int certverify, + int forcessl); +------ DESCRIPTION ----------- -The *upscli_add_host_cert()* function register a security rule associated +The *upscli_add_host_cert()* function registers a security rule associated to the 'hostname'. All connections to this host use this rule. -The rule is composed of the certificate name 'certname 'expected for +The rule is composed of the certificate name 'certname' expected for the host, 'certverify' if the certificate must be validated for the host and 'forcessl' if a secured connection must be used to connect to the host. diff --git a/docs/man/upscli_cleanup.txt b/docs/man/upscli_cleanup.txt index 60431ec30c..254f572216 100644 --- a/docs/man/upscli_cleanup.txt +++ b/docs/man/upscli_cleanup.txt @@ -9,9 +9,11 @@ upscli_cleanup - Clean-up upsclient module after usage. SYNOPSIS -------- - #include +------ + #include - int upscli_cleanup(void); + int upscli_cleanup(void); +------ DESCRIPTION ----------- @@ -22,7 +24,7 @@ used internally in upsclient module. RETURN VALUE ------------ -The *upscli_cleanup()* function returns 1 on success, or -1 if an error +The *upscli_cleanup()* function returns '1' on success, or '-1' if an error occurs. SEE ALSO diff --git a/docs/man/upscli_connect.txt b/docs/man/upscli_connect.txt index c2e3ddef27..7e9fe0d21e 100644 --- a/docs/man/upscli_connect.txt +++ b/docs/man/upscli_connect.txt @@ -4,14 +4,16 @@ UPSCLI_CONNECT(3) NAME ---- -upscli_connect - Open a connection to a NUT upsd +upscli_connect - Open a connection to a NUT upsd data server SYNOPSIS -------- - #include +------ + #include - int upscli_connect(UPSCONN_t *ups, const char *host, uint16_t port, int flags); + int upscli_connect(UPSCONN_t *ups, const char *host, uint16_t port, int flags); +------ DESCRIPTION ----------- @@ -42,7 +44,7 @@ RETURN VALUE ------------ The *upscli_connect()* function modifies the `UPSCONN_t` structure and -returns 0 on success, or -1 if an error occurs. +returns '0' on success, or '-1' if an error occurs. SEE ALSO -------- diff --git a/docs/man/upscli_disconnect.txt b/docs/man/upscli_disconnect.txt index 76a8e61100..bbd3c732d8 100644 --- a/docs/man/upscli_disconnect.txt +++ b/docs/man/upscli_disconnect.txt @@ -4,14 +4,16 @@ UPSCLI_DISCONNECT(3) NAME ---- -upscli_disconnect - disconnect from a UPS server +upscli_disconnect - Disconnect from a UPS server SYNOPSIS -------- - #include +------ + #include - int upscli_disconnect(UPSCONN_t *ups); + int upscli_disconnect(UPSCONN_t *ups); +------ DESCRIPTION ----------- @@ -28,7 +30,7 @@ file descriptors. RETURN VALUE ------------ -The *upscli_disconnect()* function returns 0 on success, or -1 if an +The *upscli_disconnect()* function returns '0' on success, or '-1' if an error occurs. SEE ALSO diff --git a/docs/man/upscli_fd.txt b/docs/man/upscli_fd.txt index 1fd2971c08..961ca2ed71 100644 --- a/docs/man/upscli_fd.txt +++ b/docs/man/upscli_fd.txt @@ -9,9 +9,11 @@ upscli_fd - Get file descriptor for connection SYNOPSIS -------- - #include +------ + #include - int upscli_fd(UPSCONN_t *ups); + int upscli_fd(UPSCONN_t *ups); +------ DESCRIPTION ----------- @@ -29,7 +31,7 @@ RETURN VALUE The *upscli_fd()* function returns the file descriptor, which may be any non-negative number. -It returns -1 if an error occurs. +It returns '-1' if an error occurs. SEE ALSO -------- diff --git a/docs/man/upscli_get.txt b/docs/man/upscli_get.txt index 0d524fe9ba..1911676475 100644 --- a/docs/man/upscli_get.txt +++ b/docs/man/upscli_get.txt @@ -4,15 +4,21 @@ UPSCLI_GET(3) NAME ---- -upscli_get - retrieve data from an UPS +upscli_get - Retrieve data from an UPS SYNOPSIS -------- - #include - - int upscli_get(UPSCONN_t *ups, size_t numq, const char **query, - size_t *numa, char ***answer) +------ + #include + + int upscli_get( + UPSCONN_t *ups, + size_t numq, + const char **query, + size_t *numa, + char ***answer) +------ DESCRIPTION ----------- @@ -29,7 +35,7 @@ The number of usable answer components will be returned in 'numa'. USES ---- -This function implements the "GET" command in the protocol. +This function implements the "GET" command in the NUT protocol. As a result, you can use it to request many different things from the server. @@ -82,10 +88,12 @@ ERROR CHECKING -------------- This function will check your query against the response from -linkman:upsd[8]. For example, if you send "VAR" "su700" "ups.status", +linkman:upsd[8] data server. + +For example, if you send `"VAR"` `"su700"` `"ups.status"`, it will expect to see those at the beginning of the response. -If the results from *upsd* do not pass this case-insensitive test +If the results from `upsd` do not pass this case-insensitive test against your request, this function will return an error. When this happens, linkman:upscli_upserror[3] will return 'UPSCLI_ERR_PROTOCOL'. @@ -93,7 +101,7 @@ ANSWER ARRAY LIFETIME --------------------- The pointers contained within the 'answer' array are only valid -until the next call to a 'upsclient' function which references them. +until the next call to an 'upsclient' function which references them. If you need to use data from multiple calls, you must copy it somewhere else first. @@ -109,7 +117,7 @@ Any access after that point is also undefined. RETURN VALUE ------------ -The *upscli_get()* function returns 0 on success, or -1 if an +The *upscli_get()* function returns '0' on success, or '-1' if an error occurs. If *upsd* disconnects, you may need to handle or ignore `SIGPIPE` @@ -119,10 +127,12 @@ the library writes to the disconnected socket. The following code in your initialization function will allow the *upscli_get()* call to return an error in that case: - #include - ... - signal (SIGPIPE, SIG_IGN); - ... +------ + #include + ... + signal (SIGPIPE, SIG_IGN); + ... +------ SEE ALSO -------- diff --git a/docs/man/upscli_init.txt b/docs/man/upscli_init.txt index e9b17404d4..7146845627 100644 --- a/docs/man/upscli_init.txt +++ b/docs/man/upscli_init.txt @@ -9,37 +9,44 @@ upscli_init - Initialize upsclient module specifying security properties. SYNOPSIS -------- - #include +------ + #include - int upscli_init(int certverify, const char *certpath, - const char *certname, const char *certpasswd); + int upscli_init( + int certverify, + const char *certpath, + const char *certname, + const char *certpasswd); +------ DESCRIPTION ----------- -The *upscli_init()* function initialize upsclient module and set many +The *upscli_init()* function initializes upsclient module and sets many TLS/SSL-related properties: 'certverify' to 1 makes certificate verification required for all SSL connections and 'certpath' is the location of certificate database. -If compiled with OpenSSL, certpath refers to directory containing -certificates where the certificates must be named according to their -hash values ending in a ".0" extension. If two certificates result in -the same hash value (thus file name), the ".0" can be incremented to ".1" -and so on, as needed. The bash command for creating links in this manner -would be: - - ln -s ca.pem ./$(openssl x509 -hash -noout -in ca.pem).0 - -Alternatively, the c_rehash utility (provided by openssl-perl) can take a -directory and iterate it to link all certificates found in that directory, -in the manner described above. +* If compiled with OpenSSL, 'certpath' refers to directory containing + certificates where the certificates must be named according to their + hash values ending in a ".0" extension. If two certificates result in + the same hash value (thus file name), the ".0" can be incremented to ".1" + and so on, as needed. The shell command for creating links in this manner + would be: ++ +---- +:; ln -s ca.pem ./$(openssl x509 -hash -noout -in ca.pem).0 +---- ++ +Alternatively, the `c_rehash` utility (provided by e.g. `openssl-perl` + package) can take a directory and iterate it to link all certificates + found in that directory, in the manner described above. -If compiled with NSS, certpath refers to a directory containing database -files. +* If compiled with NSS, 'certpath' refers to a directory containing its + database files. -If compiled with NSS and using SSL, you can specify 'certname' the name -of the certificate to send to upsd and 'certpasswd' the password used +If compiled with NSS and using SSL, you can specify 'certname' with the name +of the certificate to send to `upsd`, and 'certpasswd' with the password used to decrypt certificate private key. If compiled with NSS, it would normally log either the infamous message @@ -48,8 +55,8 @@ or "Init SSL with certificate database located at %s" otherwise. Since some programmatic consumers become confused by such extra text on the `stderr` of tools they call (such as monitoring systems doing `upsc` queries), you can export an environment variable `NUT_QUIET_INIT_SSL` -with string values "true", "TRUE" or "1", to avoid logging these messages -and just emit them as debug stream (at verbosity 1 or higher). +with string values `"true"`, `"TRUE"` or `"1"`, to avoid logging these +messages and just emit them as debug stream (at verbosity 1 or higher). You can call linkman:upscli_add_host_cert[3] to register specific host security policy before initialize connections to them. @@ -59,7 +66,8 @@ You must call linkman:upscli_cleanup[3] when exiting application. RETURN VALUE ------------ -The *upscli_init()* function returns 1 on success, or -1 if an error occurs. +The *upscli_init()* function returns '1' on success, or '-1' if an error +occurs. SEE ALSO -------- diff --git a/docs/man/upscli_list_next.txt b/docs/man/upscli_list_next.txt index 9612136cde..a5eb3b8d34 100644 --- a/docs/man/upscli_list_next.txt +++ b/docs/man/upscli_list_next.txt @@ -4,15 +4,21 @@ UPSCLI_LIST_NEXT(3) NAME ---- -upscli_list_next - retrieve list items from a UPS +upscli_list_next - Retrieve list items from a UPS SYNOPSIS -------- - #include +------ + #include - int upscli_list_next(UPSCONN_t *ups, size_t numq, const char **query, - size_t *numa, char ***answer) + int upscli_list_next( + UPSCONN_t *ups, + size_t numq, + const char **query, + size_t *numa, + char ***answer) +------ DESCRIPTION ----------- @@ -24,12 +30,12 @@ expects to find either another list item or the end of a list. You must call linkman:upscli_list_start[3] before calling this function. -This function will return 1 and set values in 'numa' and +This function will return '1' and set values in 'numa' and 'answer' if a list item is received. If the list is done, it will -return 0, and the values in 'numa' and 'answer' are undefined. +return '0', and the values in 'numa' and 'answer' are undefined. -Calling this function after it returns something other than 1 is -undefined. +Calling this function after it returns something other than '1' is +undefined behavior. QUERY FORMATTING ---------------- @@ -58,10 +64,10 @@ When this happens, linkman:upscli_upserror[3] will return RETURN VALUE ------------ -The *upscli_list_next()* function returns 1 when list data is -present, 0 if the list is finished, or -1 if an error occurs. +The *upscli_list_next()* function returns '1' when list data is +present, '0' if the list is finished, or '-1' if an error occurs. -It is possible to have an empty list. The function will return 0 for +It is possible to have an empty list. The function will return '0' for its first call in that case. SEE ALSO diff --git a/docs/man/upscli_list_start.txt b/docs/man/upscli_list_start.txt index c564c36e0e..b18f32fbc0 100644 --- a/docs/man/upscli_list_start.txt +++ b/docs/man/upscli_list_start.txt @@ -4,14 +4,16 @@ UPSCLI_LIST_START(3) NAME ---- -upscli_list_start - begin multi-item retrieval from a UPS +upscli_list_start - Begin multi-item retrieval from a UPS SYNOPSIS -------- - #include +------ + #include - int upscli_list_start(UPSCONN_t *ups, size_t numq, const char **query) + int upscli_list_start(UPSCONN_t *ups, size_t numq, const char **query) +------ DESCRIPTION ----------- @@ -72,7 +74,7 @@ When this happens, linkman:upscli_upserror[3] will return RETURN VALUE ------------ -The *upscli_list_start()* function returns 0 on success, or -1 if an +The *upscli_list_start()* function returns '0' on success, or '-1' if an error occurs. SEE ALSO diff --git a/docs/man/upscli_readline.txt b/docs/man/upscli_readline.txt index 120ad21b78..f6cf5b4398 100644 --- a/docs/man/upscli_readline.txt +++ b/docs/man/upscli_readline.txt @@ -4,18 +4,20 @@ UPSCLI_READLINE(3) NAME ---- -upscli_readline, upscli_readline_timeout - read a single response from a UPS +upscli_readline, upscli_readline_timeout - Read a single response from a UPS SYNOPSIS -------- - #include - #include /* or on some platforms */ +------ + #include + #include /* or on some platforms */ - int upscli_readline(UPSCONN_t *ups, char *buf, size_t buflen); + int upscli_readline(UPSCONN_t *ups, char *buf, size_t buflen); - int upscli_readline_timeout(UPSCONN_t *ups, char *buf, size_t buflen, - const time_t timeout); + int upscli_readline_timeout(UPSCONN_t *ups, char *buf, size_t buflen, + const time_t timeout); +------ DESCRIPTION ----------- @@ -27,7 +29,7 @@ into the buffer 'buf'. Some parsing of the string occurs during reception. In particular, ERR messages from linkman:upsd[8] are detected and will cause this -function to return -1. +function to return '-1'. The difference between the two functions is that *upscli_readline_timeout()* lets the caller decide the amount of time ('timeout' seconds) after which it @@ -38,7 +40,7 @@ RETURN VALUE ------------ The *upscli_readline()* and *upscli_readline_timeout()* functions -return 0 on success, or -1 if an error occurs. +return '0' on success, or '-1' if an error occurs. SEE ALSO -------- diff --git a/docs/man/upscli_sendline.txt b/docs/man/upscli_sendline.txt index 895f0baed0..f2f70f0034 100644 --- a/docs/man/upscli_sendline.txt +++ b/docs/man/upscli_sendline.txt @@ -4,18 +4,20 @@ UPSCLI_SENDLINE(3) NAME ---- -upscli_sendline, upscli_sendline_timeout - send a single command to a UPS +upscli_sendline, upscli_sendline_timeout - Send a single command to a UPS SYNOPSIS -------- - #include - #include /* or on some platforms */ +------ + #include + #include /* or on some platforms */ - int upscli_sendline(UPSCONN_t *ups, const char *buf, size_t buflen); + int upscli_sendline(UPSCONN_t *ups, const char *buf, size_t buflen); - int upscli_sendline_timeout(UPSCONN_t *ups, const char *buf, size_t buflen, - const time_t timeout); + int upscli_sendline_timeout(UPSCONN_t *ups, const char *buf, size_t buflen, + const time_t timeout); +------ DESCRIPTION ----------- @@ -36,7 +38,7 @@ RETURN VALUE ------------ The *upscli_sendline()* and *upscli_sendline_timeout()* functions -return 0 on success, or -1 if an error occurs. +return '0' on success, or '-1' if an error occurs. SEE ALSO -------- diff --git a/docs/man/upscli_splitaddr.txt b/docs/man/upscli_splitaddr.txt index a3f2c34aa0..ea923dcccc 100644 --- a/docs/man/upscli_splitaddr.txt +++ b/docs/man/upscli_splitaddr.txt @@ -4,15 +4,17 @@ UPSCLI_SPLITADDR(3) NAME ---- -upscli_splitaddr - split a listening address into its components +upscli_splitaddr - Split a listening address into its components SYNOPSIS -------- - #include +------ + #include - int upscli_splitaddr(const char *buf, char **hostname, - int *port) + int upscli_splitaddr(const char *buf, char **hostname, + int *port) +------ DESCRIPTION ----------- @@ -29,18 +31,18 @@ A listening address definition is specified according to this format: [:] Definitions without an explicit port value receive the default value of -3493. +'3493'. MEMORY USAGE ------------ -You must *free*(3) the pointer 'hostname' when you are done +You must linkman:free[3] the pointer 'hostname' when you are done with it to avoid memory leaks. RETURN VALUE ------------ -The *upscli_splitaddr()* function returns 0 on success, or -1 if an +The *upscli_splitaddr()* function returns '0' on success, or '-1' if an error occurs. SEE ALSO diff --git a/docs/man/upscli_splitname.txt b/docs/man/upscli_splitname.txt index d40e642982..89646bbd09 100644 --- a/docs/man/upscli_splitname.txt +++ b/docs/man/upscli_splitname.txt @@ -4,15 +4,17 @@ UPSCLI_SPLITNAME(3) NAME ---- -upscli_splitname - split a UPS definition into its components +upscli_splitname - Split a UPS definition into its components SYNOPSIS -------- - #include +------ + #include - int upscli_splitname(const char *buf, char **upsname, - char **hostname, int *port) + int upscli_splitname(const char *buf, char **upsname, + char **hostname, int *port) +------ DESCRIPTION ----------- @@ -25,26 +27,26 @@ number into 'port'. FORMATTING ---------- -A UPS definition is specified according to this format: +An UPS definition is specified according to this format: [@[:]] When the UPS name is not given, this function will print an error to -stderr and return -1 without changing anything. +`stderr` and return '-1' without changing anything. Definitions without an explicit port value receive the default value of -3493. The default hostname is "localhost". +'3493'. The default hostname is "localhost". MEMORY USAGE ------------ -You must *free*(3) the pointers to 'upsname' and 'hostname' +You must linkman:free[3] the pointers to 'upsname' and 'hostname' when you are done with them to avoid memory leaks. RETURN VALUE ------------ -The *upscli_splitname()* function returns 0 on success, or -1 if an +The *upscli_splitname()* function returns '0' on success, or '-1' if an error occurs. SEE ALSO diff --git a/docs/man/upscli_ssl.txt b/docs/man/upscli_ssl.txt index 1b1620e657..6113de4cc4 100644 --- a/docs/man/upscli_ssl.txt +++ b/docs/man/upscli_ssl.txt @@ -9,24 +9,25 @@ upscli_ssl - Check SSL mode for current connection SYNOPSIS -------- - #include +------ + #include - int upscli_ssl(UPSCONN_t *ups); + int upscli_ssl(UPSCONN_t *ups); +------ DESCRIPTION ----------- The *upscli_ssl*() function takes the pointer 'ups' to a -`UPSCONN_t` state structure. It only returns 1 if SSL support has been +`UPSCONN_t` state structure. It only returns '1' if SSL support has been compiled into the linkman:upsclient[3] library, and if it was successfully enabled for this connection. - RETURN VALUE ------------ -The *upscli_ssl*() function returns 1 if SSL is running, and 0 if -not. It returns -1 in the event of an error. +The *upscli_ssl*() function returns '1' if SSL is running, and '0' if +not. It returns '-1' in the event of an error. SEE ALSO -------- diff --git a/docs/man/upscli_strerror.txt b/docs/man/upscli_strerror.txt index b9b8462a1f..f4ec42ef10 100644 --- a/docs/man/upscli_strerror.txt +++ b/docs/man/upscli_strerror.txt @@ -4,14 +4,16 @@ UPSCLI_STRERROR(3) NAME ---- -upscli_strerror - return string describing error condition +upscli_strerror - Return a string describing error condition SYNOPSIS -------- - #include +------ + #include - const char *upscli_strerror(UPSCONN_t *ups); + const char *upscli_strerror(UPSCONN_t *ups); +------ DESCRIPTION ----------- @@ -25,7 +27,7 @@ RETURN VALUE ------------ The *upscli_strerror*() function returns a description of the error, -or an unknown error message if the error code is not recognized. +or an "unknown error" message if the error code is not recognized. SEE ALSO -------- diff --git a/docs/man/upscli_upserror.txt b/docs/man/upscli_upserror.txt index c4b5ac363b..27716bc8c6 100644 --- a/docs/man/upscli_upserror.txt +++ b/docs/man/upscli_upserror.txt @@ -9,9 +9,11 @@ upscli_upserror - Get current error number for connection SYNOPSIS -------- - #include +------ + #include - int upscli_upserror(UPSCONN_t *ups); + int upscli_upserror(UPSCONN_t *ups); +------ DESCRIPTION ----------- @@ -31,7 +33,7 @@ RETURN VALUE ------------ The *upscli_upserror*() function returns one of the `UPSCLI_ERR_*` -values from `upsclient.h`, or 0 if no error has occurred. +values from `upsclient.h`, or '0' if no error has occurred. SEE ALSO -------- diff --git a/docs/man/upsclient.txt b/docs/man/upsclient.txt index 2f78415c84..5e05f818b4 100644 --- a/docs/man/upsclient.txt +++ b/docs/man/upsclient.txt @@ -10,9 +10,9 @@ DESCRIPTION ----------- The Network UPS Tools (NUT) *upsclient* library provides a number of -useful functions for programs to use when communicating with +useful functions for client programs to use when communicating with linkman:upsd[8]. Many of the low-level socket and protocol details are -handled automatically when using this interface. +handled automatically when using this interface, also known as "upscli" API. State is maintained across calls in an opaque structure called `UPSCONN_t`. Callers are expected to create one per connection. These will be @@ -27,8 +27,8 @@ Before creating any connection, and in general using any upscli function, you must call linkman:upscli_init[3] with proper parameters to initialize upscli module. -To register specific host security policy, you must call -linkman:upscli_add_host_cert[3] before initialize connection to it. +To register a specific host security policy, you must call +linkman:upscli_add_host_cert[3] before initializing a connection to it. In the same way, just before exiting, and after all upscli usage, you must call linkman:upscli_cleanup[3] to flush cache files and perform other cleanup. @@ -69,6 +69,7 @@ also be used to retrieve the error number. These numbers are defined in SEE ALSO -------- +linkman:nutclient[3], linkman:libupsclient-config[1], linkman:upscli_init[3], linkman:upscli_cleanup[3], linkman:upscli_add_host_cert[3], From 97c6fbb19bf0c4e4122db25823da935509a9acb3 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Wed, 5 Feb 2025 16:31:34 +0100 Subject: [PATCH 11/67] docs/man/index.txt: reference recent API and nutconf man pages Signed-off-by: Jim Klimov --- docs/man/index.txt | 38 +++++++++++++++++++++++++++----------- 1 file changed, 27 insertions(+), 11 deletions(-) diff --git a/docs/man/index.txt b/docs/man/index.txt index 9bc37ab8f7..c259b21ab8 100644 --- a/docs/man/index.txt +++ b/docs/man/index.txt @@ -37,6 +37,7 @@ Clients commands Configuration commands ~~~~~~~~~~~~~~~~~~~~~~ +- linkman:nutconf[8] - linkman:nut-scanner[8] CGI programs @@ -80,10 +81,13 @@ Client library - linkman:libnutclient_variables[3] - linkman:upsclient[3] +- linkman:upscli_add_host_cert[3] +- linkman:upscli_cleanup[3] - linkman:upscli_connect[3] - linkman:upscli_disconnect[3] - linkman:upscli_fd[3] - linkman:upscli_get[3] +- linkman:upscli_init[3] - linkman:upscli_list_next[3] - linkman:upscli_list_start[3] - linkman:upscli_readline[3] @@ -99,17 +103,29 @@ Device discovery library ~~~~~~~~~~~~~~~~~~~~~~~~ - linkman:nutscan[3] -- linkman:nutscan_scan_usb[3] -- linkman:nutscan_scan_snmp[3] -- linkman:nutscan_scan_xml_http_range[3] -- linkman:nutscan_scan_nut[3] -- linkman:nutscan_scan_avahi[3] -- linkman:nutscan_scan_ipmi[3] -- linkman:nutscan_scan_eaton_serial[3] -- linkman:nutscan_display_parsable[3] -- linkman:nutscan_display_ups_conf[3] -- linkman:nutscan_new_device[3] -- linkman:nutscan_free_device[3] - linkman:nutscan_add_device_to_device[3] +- linkman:nutscan_add_ip_range[3] - linkman:nutscan_add_option_to_device[3] - linkman:nutscan_cidr_to_ip[3] +- linkman:nutscan_display_parsable[3] +- linkman:nutscan_display_sanity_check[3] +- linkman:nutscan_display_sanity_check_serial[3] +- linkman:nutscan_display_ups_conf[3] +- linkman:nutscan_display_ups_conf_with_sanity_check[3] +- linkman:nutscan_free_device[3] +- linkman:nutscan_free_ip_ranges[3] +- linkman:nutscan_get_serial_ports_list[3] +- linkman:nutscan_init[3] +- linkman:nutscan_init_ip_ranges[3] +- linkman:nutscan_ip_ranges_iter_inc[3] +- linkman:nutscan_ip_ranges_iter_init[3] +- linkman:nutscan_new_device[3] +- linkman:nutscan_scan_avahi[3] +- linkman:nutscan_scan_eaton_serial[3] +- linkman:nutscan_scan_ipmi[3] +- linkman:nutscan_scan_nut[3] +- linkman:nutscan_scan_nut_simulation[3] +- linkman:nutscan_scan_snmp[3] +- linkman:nutscan_scan_usb[3] +- linkman:nutscan_scan_xml_http_range[3] +- linkman:nutscan_stringify_ip_ranges[3] From 2d3a4af429ba310537cbb428b48d2134e52b2ad5 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Wed, 5 Feb 2025 20:00:24 +0100 Subject: [PATCH 12/67] docs/man/metasys.txt: link to copy of the protocol in NUT website library Signed-off-by: Jim Klimov --- docs/man/metasys.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/man/metasys.txt b/docs/man/metasys.txt index 519c294700..0867c06796 100644 --- a/docs/man/metasys.txt +++ b/docs/man/metasys.txt @@ -23,7 +23,7 @@ SUPPORTED HARDWARE The *metasys* driver was written with the "Meta System UPS Protocol Rev.1.12" kindly supplied from Meta System. -The driver should support all the common features of the ups models: +The driver should support all the common features of the UPS models: - HF Line (/2) 1-8 boards - HF Millennium (810, 820) @@ -70,4 +70,5 @@ linkman:nutupsdrv[8] Internet resources: ~~~~~~~~~~~~~~~~~~~ -The NUT (Network UPS Tools) home page: https://www.networkupstools.org/ +* The NUT (Network UPS Tools) home page: https://www.networkupstools.org/ +* Meta System UPS protocol: https://networkupstools.org/ups-protocols.html#_legrand From 7ea286fbfc792760dab8ee6b429bf7f82ef851be Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Wed, 5 Feb 2025 20:22:28 +0100 Subject: [PATCH 13/67] docs/man/nut-recorder.txt: link to upslog as a similar program Signed-off-by: Jim Klimov --- docs/man/nut-recorder.txt | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/man/nut-recorder.txt b/docs/man/nut-recorder.txt index 2758844d6d..e809d77a4e 100644 --- a/docs/man/nut-recorder.txt +++ b/docs/man/nut-recorder.txt @@ -74,6 +74,11 @@ The dummy-ups driver: linkman:dummy-ups[8] +The logging daemon: +~~~~~~~~~~~~~~~~~~~ + +linkman:upslog[8] + Internet resources: ~~~~~~~~~~~~~~~~~~~ From 4a3f899eae55e1146a0642b95f98eafed85bbb8f Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Wed, 5 Feb 2025 20:28:14 +0100 Subject: [PATCH 14/67] docs/man/nut-scanner.txt: fix "-U..." table markup Signed-off-by: Jim Klimov --- docs/man/nut-scanner.txt | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/docs/man/nut-scanner.txt b/docs/man/nut-scanner.txt index 075589c152..ad70efa9f5 100644 --- a/docs/man/nut-scanner.txt +++ b/docs/man/nut-scanner.txt @@ -64,10 +64,15 @@ This option can be specified several times, for more hardware link-specific details; these can be counter-productive in case of USB enumeration changes over time: + -| `-U` | do not report any bus/device/busport details | -| `-UU` | report bus and busport, if available | -| `-UUU` | report bus/device/busport details | -| `-UUUU` | report bus/device/busport details, and bcdDevice (limited use and benefit) | +[options="header",cols="1,3a"] +|=========================================================================== +| Option count | Practical meaning +| `-U` | do not report any `bus`/`device`/`busport` details +| `-UU` | report `bus` and `busport`, if available +| `-UUU` | report `bus`/`device`/`busport` details +| `-UUUU` | report `bus`/`device`/`busport` details, + and `bcdDevice` (limited use and benefit) +|=========================================================================== + NOTE: For reliability, it is preferable to match just by vendor and product identification, and a serial number if available and unique. From b7884937c34a5b1052f3b26f7584466ddf6f7ba5 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Wed, 5 Feb 2025 20:38:25 +0100 Subject: [PATCH 15/67] docs/man/nut-scanner.txt: fix NETWORK OPTIONS "NOTE" block markup Signed-off-by: Jim Klimov --- docs/man/nut-scanner.txt | 40 +++++++++++++++++++++++++--------------- 1 file changed, 25 insertions(+), 15 deletions(-) diff --git a/docs/man/nut-scanner.txt b/docs/man/nut-scanner.txt index ad70efa9f5..f6cd6b37b7 100644 --- a/docs/man/nut-scanner.txt +++ b/docs/man/nut-scanner.txt @@ -106,35 +106,45 @@ This option must be requested explicitly, even for a complete scan. 'serial ports' can be expressed in various forms: + - 'auto' to scan all serial ports. -- a single character indicating a port number ('0' (zero) for /dev/ttyS0 and - /dev/ttyUSB0 on Linux, '1' for COM1 on Windows, 'a' for /dev/ttya on Solaris...) +- a single character indicating a port number ('0' (zero) for `/dev/ttyS0` and + `/dev/ttyUSB0` on Linux, '1' for `COM1` on Windows, 'a' for `/dev/ttya` + on Solaris...) - a range of N characters, hyphen separated, describing the range of - ports using 'X-Y', where X and Y are characters referring to the port number. + ports using `X-Y` syntax, where 'X' and 'Y' are characters referring + to the port number. - a single port name. -- a list of ports name, coma separated, like '/dev/ttyS1,/dev/ttyS4'. +- a list of ports name, comma separated, like `/dev/ttyS1,/dev/ttyS4`. NETWORK OPTIONS --------------- -NOTE: The networked buses (such as SNMP, NetXML, IPMI and "Old NUT") allow to +[NOTE] +====== +The networked buses (such as SNMP, NetXML, IPMI and "Old NUT") allow to specify several IP (IPv4 or IPv6) address ranges, down to individual single -IP addresses. Normally a new range is specified by a set of one `-s` and one -`-e` options following each other (in any order). Lone or consecutive `-s` or -`-e` options present on the command line would translate to single-IP queries. -Also a `-m` option squashed between two `-s` and `-e` options would be a new +IP addresses. + +Normally a new range is specified by a set of one `-s` and one `-e` options +following each other (in any order on the command line). + +Lone or consecutive `-s` or `-e` options present on the command line would +translate to single-IP queries. + +Also, a `-m` option squashed between two `-s` and `-e` options would be a new range, turning those two into single-IP queries. This feature does not by itself recombine "neighboring" addresses into one range, nor even check for duplicate or overlapping specifications. -+ -Also note that some buses require IP address(es) to scan, and others have a -different behavior when exactly no addresses are specified (it is not currently -possible to mix the two behaviors in one invocation of the `nut-scanner` tool). -+ + A single-address range may be a host name which would be resolved into one IP address by the system resolver. A CIDR using a host name and netmask length would be resolved into an IP address and subjected to the mask application, to query hosts "near" the named one. -+ +====== + +Also note that some buses require IP address(es) to scan, and others have a +different behavior when exactly no addresses are specified (it is not currently +possible to mix the two behaviors in one invocation of the `nut-scanner` tool). + Finally note that currently even if multi-threaded support is available, each range specification is a separate fan-out of queries constrained by the timeout. Requests to scan many single IP addresses will take a while to complete, much From 12eedcb18ae4f4b30382306dc2c22e2ea43ff3e4 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Wed, 5 Feb 2025 20:44:00 +0100 Subject: [PATCH 16/67] docs/man/nut.conf.txt: fix DIRECTIVES section rendering Signed-off-by: Jim Klimov --- docs/man/nut.conf.txt | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/man/nut.conf.txt b/docs/man/nut.conf.txt index 80c8939153..3441772309 100644 --- a/docs/man/nut.conf.txt +++ b/docs/man/nut.conf.txt @@ -44,7 +44,6 @@ IMPORTANT NOTES not in range would be ignored with a warning message). Refer to the EXAMPLE section for illustrations. ----------------- DIRECTIVES ---------- From 7b0e0e479d3c2139e6eb3638f06085f77672ca77 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Wed, 5 Feb 2025 20:46:10 +0100 Subject: [PATCH 17/67] docs/man/nut_usb_addvars.txt: fix libusb docs URL rendering (double underscore is special) Signed-off-by: Jim Klimov --- docs/man/nut_usb_addvars.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/man/nut_usb_addvars.txt b/docs/man/nut_usb_addvars.txt index af95a0aaf1..623d2f8abd 100644 --- a/docs/man/nut_usb_addvars.txt +++ b/docs/man/nut_usb_addvars.txt @@ -142,4 +142,4 @@ For more details, including the currently supported values for your version of the library, see e.g.: * https://libusb.sourceforge.io/api-1.0/ -* https://libusb.sourceforge.io/api-1.0/group__libusb__lib.html +* link:https://libusb.sourceforge.io/api-1.0/group__libusb__lib.html[https://libusb.sourceforge.io/api-1.0/group\__libusb__lib.html] From 5c409c57ee8bbda65aa22860aeace08237f232dc Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Wed, 5 Feb 2025 21:01:40 +0100 Subject: [PATCH 18/67] docs/man/nutconf.txt: fix IPMI cipher suite option representation as a table Signed-off-by: Jim Klimov --- docs/man/nutconf.txt | 32 ++++++++++++++++++-------------- 1 file changed, 18 insertions(+), 14 deletions(-) diff --git a/docs/man/nutconf.txt b/docs/man/nutconf.txt index 74835f3a50..aa7a8384de 100644 --- a/docs/man/nutconf.txt +++ b/docs/man/nutconf.txt @@ -223,20 +223,24 @@ confidentiality algorithms to use for IPMI 2.0 communication. The authenticatio to use for session setup, the integrity algorithm identifies the algorithm to use for session packet signatures, and the confidentiality algorithm identifies the algorithm to use for payload encryption (default=3). :: -The following cipher suite ids are currently supported (Authentication; Integrity; Confidentiality): - -- '0': None; None; None -- '1': HMAC-SHA1; None; None -- '2': HMAC-SHA1; HMAC-SHA1-96; None -- '3': HMAC-SHA1; HMAC-SHA1-96; AES-CBC-128 -- '6': HMAC-MD5; None; None -- '7': HMAC-MD5; HMAC-MD5-128; None -- '8': HMAC-MD5; HMAC-MD5-128; AES-CBC-128 -- '11': HMAC-MD5; MD5-128; None -- '12': HMAC-MD5; MD5-128; AES-CBC-128 -- '15': HMAC-SHA256; None; None -- '16': HMAC-SHA256; HMAC_SHA256_128; None -- '17': HMAC-SHA256; HMAC_SHA256_128; AES-CBC-128 +The following cipher suite IDs are currently supported: ++ +[options="header"] +|=========================================================================== +| Code | Authentication | Integrity | Confidentiality +| '0' | None | None | None +| '1' | HMAC-SHA1 | None | None +| '2' | HMAC-SHA1 | HMAC-SHA1-96 | None +| '3' | HMAC-SHA1 | HMAC-SHA1-96 | AES-CBC-128 +| '6' | HMAC-MD5 | None | None +| '7' | HMAC-MD5 | HMAC-MD5-128 | None +| '8' | HMAC-MD5 | HMAC-MD5-128 | AES-CBC-128 +| '11' | HMAC-MD5 | MD5-128 | None +| '12' | HMAC-MD5 | MD5-128 | AES-CBC-128 +| '15' | HMAC-SHA256 | None | None +| '16' | HMAC-SHA256 | HMAC_SHA256_128 | None +| '17' | HMAC-SHA256 | HMAC_SHA256_128 | AES-CBC-128 +|=========================================================================== *--scan-serial* ''*:: Scans for serial devices (of supported types) on the specified From 0b83d6fad7d338eeb74c0246ffb75ebb231acd4f Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Wed, 5 Feb 2025 21:46:59 +0100 Subject: [PATCH 19/67] docs/man/nutupsdrv.txt: document NUT_QUIET_INIT_UPSNOTIFY and NUT_QUIET_INIT_BANNER support; link to ups.conf and nut.conf man pages Signed-off-by: Jim Klimov --- docs/man/nutupsdrv.txt | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/man/nutupsdrv.txt b/docs/man/nutupsdrv.txt index 6d6fe6564a..598318bf93 100644 --- a/docs/man/nutupsdrv.txt +++ b/docs/man/nutupsdrv.txt @@ -236,6 +236,16 @@ The *STATEPATH* directive in linkman:upsd.conf[5] overrides this variable. *upsd* and drivers use either *NUT_STATEPATH* if set, or ALTPIDPATH if set, or otherwise the built-in default *STATEPATH*. +*NUT_QUIET_INIT_UPSNOTIFY=true* can be used to prevent daemons which can +notify service management frameworks (such as systemd) about passing +their lifecycle milestones from emitting such notifications (including +those about lack of system support for such modern features, once per run). + +*NUT_QUIET_INIT_BANNER=true* can be used to suppress NUT tool name and +version banner. NOT recommended for services due to adverse troubleshooting +impact, but may be helpful in shell profiles or scripts which process NUT +tool outputs. + BUGS ---- @@ -245,6 +255,12 @@ information. SEE ALSO -------- +Configuration: +~~~~~~~~~~~~~~ + +- linkman:ups.conf[5] +- linkman:nut.conf[5] + Server: ~~~~~~~ From 42f129d4a1043e5d362b1d773efc3eb13035b9e1 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 09:47:41 +0100 Subject: [PATCH 20/67] docs/man/upsd.txt: clarify that driver shutdown commands need no upsd Signed-off-by: Jim Klimov --- docs/man/upsd.txt | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/man/upsd.txt b/docs/man/upsd.txt index d781bb6d7b..0e8d82fef0 100644 --- a/docs/man/upsd.txt +++ b/docs/man/upsd.txt @@ -27,7 +27,10 @@ Communication between *upsd* and clients is handled on a TCP port. Configuration details for this port are described in linkman:upsd.conf[8]. This program is essential, and must be running at all times to actually -make any use out of the drivers and clients. +make any use out of the drivers and clients (except for final UPS power-off +commands just before your server goes down, which NUT driver programs can +do alone when called as `drivername -k` in a shutdown hook or late ordered +SysV init script). Controls in the configuration files allow you to limit access to the server, but you should also use a firewall for extra protection. Client From 72e1a6f1bdbc431319488a69d89ede2e925493aa Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 10:20:56 +0100 Subject: [PATCH 21/67] docs/man/{ups.conf,upsd.conf,upsd.users,upsmon.conf}.txt: extend IMPORTANT NOTES with considerations on FS access security, slightly different for each file Signed-off-by: Jim Klimov --- docs/man/ups.conf.txt | 19 +++++++++++++++++++ docs/man/upsd.conf.txt | 19 +++++++++++++++++++ docs/man/upsd.users.txt | 28 ++++++++++++++++++++++++++++ docs/man/upsmon.conf.txt | 14 ++++++++++++++ 4 files changed, 80 insertions(+) diff --git a/docs/man/ups.conf.txt b/docs/man/ups.conf.txt index d0c6424f95..dcdee66aac 100644 --- a/docs/man/ups.conf.txt +++ b/docs/man/ups.conf.txt @@ -53,6 +53,25 @@ IMPORTANT NOTES * Contents of this file should be pure ASCII (character codes not in range would be ignored with a warning message). +* Balance the run-time user permissions to access the file (and perhaps the + directory it is in) for only `upsd` and the drivers to be able to read it; + write access is not needed. It is common to use `chown root:nut` and + `chmod 640` to set up acceptable file permissions. + - Packages (and build recipes) typically prepare one set of user and + group accounts for NUT. Custom builds with minimal configuration might + even use `nobody:nogroup` or similar, which is inherently insecure. + - On systems with extra security concerns, NUT drivers, data server + should run as separate user accounts which would be members of one + same group for shared access to local Unix socket files and the + directory they are in, as well for reading `ups.conf`, but different + groups for other configuration file access. This would need some + daemons to use customized `user`, `group`, `RUN_AS_USER` and/or + `RUN_AS_GROUP` settings to override the single built-in value. + - Note that the monitoring, logging, etc. clients are networked-only. + They do not need access to these files and directories, and can run + as an independent user and group altogether. + - Keep in mind the security of also any backup copies of this file, + e.g. the archive files it might end up in. GLOBAL DIRECTIVES ----------------- diff --git a/docs/man/upsd.conf.txt b/docs/man/upsd.conf.txt index c1c1c26164..9101ffe201 100644 --- a/docs/man/upsd.conf.txt +++ b/docs/man/upsd.conf.txt @@ -19,6 +19,25 @@ IMPORTANT NOTES * Contents of this file should be pure ASCII (character codes not in range would be ignored with a warning message). +* Balance the run-time user permissions to access the file (and perhaps the + directory it is in) for only `upsd` to be able to read it; write access + is not needed. It is common to use `chown root:nut` and `chmod 640` + to set up acceptable file permissions. + - Packages (and build recipes) typically prepare one set of user and + group accounts for NUT. Custom builds with minimal configuration might + even use `nobody:nogroup` or similar, which is inherently insecure. + - On systems with extra security concerns, NUT drivers and data server + should run as separate user accounts which would be members of one + same group for shared access to local Unix socket files and the + directory they are in, but different groups for configuration file + access. This would need some daemons to use customized `user`, `group`, + `RUN_AS_USER` and/or `RUN_AS_GROUP` settings to override the single + built-in value. + - Note that the monitoring, logging, etc. clients are networked-only. + They do not need access to these files and directories, and can run + as an independent user and group altogether. + - Keep in mind the security of also any backup copies of this file, + e.g. the archive files it might end up in. CONFIGURATION DIRECTIVES ------------------------ diff --git a/docs/man/upsd.users.txt b/docs/man/upsd.users.txt index 2a0889f2db..130399ad84 100644 --- a/docs/man/upsd.users.txt +++ b/docs/man/upsd.users.txt @@ -13,6 +13,34 @@ Administrative commands such as setting variables and the instant commands are powerful, and access to them needs to be restricted. This file defines who may access them, and what is available. +IMPORTANT NOTES +--------------- + +* Contents of this file should be pure ASCII (character codes + not in range would be ignored with a warning message). +* Balance the run-time user permissions to access the file (and perhaps the + directory it is in) for only `upsd` to be able to read it; write access + is not needed. It is common to use `chown root:nut` and `chmod 640` + to set up acceptable file permissions. + - Packages (and build recipes) typically prepare one set of user and + group accounts for NUT. Custom builds with minimal configuration might + even use `nobody:nogroup` or similar, which is inherently insecure. + - On systems with extra security concerns, NUT drivers and data server + should run as separate user accounts which would be members of one + same group for shared access to local Unix socket files and the + directory they are in, but different groups for configuration file + access. This would need some daemons to use customized `user`, `group`, + `RUN_AS_USER` and/or `RUN_AS_GROUP` settings to override the single + built-in value. + - Note that the monitoring, logging, etc. clients are networked-only. + They do not need access to these files and directories, and can run + as an independent user and group altogether. + - Keep in mind the security of also any backup copies of this file, + e.g. the archive files it might end up in. + +SECTIONS +-------- + Each user gets its own section. The fields in that section set the parameters associated with that user's privileges. The section begins with the name of the user in brackets, and continues until the next user diff --git a/docs/man/upsmon.conf.txt b/docs/man/upsmon.conf.txt index 15620e1df5..bf1934cb0e 100644 --- a/docs/man/upsmon.conf.txt +++ b/docs/man/upsmon.conf.txt @@ -27,6 +27,20 @@ IMPORTANT NOTES * Contents of this file should be pure ASCII (character codes not in range would be ignored with a warning message). +* Balance the run-time user permissions to access the file (and perhaps the + directory it is in) for only `upsmon` to be able to read it; write access + is not needed. It is common to use `chown root:nut` and `chmod 640` to + set up acceptable file permissions. + - Packages (and build recipes) typically prepare one set of user and + group accounts for NUT. Custom builds with minimal configuration might + even use `nobody:nogroup` or similar, which is inherently insecure. + - On systems with extra security concerns, NUT drivers, data server, + and any other monitoring, logging, etc. clients, should run as separate + user accounts. This would need some daemons to use customized `user`, + `group`, `RUN_AS_USER` and/or `RUN_AS_GROUP` settings to override the + single built-in value. + - Keep in mind the security of also any backup copies of this file, + e.g. the archive files it might end up in. CONFIGURATION DIRECTIVES ------------------------ From 30e40e36461180d3437212cd4c92b44ad674c1a5 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 10:25:44 +0100 Subject: [PATCH 22/67] docs/man/upsd.txt: document NUT_QUIET_INIT_UPSNOTIFY and NUT_QUIET_INIT_BANNER support Signed-off-by: Jim Klimov --- docs/man/upsd.txt | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/man/upsd.txt b/docs/man/upsd.txt index 0e8d82fef0..cea2389f46 100644 --- a/docs/man/upsd.txt +++ b/docs/man/upsd.txt @@ -171,6 +171,16 @@ The *STATEPATH* directive in linkman:upsd.conf[5] overrides this variable. *upsd* and drivers use either *NUT_STATEPATH* if set, or ALTPIDPATH if set, or otherwise the built-in default *STATEPATH*. +*NUT_QUIET_INIT_UPSNOTIFY=true* can be used to prevent daemons which can +notify service management frameworks (such as systemd) about passing +their lifecycle milestones from emitting such notifications (including +those about lack of system support for such modern features, once per run). + +*NUT_QUIET_INIT_BANNER=true* can be used to suppress NUT tool name and +version banner. NOT recommended for services due to adverse troubleshooting +impact, but may be helpful in shell profiles or scripts which process NUT +tool outputs. + SEE ALSO -------- From 0cdc3515334364433a032edc070d0e5c5669dc54 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 10:25:59 +0100 Subject: [PATCH 23/67] docs/man/upsmon.txt: document NUT_QUIET_INIT_UPSNOTIFY and NUT_QUIET_INIT_BANNER support Signed-off-by: Jim Klimov --- docs/man/upsmon.txt | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/man/upsmon.txt b/docs/man/upsmon.txt index 55110802bc..9a98ae7a86 100644 --- a/docs/man/upsmon.txt +++ b/docs/man/upsmon.txt @@ -570,6 +570,16 @@ runs in foreground mode. `upsmon.conf` and other configuration files. If this variable is not set, *upsmon* uses a built-in default, which is often `/usr/local/ups/etc`. +*NUT_QUIET_INIT_UPSNOTIFY=true* can be used to prevent daemons which can +notify service management frameworks (such as systemd) about passing +their lifecycle milestones from emitting such notifications (including +those about lack of system support for such modern features, once per run). + +*NUT_QUIET_INIT_BANNER=true* can be used to suppress NUT tool name and +version banner. NOT recommended for services due to adverse troubleshooting +impact, but may be helpful in shell profiles or scripts which process NUT +tool outputs. + FILES ----- From 42a0f1a7ee9d44cdab2128590bac340fc91a3db4 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 10:41:03 +0100 Subject: [PATCH 24/67] docs/man/{hosts,upsset}.conf.txt: considerations on FS and HTTPS access security Signed-off-by: Jim Klimov --- docs/man/hosts.conf.txt | 4 ++++ docs/man/upsset.conf.txt | 4 ++++ 2 files changed, 8 insertions(+) diff --git a/docs/man/hosts.conf.txt b/docs/man/hosts.conf.txt index 9c82cd016c..e760fea326 100644 --- a/docs/man/hosts.conf.txt +++ b/docs/man/hosts.conf.txt @@ -19,6 +19,10 @@ IMPORTANT NOTES * Contents of this file should be pure ASCII (character codes not in range would be ignored with a warning message). +* This file does not contain passwords. Read-only monitoring in NUT is + anonymous, and the linkman:upsset[8] program asks for credentials in + the browser session when commanding a particular UPS (web-server should + be secured, as reported to the program by linkman:upsset.conf[5] file). DIRECTIVES ---------- diff --git a/docs/man/upsset.conf.txt b/docs/man/upsset.conf.txt index a9170cde2c..385583fee3 100644 --- a/docs/man/upsset.conf.txt +++ b/docs/man/upsset.conf.txt @@ -26,6 +26,10 @@ linkman:upsset.cgi[8] allows you to try login name and password combinations. There is no rate limiting, as the program shuts down between every request. Such is the nature of CGI programs. +Credentials are provided to `upsset.cgi` as part of your browsing session, +so it is highly recommended to set up HTTPS on the web server; ways to do +so are outside the scope of this document. + Normally, attackers would not be able to access your linkman:upsd[8] server directly as it would be protected by the LISTEN directives in your linkman:upsd.conf[5] file, tcp-wrappers (if available when NUT was built), From 993329021eef05cf9f6bac1d06917e6911e7f858 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 11:09:45 +0100 Subject: [PATCH 25/67] docs/man/upsd.users.txt, docs/man/upsmon.txt: revise "upsmon" as more of a role than a set of actions Signed-off-by: Jim Klimov --- docs/man/upsd.users.txt | 9 ++++++--- docs/man/upsmon.txt | 15 ++++++++------- 2 files changed, 14 insertions(+), 10 deletions(-) diff --git a/docs/man/upsd.users.txt b/docs/man/upsd.users.txt index 130399ad84..38471ddd46 100644 --- a/docs/man/upsd.users.txt +++ b/docs/man/upsd.users.txt @@ -100,13 +100,16 @@ of most of the known command names. *upsmon*:: -Add the necessary actions for a upsmon process to work. This is either -set to "primary" or "secondary". +Add the necessary actions for an `upsmon` process, and can be viewed as a +role of a particular client instance to work with this data server instance. +This is either set to 'primary' (may request FSD) or 'secondary' (follows +critical situations to shut down when needed). + Do not attempt to assign actions to upsmon by hand, as you may miss something important. This method of designating a "upsmon user" was created so internal capabilities could be changed later on without -breaking existing installations. +breaking existing installations (potentially using actions that are +not exposed for direct assignment). SEE ALSO -------- diff --git a/docs/man/upsmon.txt b/docs/man/upsmon.txt index 9a98ae7a86..b514cdcb3c 100644 --- a/docs/man/upsmon.txt +++ b/docs/man/upsmon.txt @@ -114,13 +114,14 @@ on power values below. The 'username' is a section in your linkman:upsd.users[5] file. Whatever password you set in that section must match the 'password' -set in this file. - -The type set in that section must also match the 'type' here -- -*primary* or *secondary*. In general, a primary process is one -running on the system with the UPS actually plugged into a serial -port, and a secondary is drawing power from the UPS but can't -talk to it directly. See the section on UPS types for more. +set in this file for the corresponding data server instance. + +The type set in that section of the data server configuration must also match +the 'type' here -- *primary* or *secondary* (consider it an "upsmon role"). +In general, a "primary" client process is one running on the system with the +UPS actually plugged into a serial or USB port, and a "secondary" is drawing +power from the UPS but can't talk to it directly. +See the section on UPS types for more. NOTIFY EVENTS ------------- From e23feb6ac40ce67c15efbec00bbc3b79c915288f Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 12:34:49 +0100 Subject: [PATCH 26/67] docs/man/upsdrvctl.txt: revise note of upsdrvsvcctl, and add reasons to run drivers directly sometimes Signed-off-by: Jim Klimov --- docs/man/upsdrvctl.txt | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/docs/man/upsdrvctl.txt b/docs/man/upsdrvctl.txt index d68b459e82..cd7ebd33ef 100644 --- a/docs/man/upsdrvctl.txt +++ b/docs/man/upsdrvctl.txt @@ -27,14 +27,24 @@ whenever possible. When used properly, upsdrvctl lets you maintain identical startup scripts across multiple systems with different UPS configurations. -NOTE: For operating systems with service management frameworks, such as -Solaris SMF or Linux systemd, the *upsdrvsvcctl* may be a better choice. +[WARNING] +========= +For operating systems with service management frameworks, such as +Solaris/illumos SMF or Linux systemd, the linkman:upsdrvsvcctl[8] +may be a better choice. + In fact, service instances prepared by linkman:nut-driver-enumerator[8] based on contents of your linkman:ups.conf[5] file and automatically maintained by the respective framework can conflict with manual execution -of drivers, so this tool would emit a warning in NUT builds with that -capability (can be silenced by exporting a `NUT_QUIET_INIT_NDE_WARNING` +of drivers. In this case, `upsdrvctl` would emit a warning in NUT builds with +that capability (can be silenced by exporting a `NUT_QUIET_INIT_NDE_WARNING` environment variable with any value). +========= + +You may be required to stop service units (if used) and run driver programs +directly rather than via `upsdrvctl` for troubleshooting, e.g. to facilitate +debug log collection or test any custom builds of drivers without conflict +with a normally running packaged instance. OPTIONS ------- From 5b028e13d5cea86e9b7d62e9a37574c2e9bc24e9 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 12:35:33 +0100 Subject: [PATCH 27/67] docs/man/upsdrvctl.txt: mention "list" and "status" as commands (chapter intro) Signed-off-by: Jim Klimov --- docs/man/upsdrvctl.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/man/upsdrvctl.txt b/docs/man/upsdrvctl.txt index cd7ebd33ef..94bb0f6afb 100644 --- a/docs/man/upsdrvctl.txt +++ b/docs/man/upsdrvctl.txt @@ -105,9 +105,10 @@ Alias for `list` command. COMMANDS -------- -upsdrvctl supports three commands - start, stop and shutdown. +`upsdrvctl` supports three active commands -- `start`, `stop` and `shutdown`. It also supports passing requests to running drivers using `-c COMMAND` syntax, similar to that in some other daemons. +A couple of helper commands are also available -- `list` and `status`. They all can take an optional argument which is a UPS name from linkman:ups.conf[5]. Without that argument, they operate on every From 156f96ca62b260175de0eb044bc3ab8d93c757c2 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 13:29:11 +0100 Subject: [PATCH 28/67] docs/asciidoc-vars.conf, docs/asciidoc.conf, docs/man/asciidoc.conf: introduce linkmanext and linkmanext2 macros for non-NUT man pages Signed-off-by: Jim Klimov --- docs/asciidoc-vars.conf | 8 ++++++++ docs/asciidoc.conf | 25 +++++++++++++++++++++++++ docs/man/asciidoc.conf | 23 +++++++++++++++++++++++ 3 files changed, 56 insertions(+) diff --git a/docs/asciidoc-vars.conf b/docs/asciidoc-vars.conf index 75c9003e3d..0a7a69f314 100644 --- a/docs/asciidoc-vars.conf +++ b/docs/asciidoc-vars.conf @@ -44,6 +44,10 @@ ifndef::asciidoc-vars-nut-included[] // the command shown. This is also needed to properly display links // to manpages in both GitHub and generated docs without defining an // attribute for each manpage. +// * `linkmanext` and `linkmanext2` macros repeat the behavior of the default ones. +// These macros are intended for system man pages (e.g. HTML links might lead +// to a generic internet site, or possibly to a distro-provided library +// online or locally). // // Optional attributes set by callers: // * `website-url` (defaulted below) may be used for "historic website" @@ -120,6 +124,8 @@ ifndef::env-github[] :lm-s: [ :lm-c: , :lm-e: ] +:linkmanext: https://www.die.net/search/?q= +:linkmanext2: https://www.die.net/search/?q= endif::env-github[] // // - on GitHub: @@ -156,6 +162,8 @@ ifdef::env-github[] :lm-s: .html[ :lm-c: ( :lm-e: )] +:linkmanext: https://www.die.net/search/?q= +:linkmanext2: https://www.die.net/search/?q= endif::env-github[] endif::asciidoc-vars-nut-included[] // diff --git a/docs/asciidoc.conf b/docs/asciidoc.conf index 8fff6c0756..17e472c437 100644 --- a/docs/asciidoc.conf +++ b/docs/asciidoc.conf @@ -11,10 +11,15 @@ # - in linkman, {0} is the manpage section, while {target} is the command. # - in linkman2, {0} is the whole list of attributes, {1} is the command to be # shown, {2} is the manpage section, while {target} is the command page. +# - linkmanext and linkmanext2 macros repeat the behavior of the default ones. +# These macros are intended for system man pages (e.g. HTML links might lead +# to a generic internet site, or possibly to a distro-provided library +# online or locally). # # Example: # linkman:ups.conf[5] # linkman2:ups_conf[ups.conf,5] +# linkmanext:chroot[2] # # Show NUT link as: (
); if section is defined, else just show # the command. @@ -73,6 +78,8 @@ # are performed. (?su)[\\]?(?Plinkman):(?P\S*?)\[(?P.*?)\]= (?su)[\\]?(?Plinkman2):(?P\S*?)\[(?P.*?)\]= +(?su)[\\]?(?Plinkmanext):(?P\S*?)\[(?P.*?)\]= +(?su)[\\]?(?Plinkmanext2):(?P\S*?)\[(?P.*?)\]= (?su)[\\]?(?Plinkdoc):(?P\S*?)\[(?P.*?)\]= (?su)[\\]?(?Plinksingledoc):(?P\S*?)\[(?P.*?)\]= (?su)[\\]?(?Psuggestsrcdoc):(?P\S*?)\[(?P.*?)\]= @@ -95,6 +102,12 @@ ifdef::xhtml11_format[] {target}{0?({0})} [linkman2-inlinemacro] {1={target}}{2?({2})} +# FIXME: Allow to define external man page URL structure and whether +# sections should change via configure script options: +[linkmanext-inlinemacro] +{target}{0?({0})} +[linkmanext2-inlinemacro] +{1={target}}{2?({2})} [linkdoc-inlinemacro] {1}{3?suggestsrcdoc:{3}[]} [linksingledoc-inlinemacro] @@ -112,6 +125,12 @@ ifdef::chunked_format[] {target}{0?({0})} [linkman2-inlinemacro] {1={target}}{2?({2})} +# FIXME: Allow to define external man page URL structure and whether +# sections should change via configure script options: +[linkmanext-inlinemacro] +{target}{0?({0})} +[linkmanext2-inlinemacro] +{1={target}}{2?({2})} [linkdoc-inlinemacro] {1}{3?suggestsrcdoc:{3}[]} [linksingledoc-inlinemacro] @@ -126,6 +145,12 @@ ifdef::pdf_format[] {target}{0?({0})} [linkman2-inlinemacro] {1={target}}{2?({2})} +# FIXME: Allow to define external man page URL structure and whether +# sections should change via configure script options: +[linkmanext-inlinemacro] +{target}{0?({0})} +[linkmanext2-inlinemacro] +{1={target}}{2?({2})} [linkdoc-inlinemacro] {1}{3?suggestsrcdoc:{3}[]} [linksingledoc-inlinemacro] diff --git a/docs/man/asciidoc.conf b/docs/man/asciidoc.conf index a2761d0db0..12b176ac41 100644 --- a/docs/man/asciidoc.conf +++ b/docs/man/asciidoc.conf @@ -8,6 +8,10 @@ # - in linkman, {0} is the manpage section, while {target} is the command. # - in linkman2, {0} is the whole list of attributes, {1} is the command to be # shown, {2} is the manpage section, while {target} is the command page. +# - linkmanext and linkmanext2 macros repeat the behavior of the default ones. +# These macros are intended for system man pages (e.g. HTML links might lead +# to a generic internet site, or possibly to a distro-provided library +# online or locally). # # Show NUT link as: (
); if section is defined, else just show # the command. @@ -15,6 +19,8 @@ [macros] (?su)[\\]?(?Plinkman):(?P\S*?)\[(?P.*?)\]= (?su)[\\]?(?Plinkman2):(?P\S*?)\[(?P.*?)\]= +(?su)[\\]?(?Plinkmanext):(?P\S*?)\[(?P.*?)\]= +(?su)[\\]?(?Plinkmanext2):(?P\S*?)\[(?P.*?)\]= ifdef::backend-docbook[] [linkman-inlinemacro] @@ -27,6 +33,16 @@ ifdef::backend-docbook[] {2#} {2#{1={target}}{2}} {2#} +[linkmanext-inlinemacro] +{0%{target}} +{0#} +{0#{target}{0}} +{0#} +[linkmanext2-inlinemacro] +{2%{1={target}}} +{2#} +{2#{1={target}}{2}} +{2#} endif::backend-docbook[] ifdef::backend-xhtml11[] @@ -35,6 +51,13 @@ ifdef::backend-xhtml11[] [linkman2-inlinemacro] {1={target}}{2?({2})} +# FIXME: Allow to define external man page URL structure and whether +# sections should change via configure script options: +[linkmanext-inlinemacro] +{target}{0?({0})} +[linkmanext2-inlinemacro] +{1={target}}{2?({2})} + # Override HTML footer, to include NUT version [footer-text] Last updated {docdate} {doctime} -- Network UPS Tools {nutversion} From 55c98476c4dd74811fac73ee1782d0cf58ce6793 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 13:46:38 +0100 Subject: [PATCH 29/67] docs/man/upslog.txt: clarify that "-N" does not do sanity checks Signed-off-by: Jim Klimov --- docs/man/upslog.txt | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/man/upslog.txt b/docs/man/upslog.txt index 791e765225..b1b563d4ff 100644 --- a/docs/man/upslog.txt +++ b/docs/man/upslog.txt @@ -63,6 +63,9 @@ The default format string is: *-N*:: Prefix `%UPSHOST%%t` before the format string (whether default or custom). Useful when logging many systems into same target. ++ +NOTE: This option DOES NOT currently check if you already have `%UPSHOST%` +in the formatting string (e.g. specified explicitly). *-i* 'interval':: From 01bf85fcdd01ad002d81afbec68d75b2b6bc88a2 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 14:58:45 +0100 Subject: [PATCH 30/67] docs/man/usbhid-ups.txt: "Selecting a specific UPS": clarify use of serial number, allow_duplicates, etc. Signed-off-by: Jim Klimov --- docs/man/usbhid-ups.txt | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/docs/man/usbhid-ups.txt b/docs/man/usbhid-ups.txt index 1e9863e882..ac6b642193 100644 --- a/docs/man/usbhid-ups.txt +++ b/docs/man/usbhid-ups.txt @@ -269,10 +269,13 @@ Selecting a specific UPS ~~~~~~~~~~~~~~~~~~~~~~~~ As mentioned above, the driver ignores the "port" value in *ups.conf*. + Unlike previous versions of this driver, it is now possible to control -multiple UPS units simultaneously with this driver, provided they can -be distinguished by setting some combination of the device-matching options. -For instance: +multiple UPS units simultaneously with instances of this driver running +in parallel, provided they can be distinguished by setting some combination +of the device-matching options. + +For example: [mge] driver = usbhid-ups @@ -283,6 +286,15 @@ For instance: port = auto vendorid = 09ae +To monitor devices using the same vendor and product identification (e.g. +two pieces of the same model), you would need to find a reliable unique +matching criteria: + +* The 'serial' number is the best option, if populated. +* Link-level `bus`/`device`/`busport` may be unreliable (due to re-enumeration + on a whim by the operating system). +* If nothing else helps, `allow_duplicates` may be an option in some cases. + USB Polling and Interrupt Transfers ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 8afece2b315b3a45ef6b1b64660f6e6822e99f04 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 15:02:56 +0100 Subject: [PATCH 31/67] drivers/upsdrvctl.c: wrap long line in help() Signed-off-by: Jim Klimov --- drivers/upsdrvctl.c | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/drivers/upsdrvctl.c b/drivers/upsdrvctl.c index 812b2c2ebb..e730bea1b7 100644 --- a/drivers/upsdrvctl.c +++ b/drivers/upsdrvctl.c @@ -1192,7 +1192,8 @@ static void help(const char *arg_progname) printf("\nListing known driver(s):\n"); printf(" -l | list list all device driver confgurations that can be managed\n"); - printf(" -l | list only try to list the specified device driver confgurations (error if unresolved)\n"); + printf(" -l | list only try to list the specified device driver confgurations\n"); + printf(" (error out if the device name is unresolved)\n"); printf("\nSignalling a running driver:\n"); printf(" -c send via signal to running driver(s)\n"); From 997d97c74431b7a6d20f62946ebebb517c410978 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 15:03:36 +0100 Subject: [PATCH 32/67] docs/man/*.txt: revise asciidoc markup and man page contents * Align multi-paragraph blocks to render with correct indentation * Upper-case program description sentences on top, and start of text in NOTE/WARNING blocks * Apply linkman/linkmanext instead of direct emphasis * Apply backtick verbatim format in more places for files, commands, etc. * Do not state that a driver "is not built by default", but that it "may be not built by default" (`configure --with-all=auto` is now default for some time) * Assorted typos * Short content clarifications and extensions here and there (long/significant ones tracked by other commits) Signed-off-by: Jim Klimov --- docs/man/adelsystem_cbi.txt | 4 +- docs/man/al175.txt | 2 +- docs/man/apcsmart-old.txt | 3 +- docs/man/apcsmart.txt | 49 ++++---- docs/man/apcupsd-ups.txt | 11 +- docs/man/asciidoc.conf | 3 +- docs/man/asem.txt | 17 +-- docs/man/bcmxcp.txt | 1 + docs/man/bcmxcp_usb.txt | 14 ++- docs/man/belkinunv.txt | 10 +- docs/man/bestfortress.txt | 2 +- docs/man/blazer-common.txt | 2 +- docs/man/gamatronic.txt | 2 +- docs/man/generic_gpio.txt | 41 ++++--- docs/man/generic_modbus.txt | 10 +- docs/man/genericups.txt | 53 +++++---- docs/man/hosts.conf.txt | 5 +- docs/man/huawei-ups2000.txt | 39 ++++--- docs/man/hwmon_ina219.txt | 2 +- docs/man/ivtscd.txt | 2 +- docs/man/libnutclient_commands.txt | 2 +- docs/man/libnutclient_devices.txt | 2 +- docs/man/libnutclient_variables.txt | 2 +- docs/man/liebert-esp2.txt | 2 +- docs/man/liebert.txt | 5 +- docs/man/macosx-ups.txt | 14 ++- docs/man/mge-shut.txt | 10 +- docs/man/mge-utalk.txt | 14 +-- docs/man/netxml-ups.txt | 13 ++- docs/man/nhs_ser.txt | 2 +- docs/man/nut-driver-enumerator.txt | 2 +- docs/man/nut-ipmipsu.txt | 22 ++-- docs/man/nut-recorder.txt | 10 +- docs/man/nut-scanner.txt | 43 +++++--- docs/man/nut.conf.txt | 24 ++-- docs/man/nut.exe.txt | 14 ++- docs/man/nut_usb_addvars.txt | 16 +-- docs/man/nutconf.txt | 100 +++++++++-------- docs/man/nutdrv_atcl_usb.txt | 6 +- docs/man/nutdrv_qx.txt | 24 +++- docs/man/nutdrv_siemens_sitop.txt | 22 ++-- docs/man/nutscan_add_option_to_device.txt | 2 +- docs/man/nutscan_cidr_to_ip.txt | 2 +- docs/man/nutupsdrv.txt | 70 +++++++----- docs/man/oneac.txt | 8 +- docs/man/phoenixcontact_modbus.txt | 12 +- docs/man/pijuice.txt | 4 +- docs/man/powerman-pdu.txt | 8 +- docs/man/richcomm_usb.txt | 4 +- docs/man/skel.txt | 2 +- docs/man/snmp-ups.txt | 13 ++- docs/man/sockdebug.txt | 6 +- docs/man/socomec_jbus.txt | 12 +- docs/man/tripplite_usb.txt | 18 +-- docs/man/ups.conf.txt | 2 +- docs/man/upsc.txt | 10 +- docs/man/upscli_splitaddr.txt | 2 +- docs/man/upscli_splitname.txt | 2 +- docs/man/upscmd.txt | 6 +- docs/man/upsd.conf.txt | 74 +++++++------ docs/man/upsd.txt | 48 ++++---- docs/man/upsd.users.txt | 25 +++-- docs/man/upsdrvctl.txt | 73 +++++++----- docs/man/upsdrvsvcctl.txt | 53 ++++----- docs/man/upsimage.cgi.txt | 2 +- docs/man/upslog.txt | 78 +++++++------ docs/man/upsmon.conf.txt | 16 +-- docs/man/upsmon.txt | 129 +++++++++++++--------- docs/man/upsrw.txt | 8 +- docs/man/upsset.cgi.txt | 4 + docs/man/upsset.conf.txt | 22 ++-- docs/man/upsstats.cgi.txt | 5 +- docs/man/upsstats.html.txt | 36 +++--- docs/man/usbhid-ups.txt | 28 ++--- docs/man/victronups.txt | 2 +- docs/nut.dict | 4 +- 76 files changed, 791 insertions(+), 620 deletions(-) diff --git a/docs/man/adelsystem_cbi.txt b/docs/man/adelsystem_cbi.txt index 5cbe3d45c1..2ae213baa5 100644 --- a/docs/man/adelsystem_cbi.txt +++ b/docs/man/adelsystem_cbi.txt @@ -84,11 +84,11 @@ executes "instant poweroff" INSTALLATION ------------ -This driver is not built by default. You can build it by installing +This driver may be not built by default. You can build it by installing libmodbus and running `configure --with-modbus=yes`. You also need to give proper permissions on the local serial device -file (/dev/ttyUSB0 for example) to allow the run-time NUT driver user +file (`/dev/ttyUSB0` for example) to allow the run-time NUT driver user account to access it. AUTHOR diff --git a/docs/man/al175.txt b/docs/man/al175.txt index 276f85f11b..eb8a7efc26 100644 --- a/docs/man/al175.txt +++ b/docs/man/al175.txt @@ -22,7 +22,7 @@ SUPPORTED HARDWARE The *al175* driver is known to work with the following UPSes: - Eltek MPSU4000 with AL175 alarm module +* Eltek MPSU4000 with AL175 alarm module It may also work with other UPSes equipped with AL175 alarm module, but they have not been tested. diff --git a/docs/man/apcsmart-old.txt b/docs/man/apcsmart-old.txt index 200dffe351..bcef2737c4 100644 --- a/docs/man/apcsmart-old.txt +++ b/docs/man/apcsmart-old.txt @@ -93,7 +93,8 @@ This driver was called `newapc` for a time and was renamed in the 1.5 series. In 2.6.2 the driver was renamed to `apcsmart-old`, being superseded -by updated version with new features. +by updated version with new features which currently holds the +`apcsmart` name. SEE ALSO -------- diff --git a/docs/man/apcsmart.txt b/docs/man/apcsmart.txt index 09ba08e011..5d02c5df10 100644 --- a/docs/man/apcsmart.txt +++ b/docs/man/apcsmart.txt @@ -62,11 +62,14 @@ those are pretty fuzzy): it through *NUT* is to purchase a "legacy communications card" -- part #AP9620 (google 'AP9620' for more details). Or if that's not an option, rely on official software. - + - UPDATE: later releases of *apcupsd* claimed support for new APC ++ +-- +.UPDATE: +Later releases of *apcupsd* claimed support for new APC protocols, so it is worth checking if *apcupsd* software would work with your device, and *apcupsd-ups* NUT driver would handle it as part of NUT-managed ecosystem. +-- Microsol models:: Several Microsol serial models sold in Brazil have been rebranded @@ -82,7 +85,7 @@ Microsol models:: Another thing to remember is that Smart protocol is not USB protocol. If you have UPS with both USB and serial ports, then depending on how -you connect it, you will need either apcsmart or usbhid-ups driver. +you connect it, you will need either `apcsmart` or `usbhid-ups` driver. CABLING ------- @@ -104,11 +107,11 @@ wiring. You can specify alternate cable in linkman:ups.conf[5]: -*cable*=940-0095B + *cable*=940-0095B Alternatively, you can also provide it on the command line using: --x *cable*=940-0095B + -x *cable*=940-0095B TTY MODES --------- @@ -119,11 +122,11 @@ obscure serial cards or serial-USB converters that could cause problems as well. You can use 'ttymode=' option to force non-canonical discipline in linkman:ups.conf[5]: -*ttymode*=raw + *ttymode*=raw Alternatively, you can also provide it on the command line using: --x *ttymode*=raw + -x *ttymode*=raw NOTE: Any other value will make the driver work in the canonical mode. @@ -177,17 +180,19 @@ command if your UPS supports it (and is not too old, see below). The behaviour is -- unfortunately -- similarly primitive to *S*. The UPS unconditionally wakes up after $$nnn*6$$ minutes: *it doesn't care if the power returned !* - If nnn = 000, then UPS will do precisely nothing. - On those models you're better specifying nnn > 0, if you can ++ +NOTE: If 'nnn = 000', then UPS will do precisely nothing. + On those models you should better specify 'nnn > 0', if you can estimate the kind of power problems that might be happening in your environment. - Another thing to consider with "old" models -- you might lose the ++ +Another thing to consider with "old" models -- you might lose the connection with the UPS, until it wakes up (with *S*, the serial connection is kept alive). "new" models: :: All the usual variables defined in EEPROM are respected (see *S*). - Additionally, if nnn > 0, the $$nnn*6$$ minutes are added to EEPROM + Additionally, if 'nnn > 0', the $$nnn*6$$ minutes are added to EEPROM defined delay. UPS will not power up if it's running on batteries, contrary to what "old" models used to do -- the combined delay is counted from the moment of power return. @@ -286,22 +291,22 @@ in driver's section of linkman:ups.conf[5]. When such option is in effect, the core driver will ignore LB state as reported by specific driver and start shutdown basing the decision _only_ on two conditions: -battery.charge < battery.charge.low + battery.charge < battery.charge.low *OR* -battery.runtime < battery.runtime.low + battery.runtime < battery.runtime.low Of course -- if any of the variables are not available, the appropriate condition is not checked. If you want to explicitly disable one of the conditions, simply override the right hand variable causing the condition to always evaluate to false (you can even provide negative numbers). -APC UPSes don't have battery.charge.low -- you will have to define it +APC UPSes don't have `battery.charge.low` -- you will have to define it if you want to use such condition (prefix the variable with `override.` or `default.`). -"New" units have battery.runtime.low, but depending on battery quality, +"New" units have `battery.runtime.low`, but depending on battery quality, firmware version, calibration and UPS load -- this variable can be underestimated quite a bit -- especially right after going into OB state. This in turn can cause LB to be asserted, which under normal conditions @@ -320,7 +325,7 @@ Simple example: This would cause apcsmart to go into shutdown _only_ if detected battery charge < 15%. Runtime condition is always false in this example. -You could ask -- why bother ? Well, the reason is already hinted above. +You could ask -- why bother? Well, the reason is already hinted above. APC units can be very picky about the batteries, and their firmware can underestimate the remaining runtime (especially right after going into OB state). *ignorelb* option and *$$override.*$$* let you remain in @@ -391,14 +396,12 @@ AUTHORS AND HISTORY ------------------- Nigel Metheringham (drawing -heavily on the original `apcsmart` driver by Russell Kroll). - -This driver was called `newapc` for a time and was renamed in -the 1.5 series. +heavily on the original `apcsmart` driver by Russell Kroll) wrote a +driver called `newapc` for a time, which was renamed in the 1.5 series. -In 2.6.2 it was renamed to `apcsmart-old`, being superseded by -updated version with new features, which is maintained by Michal -Soltys +In 2.6.2 that driver was renamed finally to `apcsmart-old`, being superseded +by this updated version with new features which currently holds the +`apcsmart` name, and is maintained by Michal Soltys . SEE ALSO -------- diff --git a/docs/man/apcupsd-ups.txt b/docs/man/apcupsd-ups.txt index 710db8e60f..ebdad2d467 100644 --- a/docs/man/apcupsd-ups.txt +++ b/docs/man/apcupsd-ups.txt @@ -24,7 +24,7 @@ This driver is a client to *apcupsd* (another UPS monitoring project). *apcupsd-ups* acts as an *apcupsd* client, simply forwarding data. This can be useful in cases where both protocols are required in a network, -or in case apcupsd has a required UPS access mode missing from NUT. +or in case `apcupsd` code base has a required UPS access mode missing from NUT. EXTRA ARGUMENTS --------------- @@ -36,7 +36,7 @@ This is the name of a remote host running apcupsd (plus an optional port). For instance: - [apcupsd] + [apcupsd] driver = apcupsd-ups port = localhost desc = "apcupsd client" @@ -98,7 +98,7 @@ LIMITATIONS Access to *apcupsd* is strictly read only: no commands can be issued. This stems from the design of *apcupsd*, where the settings are changed in *apctest*. In order to run *apctest*, *apcupsd* must be stopped -(and it is *apcupsd* exposes the UPS to the network and to this NUT +(and it is *apcupsd* that exposes the UPS to the network and to this NUT driver as its client). AUTHOR @@ -117,3 +117,8 @@ Internet Resources: * The NUT (Network UPS Tools) home page: https://www.networkupstools.org/ * The apcupsd home page: http://www.apcupsd.org/ + - Development of *apcupsd* project itself seems to have stalled + in 2016/2017, with release 3.14.14 being the latest official tag. + Its community discussions do remain quite active, however. + - Just in case, a replica of its sources is stored at + https://github.com/networkupstools/apcupsd diff --git a/docs/man/asciidoc.conf b/docs/man/asciidoc.conf index 12b176ac41..11cd4290ae 100644 --- a/docs/man/asciidoc.conf +++ b/docs/man/asciidoc.conf @@ -12,6 +12,7 @@ # These macros are intended for system man pages (e.g. HTML links might lead # to a generic internet site, or possibly to a distro-provided library # online or locally). + # # Show NUT link as: (
); if section is defined, else just show # the command. @@ -50,14 +51,12 @@ ifdef::backend-xhtml11[] {target}{0?({0})} [linkman2-inlinemacro] {1={target}}{2?({2})} - # FIXME: Allow to define external man page URL structure and whether # sections should change via configure script options: [linkmanext-inlinemacro] {target}{0?({0})} [linkmanext2-inlinemacro] {1={target}}{2?({2})} - # Override HTML footer, to include NUT version [footer-text] Last updated {docdate} {doctime} -- Network UPS Tools {nutversion} diff --git a/docs/man/asem.txt b/docs/man/asem.txt index ccafdcda71..bf1606a586 100644 --- a/docs/man/asem.txt +++ b/docs/man/asem.txt @@ -4,7 +4,7 @@ ASEM(8) NAME ---- -asem - driver for UPS in ASEM PB1300 +asem - Driver for UPS in ASEM PB1300 SYNOPSIS -------- @@ -25,10 +25,11 @@ Likely other I2C devices from the same manufacturer will work too, since this is a "custom" charger. Seems that there are two versions of the charger. Older one is based on -Max1667, newer one is a custom solution. Both are on I2C address 0x09. -To be compatible with both versions, the driver just reads bit 15 of -address 0x13 which yields online/on battery status. -Battery monitor is a BQ2060 at address 0x0B. +Max1667, newer one is a custom solution. Both are on I2C address *0x09*. +To be compatible with both versions, the driver just reads *bit 15* of +address *0x13* which yields online/on battery status. + +Battery monitor is a BQ2060 at address *0x0B*. EXTRA ARGUMENTS --------------- @@ -49,11 +50,11 @@ Set the high battery threshold to 'num' volts. INSTALLATION ------------ -This driver is specific to the Linux I2C API, and requires the lm_sensors -libi2c-dev or its equivalent to compile. +This driver is specific to the Linux I2C API, and requires the libi2c-dev +library and headers from lm_sensors project, or its equivalent, to compile. Beware that the SystemIO memory used by the I2C controller is reserved -by ACPI. If only a native I2C driver (e.g. i2c_i801, as of 3.5.X Linux +by ACPI. If only a native I2C driver (e.g. `i2c_i801`, as of 3.5.X Linux kernels) is available, then you'll need to relax the ACPI resources check. For example, you can boot with the `acpi_enforce_resources=lax` option. diff --git a/docs/man/bcmxcp.txt b/docs/man/bcmxcp.txt index cfae0ebe76..5a53255239 100644 --- a/docs/man/bcmxcp.txt +++ b/docs/man/bcmxcp.txt @@ -22,6 +22,7 @@ SUPPORTED HARDWARE This driver should recognize all serial BCM/XCP-compatible UPSes. It has been developed and tested on Powerware PW5115 and PW9120 hardware. + If your UPS has a USB connection, you may also consult the linkman:bcmxcp_usb[8] driver documentation. diff --git a/docs/man/bcmxcp_usb.txt b/docs/man/bcmxcp_usb.txt index bf980a416e..1581f51dd4 100644 --- a/docs/man/bcmxcp_usb.txt +++ b/docs/man/bcmxcp_usb.txt @@ -15,7 +15,7 @@ SYNOPSIS *bcmxcp_usb* -a 'UPS_NAME' ['OPTIONS'] NOTE: This man page only documents the hardware-specific features of the -bcmxcp_usb driver. For information about the core driver, see +`bcmxcp_usb` driver. For information about the core driver, see linkman:nutupsdrv[8]. NOTE: This driver is a variant of the serial driver linkman:bcmxcp[8] and @@ -85,16 +85,18 @@ EXPERIMENTAL DRIVER ------------------- This driver has been tagged experimental, even if it has been reported -to be stable. Thus it is not suitable for production systems and it is -not built by default. This is mainly due to the fact that it is a +to be stable. Thus it is not suitable for production systems and it may +be not built by default. This is mainly due to the fact that it is a new driver. INSTALLATION ------------ -This driver is not built by default. You can build it by using -"configure --with-usb=yes". Note that it will also install other USB -drivers. +This driver may be not built by default. You can require building it +by using `./configure --with-usb=yes` (note that it will also install +other USB drivers), or `./configure --with-drivers=bcmxcp_usb`. Either +way, you would need libusb-dev (libraries and headers package) or +equivalent for other platforms. You also need to install manually the hotplug files (libhidups and libhid.usermap), generally in etc/hotplug/usb/, to address the diff --git a/docs/man/belkinunv.txt b/docs/man/belkinunv.txt index 1723acc197..9aab3809d1 100644 --- a/docs/man/belkinunv.txt +++ b/docs/man/belkinunv.txt @@ -43,7 +43,7 @@ One problem with the Belkin Universal UPS is that it cannot enter a soft shutdown (shut down the load until AC power returns) unless the batteries are completely depleted. Thus, one cannot just shut off the UPS after operating system shutdown; it will not come back on when the -power comes back on. Therefore, the belkinunv driver should never be +power comes back on. Therefore, the *belkinunv* driver should never be used with the *-k* option. Instead, the *-x wait* option is provided as a workaround. @@ -54,7 +54,7 @@ to return, and then exits with status 0. This is meant to be used in a shutdown script as follows: during a shutdown, after all filesystems have been remounted read-only, and -just before the system would normally be halted: check /etc/killpower +just before the system would normally be halted: check `/etc/killpower` (or similar) to see if this shutdown was caused by linkman:upsmon[8], and if yes, call *belkinunv -x wait*. If AC power comes back on, *belkinunv* exits, and things should be arranged so that the @@ -292,7 +292,7 @@ read-only, and just before the computer halts. Note that *belkinunv* must be installed in a directory which is still readable at that point. - +---- # NEAR END OF SHUTDOWN SCRIPT: # if shutdown was caused by UPS, perform Belkin UPS workaround. if [ -f /etc/killpower ] || /usr/sbin/upsmon -K ; then @@ -303,13 +303,14 @@ readable at that point. echo "Power is back. Rebooting..." reboot fi +---- And here is an example of how to use *belkinunv* in the startup script. These commands should go near the beginning of the startup script, before any file systems are mounted read/write, and before any file system integrity checks are done. - +---- # NEAR BEGINNING OF STARTUP SCRIPT: # if we are recovering from a power failure, wait for the UPS to # charge to a comfortable level before writing anything to disk @@ -317,6 +318,7 @@ file system integrity checks are done. echo "Waiting for UPS battery charge to reach 60%..." /usr/bin/belkinunv -x wait=60 -x nohang /dev/ttyS1 fi +---- EXIT STATUS ----------- diff --git a/docs/man/bestfortress.txt b/docs/man/bestfortress.txt index 9c4101ac92..e494b5282a 100644 --- a/docs/man/bestfortress.txt +++ b/docs/man/bestfortress.txt @@ -32,7 +32,7 @@ This driver supports the following optional settings in the linkman:ups.conf[5]: *baudrate*='num':: -Set the speed of the serial connection - 1200, 2400, 4800 or 9600. +Set the speed of the serial connection -- 1200, 2400, 4800 or 9600. *max_load*='VA':: Set the full-scale value of the *ups.load* variable. diff --git a/docs/man/blazer-common.txt b/docs/man/blazer-common.txt index d9d6f99096..54daba0b66 100644 --- a/docs/man/blazer-common.txt +++ b/docs/man/blazer-common.txt @@ -89,7 +89,7 @@ Setting this flag will make the driver skip this step. *protocol =* 'string':: Skip autodetection of the protocol to use and only use the one specified. -Supported values 'megatec', 'megatec/old', 'mustek' and 'zinto'. +Supported values are 'megatec', 'megatec/old', 'mustek' and 'zinto'. *runtimecal =* 'value,value,value,value':: diff --git a/docs/man/gamatronic.txt b/docs/man/gamatronic.txt index 29d071b9fb..eca1c78fc8 100644 --- a/docs/man/gamatronic.txt +++ b/docs/man/gamatronic.txt @@ -20,7 +20,7 @@ linkman:nutupsdrv[8]. SUPPORTED HARDWARE ------------------ -Various - Rebuilt to work with Gamatronic UPS Units, but should recognize any +Various -- Rebuilt to work with Gamatronic UPS Units, but should recognize any UPS that speaks the SEC protocol at 1200-19200 bps. EXTRA ARGUMENTS diff --git a/docs/man/generic_gpio.txt b/docs/man/generic_gpio.txt index 5e859254f4..03cf386818 100644 --- a/docs/man/generic_gpio.txt +++ b/docs/man/generic_gpio.txt @@ -40,10 +40,19 @@ Driver control: *rules*='value':: A string consisting of sub-strings. Each sub-string describes GPIO line states conversion formula to specific NUT state, like -`nut_state=[^]line_num[logical_operation[^]line_num]...;`. Not (^) , and (&) , or -(|)operations are supported for now. nut_state should correspond to NUT -state, line_num to GPIO line number connected to UPS open collector pin. ++ +---- +nut_state=[^]line_num[logical_operation[^]line_num]...; +---- ++ +The logical "Not" (`^`), "And" (`&`), and "Or" (`|`) operations are +supported for now. ++ +The `nut_state` should correspond to NUT state, and `line_num` to the +GPIO line number connected to UPS open collector pin. ++ CyberShield CSN27U12V describes pins as: ++ |=== |Battery state|State details|GPIO line |ON BATTERY|*Low* when operating from utility line @@ -59,13 +68,16 @@ CyberShield CSN27U12V describes pins as: *Open* when operating from a battery with < 20% capacity|3 |=== -and rules might be defined as - -`rules = "OL=^0;OB=0;LB=3;RB=1;DISCHRG=0&^6;BYPASS=6;"` - -assuming battery pin connection to GPIO lines as listed in table. Expecting simple formula -to be used for each state, extra may increase state reliability and may need to be -checked on each specific UPS. +and then the 'rules' value might be defined as ++ +---- +rules = "OL=^0;OB=0;LB=3;RB=1;DISCHRG=0&^6;BYPASS=6;" +---- ++ +assuming battery pin connection to GPIO lines as listed in table. ++ +Expecting simple formula to be used for each state, extra may increase +state reliability and may need to be checked on each specific UPS. Battery Charge: ~~~~~~~~~~~~~~ @@ -97,15 +109,16 @@ This driver does not support shutdown command. INSTALLATION ------------ -This driver is not built by default. You can build it by installing +This driver may be not built by default. You can build it by installing libgpiod and running `configure --with-gpio=yes`. You also need to give proper permissions on the local serial device -file (/dev/gpiochip0 for example) to allow the run-time NUT driver user -account to access it, like by adding the following rule to Linux rules.d directory: +file (`/dev/gpiochip0` for example) to allow the run-time NUT driver user +account to access it, like by adding the following rule to Linux `rules.d` +directory: SUBSYSTEM=="gpio*", PROGRAM="/bin/sh -c '\ - chown -R nut:nut /dev/gpiochip0 && chmod -R 700 /dev/gpiochip0\ + chown -R nut:nut /dev/gpiochip0 && chmod -R 700 /dev/gpiochip0' AUTHOR ------ diff --git a/docs/man/generic_modbus.txt b/docs/man/generic_modbus.txt index 627474f45c..e7efed2556 100644 --- a/docs/man/generic_modbus.txt +++ b/docs/man/generic_modbus.txt @@ -74,7 +74,7 @@ This driver supports the following optional settings in the linkman:ups.conf[5] file: Generic: -~~~~~~~ +~~~~~~~~ *device_mfr*='value':: A string specifying the manufacturer of the UPS device (default UNKNOWN). @@ -83,7 +83,7 @@ A string specifying the manufacturer of the UPS device (default UNKNOWN). A string specifying the model of the UPS device (default UNKNOWN). Serial: -~~~~~~ +~~~~~~~ *ser_baud_rate*='value':: A integer specifying the serial port baud rate (default 9600). @@ -98,7 +98,7 @@ A character specifying the serial port parity (default N). An integer specifying the serial port stop bit (default 1). Modbus: -~~~~~~ +~~~~~~~ *rio_slave_id*='value':: An integer specifying the RIO modbus slave ID (default 1). @@ -206,11 +206,11 @@ executes "instant poweroff" INSTALLATION ------------ -This driver is not built by default. You can build it by installing +This driver may be not built by default. You can build it by installing libmodbus and running `configure --with-modbus=yes`. You also need to give proper permissions on the local serial device -file (/dev/ttyUSB0 for example) to allow the run-time NUT driver user +file (`/dev/ttyUSB0` for example) to allow the run-time NUT driver user account to access it. OTHER NOTES diff --git a/docs/man/genericups.txt b/docs/man/genericups.txt index 31a2b93d94..f3d0b1c5df 100644 --- a/docs/man/genericups.txt +++ b/docs/man/genericups.txt @@ -79,22 +79,24 @@ it gets tired of waiting for the driver to return. CUSTOM CONFIGURATIONS --------------------- -You may override the values for CP, OL, LB, and SD by defining them in -the linkman:ups.conf[5] after the upstype setting. +You may override the values for `CP`, `OL`, `LB`, and `SD` by defining them in +the linkman:ups.conf[5] after the `upstype` setting. -For example, to set the cable power to DTR and the low battery value to -DCD, it would look like this: +For example, to set the cable power to `DTR` and the low battery value to +`DCD`, it would look like this: +---- CP = DTR LB = DCD +---- -Recognized values for input lines are CTS, DCD, and RNG. Recognized -values for output lines are DTR, RTS, and ST. See below for more about +Recognized values for input lines are `CTS`, `DCD`, and `RNG`. Recognized +values for output lines are `DTR`, `RTS`, and `ST`. See below for more about what these signals mean. -These values may be negated for active low signals. That is, "LB=-DCD" -recognizes a low battery condition when DCD is not held high. +These values may be negated for active low signals. That is, `LB=-DCD` +recognizes a low battery condition when `DCD` is not held high. TYPE INFORMATION ---------------- @@ -102,7 +104,7 @@ TYPE INFORMATION The essence of a UPS definition in this driver is how it uses the serial lines that are available. These are the abbreviations you will see below: -OL:: On line (no power failure) (opposite of OB - on battery) +OL:: On line (no power failure) (opposite of 'OB' -- on battery) LB:: Low battery @@ -128,13 +130,13 @@ DSR:: Data Set Ready. Received from the UPS. ST:: Send a BREAK on the transmit data line -NULL:: Disable this signal. Disabled signal will always be low except for OL +NULL:: Disable this signal. Disabled signal will always be low except for 'OL' which will always be high. none:: Alias to `NULL` which matches some other documentation. -A "-" in front of a signal name (like -RNG) means that the indicated -condition is signaled with an active low signal. For example, [LB=-RNG] +A `-` in front of a signal name (like `-RNG`) means that the indicated +condition is signaled with an active low signal. For example, `[LB=-RNG]` means the battery is low when the ring indicate line goes low, and that the battery is OK when that line is held high. @@ -150,11 +152,10 @@ UPS TYPES [CP=DTR] [OL=-RNG] [LB=DCD] [SD=RTS] 2 = APC Back-UPS/Back-UPS Pro/Smart-UPS with 940-0020B cable +(Note: Type 2 has also been reported to work with the 940-0020C cable). [CP=RTS] [OL=-CTS] [LB=DCD] [SD=DTR+RTS] - Type 2 has also been reported to work with the 940-0020C cable. - 3 = PowerTech Comp1000 with DTR cable power [CP=DTR] [OL=CTS] [LB=DCD] [SD=DTR+RTS] @@ -173,7 +174,7 @@ UPS TYPES 7 = CyberPower Power99 Also Upsonic Power Guardian PG-500, Belkin Belkin Home Office, - F6H350-SER, F6H500-SER, F6H650-SER, Eaton Management Card Contact - Config3 + F6H350-SER, F6H500-SER, F6H650-SER, Eaton Management Card Contact -- Config3 with cable 66033 (shutdown does not work) [CP=RTS] [OL=CTS] [LB=-DCD] [SD=DTR] @@ -226,12 +227,10 @@ UPS TYPES [CP=DTR] [OL=CTS] [LB=-DCD] [SD=RTS] -20 = Powerware 5119 RM +20 = Powerware 5119 RM (check `docs/cables/powerware.txt` in NUT sources) [CP=DTR] [OL=-CTS] [LB=DCD] [SD=ST] - Check docs/cables/powerware.txt - 21 = Generic RUPS 2000 (Megatec M2501 cable) [CP=RTS] [OL=CTS] [LB=-DCD] [SD=RTS+DTR] @@ -253,7 +252,7 @@ Many different UPS companies make models with similar interfaces. The RUPS cable seems to be especially popular in the "power strip" variety of UPS found in office supply stores. If your UPS works with an entry in the table above, but the model or manufacturer information don't match, -don't despair. You can fix that easily by using the mfr and model +don't despair. You can fix that easily by using the `mfr` and `model` variables documented above in your linkman:ups.conf[5]. TESTING COMPATIBILITY @@ -276,20 +275,20 @@ going down the list. Step 1 ~~~~~~ -Pick a driver to try from the list (genericups -h) and go to step 2. +Pick a driver to try from the list (run `genericups -h`) and go to step 2. Step 2 ~~~~~~ -Start the driver with the type you want to try - +Start the driver with the type you want to try, e.g.: genericups -x upstype=n /dev/port -Let upsd sync up (watch the syslog), and then run upsc to see what it -found. If the STATUS is right (should be OL for on line), continue to -<<_step_3,Step 3>>, otherwise go back to step 1. +Let linkman:upsd[8] sync up (watch the syslog), and then run linkman:upsc[8] +to see what it found. If the `STATUS` is correct (should be "OL" for online), +continue to <<_step_3,Step 3>>, otherwise go back to step 1. -Alternatively, you can run genericups in debug mode - +Alternatively, you can run `genericups` in debug mode, e.g.: genericups -DDDDD -x upstype=n /dev/port @@ -348,7 +347,7 @@ NEW SUPPORT If the above testing sequence fails, you will probably need to create a new entry to support your hardware. All UPS types are determined from the -table in the genericups.h file in the source tree. +table in the `genericups.h` file in the source tree. On a standard 9 pin serial port, there are 6 lines that are used as the standard "high/low" signal levels. 4 of them are incoming (to the PC, @@ -373,7 +372,7 @@ shutdown sequence. - Neil Muller The Tripp-Lite Internet Office 700 must be used with the black 73-0844 cable instead of the gray 73-0743 cable. This entry should work with any -of their models with the Lan 2.2 interface - see the sticker by the DB9 +of their models with the Lan 2.2 interface -- see the sticker by the DB9 connector on the UPS. - Stephen Brown Type 5 should work with the Tripp-Lite Lan 2.1 interface and the 73-0724 diff --git a/docs/man/hosts.conf.txt b/docs/man/hosts.conf.txt index e760fea326..940329b871 100644 --- a/docs/man/hosts.conf.txt +++ b/docs/man/hosts.conf.txt @@ -30,8 +30,9 @@ DIRECTIVES *MONITOR* 'ups' 'description':: The 'ups' element is in the form `upsname[@hostname[:port]]`. -To allow connections to a UPS called "snoopy" on a system called -"doghouse" that runs upsd on port 7877, it would look like this: ++ +To allow connections to an UPS called "snoopy" on a system called +"doghouse" that runs `upsd` on port 7877, it would look like this: MONITOR snoopy@doghouse:7877 "Joe Cool" + diff --git a/docs/man/huawei-ups2000.txt b/docs/man/huawei-ups2000.txt index 0cbe179a9f..1479ff17a6 100644 --- a/docs/man/huawei-ups2000.txt +++ b/docs/man/huawei-ups2000.txt @@ -149,7 +149,7 @@ operating system. INSTALLATION ------------ -This driver is not built by default. You can build it by installing libmodbus +This driver may be not built by default. You can build it by installing libmodbus (with development packages) and running configure --with-serial=yes --with-modbus=yes @@ -326,17 +326,23 @@ normal uses, please file a bug report with full logs attached. Before troubleshooting or reporting a problem, it's important to check your *dmesg* log for USB connect and disconnect events to avoid wasting -time on the NUT driver when the actual problem is USB. For example, if -someone yanks the cable out of the USB port, or if a new USB device is -plugged into a USB host/hub that is struggling to power its ports -(common on single-board computers like Raspberry Pi), or if you have -flaky cabling or EMI noise, the serial converter can get disconnected -from USB, at least briefly. This creates a permanent data stale, the driver -must be restarted (plugging the USB back won't fix it, since the driver -is still using the nonexistent serial device). These USB problems usually -have nothing to do with NUT. If it's the case, you should solve the -underlying USB problem - check the cable, check the converter, try a -powered USB hub, try a full-speed USB isolator, etc. +time on the NUT driver when the actual problem is USB. + +For example, if someone yanks the cable out of the USB port, or if a +new USB device is plugged into a USB host/hub that is struggling to +power its ports (common on single-board computers like Raspberry Pi), +or if you have flaky cabling or EMI noise, due to all these and similar +reasons the serial converter can get disconnected from USB, at least +briefly. + +This creates a permanent data stale situation, and the driver must be +restarted (plugging the USB back won't fix it, since the driver is still +using the nonexistent serial device, if the system kernel initializes +a new device driver instance internally). + +These USB problems usually have nothing to do with NUT. If it's the case, +you should solve the underlying USB problem -- check the cable, check the +converter, try a powered USB hub, try a full-speed USB isolator, etc. Serial port becomes unresponsive ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -344,8 +350,9 @@ Serial port becomes unresponsive Some malformed commands are known to lock up the serial port (including USB, which is a USB-to-serial device). Upon receiving them, UPS2000 stops all serial communications. The result is a completely unresponsive UPS, -regardless of what you do - restarting NUT, rebooting the computer - -cannot restore connectivity, as if someone has unplugged the RS-232 cable. +regardless of what you do -- restarting NUT, rebooting the computer -- can +not restore connectivity, as if someone has unplugged the RS-232 cable. + To recover, simply power cycle the UPS: Turn off the UPS output via the front panel, then unplug the UPS from line power. Wait for the LCD front screen to go black. Finally reconnect line power and restart your UPS. @@ -358,8 +365,8 @@ they're unlikely to be accidentally generated. Still, we recommend to power cycle your UPS after making a cabling change, especially after changing from RS-485/USB to RS-232, just to ensure the UPS selects the correct communication interface. Also, if you have -discovered a reproducible serial port lockup problem, it can be an -previously unknown bug, make sure to file a bug report. +discovered a reproducible serial port lockup problem, it can be a +previously unknown bug, so please make sure to file a bug report. USB chip (MaxLinear/Exar RX21V1410) is unsupported ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/man/hwmon_ina219.txt b/docs/man/hwmon_ina219.txt index 9cf8394186..e2ea64388f 100644 --- a/docs/man/hwmon_ina219.txt +++ b/docs/man/hwmon_ina219.txt @@ -4,7 +4,7 @@ HWMON_INA219(8) NAME ---- -hwmon_ina219 - driver for UPS based on INA219 +hwmon_ina219 - Driver for UPS based on INA219 SYNOPSIS -------- diff --git a/docs/man/ivtscd.txt b/docs/man/ivtscd.txt index 5d6da16972..40f9053e41 100644 --- a/docs/man/ivtscd.txt +++ b/docs/man/ivtscd.txt @@ -4,7 +4,7 @@ IVTSCD(8) NAME ---- -ivtscd - driver for the IVT Solar Controller Device +ivtscd - Driver for the IVT Solar Controller Device SYNOPSIS -------- diff --git a/docs/man/libnutclient_commands.txt b/docs/man/libnutclient_commands.txt index 676d35e48a..4572ebe19f 100644 --- a/docs/man/libnutclient_commands.txt +++ b/docs/man/libnutclient_commands.txt @@ -56,7 +56,7 @@ Return '1' if supported and '0' if not. * The *nutclient_get_device_command_description* function retrieves the command description, if any. + -The returned string must be freed by linkman:free[3] +The returned string must be freed by linkmanext:free[3] (see linkman:libnutclient_general[3]). * The *nutclient_execute_device_command* intends to execute diff --git a/docs/man/libnutclient_devices.txt b/docs/man/libnutclient_devices.txt index d0fd5e0b51..432e451944 100644 --- a/docs/man/libnutclient_devices.txt +++ b/docs/man/libnutclient_devices.txt @@ -43,7 +43,7 @@ The returned strarr must be freed by 'strarr_free' * The *nutclient_get_device_description()* function retrieves the device description. + -The returned description string must be freed by linkman:free[3]. +The returned description string must be freed by linkmanext:free[3]. Common arguments: diff --git a/docs/man/libnutclient_variables.txt b/docs/man/libnutclient_variables.txt index 28f5efbc8d..e61988ce27 100644 --- a/docs/man/libnutclient_variables.txt +++ b/docs/man/libnutclient_variables.txt @@ -69,7 +69,7 @@ Return '1' if supported and '0' if not. * The *nutclient_get_device_variable_description* function retrieves the variable description, if any. + -The returned string must be freed by linkman:free[3]. +The returned string must be freed by linkmanext:free[3]. * The *nutclient_get_device_variable_values* returns variable values (generally only one). diff --git a/docs/man/liebert-esp2.txt b/docs/man/liebert-esp2.txt index 95b364878b..31e5547f4d 100644 --- a/docs/man/liebert-esp2.txt +++ b/docs/man/liebert-esp2.txt @@ -49,7 +49,7 @@ EXTRA ARGUMENTS This driver supports the following optional settings in linkman:ups.conf[5]: *baudrate=*'num':: -Set the speed of the serial connection - 1200, 2400 (default), 4800, 9600 +Set the speed of the serial connection -- 1200, 2400 (default), 4800, 9600 or 19200. AUTHORS diff --git a/docs/man/liebert.txt b/docs/man/liebert.txt index ce8bb6c9e3..4d8d241e30 100644 --- a/docs/man/liebert.txt +++ b/docs/man/liebert.txt @@ -22,8 +22,9 @@ SUPPORTED HARDWARE This driver supports some Liebert UPS equipment with a contact-closure interface. This includes the UPStation GXT2 with their contact-closure -cable. The smart mode ("Multilink") cable is not supported by this -driver. +cable. + +The smart mode ("Multilink") cable is NOT supported by this driver. EXTRA ARGUMENTS --------------- diff --git a/docs/man/macosx-ups.txt b/docs/man/macosx-ups.txt index bd57e38b7b..2a76f4c07d 100644 --- a/docs/man/macosx-ups.txt +++ b/docs/man/macosx-ups.txt @@ -4,7 +4,7 @@ MACOSX-UPS(8) NAME ---- -macosx-ups - monitor for Mac OS X built-in UPS and battery driver +macosx-ups - Monitor for Mac OS X built-in UPS and battery driver SYNOPSIS -------- @@ -46,7 +46,7 @@ DIAGNOSTICS If the driver cannot find an UPS, first open System Preferences and see if there is an "UPS" tab on the Energy Saver panel. If so, re-run the driver -with the *-D* flag to list the names of the power sources found. +with the `-D` flag to list the names of the power sources found. KNOWN ISSUES AND BUGS --------------------- @@ -54,12 +54,12 @@ KNOWN ISSUES AND BUGS This driver is a monitoring-only driver, and cannot shut down an UPS on its own. However, this should not be a problem in practice: it is monitoring the built-in Mac OS X UPS driver, which has configuration options for several -shutdown scenarios. Consult the Energy Saver control panel or *pmset*(8) for -more information. +shutdown scenarios. Consult the Energy Saver control panel or +linkmanext:pmset[8] for more information. The default distribution of *apcupsd* installs a kernel extension which prevents Mac OS X from attaching to the UPS. In order to use this driver after -installing apcupsd, you must first run the `apcupsd-uninstall` script and +installing `apcupsd`, you must first run the `apcupsd-uninstall` script and reboot. Note that other UPS monitoring solutions may show more detail than what is @@ -76,7 +76,9 @@ Charles Lepple SEE ALSO -------- -linkman:usbhid-ups[8], *pmset*(8), *regex*(3) +linkman:usbhid-ups[8], +linkmanext:pmset[8], +linkmanext:regex[3] The core driver: ~~~~~~~~~~~~~~~~ diff --git a/docs/man/mge-shut.txt b/docs/man/mge-shut.txt index d558613f2e..6d5deaabb4 100644 --- a/docs/man/mge-shut.txt +++ b/docs/man/mge-shut.txt @@ -40,7 +40,7 @@ the exact model. *offdelay*='num':: Set the timer before the UPS is turned off after the kill power command is -sent (via the *-k* switch). +sent (via the `-k` switch). + The default value is 20 (in seconds). Usually this *must be lower* than 'ondelay', but the driver will *not* warn you upon startup if it isn't. @@ -62,7 +62,7 @@ driver ( 3 for 30 seconds) . It is now set in seconds ( 30 for 30 seconds). Make sure you use the correct unit in your configuration. *notification*='num':: -Set notification type to 1 (no), 2 (light) or 3 (yes). +Set notification type to '1' (no), '2' (light) or '3' (yes). + This argument is ignored. It is only here for backward compatibility. @@ -72,11 +72,11 @@ KNOWN ISSUES Repetitive timeout and staleness ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Some models tends to be unresponsive with the default polling frequency. +Some models tend to be unresponsive with the default polling frequency. The result is that you have some "data stale" errors in your system log. -In this case, simply modify the general parameter "pollinterval" to a higher -value (like 10 for 10 seconds). This should solve the issue. +In this case, simply modify the general parameter `pollinterval` to a higher +value (like '10' for 10 seconds). This should solve the issue. Using 'notification=3' might also help. diff --git a/docs/man/mge-utalk.txt b/docs/man/mge-utalk.txt index b287f56ba2..058c67ea2d 100644 --- a/docs/man/mge-utalk.txt +++ b/docs/man/mge-utalk.txt @@ -33,8 +33,8 @@ mge-utalk supports the following legacy units, using the MGE UTalk protocol: This driver also support some newer models with backward UTalk compatibility, such as Pulsar Evolution and Pulsar EXtreme C. As these models also support -the SHUT protocol, prefer mge-shut for serial communication, or use the USB -port, if available, with the usbhid-ups driver. +the SHUT protocol, prefer linkman:mge-shut[8] for serial communication, or +use the USB port, if available, with the linkman:usbhid-ups[8]] driver. EXTRA ARGUMENTS --------------- @@ -45,12 +45,12 @@ This driver supports the following optional settings in the linkman:ups.conf[5]: Set the low battery warning threshold at which shutdown is initiated by linkman:upsmon[8]. + -The factory default value is 30 (in percent), and can be settable depending on -the exact model. +The factory default value is '30' (in percent), and can be settable depending +on the exact model. *offdelay*='num':: Set the timer before the UPS is turned off after the kill power command is -sent (via the *-k* switch). +sent (via the `-k` switch). + The default value is 20 (in seconds). @@ -72,8 +72,8 @@ Repetitive timeout and staleness Older models, such as ES/ESV ones, might report repetitive "data stale" errors. This is due to the fact that these models don't support too much polling. -To solve this problem, add "pollinterval=20" in ups.conf, and change the value -of MAXAGE to 25 in upsd.conf, and DEADTIME to 25 in upsmon.conf. +To solve this problem, add `pollinterval=20` in `ups.conf`, and change the value +of `MAXAGE` to '25' in `upsd.conf`, and `DEADTIME` to '25' in `upsmon.conf`. AUTHORS ------- diff --git a/docs/man/netxml-ups.txt b/docs/man/netxml-ups.txt index 658168cb9b..f3e8bff894 100644 --- a/docs/man/netxml-ups.txt +++ b/docs/man/netxml-ups.txt @@ -34,7 +34,7 @@ Supported card and proxy models are: * ePDU Monitored (newer version). Older models, such as SNMP card (Ref 66062 and Ref 66045), use the SNMP -protocol and should use the linkman:snmp-ups[8] driver with the "mibs=mge" +protocol and should use the linkman:snmp-ups[8] driver with the `mibs=mge` parameter. EXTRA ARGUMENTS @@ -46,8 +46,8 @@ linkman:ups.conf[5]: *timeout*='value':: The timeout for connecting to and reading from the UPS. Defaults to 5 seconds. Don't change this value unless you know exactly what you're doing. - -This value *must never* be higher than half the MAXAGE value specified in ++ +This value *must never* be higher than half the `MAXAGE` value specified in linkman:upsd.conf[5], otherwise you run the risk that linkman:upsd[8] declares the driver stale while it is waiting for a connection to timeout. @@ -71,13 +71,14 @@ shutdown. Defaults to 120 seconds. *shutdown_timer*='value':: Set the shutdown timer, in seconds. After 'value' seconds running on battery, -the local system will receive a notification to shutdown. +the local system will receive a notification to shut down. Defaults to "none" (disabled). *do_convert_deci*:: If this flag value is present, the driver assumes you have a very old MGE networked UPS (or rather an old network management card firmware) which serves certain measurements spelled 10x too big in the XML markup. ++ Originally such measurements were decimated by the driver -- but this is wrong for newer, more sane, devices -- so this behavior was deprecated and is now disabled by default. Enabling this flag in configuration of a @@ -86,8 +87,8 @@ particular driver instance restores the old behavior for those measurements. IMPLEMENTATION -------------- -The hostname of the UPS is specified with the "port" value in -*ups.conf*, i.e.: +The hostname of the networked UPS is specified with the `port` value in +`ups.conf`, i.e.: [mgexml] driver = netxml-ups diff --git a/docs/man/nhs_ser.txt b/docs/man/nhs_ser.txt index b998906361..62f42f715d 100644 --- a/docs/man/nhs_ser.txt +++ b/docs/man/nhs_ser.txt @@ -4,7 +4,7 @@ NHS_SER(8) NAME ---- -nhs_ser - driver for NHS Nobreaks, senoidal line, with serial port +nhs_ser - Driver for NHS Nobreaks, senoidal line, with serial port SYNOPSIS -------- diff --git a/docs/man/nut-driver-enumerator.txt b/docs/man/nut-driver-enumerator.txt index 51b8b6f66f..cedc52f485 100644 --- a/docs/man/nut-driver-enumerator.txt +++ b/docs/man/nut-driver-enumerator.txt @@ -4,7 +4,7 @@ NUT-DRIVER-ENUMERATOR(8) NAME ---- -nut-driver-enumerator - tool to map NUT device entries to service instances +nut-driver-enumerator - Tool to map NUT device entries to service instances SYNOPSIS -------- diff --git a/docs/man/nut-ipmipsu.txt b/docs/man/nut-ipmipsu.txt index 8cda9c28ea..0d22c43314 100644 --- a/docs/man/nut-ipmipsu.txt +++ b/docs/man/nut-ipmipsu.txt @@ -25,7 +25,7 @@ SUPPORTED HARDWARE This driver should support a wide range of PSUs through local IPMI interface. -nut-ipmipsu currently use the GNU FreeIPMI project, for IPMI implementation. +nut-ipmipsu currently uses the GNU FreeIPMI project, for IPMI implementation. EXTRA ARGUMENTS @@ -36,16 +36,18 @@ This driver doesn't support any optional settings. INSTALLATION ------------ -This driver is not built by default. You can build it by using -"configure --with-ipmi=yes". +This driver may be not built by default. You can build it by installing +the libfreeipmi-dev dependencies and using `configure --with-ipmi=yes`. You also need to give proper permissions on the local IPMI device file -(/dev/ipmi0 for example) to allow the NUT user to access it. +(`/dev/ipmi0` for example) to allow the NUT user to access it. -An udev rules file (nut-ipmipsu.rules) is provided and automatically installed -on udev enabled system. This file is generally installed in /etc/udev/rules.d/ -or /lib/udev/rules.d/ on newer systems, to address the permission settings -problem. For more information, refer to nut/scripts/udev/README. +An *udev* rules file (`nut-ipmipsu.rules`) is provided and automatically +installed on an *udev* enabled system. This file is generally installed +in `/etc/udev/rules.d/`, or `/lib/udev/rules.d/` on newer systems, to +address the permission settings problem. + +For more information, refer to `scripts/udev/README.adoc` in NUT sources. INSTANT COMMANDS ---------------- @@ -55,8 +57,8 @@ This driver doesn't support any instant commands. IMPLEMENTATION -------------- -The "port" value is used to identify the PSU. For instance, to target -FRU 0x2, use the following in *ups.conf*: +The `port` value is used to identify the PSU. For instance, to target +FRU '0x2', use the following in *ups.conf*: [pdu] driver = nut-ipmipsu diff --git a/docs/man/nut-recorder.txt b/docs/man/nut-recorder.txt index e809d77a4e..0060a49f5a 100644 --- a/docs/man/nut-recorder.txt +++ b/docs/man/nut-recorder.txt @@ -4,7 +4,7 @@ NUT-RECORDER(8) NAME ---- -nut-recorder - utility to record device status and values changes +nut-recorder - Utility to record device status and values changes SYNOPSIS -------- @@ -15,10 +15,10 @@ DESCRIPTION ----------- *nut-recorder* is an utility to record sequences from running devices (such as -power failures, or any other value changes) from upsd, and dump it in a .seq -format. +power failures, or any other value changes) from linkman:upsd[8] data server, +and dump it in a `.seq` format. -The .seq file can then be used by the linkman:dummy-ups[8] driver +The `.seq` file can then be used by the linkman:dummy-ups[8] driver to replay the sequence. OPTIONS @@ -44,7 +44,7 @@ EXAMPLES To record data from 'ups1@host1' every 10 seconds: - $ nut-recorder ups1@host1' ups1-output.seq 10 + :; nut-recorder ups1@host1' ups1-output.seq 10 . . . battery.charge: 100.0 battery.voltage: 13.9 diff --git a/docs/man/nut-scanner.txt b/docs/man/nut-scanner.txt index f6cd6b37b7..8366e2bf23 100644 --- a/docs/man/nut-scanner.txt +++ b/docs/man/nut-scanner.txt @@ -4,7 +4,7 @@ NUT-SCANNER(8) NAME ---- -nut-scanner - scan communication buses for NUT devices +nut-scanner - Tool to scan communication buses for NUT devices SYNOPSIS -------- @@ -20,17 +20,20 @@ DESCRIPTION NUT-compatible devices it has found. *nut-scanner* can also display the detected devices in various formats, -including ups.conf, and ensures that the generated devices name are unique +including `ups.conf`, and ensures that the generated devices name are unique across buses. INSTALLATION ------------ *nut-scanner* is only built if libltdl (part of libtool development suite) -is available. Available options (USB, SNMP, IPMI, ...) will vary according -to the available compile time and runtime dependencies. For example, if -Net-SNMP is installed, thus providing libsnmp (.so or .dll) and headers, -both during compilation and runtime, then SNMP discovery will be available. +is available. + +Available scanning options (USB, SNMP, IPMI, ...) will vary according +to the available compile-time and run-time dependencies. For example, if +Net-SNMP is installed, thus providing libsnmp libraries (`*.so` or `*.dll`) +and header files during compilation, and at least the library files on the +monitoring system, then SNMP discovery will be available. OPTIONS ------- @@ -42,11 +45,11 @@ DISPLAY OPTIONS --------------- *-Q* | *--disp_nut_conf_with_sanity_check*:: -Display result in the 'ups.conf' format with sanity-check warnings (if any) +Display result in the `ups.conf` format with sanity-check warnings (if any) as comments (default). *-N* | *--disp_nut_conf*:: -Display result in the 'ups.conf' format. +Display result in the `ups.conf` format. *-P* | *--disp_parsable*:: Display result in a parsable format. @@ -87,10 +90,13 @@ interface(s) to retrieve XML/HTTP capable devices. No IP required in this mode. If IP address ranges are specified, they would be scanned instead of a broadcast. *-O* | *--oldnut_scan*:: -Scan NUT devices (i.e. upsd daemon) on IP ranging from 'start IP' to 'end IP'. +Scan NUT devices (i.e. `upsd` daemon) on IP ranging from 'start IP' to 'end IP'. *-n* | *--nut_simulation_scan*:: -Scan NUT simulated devices (`.dev` files in `$NUT_CONFPATH`). +Scan NUT simulated devices (`.dev` files in the built-in "sysconfig" location). ++ +WARNING: The `NUT_CONFPATH` environment variable override is not currently +supported. *-A* | *--avahi_scan*:: Scan NUT servers using Avahi request on the current network interface(s). @@ -285,7 +291,7 @@ Display only scan result. No information on currently scanned bus is displayed. *-D* | *--nut_debug_level*:: Raise the debugging level. Use this multiple times to see more details. -NOTE: The level of debugging needed depends both on nut-scanner and the +NOTE: The level of debugging needed depends both on `nut-scanner` and the problem you're trying to diagnose. Therefore, first explain the problem you have with `nut-scanner` to a developer/maintainer, before sending them debugging output. More often than not, if you just pick a level, the output may be @@ -304,8 +310,8 @@ To scan USB devices only: port = "192.168.0.42" ---- -To scan SNMP v1 device with public community on address range 192.168.0.0 -to 192.168.0.255: +To scan SNMP v1 device with 'public' (default) community on address range +'192.168.0.0 to 192.168.0.255': ---- :; nut-scanner -S -s 192.168.0.0 -e 192.168.0.255 @@ -325,8 +331,8 @@ The same using CIDR notation: port = "192.168.0.42" ---- -To scan NUT servers with a timeout of 10 seconds on IP range 192.168.0.0 -to 192.168.0.127 using CIDR notation: +To scan NUT servers with a timeout of '10' seconds on IP range '192.168.0.0 +to 192.168.0.127' using CIDR notation: ---- :; nut-scanner -O -t 10 -m 192.168.0.0/25 @@ -337,20 +343,21 @@ to 192.168.0.127 using CIDR notation: ---- To scan for power supplies, through IPMI (1.5 mode) over the network, -on address range 192.168.0.0 to 192.168.0.255 using CIDR notation: +on address range '192.168.0.0 to 192.168.0.255' using CIDR notation: ---- :; nut-scanner -I -m 192.168.0.0/24 -b username -B password ---- -To scan for Eaton serial devices on ports 0 and 1 (`/dev/ttyS0`, +To scan for Eaton serial devices on ports '0' and '1' (`/dev/ttyS0`, `/dev/ttyUSB0`, `/dev/ttyS1` and `/dev/ttyUSB1` on Linux): ---- :; nut-scanner --eaton_serial 0-1 ---- -To scan for Eaton serial devices on ports 1 and 2 (`COM1` and `COM2` on Windows): +To scan for Eaton serial devices on ports '1' and '2' (`COM1` and `COM2` +on Windows): ---- :; nut-scanner --eaton_serial 1-2 diff --git a/docs/man/nut.conf.txt b/docs/man/nut.conf.txt index 3441772309..a183f761b3 100644 --- a/docs/man/nut.conf.txt +++ b/docs/man/nut.conf.txt @@ -10,14 +10,14 @@ DESCRIPTION ----------- This file attempts to standardize the various files being found -in different installations, like /etc/default/nut on Debian based -systems and /etc/sysconfig/ups on RedHat based systems. +in different installations, like `/etc/default/nut` on Debian based +systems and `/etc/sysconfig/ups` on RedHat based systems. Distribution's init script should source this file in order to determine which components have to be started. -Blank lines are ignored. Lines with a hash ('#') character at the -1st position of the line are ignored, too. They can be used to add +Blank lines are ignored. Lines with a hash (`#`) character at the +first position of the line are ignored, too. They can be used to add comments. IMPORTANT NOTES @@ -104,22 +104,22 @@ should be running. *UPSMON_OPTIONS*:: Optional. Set upsmon specific options. See linkman:upsmon[8] for more details. It is ignored when 'MODE' above indicates that no -upsmon should be running. +`upsmon` should be running. *POWEROFF_WAIT*:: Optional. At the end of an emergency system halt, the upsmon primary will signal the UPS to switch off. This may fail for a number of reasons. Most notably is the case that mains power returns during the shutdown process. See the section "Power races" in -/usr/share/doc/nut/FAQ.txt.gz. The system will wait this +`/usr/share/doc/nut/FAQ.txt.gz`. The system will wait this long for the UPS to cut power, and then reboot. It should be long enough to exhaust the batteries, in case line power continues to be unavailable. On the other hand, it should not be so long that the system remains offline for an unreasonable amount of time if line -power has returned. See sleep(1) for compatible time syntax. +power has returned. See linkmanext:sleep[1] for compatible time syntax. If you specify the time in seconds, use the "s" suffix. + -WARNING: this workaround might be dangerous under some circumstances. +WARNING: This workaround might be dangerous under some circumstances. Please read http://bugs.debian.org/358696 for more details. *POWEROFF_QUIET*:: @@ -147,11 +147,11 @@ the daemons logging to stderr (useful e.g. in NUT Integration Test suite to not pollute the OS logs, or in systemd where stderr and syslog both go into the same journal). Recognized values: + -[options="header"] +[options="header",cols="1,3a"] |=========================================================================== | Value | Description -| `stderr` | Disabled and background() keeps stderr attached -| `none` | Disabled and background() detaches stderr as usual +| `stderr` | Disabled and `background()` keeps `stderr` attached +| `none` | Disabled and `background()` detaches `stderr` as usual | `default` | Not disabled | unset/other | Not disabled |=========================================================================== @@ -200,7 +200,7 @@ EXAMPLE INTEGRATION ----------- -An init script, such as /etc/init.d/nut, is expected to source this +An init script, such as `/etc/init.d/nut`, is expected to source this file in order to determine which components have to be started. SEE ALSO diff --git a/docs/man/nut.exe.txt b/docs/man/nut.exe.txt index c176a89d33..2cbec9f741 100644 --- a/docs/man/nut.exe.txt +++ b/docs/man/nut.exe.txt @@ -20,11 +20,12 @@ DESCRIPTION *nut.exe* wraps NUT programs to start and stop as a Windows service. -Depending on 'nut.conf' setting of 'MODE', it would manage the bundle of -driver(s), 'upsd' data server and 'upsmon' client, as well as attempt an -UPS shutdown command in case of FSD handling, or for mere 'netclient' systems -it would run just the 'upsmon' client to monitor remote UPS device(s) and -initiate the OS shut down on the local Windows system as applicable. +Depending on linkman:nut.conf[5]] setting of 'MODE', it would manage the +bundle of driver(s), linkman:upsd[8] data server and linkman:upsmon[8] client, +as well as attempt an UPS shutdown command in case of FSD handling, or for +mere 'netclient' systems it would run just the linkman:upsmon[8] client to +monitor remote UPS device(s) and initiate the OS shut down on the local +Windows system as applicable. Beside launching or stopping a set of the NUT programs in certain cases, this helper program also allows to register (or un-register) itself as a @@ -64,7 +65,8 @@ powershell.exe -Command "Start-Process netsh.exe -ArgumentList ---- Keep in mind that by default NUT `upsd` only listens on `localhost`, so -you would need to add some `LISTEN` directives in `upsd.conf` as well. +you would need to add some `LISTEN` directives in `upsd.conf` as well +in this case. OPTIONS ------- diff --git a/docs/man/nut_usb_addvars.txt b/docs/man/nut_usb_addvars.txt index 623d2f8abd..137d47972c 100644 --- a/docs/man/nut_usb_addvars.txt +++ b/docs/man/nut_usb_addvars.txt @@ -38,12 +38,12 @@ risky!) Select a specific UPS, in case there is more than one connected via USB. Each option specifies an extended regular expression (see -*regex(7)* for more information on regular expressions), which -must match the UPS's entire respective vendor/product/serial string -(minus any surrounding whitespace), or the whole 4-digit +linkmanext:regex[7] for more information on regular expressions), which +must match the UPS's entire respective `vendor`/`product`/`serial` +string values (minus any surrounding whitespace), or the whole 4-digit hexadecimal code for `vendorid` and `productid`. + -Try *lsusb(8)* or running this NUT driver with *-DD* command-line +Try linkmanext:lsusb[8] or running this NUT driver with `-DD` command-line argument for finding out the strings to match. + Examples: @@ -57,14 +57,14 @@ Examples: Select a UPS on a specific USB bus or group of buses. The argument is a regular expression that must match the bus name where the UPS is connected (e.g. `bus="002"` or `bus="00[2-3]"`) as seen on Linux in -`/sys/bus/usb/devices` or *lsusb(8)*; including leading zeroes. +`/sys/bus/usb/devices` or linkmanext:lsusb[8]; including leading zeroes. *device =* 'regex':: Select a UPS on a specific USB device or group of devices. The argument is a regular expression that must match the device name where the UPS is connected (e.g. `device="001"` or `device="00[1-2]"`) as seen on Linux -in `/sys/bus/usb/devices` or *lsusb(8)*; including leading zeroes. +in `/sys/bus/usb/devices` or linkmanext:lsusb[8]; including leading zeroes. + NOTE: device numbers are not guaranteed by the OS to be stable across re-boots or device re-plugging. @@ -84,7 +84,7 @@ that NUT can run on. *allow_duplicates*:: If you have several UPS devices which may not be uniquely identified by -the options above (e.g. only VID:PID can be discovered there), this flag +the options above (e.g. only 'VID:PID' can be discovered there), this flag allows each driver instance where it is set to take the first match if available, or proceed to try another. + @@ -117,7 +117,7 @@ by the interface number `0` (default). *usb_hid_ep_out*:: Force use of specific interface, endpoint, descriptor index etc. numbers, -rather than defaulting to 0 (rarely other values in certain drivers for +rather than defaulting to '0' (rarely other values in certain drivers for some devices known to use non-zero numbers). Specified as a hexadecimal number. + diff --git a/docs/man/nutconf.txt b/docs/man/nutconf.txt index aa7a8384de..4c82b8046f 100644 --- a/docs/man/nutconf.txt +++ b/docs/man/nutconf.txt @@ -1,13 +1,14 @@ NUTCONF(8) ========== - NAME ---- + nutconf - NUT configuration tool SYNOPSIS -------- + *nutconf* --help *nutconf* ['OPTIONS'] @@ -47,8 +48,7 @@ Prints current NUT configuration mode *--set-mode* 'mode':: Sets NUT configuration mode. - - :: ++ Known modes are: - standalone @@ -71,31 +71,35 @@ Note that such options may be specified multiple times for one run *--set-monitor* | *--add-monitor* '':: Sets/adds a NUT monitor. - - :: -Arguments: ++ +* Arguments: ++ +---- '' '[:]' '' '' '' '(\"master\"|\"slave\")' +---- *--set-listen* | *--add-listen* '
' '[]':: -Sets/adds 'upsd' daemon listen address +Sets/adds linkman:upsd[8] daemon listen address. *--set-device* | *--add-device* '':: Sets/adds a device (typically a UPS). - - :: -Arguments: ++ +* Arguments: ++ +---- '' '' '' '[=]*' - - :: +---- ++ The attribute/value pairs follow device configuration syntax. Devices may have very different configuration attributes depending on the driver. Exhaustive description of them is beyond this man page and may be found in NUT documentation. *--set-notifyflags* | *--add-notifyflags* '' '+':: ++ +-- Sets/adds notification flags for the notification type. - :: -Notification types are: +* Notification types are: - 'ONLINE' (mains is present) - 'ONBATT' (mains is gone) @@ -120,13 +124,13 @@ Notification types are: - 'SUSPEND_STARTING' (OS is entering sleep/suspend/hibernate mode) - 'SUSPEND_FINISHED' (OS just finished sleep/suspend/hibernate mode) - :: -Notification flags: +* Notification flags: - 'SYSLOG' (use syslogd to log the notification) - 'WALL' (push a message to users' terminals) - 'EXEC' (execute a command) - 'IGNORE' (don't act) +-- *--set-notifymsg* '' '':: Sets message for the specified notification type. @@ -136,17 +140,16 @@ Sets command used to shut the system down. *--set-user* | *--add-user* '':: Sets/adds NUT user. - - :: -Arguments: ++ +* Arguments: - '' (specifies user name). -For 'upsmon' user, it has a special form of -'upsmon=(master|slave)' which specifies the monitoring mode. + For 'upsmon' user, it has a special form of + `upsmon=(primary|master|secondary|slave)` which specifies the monitoring mode. - 'password=' sets password for the user - 'actions=' sets actions ('SET', 'FSD' are supported) - 'instcmds=' sets instant commands allowed for the user -(may be used multiple times) + (may be used multiple times) SCANNING OPTIONS ---------------- @@ -154,16 +157,15 @@ SCANNING OPTIONS Availability of each scanning option depends on availability of various 3rd-party libraries both at compile time and run time. -Issue the tool with the *--help* option to check which of the +Run the tool with the *--help* option to check which of the *--scan-...* options are actually supported. All timeouts are in microseconds. *--scan-snmp* '' '' '[=]*':: Scans for SNMP devices on IP addresses from the specified range. - - :: -Known attributes are: ++ +* Known attributes are: - 'timeout' device scan timeout - 'community' SNMP community (default: *public*) @@ -188,10 +190,11 @@ Scans for NUT (pseudo-)devices on the network. Scans for Avahi devices. *--scan-ipmi* '' '' '[=]'*:: ++ +-- Scans for IPMI devices on IP addresses from the specified range. - :: -Known attributes are: +* Known attributes are: - 'username' username (mandatory for IPMI/LAN) - 'password' user password (mandatory for IPMI/LAN) @@ -202,11 +205,11 @@ Known attributes are: - 'workaround-flags' - 'version' (1.5 or 2.0) - :: -Authentication types: - :: -Specifies the IPMI 1.5 authentication type to use (NONE, STRAIGHT_PASSWORD_KEY, MD2, and MD5) with the remote host (default=MD5). -This forces connection through the 'lan' IPMI interface , thus in IPMI 1.5 mode. +* Authentication types: ++ +Specifies the IPMI 1.5 authentication type to use (NONE, STRAIGHT_PASSWORD_KEY, +MD2, and MD5) with the remote host (default=MD5). +This forces connection through the 'lan' IPMI interface, thus in IPMI 1.5 mode. - 'none' (authentication is disabled) - 'MD2' @@ -215,14 +218,18 @@ This forces connection through the 'lan' IPMI interface , thus in IPMI 1.5 mode. - 'OEM' - 'RMCPplus' - :: -Cipher suite IDs: - :: -Specifies the IPMI 2.0 cipher suite ID to use. The Cipher Suite ID identifies a set of authentication, integrity, and -confidentiality algorithms to use for IPMI 2.0 communication. The authentication algorithm identifies the algorithm -to use for session setup, the integrity algorithm identifies the algorithm to use for session packet signatures, and the -confidentiality algorithm identifies the algorithm to use for payload encryption (default=3). - :: +* Cipher suite IDs: ++ +Specifies the IPMI 2.0 cipher suite ID to use. ++ +The Cipher Suite ID identifies a set of authentication, integrity, and +confidentiality algorithms to use for IPMI 2.0 communication. ++ +The authentication algorithm identifies the algorithm to use for session setup, +the integrity algorithm identifies the algorithm to use for session packet +signatures, and the confidentiality algorithm identifies the algorithm to +use for payload encryption (default=3). ++ The following cipher suite IDs are currently supported: + [options="header"] @@ -241,25 +248,26 @@ The following cipher suite IDs are currently supported: | '16' | HMAC-SHA256 | HMAC_SHA256_128 | None | '17' | HMAC-SHA256 | HMAC_SHA256_128 | AES-CBC-128 |=========================================================================== +-- *--scan-serial* ''*:: Scans for serial devices (of supported types) on the specified -serial ports. +serial port(s). EXAMPLES -------- To set alternative directory for configuration files: -*nutconf --local ~/test/nut/etc* + :; nutconf --local ~/test/nut/etc To add another user (keeping the existing ones): -*nutconf --add-user bart password=qwerty* + :; nutconf --add-user bart password=qwerty -To scan USB devices and serial devices (on the 1st two ports): +To scan USB devices and serial devices (on the first two ports): -*nutconf --scan-usb --scan-serial /dev/ttyS1 /dev/ttyS2* + :; nutconf --scan-usb --scan-serial /dev/ttyS1 /dev/ttyS2 SEE ALSO -------- diff --git a/docs/man/nutdrv_atcl_usb.txt b/docs/man/nutdrv_atcl_usb.txt index 3f8e12105c..d34d87f807 100644 --- a/docs/man/nutdrv_atcl_usb.txt +++ b/docs/man/nutdrv_atcl_usb.txt @@ -19,8 +19,8 @@ driver. For information about the core driver, see linkman:nutupsdrv[8]. SUPPORTED HARDWARE ------------------ -This driver is for UPS hardware which identifies itself as USB idVendor 0001 -and idProduct 0000, and iManufacturer +ATCL FOR UPS+. Known manufacturers +This driver is for UPS hardware which identifies itself as USB idVendor +0001+ +and idProduct +0000+, and iManufacturer +ATCL FOR UPS+. Known manufacturers include Kanji and Plexus. The UPS interface seems to be a generic USB-to-serial chip, and for @@ -31,7 +31,7 @@ linkman:genericups[8]), with no other dynamic status values reported. Note that these USB identifiers (including the iManufacturer string) have also been seen on devices that are supported by the `fuji` -subdriver of linkman:nutdrv_qx[8]. +subdriver of linkman:nutdrv_qx[8], and some others. EXTRA ARGUMENTS --------------- diff --git a/docs/man/nutdrv_qx.txt b/docs/man/nutdrv_qx.txt index b91eca2497..f70f175e50 100644 --- a/docs/man/nutdrv_qx.txt +++ b/docs/man/nutdrv_qx.txt @@ -22,16 +22,28 @@ linkman:nutupsdrv[8]. SUPPORTED HARDWARE ------------------ +The protocol originates from Mega System Technologies, Inc. in Taiwan +and was used by numerous vendors, as well as evolved over time, growing +both in features and nuance incompatibilities. NUT documentation usually +refers to this large family of similar dialects as the 'Megatec Q*' or +'Megatec Qx' protocol family. + The *nutdrv_qx* driver is known to work with various UPSes from 'Armac', 'Blazer', 'Energy Sistem', 'Fenton Technologies', 'General Electric', 'Hunnox', 'Masterguard', 'Mustek', 'Powercool', 'Voltronic Power', 'SKE' -(rebranded by many, many - have I said many? - others... +(rebranded by many, many -- have I said many? -- others... Long story short: if your UPS came with a software called 'Viewpower', chances are high that it works with this driver with one of the <<_extra_arguments,'voltronic*' protocols or with the 'mecer' one>>), and many others. +NOTE: Due to historical reasons, two important tunables of this driver are +somewhat inconveniently named *protocol* (for the Qx dialect) and *subdriver* +(for USB to serial link conversion). Other multi-dialect drivers refer to their +dialect modules as *subdrivers*, and actually the modular source code of +`nutdrv_qx` also does. + The <<_internet_resources,NUT compatibility table>> lists all the known supported models. Keep in mind, however, that other models not listed there may also be supported, but haven't been tested or reported back. @@ -60,7 +72,7 @@ Time to wait before shutting down the UPS (seconds). This value is truncated to units of 6 seconds (less than 60 seconds) or 60 seconds (more than 60 seconds). Defaults to 30 seconds. + -This option provides a default value for *ups.delay.shutdown* that will then be used by the driver in the automatic shutdown sequence (i.e. calling the driver with the *-k* option, calling linkman:upsdrvctl[8] with the *shutdown* option or when the +FSD+ flag is set and linkman:upsmon[8] enters its shutdown sequence): however you can change this value `on the fly' for the actual session, only for the use with instant commands, setting *ups.delay.shutdown* with linkman:upsrw[8]. +This option provides a default value for *ups.delay.shutdown* that will then be used by the driver in the automatic shutdown sequence (i.e. calling the driver with the *-k* option, calling linkman:upsdrvctl[8] with the *shutdown* option or when the +FSD+ flag is set and linkman:upsmon[8] enters its shutdown sequence): however you can change this value "on the fly" for the actual session, only for the use with instant commands, setting *ups.delay.shutdown* with linkman:upsrw[8]. *stayoff*:: If you set stayoff in linkman:ups.conf[5] when FSD arises the UPS will call a *shutdown.stayoff* shutting down after *ups.delay.shutdown* seconds and won't return (see <<_known_problems,KNOWN PROBLEMS>>), otherwise (standard behaviour) the UPS will call *shutdown.return* shutting down after *ups.delay.shutdown* seconds and then turn on after *ups.delay.start* seconds (if mains meanwhile returned). @@ -122,7 +134,7 @@ value as a multiple of *battery.packs* and "native" *battery.voltage*). + Note this is primarily useful for consistent diagnostics and graphing of the numbers, and should not impact the "guesstimation" of `battery.charge` and/or -`battery.runtime` - so rather a cosmetic adjustment, than critical. +`battery.runtime` -- so rather a cosmetic adjustment, than critical. *runtimecal =* 'value,value,value,value':: Parameter used in the (optional) runtime estimation. @@ -333,7 +345,7 @@ TESTING This protocol comes with a couple of functions that are not enabled by default because of the lack of knowledge of some part of the communication protocol used by these UPSes by your friendly neighborhood developer. Since these functions are supposed to be queries to the UPS for some kind of information, they _should_ not make your UPS go boom. -So if you are brave enough to risk your UPS and attached devices' life to help the developers, this will be very appreciated.. +So if you are brave enough to risk your UPS and attached devices' life to help the developers, this will be very appreciated. *Do it at your own risk*. *testing*:: @@ -610,7 +622,7 @@ It no longer defaults to 0 minutes but to 3 minutes (i.e. 180 seconds) for compa *battnumb*:: This option has been renamed to *battery_number*. -The following options are no longer supported by this driver, you can now change them more conveniently `on the fly' calling linkman:upsrw[8] with the appropriate NUT variable - provided that your UPS supports them. +The following options are no longer supported by this driver, you can now change them more conveniently "on the fly" calling linkman:upsrw[8] with the appropriate NUT variable -- provided that your UPS supports them. [horizontal] *battpacks*:: -> *battery.packs* @@ -739,7 +751,7 @@ Since more than one warning at a time can be signaled, and because of the limite If you want to know the explanation of that bit you can either watch the log or see the next table (unlisted bits equal to unknown warnings). .UPS Warnings for 'voltronic' UPSes -[cols="5>,95",options="autowidth,header",frame="topbot",grid="rows",align="center",caption=""] +[cols="5,95",options="autowidth,header",frame="topbot",grid="rows",align="center",caption=""] |==== |# |Corresponding Warning |1 |Battery disconnected diff --git a/docs/man/nutdrv_siemens_sitop.txt b/docs/man/nutdrv_siemens_sitop.txt index 87bf629a16..11a2fe4883 100644 --- a/docs/man/nutdrv_siemens_sitop.txt +++ b/docs/man/nutdrv_siemens_sitop.txt @@ -4,7 +4,7 @@ NUTDRV_SIEMENS_SITOP(8) NAME ---- -nutdrv_siemens_sitop - driver for the Siemens SITOP UPS500 series UPS +nutdrv_siemens_sitop - Driver for the Siemens SITOP UPS500 series UPS SYNOPSIS -------- @@ -66,7 +66,7 @@ USB driver The USB-versions of the UPS contain an FTDI USB-to-serial converter chip. It is programmed with a non-standard product ID (for example _0403:e0e3_), -but can still be used with the normal ftdi_sio driver. +but can still be used with the normal `ftdi_sio` driver. NOTE: The following hints may be specific to GNU/Linux. @@ -79,7 +79,7 @@ modprobe ftdi_sio echo 0403 e0e3 > /sys/bus/usb-serial/drivers/ftdi_sio/new_id .... -If your system uses *udev*, this can be automated via a udev rule: +If your system uses *udev*, this can be automated via an *udev* rule: ---- ACTION=="add", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="e0e3", \ @@ -88,7 +88,7 @@ ACTION=="add", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="e0e3", \ ---- You can use the following udev rule to obtain a predictable device name, -for example _/dev/ttyUPS_: +for example `/dev/ttyUPS`: ---- SUBSYSTEM=="tty" ATTRS{idVendor}=="0403", ATTRS{idProduct}=="e0e3" SYMLINK+="ttyUPS" ---- @@ -113,7 +113,8 @@ This driver supports the following optional settings: The serial port is polled periodically for new data (see *Polling*). If there is no valid new data after 'num' polls, it is assumed that communication with the UPS is lost. -The default value is 2. Lower values may cause spurious 'Data stale' ++ +The default value is '2'. Lower values may cause spurious 'Data stale' messages, especially at startup. INSTANT COMMANDS @@ -144,7 +145,7 @@ Make sure that your operating system has created a serial device for the UPS. See the section *USB driver* for more information. Next, make sure that NUT has access rights to this device file. -For example, by creating a udev rule that grants permission to the NUT user, +For example, by creating an udev rule that grants permission to the NUT user, or by adding the NUT user to a user group that can access serial devices (e.g. the *dialout* group on Debian-based systems). @@ -152,10 +153,10 @@ DIAGNOSTICS ----------- You can verify the correct functioning of the hardware, by monitoring the -serial port with a terminal program, for example picocom: +serial port with a terminal program, for example `picocom`: .... -picocom -b 9600 -d 8 -p n /dev/ttyUPS +:; picocom -b 9600 -d 8 -p n /dev/ttyUPS .... NUT must not be running when you do this. @@ -181,12 +182,15 @@ The firmware in these UPSes is quite buggy. After sending data to the UPS, it sometimes stops sending status updates. This driver tries to prevent this (e.g. by sending commands twice, and by sending additional LF characters after each command). ++ Once the UPS is in this state, communication can only be restored by rebooting the UPS, or by unplugging and reconnecting the USB cable. ++ During normal operation, no commands are sent to the UPS at all (only at shutdown), so this issue is expected to have little impact on usability. -It is not sure if the serial models are affected by this issue as well. ++ +It is not certain if the serial models are affected by this issue as well. AUTHOR ------ diff --git a/docs/man/nutscan_add_option_to_device.txt b/docs/man/nutscan_add_option_to_device.txt index bed9a087f5..478911e936 100644 --- a/docs/man/nutscan_add_option_to_device.txt +++ b/docs/man/nutscan_add_option_to_device.txt @@ -50,7 +50,7 @@ The *nutscan_add_option_to_device()* adds an optional data in the given 'device'. Optional data are made of an 'option_name' and an associated 'value', and optionally a 'comment_tag'. Copies of the 'option_name', 'value' and 'comment_tag' are stored in the 'device', -so the caller can safely linkman:free[3] all of the original strings +so the caller can safely linkmanext:free[3] all of the original strings used as arguments. NOTE: A non-`NULL` value of the 'comment_tag' makes the option not-enabled diff --git a/docs/man/nutscan_cidr_to_ip.txt b/docs/man/nutscan_cidr_to_ip.txt index f631431140..ff539e82b6 100644 --- a/docs/man/nutscan_cidr_to_ip.txt +++ b/docs/man/nutscan_cidr_to_ip.txt @@ -23,7 +23,7 @@ the CIDR format given as a string in 'cidr', to two IPs in strings pointed by 'start_ip' and 'stop_ip' which can be used as input parameters in the scanning functions of the libnutscan API. -It is the caller's responsibility to linkman:free[3] the 'start_ip' +It is the caller's responsibility to linkmanext:free[3] the 'start_ip' and 'stop_ip' strings. RETURN VALUE diff --git a/docs/man/nutupsdrv.txt b/docs/man/nutupsdrv.txt index 598318bf93..55b47ae38f 100644 --- a/docs/man/nutupsdrv.txt +++ b/docs/man/nutupsdrv.txt @@ -4,7 +4,7 @@ NUTUPSDRV(8) NAME ---- -nutupsdrv - generic manual for unified NUT drivers +nutupsdrv - Generic manual for unified NUT drivers SYNOPSIS -------- @@ -40,13 +40,15 @@ systems attached must be turned off to ensure a proper reboot when power returns. In the third mode, using *-d*, the driver will exit after some update loops, -dumping the data tree (in upsc-like format) to stdout. This can be useful to -complement the nut-scanner to discover devices, along with in-depth data. +dumping the data tree (in linkman:upsc[8]-like format) to `stdout`. +This can be useful to complement the linkman:nut-scanner[8] to discover +devices, along with in-depth data. -NOTE: You probably don't want to use any of these options directly. You -should use linkman:upsdrvctl[8] to control your drivers, and -linkman:ups.conf[5] to configure them. The rest of this manual describes -options and parameters that generally are not needed by normal users. +NOTE: You probably don't want to use any of these options directly. +You should use linkman:upsdrvctl[8] (or linkman:upsdrvsvcctl[8] on systems +with a service management framework like systemd or SMF) to control your +drivers, and linkman:ups.conf[5] to configure them. The rest of this manual +describes options and parameters that generally are not needed by normal users. OPTIONS ------- @@ -65,14 +67,14 @@ Configure this driver only with command line arguments instead of reading linkman:ups.conf[5]. To be used instead of *-a* option when need to run a driver not present in driver configuration file. Instead, driver configuration have to be set with *-x* options directly in the command line. -As the driver instance cannot be controlled by linkman:upsdrvctl[8], -this option should be used for specific needs only. +As such driver instance cannot be controlled by linkman:upsdrvctl[8] or +linkman:upsdrvsvcctl[8], this option should be used for specific needs only. *-D*:: Raise the debugging level. Use this multiple times to see more details. Running a driver in debug mode will (by default) prevent it from backgrounding after startup. It will keep on logging information to the console until it -receives a SIGINT (usually Ctrl-C) or SIGTERM signal. +receives a *SIGINT* (usually Ctrl-C) or *SIGTERM* signal. + The level of debugging needed depends both on the driver and the problem you're trying to diagnose. Therefore, first explain the problem you @@ -81,11 +83,13 @@ output. More often than not, if you just pick a level, the output may be either too limited or too verbose to be of any use. *-d* 'update_count':: -Dump the data tree (in upsc-like format) to stdout after running the driver -update loop for 'update_count' times and exit. +Dump the data tree (in linkman:upsc[8]-like format) to `stdout` after running +the driver update loop for the specified 'update_count' times and exit. ++ By default this prevents the driver process from backgrounding after startup. Note that the driver banner will be printed too, so when using this option in -scripts, don't forget to trim the first line. +scripts, don't forget to trim the first line, or use the `NUT_QUIET_INIT_BANNER` +environment variable. *-q*:: Raise log level threshold. Use this multiple times to log more details. @@ -118,7 +122,7 @@ are: (so an external caller like the new driver instance, or the systemd or SMF frameworks would start another copy) -With recent NUT releases, such commands can be sent using the Unix socket +With recent NUT v2.8.x releases, such commands can be sent using the Unix socket for driver-server interaction. As a fallback, like older releases, signals can be sent to the old driver instance's PID (where possible). @@ -151,22 +155,25 @@ wizard programs. ("Kill" power) Forced shutdown mode. The UPS will power off the attached load, if possible. + -You should use +upsdrvctl shutdown+ whenever possible instead of -calling this directly. +You should use `upsdrvctl shutdown` whenever possible instead of +calling this directly. Note that the constrained operating system +context for shutdown typically rules out use of `upsdrvsvcctl shutdown`. *-r* 'directory':: -The driver will chroot(2) to 'directory' during initialization. +The driver will linkmanext:chroot[2] to 'directory' during initialization. This can be useful when securing systems. + -In addition to the state path, many systems will require /dev/null to +In addition to the state path, many systems will require `/dev/null` to exist within 'directory' for this to work. The serial ports are -opened before the chroot call, so you do not need to create them inside -the jail. In fact, it is somewhat safer if you do not. +opened before the `chroot` call, so you do not need to create them inside +the jail. In fact, it is somewhat safer if you do not (but reconnection +to devices may be no longer possible and could require a full restart of +the driver). *-u* 'username':: Override the unprivileged username that the driver may use after startup. If started as root, after opening configuration files (and optionally calling -chroot(2), as described in the previous option), the driver will look up +linkmanext:chroot[2], as described in the previous option), the driver will look up 'username' in the `passwd` database, then change to the user and group identities associated with 'username'. (If started with a nonzero UID or effective UID, the driver will silently ignore this option.) @@ -185,8 +192,8 @@ to set permissions for the filesystem socket so `upsd` may still access it if the run-time `user` of the driver normally would deny that access. *-x* 'var'='val':: -Define a variable called 'var' with the value of 'var' in the -driver. This varies from driver to driver - see the specific man pages +Define a variable called 'var' with the value of 'var' in the driver. +This varies from driver to driver -- see their specific man pages for more information. + This is like setting 'var'='val' in linkman:ups.conf[5], but @@ -195,17 +202,20 @@ This is like setting 'var'='val' in linkman:ups.conf[5], but DIAGNOSTICS ----------- -Information about the startup process is printed to stdout. Additional -messages after that point are available in the syslog. After linkman:upsd[8] -starts, the UPS clients such as linkman:upsc[8] can be used to query the status -of an UPS. +Information about the startup process is printed to `stdout` and/or `stderr`. +Additional messages after that point are only available in the syslog, unless +the driver remains in foreground (e.g. due to raised debugging verbosity). + +After linkman:upsd[8] starts, the UPS clients such as linkman:upsc[8] can +be used to query the status of an UPS. PROGRAM CONTROL --------------- -You should always use linkman:upsdrvctl[8] to control the drivers. While -drivers can be started by hand for testing purposes, it is not recommended for -production use. +You should always use linkman:upsdrvctl[8] (or linkman:upsdrvsvcctl[8] on +systems with a service management framework like systemd or SMF) to control +the drivers. While drivers can be started by hand for testing purposes, +it is not recommended for production use. FILES ----- diff --git a/docs/man/oneac.txt b/docs/man/oneac.txt index b6fda081fc..50e504a190 100644 --- a/docs/man/oneac.txt +++ b/docs/man/oneac.txt @@ -106,11 +106,11 @@ Writable Variables See linkman:upsrw[8] to see what variables are writable for the UPS. -NOTE: If your UPS supports writing battery.runtime.low, the new set value -is to be entered in minutes (up to 99) but the reported value is reported -in seconds (set value * 60). +NOTE: If your UPS supports writing `battery.runtime.low`, the new set value +is to be entered in minutes (up to '99') but the reported value is reported +in seconds (set 'value * 60'). -NOTE: If your UPS supports input.transfer.low and input.transfer.high, +NOTE: If your UPS supports `input.transfer.low` and `input.transfer.high`, those values are used to create an allowable output range. The UPS will do what it can to keep the output voltage value within the defined range (for example: tap change or switch to inverter). diff --git a/docs/man/phoenixcontact_modbus.txt b/docs/man/phoenixcontact_modbus.txt index a9f22cdc05..c5b285c3cd 100644 --- a/docs/man/phoenixcontact_modbus.txt +++ b/docs/man/phoenixcontact_modbus.txt @@ -22,8 +22,7 @@ SUPPORTED HARDWARE This driver should support the PhoenixContact QUINT-UPS industrial DC UPS, model 2320461 and all compatible models. More information about this UPS -can be found here: -https://www.phoenixcontact.com/online/portal/us?uri=pxc-oc-itemdetail:pid=2320461 +can be found among <<_internet_resources,Internet resources>> below. phoenixcontact_modbus uses the libmodbus project, for Modbus implementation. @@ -34,7 +33,7 @@ Note: this UPS and its manual refers to Low-Batt as "Shutdown Event". You need the "IFS-RS232-DATACABLE" to communicate with the UPS in Linux as the IFS-USB cable doesn't seem to be supported. FYI communication -parameters are: 115200,E,8,1. +parameters are: `115200,E,8,1`. You also need the UPS-CONF Windows software (free; download from their site), to configure the UPS signals and timers. @@ -76,11 +75,11 @@ This driver doesn't support any optional settings. INSTALLATION ------------ -This driver is not built by default. You can build it by installing +This driver may be not built by default. You can build it by installing libmodbus and running `configure --with-modbus=yes`. You also need to give proper permissions on the local serial device file -(/dev/ttyS0 for example) to allow the NUT user to access it. +(`/dev/ttyS0` for example) to allow the NUT user to access it. INSTANT COMMANDS ---------------- @@ -105,3 +104,6 @@ Internet resources: * The NUT (Network UPS Tools) home page: https://www.networkupstools.org/ * libmodbus home page: http://libmodbus.org +* More information about PhoenixContact QUINT-UPS industrial DC UPS, + model 2320461 UPS series can be found here: + https://www.phoenixcontact.com/online/portal/us?uri=pxc-oc-itemdetail:pid=2320461 diff --git a/docs/man/pijuice.txt b/docs/man/pijuice.txt index f97bce4bb0..5d415d2f7e 100644 --- a/docs/man/pijuice.txt +++ b/docs/man/pijuice.txt @@ -4,7 +4,7 @@ PIJUICE(8) NAME ---- -pijuice - driver for UPS in PiJuice HAT +pijuice - Driver for UPS in PiJuice HAT SYNOPSIS -------- @@ -45,7 +45,7 @@ This driver is specific to the Linux I2C API, and requires the lm_sensors libi2c-dev or its equivalent to compile. Beware that the SystemIO memory used by the I2C controller is reserved by ACPI. -If only a native I2C driver (e.g. i2c_i801, as of 3.5.X Linux kernels) is +If only a native I2C driver (e.g. `i2c_i801`, as of 3.5.X Linux kernels) is available, then you'll need to relax the ACPI resources check. For example, you can boot with the `acpi_enforce_resources=lax` option. diff --git a/docs/man/powerman-pdu.txt b/docs/man/powerman-pdu.txt index 30d2fcda97..296f46a5ed 100644 --- a/docs/man/powerman-pdu.txt +++ b/docs/man/powerman-pdu.txt @@ -33,8 +33,8 @@ This driver doesn't support any optional settings. INSTALLATION ------------ -This driver is not built by default. You can build it by using -"configure --with-powerman=yes". +This driver may be not built by default. You can build it by installing +prerequisites and using `configure --with-powerman=yes`. UPS COMMANDS ------------ @@ -69,8 +69,8 @@ The port used to reach 'powermand' is optional if the default port is used. KNOWN ISSUES ------------ -In the current NUT version as of this writing (2.4.1), ups.status is still -exposed, with the value "WAIT". Some other values from the ups collection +In the current NUT version as of this writing (2.4.1), `ups.status` is still +exposed, with the value "WAIT". Some other values from the `ups` collection are also exposed. AUTHOR diff --git a/docs/man/richcomm_usb.txt b/docs/man/richcomm_usb.txt index fd37343400..638b7d5a0a 100644 --- a/docs/man/richcomm_usb.txt +++ b/docs/man/richcomm_usb.txt @@ -23,8 +23,8 @@ SUPPORTED HARDWARE The Richcomm dry-contact to USB solution is a generic interface that is used to upgrade an existing (RS-232) contact closure UPS interface to USB. As such, all the limitations of the underlying contact closure interface -apply. This means that you will only get the essentials in ups.status: OL, -OB, and LB. See also linkman:genericups[8]. +apply. This means that you will only get the essentials in `ups.status`: +`OL`, `OB`, and `LB`. See also linkman:genericups[8]. //////// TODO: Uncomment after solving https://github.com/networkupstools/nut/issues/1768 diff --git a/docs/man/skel.txt b/docs/man/skel.txt index 034e3034af..7a5a32f7a9 100644 --- a/docs/man/skel.txt +++ b/docs/man/skel.txt @@ -4,7 +4,7 @@ SKEL(8) NAME ---- -skel - skeleton driver man page +skel - Skeleton driver man page SYNOPSIS -------- diff --git a/docs/man/snmp-ups.txt b/docs/man/snmp-ups.txt index 221e081ab1..086a0dc6b1 100644 --- a/docs/man/snmp-ups.txt +++ b/docs/man/snmp-ups.txt @@ -91,25 +91,26 @@ There is no default for the hostname, but the default port is 161. *mibs*='--list':: A special option which allows to list the currently known MIB-to-NUT mappings and exit the driver binary, intended for command-line usage like this: ++ ---- -$ snmp-ups -a snmp-test -x mibs=--list +:; snmp-ups -a snmp-test -x mibs=--list ---- *mibs*='name':: -Set MIB compliance (default=auto, allowed entries: refer to SUPPORTED +Set MIB compliance (default='auto', allowed entries: refer to SUPPORTED HARDWARE above). + With "auto", the driver will try a select set of SNMP objects until it finds one that the device responds to. + -Note that since NUT 2.6.2, snmp-ups has a new method that uses sysObjectID +Note that since NUT 2.6.2, snmp-ups has a new method that uses `sysObjectID` (which is a pointer to the preferred MIB of the device) to detect supported devices. This renders void the *requirement* to use the "mibs" option. *community*='name':: -Set community name (default = public). -Note that a RW community name is required to change UPS settings and -send commands (as for a powerdown). +Set community name (default is 'public') for SNMPv1 and SNMPv2c connections. +Note that an RW capable community name is required to change UPS settings and +send commands (such as for a power-down). *snmp_version*='version':: Set SNMP version (default = v1, allowed: v2c, v3) diff --git a/docs/man/sockdebug.txt b/docs/man/sockdebug.txt index 6bcd6e4017..bf78333561 100644 --- a/docs/man/sockdebug.txt +++ b/docs/man/sockdebug.txt @@ -14,11 +14,11 @@ SYNOPSIS For example (WIN32 and POSIX builds): - sockdebug.exe dummy-ups-UPS1 + :; sockdebug.exe dummy-ups-UPS1 For example (POSIX-compliant systems using an alternate state path): - sockdebug /var/state/ups/dummy-ups-UPS1 + :; sockdebug /var/state/ups/dummy-ups-UPS1 DESCRIPTION ----------- @@ -60,7 +60,7 @@ in the current directory, and then fall back to configured (built-in) state path or the value of `NUT_STATEPATH` environment variable, if set; e.g.: + ------ - NUT_STATEPATH=/tmp ./server/sockdebug dummy-ups-UPS1 +:; NUT_STATEPATH=/tmp ./server/sockdebug dummy-ups-UPS1 ------ AUTHORS diff --git a/docs/man/socomec_jbus.txt b/docs/man/socomec_jbus.txt index 8d0fecd552..46ec4775ae 100644 --- a/docs/man/socomec_jbus.txt +++ b/docs/man/socomec_jbus.txt @@ -71,7 +71,7 @@ This driver should be built by default if libmodbus and development headers are available. You can force the `configure` script to build it with the following arguments: - configure --with-serial=yes --with-modbus=yes + :; ./configure --with-serial=yes --with-modbus=yes You also need to give proper (R/W) permissions on the local serial device file to allow the NUT driver run-time user to access it. This may need @@ -102,15 +102,15 @@ KNOWN ISSUES AND BUGS Well, it is an alpha release at best, but so far appears to report the UPS status reliably. Mostly based on the work of Yifeng Li on -the huawei-ups2000 in that very same source tree. +the linkman:huawei-ups2000[8] in that very same source tree. Read failure on some JBUS addresses ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The driver polls all documented JBUS addresses and it is quite possible +The driver polls all documented JBUS addresses, and it is quite possible that your UPS model does not support one of them (e.g. the Digys does not -support address 0x1020 which should provide the current UPS status). -This should be logged with LOG_ERR from modbus_read_input_registers() +support address '0x1020' which should provide the current UPS status). +This should be logged with `LOG_ERR` from `modbus_read_input_registers()` along with the address that produced the error. Data stale @@ -141,7 +141,7 @@ from USB, at least briefly. This creates a permanent data stale, the driver must be restarted (plugging the USB back won't fix it, since the driver is still using the nonexistent serial device). These USB problems usually have nothing to do with NUT. If it's the case, you should solve the -underlying USB problem - check the cable, check the converter, try a +underlying USB problem -- check the cable, check the converter, try a powered USB hub, try a full-speed USB isolator, etc. AUTHOR diff --git a/docs/man/tripplite_usb.txt b/docs/man/tripplite_usb.txt index 087a310aa4..9f7c524216 100644 --- a/docs/man/tripplite_usb.txt +++ b/docs/man/tripplite_usb.txt @@ -18,13 +18,13 @@ SUPPORTED HARDWARE This driver should work with older Tripp Lite UPSes which are detected as USB HID-class devices, but are not true HID Power-Device Class devices. -So far, the devices supported by `tripplite_usb` have product ID 0001, +So far, the devices supported by `tripplite_usb` have product ID '0001', and the newer units (such as those with "LCD" in the model name) with -product ID 2001 require the linkman:usbhid-ups[8] driver instead. +product ID '2001' require the linkman:usbhid-ups[8] driver instead. Please report success or failure to the nut-upsuser mailing list. A key piece of information is the protocol number, returned in -`ups.firmware.aux`. Also, be sure to turn on debugging ('-DDD') +`ups.firmware.aux`. Also, be sure to turn on debugging (`-DDD`) for more informative log messages. If your Tripp Lite UPS uses a serial port, you may wish to investigate @@ -41,7 +41,7 @@ This driver has been tested with the following models: * SMART3000RM2U If you have used Tripp Lite's PowerAlert software to connect to your UPS, -there is a good chance that 'tripplite_usb' will work if it uses one of the +there is a good chance that `tripplite_usb` will work if it uses one of the following protocols: * Protocol 0004 @@ -65,8 +65,8 @@ include::nut_usb_addvars.txt[] - `-x upsid="12345"` -Select a specific UPS by its unique UPS ID. The argument is a regular expression -that must match the UPS ID string. This allows for precise identification of UPS +Select a specific UPS by its unique UPS ID. The argument is a regular expression +that must match the UPS ID string. This allows for precise identification of UPS devices when multiple devices of the same make and model are connected. See below regarding how to read and write the ups id (unit id) using linkman:upsrw[8]. @@ -151,8 +151,8 @@ same time, since they have different USB Product ID strings. If you have two SMART1500RM2U units, you would have to find which USB bus and device number each unit is on (via lsusb(8)). -Some of the SMART*2U models have a configurable Unit ID number, and you can now use the `upsid` -config argument to uniquely specify which UPS a given driver instance should control. +Some of the SMART*2U models have a configurable Unit ID number, and you can now use the `upsid` +config argument to uniquely specify which UPS a given driver instance should control. This allows for precise identification of UPS devices when multiple devices are connected. To retrieve or set the upsid use the linkman:upsrw[8] utility. @@ -162,7 +162,7 @@ AUTHORS Written by Charles Lepple, based on the linkman:tripplite[8] driver by Rickard E. (Rik) Faith and Nicholas Kain. -Please do not email the authors directly - use the nut-upsdev mailing list. +Please do not email the authors directly -- use the nut-upsdev mailing list. A Tripp Lite OMNIVS1000 was graciously donated to the NUT project by Bradley Feldman (http://www.bradleyloritheo.com) diff --git a/docs/man/ups.conf.txt b/docs/man/ups.conf.txt index dcdee66aac..a29b399385 100644 --- a/docs/man/ups.conf.txt +++ b/docs/man/ups.conf.txt @@ -17,7 +17,7 @@ which contains a number of directives that set parameters for that UPS. A UPS section begins with the name of the UPS in brackets, and continues until the next UPS name in brackets or until EOF. The name "default" is -used internally in upsd, so you can't use it in this file. +used internally in linkman:upsd[8], so you can't use it in this file. You must define the 'driver' and 'port' elements for each entry. Anything after that in a section is optional. A simple example might look like this: diff --git a/docs/man/upsc.txt b/docs/man/upsc.txt index 91e16965e0..7fe8a6b845 100644 --- a/docs/man/upsc.txt +++ b/docs/man/upsc.txt @@ -57,9 +57,9 @@ EXAMPLES -------- To list all variables on an UPS named "myups" on a host -called "mybox", with upsd(8) running on port 1234: +called "mybox", with linkman:upsd[8] running on port '1234': - $ upsc myups@mybox:1234 + :; upsc myups@mybox:1234 battery.charge: 100.0 battery.voltage: 13.9 battery.voltage.nominal: 13.6 @@ -67,20 +67,20 @@ called "mybox", with upsd(8) running on port 1234: To list the UPSes configured on this system, along with their descriptions: - $ upsc -L + :; upsc -L apc: Back-UPS 500 ppro2: Patriot Pro II To retrieve the status for all UPSes connected to mybox, using Bourne-shell syntax: - $ for UPS in `upsc -l mybox:1234`; do + :; for UPS in `upsc -l mybox:1234`; do upsc $UPS ups.status done To list clients connected on "myups": - $ upsc -c myups + :; upsc -c myups 127.0.0.1 ::1 192.168.1.2 diff --git a/docs/man/upscli_splitaddr.txt b/docs/man/upscli_splitaddr.txt index ea923dcccc..38f1a58090 100644 --- a/docs/man/upscli_splitaddr.txt +++ b/docs/man/upscli_splitaddr.txt @@ -36,7 +36,7 @@ Definitions without an explicit port value receive the default value of MEMORY USAGE ------------ -You must linkman:free[3] the pointer 'hostname' when you are done +You must linkmanext:free[3] the pointer 'hostname' when you are done with it to avoid memory leaks. RETURN VALUE diff --git a/docs/man/upscli_splitname.txt b/docs/man/upscli_splitname.txt index 89646bbd09..7e45078e02 100644 --- a/docs/man/upscli_splitname.txt +++ b/docs/man/upscli_splitname.txt @@ -40,7 +40,7 @@ Definitions without an explicit port value receive the default value of MEMORY USAGE ------------ -You must linkman:free[3] the pointers to 'upsname' and 'hostname' +You must linkmanext:free[3] the pointers to 'upsname' and 'hostname' when you are done with them to avoid memory leaks. RETURN VALUE diff --git a/docs/man/upscmd.txt b/docs/man/upscmd.txt index b60cab9843..05225269ac 100644 --- a/docs/man/upscmd.txt +++ b/docs/man/upscmd.txt @@ -4,7 +4,7 @@ UPSCMD(8) NAME ---- -upscmd - UPS administration program for instant commands +upscmd - Network UPS Tools device/driver instant commands administration tool SYNOPSIS -------- @@ -19,6 +19,10 @@ DESCRIPTION ----------- *upscmd* allows you to invoke "instant commands" in your UPS hardware. +It sends commands via the server linkman:upsd[8] to your driver, which +manages the hardware for you. You must use credentials defined in +linkman:upsd.users[5] file on that data server with appropriate permissions. + Not all hardware supports this, so check the list with -l to see if anything will work on your equipment. diff --git a/docs/man/upsd.conf.txt b/docs/man/upsd.conf.txt index 9101ffe201..a79355f656 100644 --- a/docs/man/upsd.conf.txt +++ b/docs/man/upsd.conf.txt @@ -4,14 +4,14 @@ UPSD.CONF(5) NAME ---- -upsd.conf - Configuration for Network UPS Tools upsd +upsd.conf - Configuration for Network UPS Tools upsd data server DESCRIPTION ----------- -upsd uses this file to control access to the server and set some other -miscellaneous configuration values. This file contains details on -access controls, so keep it secure. Ideally, only the upsd process +linkman:upsd[8] uses this file to control access to the server and set some +other miscellaneous configuration values. This file contains details on +access controls, so keep it secure. Ideally, only the `upsd` process should be able to read it. IMPORTANT NOTES @@ -42,22 +42,22 @@ IMPORTANT NOTES CONFIGURATION DIRECTIVES ------------------------ -"MAXAGE 'seconds'":: +*MAXAGE 'seconds'*:: -upsd usually allows a driver to stop responding for up to 15 seconds +`upsd` usually allows a driver to stop responding for up to 15 seconds before declaring the data "stale". If your driver takes a very long -time to process updates but is otherwise operational, you can use MAXAGE -to make upsd wait longer. +time to process updates but is otherwise operational, you can use `MAXAGE` +to make `upsd` wait longer. + Most users should leave this at the default value. -"TRACKINGDELAY 'seconds'":: +*TRACKINGDELAY 'seconds'*:: When instant commands and variables setting status tracking is enabled, status execution information are kept during this amount of time, and then cleaned up. This defaults to 3600 (1 hour). -"ALLOW_NO_DEVICE 'Boolean'":: +*ALLOW_NO_DEVICE 'Boolean'*:: Normally upsd requires that at least one device section is defined in ups.conf when the daemon starts, to serve its data. For automatically managed services @@ -73,14 +73,14 @@ unless the calling environment sets a same-named variable to enforce a value for the current run. One way this can happen is somebody un-commenting it in the 'nut.conf' file used by init-scripts and service unit method scripts. -"ALLOW_NOT_ALL_LISTENERS 'Boolean'":: +*ALLOW_NOT_ALL_LISTENERS 'Boolean'*:: Normally upsd requires that all `LISTEN` directives can be honoured at the moment the daemon starts. If your LAN IP address (or host name) used in one of the `LISTEN` directives may be not always accessible, and for some reason do not want to just `LISTEN *` on the wildcard interface, but e.g. you still want to use `upsmon` on `localhost`, this option can help. Note you would -have to restart `upsd` to pick up the `LISTEN`ed IP address if it appears +have to restart `upsd` to pick up the `LISTEN`'ed IP address if it appears later. + Boolean values 'true', 'yes', 'on' and '1' mean that the server would not @@ -93,9 +93,9 @@ environment sets a same-named variable to enforce a value for the current run. One way this can happen is somebody un-commenting it in the 'nut.conf' file used by init-scripts and service unit method scripts. -"STATEPATH 'path'":: +*STATEPATH 'path'*:: -Tell upsd to look for the driver state sockets in 'path' rather +Tell `upsd` to look for the driver state sockets in 'path' rather than the default that was compiled into the program. + Note that the drivers must use the same path, so `upsd` would prefer the @@ -104,7 +104,7 @@ same-named setting from `ups.conf` global section, if present, over its own. Environment variable `NUT_STATEPATH` set by caller (e.g. init script or service method) can override this setting. -"LISTEN 'interface' 'port'":: +*LISTEN 'interface' 'port'*:: Bind a listening port to the interface specified by its Internet address or name. This may be useful on hosts with multiple interfaces. @@ -113,11 +113,11 @@ on many systems. + Optionally listen on TCP port 'port' instead of the default value which was compiled into the code. This overrides any value you may have set with -'configure --with-port'. If you don't change it with configure or this value, -upsd will listen on port 3493 for this interface. +`configure --with-port`. If you don't change it with configure or this value, +`upsd` will listen on port '3493' for this interface. + -Multiple LISTEN addresses may be specified. The default is to bind to -`127.0.0.1` if no LISTEN addresses are specified (and also `::1` if IPv6 +Multiple `LISTEN` addresses may be specified. The default is to bind to +`127.0.0.1` if no `LISTEN` addresses are specified (and also `::1` if IPv6 support is compiled in). + To listen on all available interfaces and configured IP addresses of your @@ -136,7 +136,7 @@ socket to handle both address families. LISTEN 2001:0db8:1234:08d3:1319:8a2e:0370:7344 + This parameter will only be read at startup. You'll need to restart -(rather than reload) upsd to apply any changes made here. +(rather than merely reload) `upsd` to apply any changes made here. + Please note that older NUT releases could have been using the IPv4-mapped IPv6 addressing (sometimes also known as "dual-stack") mode, if provided @@ -144,25 +144,26 @@ by the system. Current versions (since NUT v2.8.1 release) explicitly try to restrict their listening sockets to only support one address family on each socket, and so avoid IPv4-mapped mode where possible. -"MAXCONN 'connections'":: +*MAXCONN 'connections'*:: This defaults to maximum number allowed on your system. Each UPS, each -LISTEN address and each client count as one connection. If the server +`LISTEN` address and each client count as one connection. If the server runs out of connections, it will no longer accept new incoming client connections. Only set this if you know exactly what you're doing. -"CERTFILE 'certificate file'":: +*CERTFILE 'certificate file'*:: When compiled with SSL support with OpenSSL backend, you can enter the certificate file here. + The certificates must be in PEM format and must be sorted starting with the subject's certificate (server certificate), followed by intermediate -CA certificates (if applicable_ and the highest level (root) CA. It should -end with the server key. See 'docs/security.txt' or the Security chapter of -NUT user manual for more information on the SSL support in NUT. +CA certificates (if applicable) and the highest level (root) CA. It should +end with the server key. See `docs/security.txt` in NUT sources, or the +Security chapter of NUT user manual, for more information on the SSL +support in NUT. -"CERTPATH 'certificate database'":: +*CERTPATH 'certificate database'*:: When compiled with SSL support with NSS backend, you can enter the certificate path here. @@ -170,7 +171,7 @@ certificate path here. Certificates are stored in a dedicated database (data split in 3 files). Specify the path of the database directory. -"CERTIDENT 'certificate name' 'database password'":: +*CERTIDENT 'certificate name' 'database password'*:: When compiled with SSL support with NSS backend, you can specify the certificate name to retrieve from database to authenticate itself and @@ -179,34 +180,35 @@ the password required to access certificate related private key. NOTE: Be sure to enclose "certificate name" in double-quotes if you are using a value with spaces in it. -"CERTREQUEST 'certificate request level'":: +*CERTREQUEST 'certificate request level'*:: When compiled with SSL support with NSS backend and client certificate -validation (disabled by default, see 'docs/security.txt'), -you can specify if upsd requests or requires client's' certificates. +validation (disabled by default, see `docs/security.txt` in NUT sources), +you can specify if `upsd` requests or requires clients' certificates. ++ +Possible values are: + -Possible values are : - '0' to not request to clients to provide any certificate - '1' to require to all clients a certificate - '2' to require to all clients a valid certificate -"DISABLE_WEAK_SSL 'BOOLEAN'":: +*DISABLE_WEAK_SSL 'BOOLEAN'*:: -Tell upsd to disable older/weak SSL/TLS protocols and ciphers. +Tell `upsd` to disable older/weak SSL/TLS protocols and ciphers. With relatively recent versions of OpenSSL or NSS it will be restricted to TLSv1.2 or better. + Unless you have really ancient clients, you probably want to enable this. Currently disabled by default to ensure compatibility with existing setups. -"DEBUG_MIN 'INTEGER'":: +*DEBUG_MIN 'INTEGER'*:: Optionally specify a minimum debug level for `upsd` data daemon, e.g. for troubleshooting a deployment, without impacting foreground or background running mode directly. Command-line option `-D` can only increase this verbosity level. + -NOTE: if the running daemon receives a `reload` command, presence of the +NOTE: If the running daemon receives a `reload` command, presence of the `DEBUG_MIN NUMBER` value in the configuration file can be used to tune debugging verbosity in the running service daemon (it is recommended to comment it away or set the minimum to explicit zero when done, to avoid diff --git a/docs/man/upsd.txt b/docs/man/upsd.txt index cea2389f46..c2a9a6c947 100644 --- a/docs/man/upsd.txt +++ b/docs/man/upsd.txt @@ -4,7 +4,7 @@ UPSD(8) NAME ---- -upsd - UPS information server +upsd - Network UPS Tools data server SYNOPSIS -------- @@ -16,8 +16,8 @@ SYNOPSIS DESCRIPTION ----------- -*upsd* is responsible for serving the data from the drivers to the clients. It -connects to each driver and maintains a local cache of the current state. +*upsd* is responsible for serving the data from the drivers to the clients. +It connects to each driver and maintains a local cache of the current state. Queries from the clients are served from this cache, so delays are minimal. It also conveys administrative messages from the clients back to the drivers, @@ -69,18 +69,17 @@ upsd will run in the background, regardless of debugging settings. Display the help text. *-r* 'directory':: -upsd will *chroot*(2) to 'directory' shortly after startup -and before parsing any configuration files with this option set. You -can use this to create a "jail" for greater security. +upsd will linkmanext:chroot[2] to 'directory' shortly after startup +and before parsing any configuration files with this option set. +You can use this to create a "jail" for greater security. + You must coordinate this with your drivers, as upsd must be able to find the state path within 'directory'. See linkman:upsdrvctl[8] and linkman:nutupsdrv[8]. *-u* 'user':: -Switch to user 'user' after startup if started as root. This -overrides whatever you may have compiled in with `configure ---with-user`. +Switch to user 'user' after startup if started as root. +This overrides whatever you may have compiled in with `configure --with-user`. *-V*:: Display the version of the program. @@ -90,8 +89,9 @@ RELOADING upsd can reload its configuration files without shutting down the process if you send it a SIGHUP or start it again with `-c reload`. This only works -if the background process is able to read those files, and if the daemon did -save a PID file when it started. +if the background process is able to read those files (permissions, `chroot` +jail), and if the daemon did save a PID file when it started (for the `reload` +command to find the older instance). [NOTE] ====== @@ -104,15 +104,17 @@ distribution uses NUT-provided unit definitions, `systemctl reload upsd` may also work. ====== -If you think that upsd can't reload, check your syslog for error messages. +If you think that `upsd` can't reload, check your syslog for error messages. If it's complaining about not being able to read the files, then you need to adjust your system to make it possible. Either change the permissions -on the files, or run upsd as another user that will be able to read them. +on the files, or run `upsd` as another user that will be able to read them, +or restart it fully (may be needed e.g. if running in a `chroot` jail). -DO NOT make your upsd.conf or upsd.users world-readable, as those files -hold important authentication information. In the wrong hands, it could -be used by some evil person to spoof your primary-mode upsmon and command -your systems to shut down. +DO NOT make your linkman:upsd.conf[5] or linkman:upsd.users[5] files +world-readable, as they hold important authentication information. +In the wrong hands, it could be used by some evil person to spoof +your primary-mode `upsmon` and command your systems to shut down, +for example. DIAGNOSTICS ----------- @@ -140,15 +142,17 @@ If the server is build with tcp-wrappers support enabled, it will check if the NUT username is allowed to connect from the client address through the `/etc/hosts.allow` and `/etc/hosts.deny` files. Note that this will only be done for commands that require to be logged into the server. Further -details are described in *hosts_access*(5). +details are described in linkmanext:hosts_access[5]. FILES ----- -The general upsd configuration file is linkman:upsd.conf[5]. The -administrative functions like SET and INSTCMD for users are defined and -controlled in linkman:upsd.users[5]. UPS definitions are found in -linkman:ups.conf[5]. +The general `upsd` configuration file is linkman:upsd.conf[5]. + +The administrative functions like `SET` and `INSTCMD` for users, and various +`upsmon` roles, are defined and controlled in linkman:upsd.users[5]. + +UPS definitions are found in linkman:ups.conf[5] (shared with actual drivers). ENVIRONMENT VARIABLES --------------------- diff --git a/docs/man/upsd.users.txt b/docs/man/upsd.users.txt index 38471ddd46..42def31e5b 100644 --- a/docs/man/upsd.users.txt +++ b/docs/man/upsd.users.txt @@ -4,7 +4,7 @@ UPSD.USERS(5) NAME ---- -upsd.users - Administrative user definitions for NUT upsd +upsd.users - Administrative user definitions for NUT upsd data server DESCRIPTION ----------- @@ -44,7 +44,8 @@ SECTIONS Each user gets its own section. The fields in that section set the parameters associated with that user's privileges. The section begins with the name of the user in brackets, and continues until the next user -name in brackets or EOF. These users are independent of /etc/passwd. +name in brackets or EOF. These users are independent of `/etc/passwd` +or other OS account databases. Here are some examples to get you started: @@ -76,16 +77,18 @@ Set the password for this user. *actions*:: -Allow the user to do certain things with upsd. To specify multiple +Allow the user to do certain things with `upsd`. To specify multiple actions, use multiple instances of the *actions* field. Valid actions are: - ++ +-- SET;; change the value of certain variables in the UPS FSD;; set the forced shutdown flag in the UPS. This is -equivalent to an "on battery + low battery" situation for the purposes -of monitoring. - + equivalent to an "on battery + low battery" situation + for the purposes of monitoring. +-- ++ The list of actions is expected to grow in the future. *instcmds*:: @@ -93,10 +96,10 @@ The list of actions is expected to grow in the future. Let a user initiate specific instant commands. Use "ALL" to grant all commands automatically. To specify multiple commands, use multiple instances of the *instcmds* field. For the full list of what your UPS -supports, use "upscmd -l". +supports, use `upscmd -l`. + -The +cmdvartab+ file supplied with the distribution contains a list -of most of the known command names. +The +cmdvartab+ file supplied with the NUT distribution contains a list +of most of the generally known command names. *upsmon*:: @@ -105,7 +108,7 @@ role of a particular client instance to work with this data server instance. This is either set to 'primary' (may request FSD) or 'secondary' (follows critical situations to shut down when needed). + -Do not attempt to assign actions to upsmon by hand, as you may miss +Do not attempt to assign actions to `upsmon` by hand, as you may miss something important. This method of designating a "upsmon user" was created so internal capabilities could be changed later on without breaking existing installations (potentially using actions that are diff --git a/docs/man/upsdrvctl.txt b/docs/man/upsdrvctl.txt index 94bb0f6afb..1b13e33c7c 100644 --- a/docs/man/upsdrvctl.txt +++ b/docs/man/upsdrvctl.txt @@ -4,7 +4,7 @@ UPSDRVCTL(8) NAME ---- -upsdrvctl - UPS driver controller +upsdrvctl - Network UPS Tools driver controller SYNOPSIS -------- @@ -21,10 +21,10 @@ DESCRIPTION ----------- *upsdrvctl* provides a uniform interface for controlling your UPS drivers. -You should use upsdrvctl instead of direct calls to the drivers +You should use `upsdrvctl` command instead of direct calls to the drivers whenever possible. -When used properly, upsdrvctl lets you maintain identical startup +When used properly, `upsdrvctl` lets you maintain identical startup scripts across multiple systems with different UPS configurations. [WARNING] @@ -53,35 +53,44 @@ OPTIONS Display the help text. *-r* 'directory':: -If starting a driver, this value will direct it to *chroot*(2) into +If starting a driver, this value will direct it to linkmanext:chroot[2] into 'directory'. This can be useful when securing systems. - -This may be set in the ups.conf with "chroot" in the global section. ++ +This may be set in the linkman:ups.conf[5] with the +chroot+ directive +in the global section. *-t*:: Enable testing mode. This also enables debug mode. Testing mode makes upsdrvctl display the actions it would execute without actually doing them. Use this to test out your configuration without actually doing anything -to your UPS drivers. This may be helpful when defining the 'sdorder' -directive in your linkman:ups.conf[5]. +to your UPS drivers. ++ +This may be helpful when defining the +sdorder+ directive in your +linkman:ups.conf[5] section for the device. *-u* 'username':: -If starting a driver, this value will direct it to *setuid*(2) to +If starting a driver, this value will direct it to linkmanext:setuid[2] to the user id associated with 'username'. - -If the driver is started as root without specifying this value, it will ++ +If the driver is started as 'root' without specifying this value, it will use the username that was compiled into the binary. This defaults to -"nobody", and is far from ideal. - -This may be set in ups.conf with "user" in the global section. +'nobody' (if not otherwise configured), which is far from ideal. ++ +This may be set in linkman:ups.conf[5] with the +user+ directive in the +global section. *-D*:: Raise the debug level. Use this multiple times for additional details. ++ Note that this does not preclude the `upsdrvctl` tool from exiting after its job is done (however an explicit *-F* option does). ++ +Also note that this option alone modifies the debug verbosity of the tool, +but not of the drivers it launches. See the additional *-d* option for that. *-d*:: Pass the selected debug level from `upsdrvctl` to launched drivers. ++ Note that by default for NUT daemons, enabled debugging means running in foreground mode; you can specify *-B* additionally to avoid that. @@ -89,9 +98,11 @@ in foreground mode; you can specify *-B* additionally to avoid that. Driver will run in the foreground (not fork away from the `upsdrvctl` process), regardless of debugging settings. It would also keep the tool program itself foregrounded with driver daemons running as its children -(in case of a single driver startup, it would not even fork). It would -also not wait for drivers to complete initialization, so `upsdrvctl` -will warn about such situations. +(in case of a single driver startup, it would not even fork). ++ +It would also not wait for drivers to complete initialization, so +`upsdrvctl` will warn about such situations. ++ Specify twice (`-FF` or `-F -F`) to save the driver PID file even in this mode (not saved by default when staying in foreground). @@ -119,7 +130,7 @@ NOTE: `upsdrvctl` can not manage devices not listed in `ups.conf` *start*:: Start the UPS driver(s). In case of failure, further attempts may be executed -by using the 'maxretry' and 'retrydelay' options - see linkman:ups.conf[5]. +by using the 'maxretry' and 'retrydelay' options -- see linkman:ups.conf[5]. *stop*:: Stop the UPS driver(s). This does not send commands to the UPS. @@ -127,16 +138,16 @@ Stop the UPS driver(s). This does not send commands to the UPS. *shutdown*:: Command the UPS driver(s) to run their shutdown sequence. This assumes that the driver is no longer running, and starts a fresh -instance via "driver -k". It is intended to be used as the last step -in system shutdown, after the filesystems are no longer mounted rw. -Drivers are stopped according to their sdorder value - see +instance via `drivername -k`. It is intended to be used as the last step +in system shutdown, after the filesystems are no longer mounted 'rw'. +Drivers are stopped according to their `sdorder` value -- see linkman:ups.conf[5]. -WARNING: this will probably power off your computers, so don't +WARNING: This will probably power off your computers, so don't play around with this option. Only use it when your systems are prepared to lose power. -NOTE: refer to linkman:ups.conf[5] for using the *nowait* parameter. +NOTE: Refer to linkman:ups.conf[5] for using the *nowait* parameter. It can be overridden by `NUT_IGNORE_NOWAIT` environment variable (e.g. used to work around certain issues with systemd otherwise). @@ -170,14 +181,15 @@ of status report would be the heading with column names: dummy dummy-ups N/A -3 NOT_RESPONSIVE N/A eco650 usbhid-ups RUNNING 3559207 RESPONSIVE 3559207 "OL" UPS2 dummy-ups RUNNING 31455 RESPONSIVE 31455 "OL BOOST" - ++ Values are TAB-separated, but UPSNAME and UPSDRV may be padded by spaces on the right and on the left respectively. Any complex string values would be encased in double-quotes. - ++ Fields reported (`PF_*` = according to PID file, if any; `S_*` = via socket protocol): - ++ +-- *UPSNAME*;; driver section configuration name *UPSDRV*;; driver program name per `ups.conf` *RUNNING*;; `RUNNING` if `PF_PID` or `S_PID` is valid, @@ -198,14 +210,16 @@ protocol): *S_PID*;; PID of driver according to `GETPID` active query, or `N/A` if the query failed *S_STATUS*;; Quoted value of `ups.status` variable - +-- ++ This mode does not discover drivers that are not in `ups.conf` (e.g. started manually for experiments with many `-x` CLI options). *-c* 'command':: Send 'command' to the background process as a signal. Valid commands are: - ++ +-- *dump*;; tell the driver(s) to dump currently known state information to their `stdout` (if attached anywhere) *reload*;; reread configuration files, ignoring modified settings @@ -229,6 +243,7 @@ are: *exit*;; tell the currently running driver instance to just exit (so an external caller like the new driver instance, or the systemd or SMF frameworks would start another copy) +-- If the `upsdrvctl` was launched to remain in memory and manage NUT driver processes, it can receive supported signals and pass them to those drivers. @@ -253,7 +268,7 @@ or otherwise the built-in default *STATEPATH*. DIAGNOSTICS ----------- -upsdrvctl will return a nonzero exit code if it encounters an error +`upsdrvctl` will return a nonzero exit code if it encounters an error while performing the desired operation. This will also happen if a driver takes longer than the 'maxstartdelay' period to enter the background. diff --git a/docs/man/upsdrvsvcctl.txt b/docs/man/upsdrvsvcctl.txt index 475d005462..84f85cd6b7 100644 --- a/docs/man/upsdrvsvcctl.txt +++ b/docs/man/upsdrvsvcctl.txt @@ -4,7 +4,7 @@ UPSDRVSVCCTL(8) NAME ---- -upsdrvsvcctl - UPS driver service instance controller +upsdrvsvcctl - Network UPS Tools driver service instance controller SYNOPSIS -------- @@ -23,16 +23,17 @@ derived from Solaris 10 codebase, including proprietary Sun/Oracle Solaris and numerous open-source illumos distributions with SMF). It may be not installed in packaging for other operating systems. -When used properly, upsdrvsvcctl lets you maintain identical startup +When used properly, `upsdrvsvcctl` lets you maintain identical startup scripts across multiple systems with different UPS configurations. -The goal of this solution is to allow the services of *upsd* data -server to start up even if some of the power devices are currently +The goal of this solution is to allow the services of linkman:upsd[8] +data server to start up even if some of the power devices are currently not accessible, and for NUT drivers to be automatically restarted by the system in case of problems (driver bug, startup failure). It also allows for faster startup of systems which monitor several -devices, by letting each driver to start in parallel with others, -and not with a sequential loop like was done previously. +devices, by letting each driver to start in parallel with others +and as soon as the required subsystem for the specific driver's media +is available, i.e. not with a sequential loop like was done previously. Independent service instances for each NUT driver also allow one to configure further dependencies, such as that networking must be @@ -46,16 +47,16 @@ It was also not easy to strike a pre-packaged balance between early UPS protection for USB/serial home setups vs. waiting for network on larger ones. -*upsdrvsvcctl* is a script which mimics the operation of *upsdrvctl* +*upsdrvsvcctl* is a script which mimics the operation of linkman:upsdrvctl[8] program (where possible) to provide similar end-user experience when manipulating drivers wrapped into service instances rather than as -directly executed daemons. It relies on *nut-driver-enumerator.sh* +directly executed daemons. It relies on linkman:nut-driver-enumerator[8] for a large part of actual operations. -You should use upsdrvsvcctl instead of direct calls to the drivers -and daemon-based management with *upsdrvctl* whenever possible (that +You should use `upsdrvsvcctl` instead of direct calls to the drivers +and daemon-based management with linkman:upsdrvctl[8] whenever possible (that is, for "production" use on compatible OSes). Otherwise (testing, -other OSes) the *upsdrvctl* is a recommended option. +other OSes) the `upsdrvctl` is a recommended option. OPTIONS ------- @@ -93,20 +94,22 @@ be better to stop the service instance and play with *upsdrvctl* directly. *-r* 'directory':: -If starting a driver, this value will direct it to *chroot*(2) into -'directory'. This can be useful when securing systems. - -This may be set in the ups.conf with "chroot" in the global section. +If starting a driver, this value will direct it to linkmanext:chroot[2] +into 'directory'. This can be useful when securing systems. ++ +This may be set in the linkman:ups.conf[5] with the +chroot+ directive +in the global section. *-u* 'username':: -If starting a driver, this value will direct it to *setuid*(2) to +If starting a driver, this value will direct it to linkmanext:setuid[2] to the user id associated with 'username'. - -If the driver is started as root without specifying this value, it will ++ +If the driver is started as 'root' without specifying this value, it will use the username that was compiled into the binary. This defaults to -"nobody", and is far from ideal. - -This may be set in ups.conf with "user" in the global section. +'nobody' (if not otherwise configured), which is far from ideal. ++ +This may be set in linkman:ups.conf[5] with the +user+ directive in the +global section. *-D*:: Raise the driver debug level. Use this multiple times for additional @@ -128,7 +131,7 @@ online. *start*:: Start the UPS driver(s). In case of failure, further attempts may be executed -by using the 'maxretry' and 'retrydelay' options - see linkman:ups.conf[5]. +by using the 'maxretry' and 'retrydelay' options -- see linkman:ups.conf[5]. *stop*:: Stop the UPS driver(s). @@ -158,7 +161,7 @@ COMMANDS OF UPSDRVCTL NOT (CURRENTLY) APPLICABLE TO UPSDRVSVCCTL *shutdown*:: Command the UPS driver(s) to run their shutdown sequence. Drivers are -stopped according to their sdorder value - see linkman:ups.conf[5]. +stopped according to their `sdorder` value -- see linkman:ups.conf[5]. WARNING: this will probably power off your computers, so don't play around with this option. Only use it when your systems are prepared @@ -200,12 +203,12 @@ this service are stored), as suggested below: Messages will normally be kept in the service journal, so: journalctl -lu nut-driver@instance-name - ++ Note that your local system configuration may be impacted by such nuances as passing the journal data to a standard syslog server, and/or by having a small cache for locally stored journal messages (so older entries would disappear). There may also be or not be a -copy of the journals stored in the filesystem. +copy of the journals stored in the persistent filesystem at all. *Solaris SMF*:: Look for `/var/svc/log/system-power-nut-driver:instance-name.log` file. diff --git a/docs/man/upsimage.cgi.txt b/docs/man/upsimage.cgi.txt index d9f6b636f7..ad7287960d 100644 --- a/docs/man/upsimage.cgi.txt +++ b/docs/man/upsimage.cgi.txt @@ -23,7 +23,7 @@ of the page generated by linkman:upsstats.cgi[8]. These represent the current battery charge, utility voltage, and UPS load where available. The images are in PNG format, and are created by linking to Boutell's -excellent gd library. +excellent 'gd' library. ACCESS CONTROL -------------- diff --git a/docs/man/upslog.txt b/docs/man/upslog.txt index b1b563d4ff..f6d4fdbd79 100644 --- a/docs/man/upslog.txt +++ b/docs/man/upslog.txt @@ -32,28 +32,30 @@ Display the help message. Monitor the UPS using this format string. Be sure to enclose 'format' in quotes so your shell doesn't split it up. Valid escapes within this string are: - ++ +-- %%;; Insert a single "%" %t;; Insert a single TAB character (like `printf("\t")`) -%TIME format%;; Insert the time with strftime formatting +%TIME format%;; Insert the time with `strftime` formatting -%ETIME%;; Insert the number of seconds, ala time_t. This is now a -10 digit number. +%ETIME%;; Insert the number of seconds since the start of "Epoch", +ala `time_t`. This is now a 10-digit number. -%HOST%;; insert the local hostname +%HOST%;; Insert the local hostname -%UPSHOST%;; insert the host of the UPS being monitored +%UPSHOST%;; Insert the host of the UPS being monitored (the `` part of your logging specification, e.g. `ups[@host[:port]]`) -%PID%;; insert the pid of upslog +%PID%;; Insert the PID of `upslog` itself -%VAR varname%;; insert the value of variable varname +%VAR varname%;; Insert the value of variable varname (see NUT developer documentation chapter "Variables" on-line or in the `docs/nut-names.txt` file in sources of the NUT version you have installed for more details) - +-- ++ The default format string is: %TIME @Y@m@d @H@M@S% %VAR battery.charge% %VAR input.voltage% @@ -69,29 +71,31 @@ in the formatting string (e.g. specified explicitly). *-i* 'interval':: -Wait this many seconds between polls. This defaults to 30 seconds. +Wait this many seconds between polls. This defaults to '30' seconds. + -If you require tighter timing, you should write your own logger using +If you require tighter timing, consider writing your own logger using the linkman:upsclient[3] library. *-d* 'count':: -Exit after specified amount of updates. Default is 0 for infinite loop +Exit after specified amount of updates. Default is '0' for infinite loop (until interrupted otherwise). *-l* 'logfile':: Store the results in this file. + -You can use "-" for stdout, but upslog will remain in the foreground +You can use `-` for stdout, but `upslog` will remain in the foreground by default. + Requires that the `-s ` option is also used for the single-system -logging. Can be used with the `-m `, will be added to the list. +logging. ++ +Can be used with the `-m `, will be added to the list. *-D*:: -Raise debugging verbosity level by one; upslog will remain in the foreground -by default. +Raise debugging verbosity level by one; `upslog` will remain in the +foreground by default. *-F*:: upslog will run in the foreground, regardless of logging target. @@ -103,21 +107,26 @@ upslog will run in the background, regardless of logging target or debugging. Monitor this UPS. The format for this option is +upsname[@hostname[:port]]+. The default hostname is "localhost". + -The upsname may be an asterisk `*` to query UPSes currently served by hostname. +The 'upsname' may be an asterisk `*` to query UPSes currently served by +'hostname', and monitor each of them (into the same logging destination). + Requires that the `-l ` option is also used for the single-system -logging. Can be used with the `-m `, will be added to the list. +logging. ++ +Can be used with the `-m `, will be added to the list. *-m* 'tuple':: Monitor multiple UPSs (provided several instances of such option). + The format for this option is a tuple of UPS system and log file specification, separated by commas. An example would be: ++ ---- upsname@hostname:9999,/var/log/nut/cps.log ---- + -The upsname may be an asterisk `*` to query UPSes currently served by hostname. +The 'upsname' may be an asterisk `*` to query UPSes currently served by +'hostname', and monitor each of them (into the same logging destination). + Tuples may specify `-` as the logfile, to emit messages on `stdout` (e.g. to be collected by the system journal for services). @@ -127,23 +136,24 @@ implies that upslog will remain in the foreground by default. *-u* 'username':: -If started as root, upslog will *setuid*(2) to the user id +If started as 'root', `upslog` will linkmanext:setuid[2] to the user id associated with 'username' for security. + If 'username' is not defined, it will use the value that was compiled into -the program. This defaults to "nobody", which is less than ideal. +the program. This defaults to 'nobody' (if not otherwise configured), +which is far from ideal. SERVICE DELAYS -------------- -The interval value is merely the number given to *sleep*(3) after running +The interval value is merely the number given to linkmanext:sleep[3] after running through the format string. Therefore, a query will actually take slightly longer than the interval, depending on the speed of your system. ON-DEMAND LOGGING ----------------- -Sending a USR1 signal to a running *upslog* process makes it wake from the +Sending a `SIGUSR1` to a running *upslog* process makes it wake from the current sleep and log immediately. This is useful when triggered from a *upssched* event trigger (e.g. `AT ONBATT` or `AT ONLINE`) to ensure that an entry always exists, even if the power goes away for a period of time shorter @@ -155,14 +165,15 @@ LOG CO-LOCATION It is possible and safe to specify the same log file (including `-` for stdout) in several tuples, and it would only be opened or closed once without conflict. -Consider adding `%UPSHOST%` to your custom formatting string to differentiate -lines corresponding to different systems, when logging them to same target. +Consider adding `%UPSHOST%` to your custom formatting string (e.g. by using +the *-N* command-line option), in order to easily differentiate lines +corresponding to different systems, when logging them to the same target. LOG ROTATION ------------ *upslog* writes its PID to `upslog.pid`, and will reopen the log file if you -send it a SIGHUP. This allows it to keep running when the log is rotated +send it a `SIGHUP`. This allows it to keep running when the log is rotated by an external program. CAVEATS @@ -170,11 +181,16 @@ CAVEATS Historically this daemon supported logging of data for one UPS system per run (specified by the `-s` option) into one log file name or `stdout` (specified -by the `-l` option). Since NUT v2.8.1 it allowed to log several devices (each -logged into its destination) as specified by multiple `-m tuple` options. -The two modes were effectively exclusive of each other (single-UPS options -were ignored if tuples are also provided) until NUT v2.8.3, but single-UPS -options are added to the list of tuples since that release. +by the `-l` option). + +Since NUT v2.8.1 it allowed to log several devices (each logged into its +individual destination file or common `stdout`) as specified by multiple +`-m tuple` options. But the two modes were effectively exclusive of each +other (single-UPS options were ignored if tuples are also provided). + +Since NUT v2.8.3, the single-UPS options are added to the list of tuples, +so both legacy and new options can be reliably used to monitor multiple +devices in the same run. SEE ALSO -------- diff --git a/docs/man/upsmon.conf.txt b/docs/man/upsmon.conf.txt index bf1934cb0e..be01ca6f71 100644 --- a/docs/man/upsmon.conf.txt +++ b/docs/man/upsmon.conf.txt @@ -4,20 +4,20 @@ UPSMON.CONF(5) NAME ---- -upsmon.conf - Configuration for Network UPS Tools upsmon +upsmon.conf - Configuration for Network UPS Tools upsmon client DESCRIPTION ----------- This file's primary job is to define the systems that linkman:upsmon[8] -will monitor and to tell it how to shut down the system when necessary. -It will contain passwords, so keep it secure. Ideally, only the upsmon +will monitor, and to tell it how to shut down the system when necessary. +It will contain passwords, so keep it secure. Ideally, only the `upsmon` process should be able to read it. A minimal configuration should include at least one `MONITOR` instruction, -`MINSUPPLIES` (may be 0 if this system is only monitoring other NUT servers), -and a `POWERDOWNFLAG` if this machine is a "primary" system connected to -the UPS and drives its late-shutdown power-off command in an emergency. +`MINSUPPLIES` (may be '0' if this system is only monitoring other NUT servers), +and a `POWERDOWNFLAG` if this machine is a "primary" system connected to the +UPS and drives its late-shutdown power-off command in case of an emergency. Additionally, other optional configuration values can be set in this file. @@ -315,7 +315,7 @@ de-activating obsolete UPS readings to avoid an unfortunate shutdown By default, upsmon sends walls global messages to all logged in users) via `/bin/wall` and writes to the syslog when things happen. -Except for Windows where upsmon only writes to the syslog by default. +Except for Windows where upsmon only writes to the Event Log by default. You can change this. + Examples: @@ -504,7 +504,7 @@ Some "secondary" systems with workloads that take considerable time to stop (e.g. virtual machines or large databases) can benefit from reporting (by virtue of logging off the data server) that they are ready for the "primary" system to begin its own shutdown and eventually -to tell the UPS to cut the power - not as soon as they have triggered +to tell the UPS to cut the power -- not as soon as they have triggered their own shutdown, but at a later point (e.g. when the upsmon service is stopped AFTER the heavier workloads). + diff --git a/docs/man/upsmon.txt b/docs/man/upsmon.txt index b514cdcb3c..26db903321 100644 --- a/docs/man/upsmon.txt +++ b/docs/man/upsmon.txt @@ -19,7 +19,7 @@ DESCRIPTION ----------- *upsmon* is the client process that is responsible for the most important part -of UPS monitoring--shutting down the system when the power goes out. It +of UPS monitoring -- shutting down the system when the power goes out. It can call out to other helper programs for notification purposes during power events. @@ -82,25 +82,26 @@ have a very good reason. Set the user for the unprivileged monitoring process. This has no effect when using -p. + -The default user is set at configure time with 'configure ---with-user=...'. Typically this is 'nobody', but other distributions -will probably have a specific 'nut' user for this task. If your -notification scripts need to run as a specific user, set it here. +The default 'user' is set at build configuration time with +`configure --with-user=...`. Typically this is 'nobody' (if not +otherwise configured), which is far from ideal, so most packaged +distributions will probably have a specific 'nut' user for this task. +If your notification scripts need to run as a specific user, set it here. + You can also set this in the linkman:upsmon.conf[5] file with the -RUN_AS_USER directive. +`RUN_AS_USER` directive. UPS DEFINITIONS --------------- In the linkman:upsmon.conf[5], you must specify at least one UPS that will -be monitored. Use the MONITOR directive. +be monitored. Use the MONITOR directive like this: MONITOR 'system' 'powervalue' 'username' 'password' 'type' The 'system' refers to a linkman:upsd[8] server, in the form -+upsname[@hostname[:port]]+. The default hostname is "localhost". Some -examples follow: ++upsname[@hostname[:port]]+. The default 'hostname' is "localhost", +and default 'port' is '3493'. Some examples follow: - "su700@mybox" means a UPS called "su700" on a system called "mybox". This is the normal form. @@ -108,8 +109,8 @@ This is the normal form. - "fenton@bigbox:5678" is a UPS called "fenton" on a system called "bigbox" which runs linkman:upsd[8] on port "5678". -The 'powervalue' refers to how many power supplies on this system are -being driven this UPS. This is typically set to 1, but see the section +The 'powervalue' refers to how many power supplies on this client system are +being driven this UPS. This is typically set to '1', but see the section on power values below. The 'username' is a section in your linkman:upsd.users[5] file. @@ -127,7 +128,7 @@ NOTIFY EVENTS ------------- *upsmon* senses several events as it monitors each UPS. They are called -notify events as they can be used to tell the users and admins about the +"notify events", as they can be used to tell the users and admins about the change in status. See the additional NOTIFY-related sections below for information on customizing the delivery of these messages. @@ -219,11 +220,14 @@ NOTIFY COMMAND In linkman:upsmon.conf[5], you can configure a program called the NOTIFYCMD that will handle events that occur. -+NOTIFYCMD+ "'path to program'" +The syntax is: +NOTIFYCMD+ "'path to program'" -+NOTIFYCMD "/usr/local/bin/notifyme"+ +Example: -Remember to wrap the path in "quotes" if it contains any spaces. + - `NOTIFYCMD "/usr/local/bin/notifyme"` + +Remember to wrap the path in "double quotes" if it contains any spaces. +It should probably not rely on receiving any command-line arguments. The program you run as your NOTIFYCMD can use the environment variables NOTIFYTYPE and UPSNAME to know what has happened and on which UPS. It @@ -241,7 +245,7 @@ By default, all notify events (see above) generate a global message Except for Windows where upsmon only writes to the syslog by default. You can change this with the NOTIFYFLAG directive in the configuration file: -+NOTIFYFLAG+ 'notifytype' 'flags' +The syntax is: +NOTIFYFLAG+ 'notifytype' 'flags' Examples: @@ -257,7 +261,7 @@ The flags that can be set on a given notify event are: Write this message to the syslog. *WALL*:: -Send this message to all users on the system via *wall*(1). +Send this message to all users on the system via linkmanext:wall[1]. *EXEC*:: Execute the NOTIFYCMD. @@ -265,8 +269,8 @@ Execute the NOTIFYCMD. *IGNORE*:: Don't do anything. If you use this, don't use any of the other flags. -You can mix these flags. "SYSLOG+WALL+EXEC" does all three for a given -event. +You can mix these flags; for example, `SYSLOG+WALL+EXEC` does all three +for a given event. NOTIFY MESSAGES --------------- @@ -274,18 +278,22 @@ NOTIFY MESSAGES upsmon comes with default messages for each of the NOTIFY events. These can be changed with the NOTIFYMSG directive. -+NOTIFYMSG+ 'type' "'message'" +The syntax is: +NOTIFYMSG+ 'type' "'message'" Examples: - `NOTIFYMSG ONLINE "UPS %s is getting line power"` - - ` NOTIFYMSG ONBATT "Someone pulled the plug on %s"` + - `NOTIFYMSG ONBATT "Someone pulled the plug on %s"` -The first instance of %s is replaced with the identifier of the UPS that +The first instance of `%s` is replaced with the identifier of the UPS that generated the event. These messages are used when sending walls to the users directly from upsmon, and are also passed to the NOTIFYCMD. +NOTE: Certain notifications, such as `NOTIFY_ALARM` and `NOTIFY_OTHER`, +can accept a second instance of `%s` that would be replaced with the +alarm text or the unrecognized token, respectively. + POWER VALUES ------------ @@ -295,50 +303,65 @@ UPS that is either on line or just on battery contributes to this number. If a UPS is critical (on battery and low battery) or has been put into "forced shutdown" mode, it no longer contributes. +The syntax is: +MONITOR+ 'upsname' 'powervalue' 'username' 'password' 'type' + A "power value" on a MONITOR line in the config file is the number of power supplies that the UPS runs on the current system. -+MONITOR+ 'upsname' 'powervalue' 'username' 'password' 'type' - -Normally, you only have one power supply, so it will be set to 1. +* Normally, you only have one power supply, so it will be set to '1'. ++ +Example: -+MONITOR myups@myhost 1 username mypassword primary+ + - `MONITOR myups@myhost 1 username mypassword primary` -On a large server with redundant power supplies, the power value for a UPS +* On a large server with redundant power supplies, the power value for a UPS may be greater than 1. You may also have more than one of them defined. ++ +Examples for a server with four power supply modules and two UPSes (each +feeding two power supplies of that server): -+MONITOR ups-alpha@myhost 2 username mypassword primary+ + - `MONITOR ups-alpha@myhost 2 username mypassword primary` -+MONITOR ups-beta@myhost 2 username mypassword primary+ + - `MONITOR ups-beta@myhost 2 username mypassword primary` -You can also set the power value for a UPS to 0 if it does not supply any +* You can also set the power value for a UPS to '0' if it does not supply any power to that system. This is generally used when you want to use the upsmon notification features for a UPS even though it's not actually -running the system that hosts upsmon. Don't set this to "primary" unless -you really want to power this UPS off when this instance of upsmon needs -to shut down for its own reasons. +powering the system that hosts this instance of the upsmon client. ++ +Don't set this to "primary" unless you really want to power this UPS off +when this instance of upsmon needs to shut down for its own reasons. ++ +Example: -+MONITOR faraway@anotherbox 0 username mypassword secondary+ + - `MONITOR faraway@anotherbox 0 username mypassword secondary` The "minimum power value" is the number of power supplies that must be -receiving power in order to keep the computer running. +receiving power in order to keep this `upsmon` client's computer running. -+MINSUPPLIES+ 'value' +The syntax is: +MINSUPPLIES+ 'value' -Typical PCs only have 1, so most users will leave this at the default. +* Typical PCs only have 1, so most users will leave this at the default. ++ +Example: -+MINSUPPLIES 1+ + - `MINSUPPLIES 1` -If you have a server or similar system with redundant power, then this +* If you have a server or similar system with redundant power, then this value will usually be set higher. One that requires three power supplies -to be running at all times would simply set it to 3. - -+MINSUPPLIES 3+ +out of 4 to be running at all times would simply set it to 3. ++ +-- +Example: -When the current overall power value drops below the minimum power value, -upsmon starts the shutdown sequence. This design allows you to lose some -of your power supplies in a redundant power environment without bringing -down the entire system while still working properly for smaller systems. + - `MINSUPPLIES 3` +-- ++ +When the current overall healthy UPS-protected external power value drops +below the minimum required power value, `upsmon` starts the shutdown sequence. +This design allows you to lose some of your power supplies in a redundant +power environment without bringing down the entire system, while still +working properly for smaller systems. UPS TYPES --------- @@ -348,7 +371,7 @@ do, any UPSes that are directly attached to the upsmon host should be monitored in "primary" mode. This makes upsmon take charge of that equipment, and it will wait for the "secondary" systems to disconnect before shutting down the local system. This allows the distant systems (monitoring over -the network) to shut down cleanly before `upsdrvctl shutdown` runs +the network) to shut down cleanly before `upsdrvctl shutdown` runs locally and turns them all off. When upsmon runs as a secondary, it is relying on the distant system to tell @@ -360,10 +383,10 @@ process. Your secondary systems must all quiesce and shut down before the primary turns off the shared power source, or filesystem damage may result. upsmon deals with secondaries that get wedged, hang, or otherwise fail to -disconnect from linkman:upsd[8] in a timely manner with the HOSTSYNC -timer. During a shutdown situation, the primary upsmon will give up after -this interval and it will shut down anyway. This keeps the primary from -sitting there forever (which would endanger that host) if a secondary +gracefully disconnect from linkman:upsd[8] in a timely manner with the +HOSTSYNC timer. During a shutdown situation, the primary upsmon will give +up after this interval and it will shut down anyway. This keeps the primary +from sitting there forever (which would endanger that host) if a secondary should break somehow. This defaults to 15 seconds. If your primary system is shutting down too quickly, set the FINALDELAY @@ -478,7 +501,7 @@ To test a synchronized shutdown without pulling the plug on your UPS(es), you need only set the forced shutdown (FSD) flag on them. You can do this by calling upsmon again to set the flag, i.e.: -+upsmon -c fsd+ + :; upsmon -c fsd After that, the primary and the secondary will do their usual shutdown sequence as if the battery had gone critical, while you can time how long @@ -488,7 +511,7 @@ crawling under a desk to find the plug. Note you can also use a dummy SHUTDOWNCMD setting to just report that the systems would shut down at this point, without actually disrupting their work. -WARNING: after such "dummy" experiments you may have to restart the NUT data +WARNING: After such "dummy" experiments you may have to restart the NUT data server `upsd` to clear its "FSD" flag for the devices and clients involved, and make sure no files named by `POWERDOWNFLAG` option (e.g. `/etc/killpower`) remain on the `upsmon primary` systems under test. diff --git a/docs/man/upsrw.txt b/docs/man/upsrw.txt index 7e93d02d1f..975be6c327 100644 --- a/docs/man/upsrw.txt +++ b/docs/man/upsrw.txt @@ -4,7 +4,7 @@ UPSRW(8) NAME ---- -upsrw - UPS variable administration tool +upsrw - Network UPS Tools device/driver variable administration tool SYNOPSIS -------- @@ -20,12 +20,13 @@ DESCRIPTION *upsrw* allows you to view and change the read/write variables inside your UPS. It sends commands via the server linkman:upsd[8] to your driver, which -configures the hardware for you. +configures the hardware for you. You must use credentials defined in +linkman:upsd.users[5] file on that data server with appropriate permissions. The list of variables that allow you to change their values is based on the capabilities of your UPS equipment. Not all models support this feature. Typically, cheaper hardware does not support any of them. -Run upsrw with a UPS identifier to see what will work for you. +Run `upsrw` with a UPS identifier to see what will work for you. OPTIONS ------- @@ -108,6 +109,7 @@ When using *upsrw* to modify a numeric float value, that values must be given using decimal (base 10) english-based representation, so using a dot, in non-scientific notation. So hexadecimal, exponents, and comma for thousands separator are forbidden. + For example: "1200.20" is valid, while "1,200.20" and "1200,20" are invalid. HISTORY diff --git a/docs/man/upsset.cgi.txt b/docs/man/upsset.cgi.txt index 3bae6a1d5c..625f6dd3b1 100644 --- a/docs/man/upsset.cgi.txt +++ b/docs/man/upsset.cgi.txt @@ -70,6 +70,10 @@ linkman:upscmd[8]. ACCESS CONTROL -------------- +It sends commands and settings via the server linkman:upsd[8] to your driver, +which manages the hardware for you. You must use credentials defined in +linkman:upsd.users[5] file on that data server with appropriate permissions. + upsset will only talk to linkman:upsd[8] servers that have been defined in your linkman:hosts.conf[8]. If it complains about "Access to that host is not authorized", check your hosts.conf first. diff --git a/docs/man/upsset.conf.txt b/docs/man/upsset.conf.txt index 385583fee3..5b3896a3a3 100644 --- a/docs/man/upsset.conf.txt +++ b/docs/man/upsset.conf.txt @@ -9,7 +9,7 @@ upsset.conf - Configuration for Network UPS Tools upsset.cgi DESCRIPTION ----------- -This file only does one job--it lets you convince linkman:upsset.cgi[8] +This file only does one job -- it lets you convince linkman:upsset.cgi[8] that your system's CGI directory is secure. The program will not run until this file has been properly defined. @@ -31,25 +31,25 @@ so it is highly recommended to set up HTTPS on the web server; ways to do so are outside the scope of this document. Normally, attackers would not be able to access your linkman:upsd[8] server -directly as it would be protected by the LISTEN directives in -your linkman:upsd.conf[5] file, tcp-wrappers (if available when NUT was built), +directly, as it would be protected by the LISTEN directives in your +linkman:upsd.conf[5] file, tcp-wrappers (if available when NUT was built), and hopefully local firewall settings in your OS. -*upsset* runs on your web server, so upsd will see it as a connection from +*upsset* runs on your web server, so `upsd` will see it as a connection from a host on an internal network. It doesn't know that the connection is -actually coming from someone on the outside. This is why you must +actually initiated by someone further outside. This is why you must secure it. -On Apache, you can use the .htaccess file or put the directives in your -httpd.conf. It looks something like this, assuming the .htaccess +On Apache, you can use the `.htaccess` file or put the directives in your +`httpd.conf`. It looks something like this, assuming the `.htaccess` method for older Apache releases: - deny from all - allow from your.network.addresses + deny from all + allow from your.network.addresses -You will probably have to set "AllowOverride Limit" for this directory +You will probably have to set `AllowOverride Limit` for this directory in your server-level configuration file as well. Modern Apache enjoys a more detailed syntax, like this: @@ -73,7 +73,7 @@ you may add the following directive to this file: I_HAVE_SECURED_MY_CGI_DIRECTORY -If you lie to the program and someone beats on your upsd through your +If you lie to the program and someone beats on your `upsd` through your web server, don't blame me. SEE ALSO diff --git a/docs/man/upsstats.cgi.txt b/docs/man/upsstats.cgi.txt index 0c6435b539..4215008d15 100644 --- a/docs/man/upsstats.cgi.txt +++ b/docs/man/upsstats.cgi.txt @@ -38,8 +38,9 @@ TEMPLATES --------- The web page that is displayed is actually a template containing -commands to upsstats which are replaced by status information. The -default file used for the overview is upsstats.html. +commands to `upsstats` which are replaced by status information. + +The default file used for the overview of devices is `upsstats.html`. When monitoring a single UPS, the file displayed is `upsstats-single.html`. diff --git a/docs/man/upsstats.html.txt b/docs/man/upsstats.html.txt index 91c4e7bf6e..ca375d40ae 100644 --- a/docs/man/upsstats.html.txt +++ b/docs/man/upsstats.html.txt @@ -4,7 +4,7 @@ UPSSTATS.HTML(5) NAME ---- -upsstats.html - HTML template for Network UPS Tools upsstats +upsstats.html - HTML template for web-based Network UPS Tools upsstats DESCRIPTION ----------- @@ -17,16 +17,20 @@ FORMATTING ---------- Commands can be placed anywhere on a line, but must start and end with `@`. + Any extra characters before or after the commands will be passed through -unchanged. It is allowed to use more than one command on a single line, -as long as each command has its own start and end character. If you need -to use the `@` sign, use @ to prevent it from being treated as a start -character. +unchanged. + +It is allowed to use more than one command on a single line, as long as +each command has its own start and end character. + +If you need to use the `@` sign, use HTML entity ++\@++ to prevent it +from being treated as a start character. BLOCK CONTROL ------------- -Some commands begin blocks - sections of the template that will be +Some commands begin blocks -- sections of the template that will be included, excluded, or repeated depending on certain parameters. BLOCK CONTROL - ITERATION @@ -90,8 +94,8 @@ OTHER COMMANDS Insert the ambient temperature in the current temperature scale. *@DATE* 'format'*@*:: -Insert the current date and time. The format string is passed to strftime, -so almost anything is possible. See *strftime*(3) for possible values. +Insert the current date and time. The format string is passed to `strftime`, +so almost anything is possible. See linkmanext:strftime[3] for possible values. *@DEGREES@*:: Insert the entity for degrees (°) and either C or F depending on @@ -111,7 +115,7 @@ current UPS. This is only useful within a FOREACHUPS block. Insert an IMG SRC to linkman:upsimage.cgi[8] for one of these status variables: - battery.charge;; Battery charge - a percentage + battery.charge;; Battery charge -- a percentage battery.voltage;; The charge on the battery in volts @@ -141,13 +145,13 @@ status variables: output.L3.power.percent;; UPS load, L3 (3phase) - ups.load;; UPS load - percentage + ups.load;; UPS load -- percentage ups.temperature;; UPS temperature 'extra' is where you can put additional definitions. Right now the valid definitions are colors for various parts of the bars drawn -by upsimage.cgi. Possible color names are: +by linkman:upsimage.cgi[8]. Possible color names are: back_col;; background color @@ -169,8 +173,8 @@ by upsimage.cgi. Possible color names are: bar_col;; the color of the bar in the middle -All colors are hex triplets - 0xff0000 is red, 0x00ff00 is green, and -0x0000ff is blue. +All colors are hex triplets -- e.g. `0xff0000` is red, `0x00ff00` is green, +and `0x0000ff` is blue. Examples: @@ -184,7 +188,7 @@ has been set by the browser. This needs to be in the HEAD section of the page. *@STATUS@*:: -Expand the abbreviations in the ups.status variable - OL becomes +Expand the abbreviations in the ups.status variable -- OL becomes "On line", OB becomes "On battery", and so on. *@STATUSCOLOR@*:: @@ -222,8 +226,8 @@ OTHER TEMPLATES --------------- linkman:upsstats.cgi[8] will also open a file called `upsstats-single.html` -if you call it with "host=" set in the URL. That file uses the same -rules and techniques documented here. +if you call it with `host=` set in the query URL. That file uses the same +rules and techniques as documented here. SEE ALSO -------- diff --git a/docs/man/usbhid-ups.txt b/docs/man/usbhid-ups.txt index ac6b642193..7f665020db 100644 --- a/docs/man/usbhid-ups.txt +++ b/docs/man/usbhid-ups.txt @@ -39,10 +39,11 @@ At the present time, usbhid-ups supports: - some TrippLite models. For a more complete list, refer to the NUT hardware compatibility list, -available in the source distribution as data/driver.list, or on the -NUT website. You may use the "explore" driver option to gather -information from HID UPSes which are not yet supported; see below for -details. +available in the NUT source distribution as `data/driver.list`, or on the +NUT website. + +You may use the `explore` driver option to gather information from HID UPSes +which are not yet supported, to help add such support; see below for details. This driver is known to work on: @@ -68,7 +69,7 @@ interface chips, notably "phoenixtec/liebert" and "mge"). Run the driver program with the `--help` option to see the exact list of `subdriver` values it would currently recognize. + -NOTE: this option first checks for exact matches to subdriver identification +NOTE: This option first checks for exact matches to subdriver identification strings, such as `"TrippLite HID 0.85"` (which are prone to bit-rot), and if there was no exact match -- retries with a case-insensitive extended regular expression. @@ -252,15 +253,16 @@ problem (while 20 seconds were not enough). INSTALLATION ------------ -This driver is not built by default. You can build it by using -"configure --with-usb=yes". Note that it will also install other USB -drivers. +This driver may be not built by default. You can build it by installing +prerequisites and using `configure --with-usb=yes`. Note that it will also +install other USB drivers. -You also need to install manually the legacy hotplug files (libhidups -and libhid.usermap, generally in /etc/hotplug/usb/), or the udev file -(nut-usbups.rules, generally in /etc/udev/rules.d/) to address the -permission settings problem. For more information, refer to the README -file in nut/scripts/hotplug or nut/scripts/udev. +You also need to install manually the legacy *hotplug* files (`libhidups` +and `libhid.usermap`, generally in `/etc/hotplug/usb/`), or the *udev* file +(`nut-usbups.rules`, generally in `/etc/udev/rules.d/`) to address the +permission settings problem. For more information, refer to the +`scripts/hotplug/README.adoc` or `scripts/udev/README.adoc` files in NUT +sources. IMPLEMENTATION -------------- diff --git a/docs/man/victronups.txt b/docs/man/victronups.txt index c9a113ffe2..31d9461fe1 100644 --- a/docs/man/victronups.txt +++ b/docs/man/victronups.txt @@ -24,7 +24,7 @@ The victronups driver should recognize all Victron models that use a serial protocol at 1200 bps. These include Match Lite, Match and the NetUps line. The Match Lite line may only report a handful of variables. This is -usually not a bug - they just don't support anything else. +usually not a bug -- they just don't support anything else. CABLING ------- diff --git a/docs/nut.dict b/docs/nut.dict index 798d255269..2726b31ea0 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 3285 utf-8 AAC AAS ABI @@ -2270,6 +2270,7 @@ liebertgxt lifecycle linevoltage linkdoc +linkmanext linksingledoc linksrcdoc linux @@ -3035,6 +3036,7 @@ ttyb ttyc ttymode ttyp +tunables tuple tuples turnon From 17e3e6c4f52e8b6df2fbca468a50ec02b071d7c1 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 15:12:55 +0100 Subject: [PATCH 33/67] docs/config-notes.txt: refer to nutconf; split the NOTE into paragraphs Signed-off-by: Jim Klimov --- docs/config-notes.txt | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/config-notes.txt b/docs/config-notes.txt index 1532b87f31..7c63a26869 100644 --- a/docs/config-notes.txt +++ b/docs/config-notes.txt @@ -9,12 +9,19 @@ There are many programs and <> in this package. You should check out the <> and other accompanying documentation to see how it all works. -NOTE: NUT does not currently provide proper graphical configuration tools. +[NOTE] +====== +NUT does not currently provide proper graphical configuration tools. However, there is now support for linkdoc:developer-guide[Augeas,augeas_user], which will enable the easier creation of configuration tools. + +The linkman:nutconf[8] tool should also help with programmatic manipulation +of various NUT configuration files. + Moreover, linkman:nut-scanner[8] is available to discover supported devices (USB, SNMP, Eaton XML/HTTP and IPMI) and NUT servers (using Avahi or the classic connection method). +====== Details about the configuration files ------------------------------------- From 2cf37119e70ba8f3f97ec499cf0ff3763873d159 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 15:16:51 +0100 Subject: [PATCH 34/67] docs/config-notes.txt: Driver configuration: clarify dependency on built-in identifiers, and that they may be avoided Signed-off-by: Jim Klimov --- docs/config-notes.txt | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/config-notes.txt b/docs/config-notes.txt index 7c63a26869..26cd6695b5 100644 --- a/docs/config-notes.txt +++ b/docs/config-notes.txt @@ -166,10 +166,12 @@ You must still set this value, but it does not matter what you set it to; a common and good practice is to set 'port' to *auto*, but you can put whatever you like. -If you only own one USB UPS, the driver will find it automatically. +If you only own one USB UPS, the driver will find it automatically +if it matches the identifiers are built into that driver. If you own more than one, refer to the driver's manual page for more -information on matching a specific device. +information on matching a specific device, or trying specific subdriver +or protocol options with a currently unknown device. ====== NOTE: On Windows systems, the second serial port (COM2), equivalent to From 2a1aa49eb3db1f6372d8b55a29b1deb95debfd5a Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 15:18:50 +0100 Subject: [PATCH 35/67] docs/config-notes.txt: Starting the driver(s): re-title that this is a chapter for legacy approach with upsdrvctl (keep same anchor) Signed-off-by: Jim Klimov --- docs/config-notes.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/config-notes.txt b/docs/config-notes.txt index 26cd6695b5..d77cd986aa 100644 --- a/docs/config-notes.txt +++ b/docs/config-notes.txt @@ -189,8 +189,8 @@ linkman:usbhid-ups[8] [[Starting_drivers]] -Starting the driver(s) -~~~~~~~~~~~~~~~~~~~~~~ +Starting the driver(s) in legacy operating systems +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Generally, you can just start the driver(s) for your hardware (all sections defined in 'ups.conf') using the following command: @@ -223,6 +223,7 @@ user account your driver starts as. After making changes, try the <> step again. +[[Starting_drivers_NDE]] Driver(s) as a service ~~~~~~~~~~~~~~~~~~~~~~ From 09fbcdff98e8c503d1e87ff422add7713c36c856 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 15:30:41 +0100 Subject: [PATCH 36/67] docs/config-notes.txt: suggest more typical locations for POWERDOWNFLAG file Signed-off-by: Jim Klimov --- docs/config-notes.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/config-notes.txt b/docs/config-notes.txt index d77cd986aa..1bacbfe376 100644 --- a/docs/config-notes.txt +++ b/docs/config-notes.txt @@ -576,8 +576,8 @@ become sufficiently charged. - generates a `NOTIFY_SHUTDOWN` event - waits `FINALDELAY` seconds -- typically `5` - - creates the `POWERDOWNFLAG` file in its local filesystem -- - usually `/etc/killpower` + - creates the `POWERDOWNFLAG` file in its local filesystem -- usually + `/etc/killpower`, or `/run/nut/killpower` in a temporary file system - calls the `SHUTDOWNCMD` 7. On most systems, `init` takes over, kills your processes, syncs and From 8c39777acd7a638d5410eb2be9f483cc45dbd93e Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 15:31:16 +0100 Subject: [PATCH 37/67] docs/config-notes.txt: refer to nutshutdown script in NUT sources Signed-off-by: Jim Klimov --- docs/config-notes.txt | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/config-notes.txt b/docs/config-notes.txt index 1bacbfe376..7a8a03d1bb 100644 --- a/docs/config-notes.txt +++ b/docs/config-notes.txt @@ -809,6 +809,9 @@ as an example: ------------------------------------------------------------------------------ +A more elaborate example can be found in NUT sources, e.g.: +https://github.com/networkupstools/nut/blob/master/scripts/systemd/nutshutdown.in + [WARNING] ============================================================================== - Be careful that `upsdrvctl shutdown` command will probably power off From e83d0d4cbb8bcbb8410ed89018eaece064deb17f Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 15:31:56 +0100 Subject: [PATCH 38/67] docs/config-notes.txt: note the system-wide sleep support beginning in NUT v2.8.3 Signed-off-by: Jim Klimov --- docs/config-notes.txt | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/config-notes.txt b/docs/config-notes.txt index 7a8a03d1bb..c099e0ace3 100644 --- a/docs/config-notes.txt +++ b/docs/config-notes.txt @@ -892,6 +892,12 @@ will the `upsmon` client. Some drivers may work after resuming, but many don't and some UPS devices will require re-initialization, so it's best not to keep them running either. +NOTE: Starting with NUT v2.8.3, there is some growing support for system-wide +sleep on some platforms (e.g. to catch the "going to sleep" event and make +a note of it in the daemons, to take the least-surprise corrective actions +after a significant change in system clock readings), but the warnings in +previous paragraph may still apply. + After stopping NUT driver, server and client you'll have to send the UPS the command to shutdown only if the `POWERDOWNFLAG` is present. Note that most likely you'll have to allow for a grace period after calling From fac25701ccf8dc0a2a67b2177bc3d099ef52e1f0 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 15:50:04 +0100 Subject: [PATCH 39/67] docs/man/libupsclient-config.txt, docs/configure.txt: clarify `lib/libupsclient-config --config-flags` vs. `libupsclient.pc` Signed-off-by: Jim Klimov --- docs/configure.txt | 5 +++-- docs/man/libupsclient-config.txt | 9 +++++++++ 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/configure.txt b/docs/configure.txt index bf3228dd62..6e2b3327a7 100644 --- a/docs/configure.txt +++ b/docs/configure.txt @@ -38,8 +38,9 @@ Network UPS Tools upsd 2.8.1 Network UPS Tools version 2.8.1 configured with flags: --with-all=auto --with-doc=skip ... ---- -A more industrial approach is to use `lib/libupsclient-config --config-flags` -where supported. +A more industrial approach is to use `lib/libupsclient-config --config-flags`, +where supported. Note that the `pkg-config` manifest `libupsclient.pc` does +not easily convey this information. Keeping a report of NUT configuration ------------------------------------- diff --git a/docs/man/libupsclient-config.txt b/docs/man/libupsclient-config.txt index 1a4e21e7f1..c2a8b9d658 100644 --- a/docs/man/libupsclient-config.txt +++ b/docs/man/libupsclient-config.txt @@ -24,6 +24,11 @@ It allows to simplify build automation for systems without a `pkg-config` implementation which would instead use the `libupsclient.pc` file installed with the NUT development files. +Note that to rebuild current NUT with same settings as the installed NUT +v2.8.1 or newer, you can use `lib/libupsclient-config --config-flags`, +where supported. Note that the `pkg-config` manifest `libupsclient.pc` does +not easily convey this information. + OPTIONS ------- @@ -38,6 +43,10 @@ Print the linker flags that are necessary to link a *libupsclient* program. *--cflags*:: Print the compiler flags that are necessary to compile a *libupsclient* program. +*--config-flags*:: +Print the flags passed to `configure` script when this installation of NUT +was originally built (supported since release v2.8.1). + AUTHORS ------- From 4b6e0ecc73bc4d81ed72936998bc0488b12f6dcc Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 15:53:58 +0100 Subject: [PATCH 40/67] docs/configure.txt: clarify in-place builds wording Signed-off-by: Jim Klimov --- docs/configure.txt | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/configure.txt b/docs/configure.txt index 6e2b3327a7..1f934225be 100644 --- a/docs/configure.txt +++ b/docs/configure.txt @@ -65,15 +65,16 @@ filesystem access permissions and configuration file locations. Tries to detect and pre-set `configure` defaults for run-time settings (which you can still override if needed, but no longer *must* specify -explicitly to be on same page as the existing setup), e.g.: +explicitly to be on same page as the existing setup), most notably: -* --sysconfdir -* --with-user -* --with-group +* `--sysconfdir` +* `--with-user` +* `--with-group` If the installed NUT version supports reporting of `CONFIG_FLAGS` used during its build, the `configure` script will try to take those values -into account when running in this mode. +into account when running in this mode (and so use the same program and +data installation paths, for example). NOTE: This does not currently rely on the configuration report optionally installed by `--enable-keep_nut_report_feature` above, but might do so From 856a22793519c8af2100dfa05f349e949f1ebc10 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 15:54:17 +0100 Subject: [PATCH 41/67] docs/configure.txt: clarify libmodbus+libusb requiring libusb-1.x API Signed-off-by: Jim Klimov --- docs/configure.txt | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/configure.txt b/docs/configure.txt index 1f934225be..782c048c89 100644 --- a/docs/configure.txt +++ b/docs/configure.txt @@ -100,12 +100,18 @@ Build and install the USB drivers (default: auto-detect) Note that you need to install the libusb development package or files, and that both libusb 0.1 and 1.0 are supported. In case both are available, libusb 1.0 takes precedence, and will be used by default. + It is however possible to override this default choice by explicitly calling `--with-usb=libusb-0.1` or `--with-usb=libusb-1.0`. + If you do specify the version to use (or `yes` for auto-detection), this option would fail if requested (or any) libusb version was not found. The default `auto` value would not fail in such case. +WARNING: If you intend to use the `libmodbus` variant with `libusb` +support, you would require `libusb-1.0` specifically; the implementation +or "compat API" of `0.1` is not supported by that library version. + SNMP drivers ~~~~~~~~~~~~ @@ -199,6 +205,7 @@ so your NUT build environment should provide a prerequisite build of https://github.com/networkupstools/libmodbus/tree/rtu_usb (may be a static library build, used from a temporary installation prefix location, to avoid potential conflicts with the OS packaged shared library). +You would also need specifically `libusb-1.0` (not the older API). At the time of this writing, such constraint can be desirable for the linkman:apc_modbus[8] driver which supports different communication media. From 2a64f966aeb101ccdf58b0940ed094de6d4df06d Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 16:10:57 +0100 Subject: [PATCH 42/67] docs/configure.txt: clarify --with-all=auto option Signed-off-by: Jim Klimov --- docs/configure.txt | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/configure.txt b/docs/configure.txt index 782c048c89..be63a2b7ba 100644 --- a/docs/configure.txt +++ b/docs/configure.txt @@ -498,6 +498,10 @@ Build and install all of the above (the serial, USB, SNMP, XML/HTTP and PowerMan drivers, the CGI programs and HTML files, and the upsclient library). +You can also use `--with-all=auto` to detect available prerequisites and +only build everything that we can build on this system (but not fail due +to inability to request a build of something from the full scope). + Networking transport security ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From cacac40b7eeffc999c1c2b8390a58c045c3fc4b1 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 16:14:21 +0100 Subject: [PATCH 43/67] docs/configure.txt: reword what "state path" is Signed-off-by: Jim Klimov --- docs/configure.txt | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/configure.txt b/docs/configure.txt index be63a2b7ba..323fd7f8e1 100644 --- a/docs/configure.txt +++ b/docs/configure.txt @@ -838,15 +838,16 @@ will leave files here. --with-altpidpath=PATH Programs that normally don't have `root` powers, like the drivers and -`upsd`, write their pid files here. By default this is whatever the +`upsd`, write their PID files here. By default this is whatever the statepath (below) is, as those programs should be able to write there. The `NUT_ALTPIDPATH` environment variable overrides this at run time. --with-statepath=PATH -Change the default location of the state sockets created by the drivers -to interact with the data server `upsd`. Default is `/var/state/ups`. +Change the default location of the local Unix sockets created by the drivers +to interact with the data server `upsd` to report their state and receive +commands. Default is `/var/state/ups`. The `NUT_STATEPATH` environment variable overrides this at run time. From 40fbf2f9bb1c571b96f6954321601760b8e2946e Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 16:14:47 +0100 Subject: [PATCH 44/67] docs/configure.txt: move LibGD header to its related content; pkg-config is a dependency of its own Signed-off-by: Jim Klimov --- docs/configure.txt | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/configure.txt b/docs/configure.txt index 323fd7f8e1..2359b25b00 100644 --- a/docs/configure.txt +++ b/docs/configure.txt @@ -862,8 +862,8 @@ systems and `"C:\\killpower"` (note the double backslashes) on Windows. Things the compiler might need to find -------------------------------------- -LibGD -~~~~~ +pkg-config tooling +~~~~~~~~~~~~~~~~~~ --with-pkg-config @@ -873,6 +873,9 @@ possibly other build-time options in `*.pc` files, to use third-party libraries. On build systems which support multiple architectures you may also want to set `PKG_CONFIG_PATH` to match your current build. +LibGD +~~~~~ + --with-gd-includes="-I/foo/bar" If you installed `libgd` in some place where your C preprocessor can't From ee47ccbe9c52377d8038e643310635490c48c74e Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 16:29:32 +0100 Subject: [PATCH 45/67] docs/configure.txt: suggest use of "-R/lib/path" with non-standard locations Signed-off-by: Jim Klimov --- docs/configure.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/configure.txt b/docs/configure.txt index 2359b25b00..c5c12513c8 100644 --- a/docs/configure.txt +++ b/docs/configure.txt @@ -916,15 +916,15 @@ Various --with-neon-includes, --with-libltdl-includes, --with-powerman-includes="-I/foo/bar" -If your system doesn't have pkg-config and support for any of the above +If your system doesn't have `pkg-config` and support for any of the above libraries isn't found (but you know it is installed), you must specify the compiler flags that are needed. --with-ssl-libs, --with-usb-libs, --with-snmp-libs, --with-neon-libs, --with-libltdl-libs - --with-powerman-libs="-L/foo/bar -labcd -lxyz" + --with-powerman-libs="-L/foo/bar -R/foo/bar -labcd -lxyz" -If system doesn't have pkg-config or it fails to provides hints for +If system doesn't have `pkg-config` or it fails to provides hints for some of the settings that are needed to set it up properly and the build in defaults are not right, you can specify the correct values for your system here. From aeddb8f71a9d95e5e41a7bd848520b2d8fdc5a35 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 16:31:40 +0100 Subject: [PATCH 46/67] docs/design.txt: explain the location and communication of the 3 layers in words Signed-off-by: Jim Klimov --- docs/design.txt | 24 +++++++++++++++++++++++- docs/nut.dict | 3 ++- 2 files changed, 25 insertions(+), 2 deletions(-) diff --git a/docs/design.txt b/docs/design.txt index 9655f01005..da813107e8 100644 --- a/docs/design.txt +++ b/docs/design.txt @@ -2,12 +2,34 @@ NUT design document =================== This software is designed around a layered scheme with drivers, a -server and clients. These layers communicate with text-based +data server, and clients. These layers communicate with text-based protocols for easier maintenance and diagnostics. The layering ------------ +The NUT driver(s) and the data server run on the same system, which +has some communications media connected to the power device (e.g. a +serial or USB link, a local IPMI interface, or a network interface +in the engineering VLAN). While each driver program talks the device +vendor-defined protocol over such media, it also talks the local +NUT Socket protocol to the local data server. + +Clients connect to the data server using the common NUT Network protocol +over TCP, whether on `localhost` or remotely. + +One most notable client is `upsmon`, which is responsible for shutdown +of the system it runs on, when the power situation becomes critical. +Design-wise, it normally splits into two daemons to minimize security +risks: one remains with 'root' privileges and is only used to start +the configured `SHUTDOWNCMD` when the time comes, and the other half +drops privileges and does the bulk of work. + +NOTE: There were requests for enhancement to also implement connectivity +using the common NUT Network protocol using local sockets, so clients +running on the same machine as the data server would not have to always +use the TCP/IP stack; however this is currently not implemented. + image:images/nut_layering.png[NUT layering] diff --git a/docs/nut.dict b/docs/nut.dict index 2726b31ea0..22b12ea5e5 100644 --- a/docs/nut.dict +++ b/docs/nut.dict @@ -1,4 +1,4 @@ -personal_ws-1.1 en 3285 utf-8 +personal_ws-1.1 en 3286 utf-8 AAC AAS ABI @@ -1334,6 +1334,7 @@ VER VERFW VFI VIB +VLAN VM VMIN VMM From 5fb4d77843bf10f1ad78bec501b9bba679f33b69 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 16:37:47 +0100 Subject: [PATCH 47/67] docs/configure.txt: clarify (again) that statepath is the default value for altpidpath, and expose why it is so named Signed-off-by: Jim Klimov --- docs/configure.txt | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/configure.txt b/docs/configure.txt index c5c12513c8..dc0bcebfb6 100644 --- a/docs/configure.txt +++ b/docs/configure.txt @@ -849,8 +849,15 @@ Change the default location of the local Unix sockets created by the drivers to interact with the data server `upsd` to report their state and receive commands. Default is `/var/state/ups`. +This is also the default location for non-`root` daemons to write a PID file, +if a separate location is not specified by `--with-altpidpath` option. + The `NUT_STATEPATH` environment variable overrides this at run time. +NOTE: Fun fact: in early iterations of the NUT project, the drivers and the +data server did exchange information by writing and reading complete state +files in a commonly accessible location, hence the name. + --with-powerdownflag=FILEPATH Change the default location (full filename path) of the POWERDOWNFLAG From b742c6897b47cbb446437fce549dea5d70e0838d Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 16:50:53 +0100 Subject: [PATCH 48/67] docs/design.txt: update the HISTORY section with NUT for Windows named pipes, and driver-to-driver queries using local socket protocol [#1903] Signed-off-by: Jim Klimov --- docs/design.txt | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/design.txt b/docs/design.txt index da813107e8..85a8c054fb 100644 --- a/docs/design.txt +++ b/docs/design.txt @@ -232,3 +232,15 @@ Drivers used to call `setinfo()` to change the local array, and then would call `writeinfo()` to push the array onto the disk, or into the mmap/shared memory space. This introduced a lag since many drivers poll quite a few variables during an update. + +By 2013 much of the work on NUT for Windows branch (based off the NUT v2.6.5 +release) was completed, adding named pipes as the equivalent to local sockets +as well as to cross-program signals. This work got a face-lift and was merged +into the main code base about a decade later, in 2022. + +In April 2023 (eventually released with NUT v2.8.1 and enhanced/fixed in +later releases), a new use-case was added: interactions of two instances +of a driver program over the local socket, as an alternative to signals +for the already-running driver to reload configuration, exit and make way +for a new instance of the driver daemon, or command the UPS to kill power +without the overhead of a new connection made by such new instance. From 412d043a16414c4665d599ae73560eb433462aea Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 16:57:36 +0100 Subject: [PATCH 49/67] docs/developer-guide.txt: refer to NUT DDL repo Signed-off-by: Jim Klimov --- docs/developer-guide.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/developer-guide.txt b/docs/developer-guide.txt index ec60aa3982..bd103ae851 100644 --- a/docs/developer-guide.txt +++ b/docs/developer-guide.txt @@ -83,7 +83,8 @@ Here is an example to setup a device simulation: the <>. Sample files are provided in the `data` directory of the NUT source. You can also download these from the development repository, such as the - link:https://github.com/networkupstools/nut/raw/master/data/evolution500.seq[evolution500.seq]. + link:https://github.com/networkupstools/nut/raw/master/data/evolution500.seq[evolution500.seq] + or from link:https://github.com/networkupstools/nut-ddl/[NUT DDL] collection. - copy the simulation file to your sysconfig directory, like `/etc/nut` or `/etc/ups` - configure NUT for simulation (linkman:ups.conf[5]): From 7a7db51a72064e47315413afb2d001d6be800e4d Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 17:49:09 +0100 Subject: [PATCH 50/67] docs/developers.txt: revise explanation of fatalx() et al - it is not always EXIT_FAILURE Signed-off-by: Jim Klimov --- docs/developers.txt | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/developers.txt b/docs/developers.txt index aa31c8c66b..b16df3ae4b 100644 --- a/docs/developers.txt +++ b/docs/developers.txt @@ -30,10 +30,12 @@ means you don't have to worry about whether you're running in the background or not. The `upslog_with_errno()` routine prints your message plus the string -expansion of `errno`. The `upslogx()` just prints the message. +expansion of current `errno` value. The `upslogx()` just prints the message. `fatal_with_errno()` and `fatalx()` work the same way, but they -also `exit(EXIT_FAILURE)` afterwards. Don't call `exit()` directly. +also `exit(arg)` afterwards, where `arg` is the first argument of the +`fatal*()` method -- typically `EXIT_FAILURE` or `EXIT_SUCCESS`. +In most cases, you should not call `exit()` directly. Debugging information ~~~~~~~~~~~~~~~~~~~~~ From a8fda81476973cfb9dff06a84c1d400a84df88b6 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 17:49:36 +0100 Subject: [PATCH 51/67] docs/developers.txt: fix formatting of a paragraph with many mentions of "C++" Signed-off-by: Jim Klimov --- docs/developers.txt | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/developers.txt b/docs/developers.txt index b16df3ae4b..97b9142ca0 100644 --- a/docs/developers.txt +++ b/docs/developers.txt @@ -188,8 +188,14 @@ It was also seen that cross-builds (e.g. NUT for Windows using mingw on Linux) may be unable to define `WIN32` and/or find symbols for linking when using a strict-C language standard. -The C++ support expects C++11 or newer (not really configured or tested -for older C++98 or C++03), modulo features that were deprecated in later +/////////// +EDITOR NOTE: plus-plus sequences are seen by asciidoc as opening/closing +tags of "literal" markup, so have to be escaped. But only pairs (the last +standalone copy in a paragraph should NOT be escaped!) +/////////// + +The C\++ support expects C\++11 or newer (not really configured or tested +for older C\++98 or C\++03), modulo features that were deprecated in later language revisions (C++14 onwards) as highlighted by warnings from newer compilers. From cc5a67bb4904c390428694bf43a2bf99f171ba98 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 17:50:57 +0100 Subject: [PATCH 52/67] docs/developers.txt: link to "Documentation/CodingStyle" of Linux kernel fame Signed-off-by: Jim Klimov --- docs/developers.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/developers.txt b/docs/developers.txt index 97b9142ca0..2d01de606d 100644 --- a/docs/developers.txt +++ b/docs/developers.txt @@ -1023,8 +1023,8 @@ used in that file will probably be dropped. If it's something we really need, it will be grudgingly reformatted before being included. When in doubt, have a look at Linus's take on this topic in the Linux -kernel -- Documentation/CodingStyle. He's done a far better job of -explaining this. +kernel -- link:https://github.com/torvalds/linux/blob/master/Documentation/process/coding-style.rst[Documentation/CodingStyle]. +He's done a far better job of explaining this. Line breaks ~~~~~~~~~~~ From eed959dfe5e064ca8378c1c1d89bba7f844f8f7d Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 17:51:56 +0100 Subject: [PATCH 53/67] docs/developers.txt: mention plan for clang-format automation Signed-off-by: Jim Klimov --- docs/developers.txt | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/developers.txt b/docs/developers.txt index 2d01de606d..165bce3053 100644 --- a/docs/developers.txt +++ b/docs/developers.txt @@ -1102,6 +1102,12 @@ configuration toggle in the GUI. Others may need a plugin, see more at https://editorconfig.org/#pre-installed page. There are also command-line tools to verify and/or enforce compliance of source files to configuration. +NOTE: A long-standing plan is to define a `clang-format` specification +for all the different nuances like where we do and don't want spaces +around parentheses, how to align multi-line conditional expressions, etc. +in a way that most of the current NUT code base would already conform. +Taking the first step is the hardest part, so PRs are welcome :) + You can go a long way towards converting your source code to the NUT coding style by piping it through the following command: From fa1a08b1955d4a8ff0674a662a0e5ac39609413b Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 17:52:20 +0100 Subject: [PATCH 54/67] docs/developers.txt: mention more of our valgrind automation Signed-off-by: Jim Klimov --- docs/developers.txt | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/docs/developers.txt b/docs/developers.txt index 165bce3053..2d61d54480 100644 --- a/docs/developers.txt +++ b/docs/developers.txt @@ -1276,13 +1276,16 @@ in the vicinity gets a visit. Memory leak checking ~~~~~~~~~~~~~~~~~~~~ -We can't say enough good things about valgrind. If you do anything with -dynamic memory in your code, you need to use this. Just compile with -`gcc -g` and start the program inside `valgrind`. Run it through the -suspected area and then exit cleanly. valgrind will tell you if you've -done anything dodgy like freeing regions twice, reading uninitialized -memory, or if you've leaked memory anywhere. +We can't say enough good things about valgrind. +If you do anything with dynamic memory in your code, you need to use this. +Just compile with `gcc -g` and start the program inside `valgrind`. +Run it through the suspected area and then exit cleanly. Then valgrind +will tell you if you've done anything dodgy like freeing regions twice, +leaving files open, reading uninitialized memory, or if you've leaked +memory anywhere. + +For NUT, there are prepared integrations like `configure --with-valgrind`. See also `scripts/valgrind` in NUT sources for a helper tool and resource files to suppress common third-party problems. From 8b4dc01c2d4210d09b4dd8ed87a9835b950ca2a0 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 18:00:00 +0100 Subject: [PATCH 55/67] docs/developers.txt: revise GitHub-based review and contribution process Signed-off-by: Jim Klimov --- docs/developers.txt | 20 +++++++++++--------- docs/nut.dict | 3 ++- 2 files changed, 13 insertions(+), 10 deletions(-) diff --git a/docs/developers.txt b/docs/developers.txt index 2d61d54480..bebee432fb 100644 --- a/docs/developers.txt +++ b/docs/developers.txt @@ -1305,7 +1305,7 @@ Current preference for suggesting changes is to open a pull request on GitHub for the https://github.com/networkupstools/nut/ project. For some cases, small patches that arrive by mailing list in unified -format (`diff -u`) as plain text attachments with no HTML and a brief +format (`diff -Naur`) as plain text attachments with no HTML and a brief summary at the top are easy to handle, but sadly also easy to overlook. If a patch is sent to the nut-upsdev mailing list, it stands a better @@ -1315,10 +1315,11 @@ for others, or if it is a large change, your best bet is to submit a pull request or create an link:https://github.com/networkupstools/nut/issues[issue on GitHub]. -The issue tracker allows us to track the patches over a longer period -of time, and it is less likely that a patch will fall through the cracks. +The issue tracker allows us to track the patches, and related discussion +for clarifications or a review process, over a longer period of time, +and it is less likely that a patch will fall through the cracks. Posting a reminder to the developers (via the nut-upsdev list) about a -patch on GitHub is fair game. +patch on GitHub is fair game, if the maintainers do not react in a few days. Patch cohesion -------------- @@ -1370,9 +1371,9 @@ Source code management ---------------------- We currently use a Git repository hosted at GitHub to track changes to -the NUT source code. This allows you to clone the repository (or fork, -in GitHub parlance), make changes, and post them online for peer review -prior to integration. +the NUT source code. This allows you to "fork" the repository (in GitHub +parlance), "clone" it to your workstation(s), make a new "branch" with +your changes, and post them back online for peer review prior to integration. To obtain permission to commit directly to the common upstream NUT repository, you must be prepared to spend a fair amount of time contributing to the @@ -1479,8 +1480,8 @@ that title is used throughout git. If your commit is just a change to one component, such as the HCL, upsd or a specific driver, prefix your commit message in a way that matches similar -commits. This helps when searching the repository or tracking down a -regression. +commits (typically with the file name(s), check `git log` for inspiration). +This helps when searching the repository or tracking down a regression. Referring to previous commits can be tricky. If you are referring to the immediate parent of a given commit, it suffices to say "the previous commit". @@ -1519,6 +1520,7 @@ configuration option. For more details see: * https://github.com/networkupstools/nut/issues/1994 +* https://github.com/networkupstools/nut/wiki/Code-contributions,-PRs,-PGP-and-DCO * https://stackoverflow.com/questions/1962094/what-is-the-sign-off-feature-in-git-for * https://stackoverflow.com/questions/15015894/git-add-signed-off-by-line-using-format-signoff-not-working diff --git a/docs/nut.dict b/docs/nut.dict index 22b12ea5e5..b3eb29502b 100644 --- a/docs/nut.dict +++ b/docs/nut.dict @@ -1,4 +1,4 @@ -personal_ws-1.1 en 3286 utf-8 +personal_ws-1.1 en 3287 utf-8 AAC AAS ABI @@ -768,6 +768,7 @@ Nadav Nagios Nash NaturalDocs +Naur Necedah NetBSD NetBeans From 03d0717d3fa8b0055748c5e8061215ae963f6bd7 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 18:00:37 +0100 Subject: [PATCH 56/67] docs/developers.txt: fix links to NEWS.adoc and UPGRADING.adoc (now with .adoc extensions) Signed-off-by: Jim Klimov --- docs/developers.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/developers.txt b/docs/developers.txt index bebee432fb..71ba466014 100644 --- a/docs/developers.txt +++ b/docs/developers.txt @@ -1361,9 +1361,9 @@ welcome an entry in the link:docs/acknowledgements.txt[] file as well, to track and know the industry players who help make NUT better and more useful. -It is nice to update the link:NEWS[] file for significant development +It is nice to update the link:NEWS.adoc[] file for significant development to be seen as part of next release, as well as to update the -link:UPGRADING[] file for potentially breaking changes and similar +link:UPGRADING.adoc[] file for potentially breaking changes and similar heads-up notes for third-party teams (distribution packagers, clients and bindings, etc.) From e82f80c6cfd67e05ae4390f272cda3f7635e5c73 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 18:16:08 +0100 Subject: [PATCH 57/67] docs/developers.txt: refresh info about CI builds Signed-off-by: Jim Klimov --- docs/developers.txt | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/docs/developers.txt b/docs/developers.txt index 71ba466014..fc61dcbfb5 100644 --- a/docs/developers.txt +++ b/docs/developers.txt @@ -318,14 +318,15 @@ the same inputs, try telling `./ci_build.sh` to loop configuring until success (instead of quickly failing), and/or tell `./configure` to use another shell at least for the system call-outs, with options like these: - SHELL=/bin/bash CONFIG_SHELL=/bin/bash CI_SHELL_IS_FLAKY=true \ - ./ci_build.sh + :; SHELL=/bin/bash CONFIG_SHELL=/bin/bash CI_SHELL_IS_FLAKY=true \ + ./ci_build.sh Jenkins CI ^^^^^^^^^^ Since mid-2021, the NUT CI farm is implemented by several virtual servers -courteously provided by link:http://fosshost.org[Fosshost] and later by +courteously provided originally by link:http://fosshost.org[Fosshost] and +later by link:https://www.digitalocean.com/?refcode=d2fbf2b9e082&utm_campaign=Referral_Invite&utm_medium=Referral_Program&utm_source=badge[DigitalOcean]. These run various operating systems as build agents, and a Jenkins instance @@ -452,7 +453,7 @@ Local private deployments of Travis CI are possible, so if anybody does use it and has updated markup to share, they are welcome to post PRs. ====== -The NUT project on GitHub has integration with Travis CI to test a large +The NUT project on GitHub had integration with Travis CI to test a large set of compiler and option combinations, covering different versions of gcc and clang, C standards, and requiring to pass builds at least in a mode without warnings (and checking the other cases where any warnings @@ -1646,7 +1647,8 @@ Even if you do not use your distribution's packages of NUT, installing the distribution's list of build dependencies for NUT can reduce the amount of trial-and-error when installing dependencies. For instance, in Debian, you can run `apt-get build-dep nut` to install all of the auto* tools as well -as any development libraries and headers. +as any development libraries and headers -- as known for the version of NUT +packaged with the OS distribution release you are using. After running `./autogen.sh`, you can pass your local configuration options to `./configure` and run `make` from the top-level directory. @@ -1673,9 +1675,12 @@ There is also `make distcheck`, which runs an even stricter set of tests than `make distcheck-light`, but will not work unless you have all of the optional third-party libraries and features installed. -Finally note, that since 2017 the GitHub upstream project is monitored +Finally note, that since 2017 the GitHub upstream project was monitored by Travis CI (in addition to earlier multi-platform buildbots which -occasionally do not work), replaced since 2021 by a dedicated NUT CI farm. +occasionally did not work), replaced since 2021 by a dedicated NUT CI farm +and a number of free cloud CI resources to test some 200-300 scenarios +with different combinations of build environments and tooling implementations. + This means that if your posted improvements are based on current NUT "master" branch, the resulting pull request should get tested for a number of scenarios automatically. If your code adds a substantial feature, consider From f8f8cde3dcc4ad095fac9274730db9c796f21e3f Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 18:23:59 +0100 Subject: [PATCH 58/67] docs/download.txt: do not list NUT for Windows MSI 2.6.5 as if it were the latest option Signed-off-by: Jim Klimov --- docs/download.txt | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/download.txt b/docs/download.txt index 984e3b7bfa..e9e9c525b9 100644 --- a/docs/download.txt +++ b/docs/download.txt @@ -165,7 +165,12 @@ link:https://github.com/networkupstools/nut/wiki/Links-to-distribution-packaging - Windows (complete port, Beta): - * link:https://www.networkupstools.org/package/windows/NUT-Installer-2.6.5-6.msi[Windows MSI installer 2.6.5-6] + * Current Appveyor CI builds are available as tarballs with binaries from + https://ci.appveyor.com/project/nut-travis/nut/build/artifacts -- but + it may be difficult to locate specifically the master-branch builds. + See link:https://github.com/networkupstools/nut/wiki/NUT-for-Windows[NUT + for Windows wiki article] for these details, and more. + * link:https://www.networkupstools.org/package/windows/NUT-Installer-2.6.5-6.msi[(OBSOLETE) Windows MSI installer 2.6.5-6] Java packages From b9891e9b37ce1820a183ac701f99d2fe67487ce0 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 19:29:58 +0100 Subject: [PATCH 59/67] docs/FAQ.txt: update some answers and a lot of asciidoc markup Signed-off-by: Jim Klimov --- docs/FAQ.txt | 317 ++++++++++++++++++++++++++++++--------------------- 1 file changed, 187 insertions(+), 130 deletions(-) diff --git a/docs/FAQ.txt b/docs/FAQ.txt index 806bb41e46..c45ac89ad2 100644 --- a/docs/FAQ.txt +++ b/docs/FAQ.txt @@ -4,7 +4,7 @@ NUT Frequently Asked Questions endif::external_title[] == I just upgraded, and ... -You have read link:UPGRADING[UPGRADING] in the base directory of the +You have read link:UPGRADING.adoc[UPGRADING] in the base directory of the distribution, right? If not, go read it now, then come back to this file if your @@ -36,10 +36,11 @@ already been done in the old version. *Answer 1* -The drivers drop root privileges long before the serial port is +The drivers drop root privileges long before the serial or USB port is opened. You'll need to change the permissions on that port so that -their new user id can access it. Normally this is "nobody", but it -may be changed at compile-time by using configure --with-user. +their new user id can access it. Normally this is 'nobody', but it +may be changed at compile-time by using `configure --with-user` or +in the `ups.conf` file for driver settings with `user=...`. Read the error message. If you have a permissions mismatch, then you'll see something like this: @@ -51,40 +52,43 @@ you'll see something like this: of /dev/ttyS2 and try again. Unable to open /dev/ttyS2: Permission denied -Now is a good time to point out that using "nobody" is a bad idea, +Now is a good time to point out that using 'nobody' is a bad idea, since it's a hack for NFS access. You should create a new role -account (perhaps called "ups" or "nut"), and use that instead. +account (perhaps called 'ups' or 'nut'), and use that instead. Also, scroll down to the "security domains" question to see an even better way of restricting privileged operations. Neither the -drivers nor upsd ever need root powers, and that answer tells you +drivers nor `upsd` ever need 'root' powers, and that answer tells you how to make it work. *Answer 2* -You can also specify a user with "user=" in the global part of -ups.conf. Just define it before any of your [sections]: +You can also specify a user with `user=` in the global part of +linkman:ups.conf[5]. Just define it before any of your `[sections]`: +---- user = nut [myups] driver = mge-shut port = /dev/ttyS0 +---- == upsc, upsstats, and the other clients say 'access denied'. The device communication port (serial, USB or network) permissions are fine, so what gives? -In this case, "access denied" means the access to upsd, not the device -communication port. You're being denied since the system has no -permission to speak to upsd according to the access controls. +In this case, "access denied" means the access to linkman:upsd[8], not the +device communication port. You're being denied since the system has no +permission to speak to `upsd` according to its access controls. -There can be various reasons. To fix it, check: +There can be due to various reasons. To fix it, check: -- the LISTEN directive in upsd.conf. It should allow your local or remote -access method, -- your firewall rules. Port 3493/tcp must be opened to incoming connections, -- your tcp-wrappers configuration (hosts.allow and hosts.deny). +- the LISTEN directive in linkman:upsd.conf[5]. It should allow your + local or remote access method, +- your firewall rules. Port '3493/tcp' must be opened to incoming connections, +- your *tcp-wrappers* configuration (`hosts.allow` and `hosts.deny`) if used. -Refer to the upsd(8) and upsd.conf(5) manpages for more information. +Refer to the linkman:upsd[8] and linkman:upsd.conf[5] manpages for more +information. == I get a 'not listening on...' error from upsd. @@ -163,19 +167,20 @@ hardware properly. *Answer 1* -We try to follow the "tool for the job" philosophy. It may mean +We try to follow the "tool for the job" philosophy of Unix. It may mean more programs running, but the flexibility you get is usually worth it. Yes, the machine with the UPS attached will generally have 3 -processes (driver, upsd, upsmon) running, but this design allows a -much bigger setup. Imagine a data room with a bunch of machines -all drawing power from the same UPS. The rest of them just run -upsmon. +processes (driver, `upsd`, `upsmon`) running, but this design allows +a much bigger setup. Imagine a data room with a bunch of machines +all drawing power from the same UPS. Only one can be connected by a +serial or USB cable, and the rest of them just run an `upsmon` client. -Besides, if upsmon were rolled into upsd, upsd would get even +Besides, if `upsmon` were rolled into `upsd`, `upsd` would get even bigger than it is now. You'd have one less process, but the -RAM consumption would be pretty close to now. +RAM consumption would be pretty close to what you have now -- but +consumed on each system involved. See the "Data Room" section in link:docs/config-notes.txt[] for more configuration ideas and explanations. @@ -183,19 +188,26 @@ more configuration ideas and explanations. *Answer 2* If this really bothers you, roll up your sleeves and use the -sockdebug code to write a "upsmon" type program that sits on top of -the state sockets. It won't work over the network, but it means -you don't need upsd. It also means only one host can monitor the +linkman:sockdebug[8]] code to write a "upsmon" type program that sits on +top of the state sockets. It won't work over the network, but it means +you don't need `upsd`. It also means only one host can monitor the UPS. This is also a good option to consider if you can't use networked monitoring code for security or safety reasons. +*Answer 3* + +There are plans in the queue... for a long time... to extend `upsd` data +server and the NUT clients with ability to use a local Unix socket for the +NUT Networked protocol. This would also allow to forgo the dependency on +TCP/IP stack for communications within one machine. + See the TODO file for more on this and other related topics. == Why isn't upssched part of upsmon? -Most users will never have any reason to use upssched. It's +Most users will never have any reason to use `upssched`. It's complicated, and getting it right for your situation can be tricky. Having it live in a separate program saves resources and lets most people avoid it completely. @@ -206,20 +218,20 @@ It is also coherent with the answer to the previous question. *Answer 1* -New versions of the init man page taken from the sysvinit package -are saying that usage of SIGPWR is discouraged, since /dev/initctl +New versions of the `init` man page taken from the *sysvinit* package +are saying that usage of `SIGPWR` is discouraged, since `/dev/initctl` control channel is the preferred way of communication. *Answer 2* -The name of the game is portability. Not everyone's init handles +The name of the game is portability. Not everyone's `init` handles that kind of signalling gracefully. What's more, some admins might want to do things differently even if they have that kind of -init running. +`init` running. So, to be compatible, upsmon just invokes a shell command. If you -want to use init's SIGPWR stuff, just put the right "kill" line in -a shell script and make upsmon call it. Everyone wins. +want to use init's `SIGPWR` stuff, just put the right "kill" line in +a shell script and make your `upsmon` call it. Everyone wins. == Why won't bestups talk to my Best Fortress UPS? @@ -254,31 +266,32 @@ directly affects how long you run on battery without knowing what's going on with the UPS. Note: some drivers occasionally need more time to update than the -default value of MAXAGE (in upsd.conf) allows. As a result, they +default value of MAXAGE (in `upsd.conf`) allows. As a result, they are temporarily marked stale even though everything is fine. This -can happen with MGE Ellipse equipment -- see the mge-shut or usbhid-ups man -pages. In such cases, you can raise the value of MAXAGE to avoid these -warnings; try a value like 25 or 30. +can happen with MGE Ellipse equipment -- see the linkman:mge-shut[8] +or linkman:usbhid-ups[8] man pages. In such cases, you can raise +the value of MAXAGE to avoid these warnings; try a value like 25 or 30. == Why do the client programs say 'Driver not connected' when I try to run them? *Answer 1* -This means that upsd can't connect to the driver for some reason. -Your ups.conf entry might be wrong, or the driver might not be +This means that `upsd` can't connect to the driver for some reason. +Your `ups.conf` entry might be wrong, or the driver might not be running. Maybe your state path is not configured properly. Check your syslog. upsd will complain regularly if it can't connect to a driver, and it should say why it can't connect. -Note: if you jumped in with both feet and didn't follow the INSTALL.nut -document, you probably started upsd by itself. You have to run -'upsdrvctl start' to start the drivers after configuring ups.conf. +Note: if you jumped in with both feet and didn't follow the link:INSTALL.nut[] +document, you probably started `upsd` by itself. You have to run +`upsdrvctl start` (explicitly -- on legacy systems only) to start +the drivers after configuring `ups.conf`. On operating systems with a supported service management framework, you might wrap your NUT drivers into individual services instances -with 'upsdrvsvcctl resync' and then manage those with commands like -'upsdrvsvcctl stop' and 'upsdrvsvcctl start' (note that on other +with `upsdrvsvcctl resync` and then manage those with commands like +`upsdrvsvcctl stop` and `upsdrvsvcctl start` (note that on other systems this tool may be not pre-installed via packaging). In fact, service instances prepared by the `nut-driver-enumerator` script @@ -292,21 +305,25 @@ environment variable with any value). Some USB UPS devices have unreliable USB to serial interfaces. In that case, it's advised to unplug / plug the device and try again. -If that resolves the issue, you should consider resetting the USB hub the device -is attached to before starting the nut driver, using usb_resetter script from -https://github.com/netinvent/usb_resetter -See scripts/usb_resetter for more information. + +If that resolves the issue, you should consider resetting the USB hub the +device is attached to before starting the nut driver, using `usb_resetter` +script (for Linux) from https://github.com/netinvent/usb_resetter + +See files under `scripts/usb_resetter/` in NUT sources for more information. == Why don't the pathnames in your documentation match the package I installed? Each distribution has conventions for where specific file types should be stored. The NUT project cannot possibly track all of these conventions, so the documentation assumes the default installation directory prefix of -`/usr/local/ups` when describing file locations. The distributions tend not to -change the base name of the files, so you can search for drivers and -configuration files in the package database of installed files. For instance, -on Debian or Ubuntu derivatives, you can use `dpkg --search usbhid-ups` to see -where the drivers are stored. +`/usr/local/ups` when describing file locations. It also allows custom +builds of NUT to minimally conflict with files of a packaged installation. + +The distributions tend not to change the base name of the files, so you +can search for drivers and configuration files in the package database +of installed files. For instance, on Debian or Ubuntu derivatives, you +can use `dpkg --search usbhid-ups` to see where the drivers are stored. == Everything works perfectly during the shutdown, and the UPS comes back on, but my system stays off. What's happening? @@ -368,7 +385,7 @@ an enemy. Let them worry about it. This is about the same situation as the ATX question above, only worse. Earlier Macs apparently supported a hack where you could -cat some magic characters at /dev/adb to enable "server mode". +cat some magic characters at `/dev/adb` to enable "server mode". This would instruct the system to reboot while unattended. From Usenet post <6boftzxz51.fsf@ecc-office.sp.cs.cmu.edu>: @@ -410,7 +427,7 @@ This is relatively simple to fix. If you have console or VNC access, log in as an administrator, go to System Preferences, click on Energy Saver, click on the options tab, check "Restart automatically after a power failure". -Alternatively, you can connect via SSH and run "sudo pmset autorestart 1" to +Alternatively, you can connect via SSH and run `sudo pmset autorestart 1` to achieve the same effect. == I want to keep the drivers and upsd in their own security domains. How can this be accomplished? @@ -448,35 +465,36 @@ You may have to remove old socket or state files first if you are changing to this security scheme from an older version. The drivers will create new files with the right owners and modes. -Note that /var/state/ups is group writable since upsd will -place the upsd.pid file here. +Note that `/var/state/ups` is group writable since `upsd` will +place the `upsd.pid` file here by default. -You may have to change the groups of upsd.conf and upsd.users to -make them readable. These files should not be owned by nutsrv, -since someone could compromise the daemon and change the config -files. Instead, put nutsrv in a group ("nut" in this example), then -make the files owned by root.nut, with mode 0640. +You may have to change the groups of `upsd.conf` and `upsd.users` to +make them readable to the NUT `upsd` program. These files should not +be owned nor writable by `nutsrv`, since someone could compromise the +daemon and change the config files. Instead, put `nutsrv` in a group +(`nut` in this example), then make the files owned by `root.nut`, with +POSIX bits mode `0640`. Once the config files are ready, start upsd: - # upsd -u nutsrv + :; upsd -u nutsrv Check your syslog to be sure everything's happy, then be sure to update your startup scripts so it uses this procedure on your next boot. -If you like this, you'll probably also find the chroot process to -be useful and interesting. See link:security.txt[] for more details. +If you like this, you'll probably also find the linkmanext:chroot[2] process +to be useful and interesting. See link:security.txt[] for more details. == What's the point of that 'security domains' concept above? The point is limiting your losses. If someone should happen to -break into upsd in that environment, they should only gain access +break into `upsd` in that environment, they should only gain access to that one user account. Direct access to the serial device is not possible, since that is owned by another user. -There is also the possibility of running the drivers and upsd in a -chroot jail. See the chroot option in link:security.txt[], `upsd` +There is also the possibility of running the drivers and `upsd` in a +chroot jail. See the `chroot` option in link:security.txt[], `upsd` and driver documentation. Why give would-be vandals any sort of help? @@ -499,14 +517,14 @@ TODO: figure out how to link to the upssched man page above. == Why doesn't upsmon shut down my system? I pulled the plug and nothing happened. -Wait. upsmon doesn't consider a UPS to be critical until it's both -'on battery' and 'low battery' at the same time. This is by design. +Wait. The `upsmon` client doesn't consider a UPS to be critical until it's +*both* 'on battery' and 'low battery' at the same time. This is by design. Nearly every UPS supports the notion of detecting the low battery all by itself. When the voltage drops below a certain point, it _will_ let you know about it. -If your system has a really complicated shutdown procedure, you -might need to shut down before the UPS raises the low battery flag. +If your system has a really complicated or time-consuming shutdown procedure, +you might need to shut down before the UPS raises the low battery flag. For most users, however, the default behavior is adequate. Ask yourself this: why buy a nice big UPS with the matching battery @@ -525,16 +543,16 @@ this is what you really want to do. Those programs need to see a host in your hosts.conf before they will attempt communications. This keeps people from feeding it -random "host=" settings, which would annoy others with outgoing +random `host=` settings, which would annoy others with outgoing connection attempts from your system. -If your hosts.conf turns out to be configured correctly with -MONITOR entries and all that, check the permissions. Your web +If your linkman:hosts.conf[5] turns out to be configured correctly with +proper `MONITOR` entries and all that, check the permissions. Your web server may be running the CGI programs as a user that can't read the file. If you run your web server in a chroot jail, make sure the programs -can still read hosts.conf. You may have to copy it into the jail +can still read `hosts.conf`. You may have to copy it into the jail for this to work. If you do that, make sure it's not writable by any of the user accounts which run inside the jail. @@ -543,9 +561,9 @@ any of the user accounts which run inside the jail. Assuming you haven't changed the TCP port number on the command line or at compile-time, then you may have some sort of firewall blocking the connection. -upsd listens on TCP port 3493 by default. If you do not specify a LISTEN -directive in upsd.conf, upsd only listens on the loopback interface. See the -upsd.conf man page for details. +`upsd` listens on TCP port '3493' by default. If you do not specify a `LISTEN` +directive in `upsd.conf`, `upsd` only listens on the loopback interface. +See the linkman:upsd.conf[5] man page for details. == How do you make upsmon reload the config file? @@ -558,8 +576,8 @@ or just start it again with '-c reload' (requires that the previously started daemon saves a PID file). If you send the signals yourself instead of using -c, be sure you -hit the right process. There are usually two upsmon processes, and you -should only send signals to one of them. To be safe, read the pid +hit the right process. There are usually two `upsmon` processes, and you +should only send signals to one of them. To be safe, read the PID file. If your daemons are managed as systemd units, it is more idiomatic to @@ -577,16 +595,22 @@ may also work. There are several driver to support USB models. -- usbhid-ups supports various manufacturers complying to the HID Power Device Class (PDC) standard, -- tripplite_usb supports various older Tripp-Lite units (with USB ProductID 0001) -- bcmxcp_usb supports various Powerware units, -- blazer_usb supports various manufacturers that use the Megatec / Q1 protocol. -- nutdrv_qx supports various manufacturers that use the Megatec / Q* protocol - family. This is the driver slated to receive all further development in this - area, it was specially designed to support many more sub-drivers and has - added a lot over time, so please do try it first nowadays. - -Refer to the 'driver-name' (8) man page for more information. +- linkman:usbhid-ups[8] supports various manufacturers complying to + the HID Power Device Class (PDC) standard, +- linkman:tripplite_usb[8] supports various older Tripp-Lite units + (with USB ProductID 0001) +- linkman:bcmxcp_usb[8] supports various Powerware units, +- linkman:blazer_usb[8] supports various manufacturers that use the + Megatec / Q1 protocol. +- linkman:nutdrv_qx[8] supports various manufacturers that use the wider + Megatec / Q* protocol family. This is the driver slated to receive all + further development in this area, it was specially designed to support + many more sub-drivers and has added a lot over time, so please do try + it first nowadays. +- linkman:apc_modbus[8] supports some APC branded devices built after 2010 + (requires to be built against a libmodbus version with RTU USB support) + +Refer to the respective 'driver-name' (8) man page for more information. You can also consult the Hardware Compatibility List (HCL) and filter on USB: https://www.networkupstools.org/stable-hcl.html?connection=USB @@ -601,9 +625,9 @@ needed to automatically load some certain driver). Often they also lack a unique serial number field, so monitoring several devices is problematic. One frequent case is with devices identifying as "Fry's Electronics" and/or -"MEC0003", if those data are served at all, or plain "0001/0000" in ID field. -In some cases they are accompanied by "UPSmart" software with a "MEGA(USB)" -connection option that works for Windows users. +"MEC0003", if those metadata are served at all, or plain "0001/0000" in ID +field. In some cases they are accompanied by "UPSmart" software with a +"MEGA(USB)" connection option that works for Windows users. Your best bet is to search for community discussions of issues on NUT GitHub at https://github.com/networkupstools/nut/issues?q=is%3Aissue and try options @@ -638,6 +662,13 @@ been fixed in the Git master branch, your distribution may still be affected. Details are available in the following GitHub issue: https://github.com/networkupstools/nut/issues/140 +There may also be a conflict with an already running instance of the driver, +e.g. when a systemd unit instance `nut-driver@yourdevicename.service` was +automatically created and started by the `nut-driver-enumerator`, and then +you try to follow older revisions of the NUT documentation or blogs, and +start another copy with `upsdrvctl` (which should only be used on legacy +systems nowadays). + == Why do you not use the Linux kernel HID driver when communicating with USB UPSes? When the `usbhid-ups` was first written, it replaced an older driver `hidups` @@ -650,7 +681,7 @@ have very similar permissions problems as the `/dev/bus/usb` nodes that the libusb approach uses. Due to difficulties in running libusb on OS X and Windows, those platforms -might benefit more from a native HID approach. +might actually benefit more from a native HID approach. == I get a message from the kernel that the driver "did not claim interface 0 before use" @@ -664,6 +695,9 @@ There is a rudimentary locking mechanism in NUT, but there is a chance that the packages might not use the same directory as the NUT default, and the conflict will be reported by the kernel. +Also see above about conflicts between driver instances started by a service +management framework like systemd and started manually (e.g. with `upsdrvctl`). + == Why does my (Eaton 5E) USB UPS on Linux connect but quickly disconnects soon? This issue was extensively investigated by NUT community members in @@ -789,10 +823,12 @@ by another NUT server. Example with `dummy-ups` driver: - [proxy] - driver = dummy-ups - port = upsname@ip-or-hostname[:port] - desc = "UPS proxy for UPS upsname on server ip-or-hostname" +---- +[proxy] + driver = dummy-ups + port = upsname@ip-or-hostname[:port] + desc = "UPS proxy for UPS upsname on server ip-or-hostname" +---- Also note that there is a `clone` driver with similar purpose, which allows users to group clients to a particular outlet of @@ -805,17 +841,19 @@ details and caveats. Example with `clone` driver: - [realups] - driver = usbhid-ups - port = auto +---- +[realups] + driver = usbhid-ups + port = auto - [clone-outlet-1] - driver = clone - port = usbhid-ups-realups - load.on = outlet.1.load.on - load.off = outlet.1.load.off - load.status = outlet.1.status - [...] +[clone-outlet-1] + driver = clone + port = usbhid-ups-realups + load.on = outlet.1.load.on + load.off = outlet.1.load.off + load.status = outlet.1.status + [...] +---- This allows to group load attached to a separately manageable outlet (or group of outlets) on larger UPS and ePDUs, in order @@ -828,23 +866,33 @@ in a larger company. It's not really two complete copies if your OS forks efficiently. -By default, upsmon runs most of the grunt work as an unprivileged -user and keeps a stub process around with root powers that can +By default, `upsmon` runs most of the grunt work as an unprivileged +user and keeps a stub process around with 'root' powers that can only shut down the system when necessary. This should make it much -harder to gain root in the event a hole is ever discovered in -upsmon. +harder to gain 'root' in the event a hole is ever discovered in +`upsmon`. If this really bothers you and you like running lots of code as -root, start upsmon with -p and it will go back to being one big -process. This is not recommended, so don't blame us if something -bad happens in this mode. +`root`, start `upsmon` with `-p` option, and it will go back to +being one big process. This is not recommended, so don't blame +us if something bad happens in this mode. == I get the following error while building: `make[4]: don't know how to make HP-UX/nut-drvctl.sh. Stop` -NUT still has some hidden dependencies on GNU Make which show up while running -`make distcheck`. If you are running `make distcheck` or its variants, you -will need to install GNU Make (`devel/gmake` in the ports tree), which is -incidentally what the official FreeBSD port of NUT does for all builds. +*Answer 1* + +Current NUT codebase (since v2.8.0) is regularly tested with GNU, BSD and +Sun implementations of `make`, so seeing failures in release snapshots +(or iterations that made it to the master branch) is very surprising. +Please raise an issue on GitHub. + +*Answer 2* + +Older NUT codebase (release tarballs) has some hidden dependencies on +GNU Make which show up while running `make distcheck`. If you are running +`make distcheck` or its variants, you will need to install GNU Make +(`devel/gmake` in the ports tree), which is incidentally what the +official FreeBSD port of NUT does for all builds. == I have 'some problem' with 'some old version' ... @@ -863,7 +911,7 @@ yet. Please do not tell us you have the "latest version for Distro XYZ" -- even if the developers are familiar with that distribution, it helps others if you quote the exact package version. -NOTE: check the release date on the version you have. If it's more +NOTE: Check the release date on the version you have. If it's more than about 6-12 months old, there's probably a newer stable tree version out there. As development happens actively, be sure to also check if a custom build from Git (usually using the `master` branch @@ -877,12 +925,19 @@ The NUT instance of Buildbot generates tar files of the latest NUT source after each successful build, and these snapshots include a pre-built version of the `./configure` script. -Otherwise, you will need recent versions of autoconf, automake, libtool, +WARNING: There is an outstanding bug that after the shutdown of BuildBot, +no regular distribution tarballs are in fact published. + +To build from Git, you will need recent versions of autoconf, automake, libtool, asciidoc, a2x and its dependencies for DocBook/dblatex. Rather than publish a list of the exact versions needed (which will quickly become out of date), we recommend you consult your distribution's dependency list for building a NUT package, and use that as a starting point. +That said, for the numerous systems running build agents of the NUT CI farm, +their lists of dependency packages are available in `docs/config-prereqs.txt` +in NUT sources. + == Do I have to use a serial connection to monitor the UPS? What about direct network connections (SNMP or otherwise)? NUT currently supports USB communication through several drivers, @@ -893,8 +948,8 @@ easily. Any time there is a gap in features, it's usually because the group of people who own that hardware and the group of people who -write code don't overlap. The fix is to make them overlap - -turn an owner into a developer or vice-versa. +write code don't overlap. The fix is to make them overlap -- turn +an owner into a developer or vice-versa. == What happened to the patch I sent? @@ -914,9 +969,11 @@ various inconsistencies can be diagnosed and fixed early. == I'm not much of a programmer. How can I help? There's always work to be done outside of the realm of code bashing. -Documentation can always be improved. A user's perspective -is sometimes needed to appreciate this. Bug reports on a project's -documentation are just as valuable as those for the actual source. +Documentation can always be improved. A new user's perspective is +sometimes needed to appreciate this, since developers and long-time +users consider everything obvious. Bug reports and pull requests +on any project's documentation are just as valuable as those for +the actual programs' sources. Fielding questions on the mailing lists is also helpful. This lets other people to focus on coding issues while allowing the @@ -1002,7 +1059,7 @@ currently open pull requests. We are not going to rehash all of the arguments for and against this in a simple FAQ entry. If you intend for your reply to go to more than just the -last person who posted, it is not too much trouble to hit "reply all". +last person who posted, it is not too much trouble to hit "Reply All". == I found some information about another kind of UPS protocol you don't support yet, but I don't know what to do with it. Can you help? From 78bb00b9d96b30c80a5979f57a0b41490f4a387c Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 20:13:40 +0100 Subject: [PATCH 60/67] Various main asciidocs: reconcile markup (multi-paragraph lists, etc.) Signed-off-by: Jim Klimov --- INSTALL.nut.adoc | 14 +++-- README.adoc | 19 ++++++- docs/cables.txt | 2 + docs/config-notes.txt | 36 ++++++------- docs/config-prereqs.txt | 51 +++++++++++++----- docs/configure.txt | 4 +- docs/daisychain.txt | 16 +++--- docs/design.txt | 4 +- docs/developer-guide.txt | 20 +++---- docs/developers.txt | 97 +++++++++++++++++---------------- docs/download.txt | 6 +-- docs/features.txt | 2 +- docs/hid-subdrivers.txt | 8 +-- docs/macros.txt | 84 +++++++++++++++-------------- docs/net-protocol.txt | 4 +- docs/new-clients.txt | 4 +- docs/new-drivers.txt | 112 ++++++++++++++++++++------------------- docs/nut-names.txt | 4 +- docs/nut-qa.txt | 2 +- docs/packager-guide.txt | 2 +- docs/security.txt | 4 +- docs/snmp-subdrivers.txt | 2 +- docs/solaris-usb.txt | 8 ++- 23 files changed, 284 insertions(+), 221 deletions(-) diff --git a/INSTALL.nut.adoc b/INSTALL.nut.adoc index 43e2007304..e14ac66204 100644 --- a/INSTALL.nut.adoc +++ b/INSTALL.nut.adoc @@ -179,6 +179,12 @@ into their operating system. On the other hand, distributions and appliances tend to package "official releases" of projects such as NUT, and so do not deliver latest and greatest fixes, new drivers, bugs and other features. +Stable distributions also tend to deliver minor fixes to the version of +third-party software (like NUT) a particular release of the operating +system has initially delivered, so those release lines can be years behind +development in terms of new features (or bug fixes, if they are not trivial +to patch into the old code base snapshot used to create the package). + [[Installing_source]] Installing from source ---------------------- @@ -300,6 +306,8 @@ This will build the NUT client and server programs and the selected drivers. It will also build any other features that were selected during <> step above. +NOTE: NUT is regularly tested with GNU, BSD and Sun implementations of `make`. + Installation ^^^^^^^^^^^^ @@ -403,7 +411,7 @@ drivers; this should allow you to follow the below instructions. However, don't forget to set up the correct permissions later!). -NOTE: if you are using something like udev or devd, make sure +NOTE: If you are using something like udev or devd, make sure these permissions stay set across a reboot. If they revert to the old values, your drivers may fail to start. @@ -489,7 +497,7 @@ the `/tree/` with "`-b`" CLI option for branch selection, like this: Testing with CI helper ~~~~~~~~~~~~~~~~~~~~~~ -NOTE: this uses the `ci_build.sh` script to arrange some rituals and +NOTE: This uses the `ci_build.sh` script to arrange some rituals and settings, in this case primarily to default the choice of drivers to auto-detection of what can be built, and to skip building documentation. Also note that this script supports many other scenarios for CI and @@ -668,7 +676,7 @@ Debian, Ubuntu and other derivatives ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ NOTE: NUT is packaged and well maintained in these systems. -The official Debian packager is part of the NUT Team. +The official Debian packager used to be part of the NUT Team. Using your preferred method (apt-get, aptitude, Synaptic, ...), install the 'nut' package, and optionally the following: diff --git a/README.adoc b/README.adoc index 22b43ad729..2a81f4e768 100644 --- a/README.adoc +++ b/README.adoc @@ -446,11 +446,14 @@ UPS Shutdowns upsdrvctl can also shut down (power down) all of your UPS hardware. -WARNING: if you play around with this command, expect your filesystems +[WARNING] +========= +If you play around with this command, expect your filesystems to die. Don't power off your computers unless they're ready for it: /usr/local/ups/sbin/upsdrvctl shutdown /usr/local/ups/sbin/upsdrvctl shutdown sparky +========= You should read the {xref}UPS_shutdown{x-s}[Configuring automatic UPS shutdowns] chapter to learn more about when to use this feature. If called at the wrong @@ -598,6 +601,7 @@ not have any effect on your system. A driver that supports read/write variables will give results like this: +---- $ upsrw sparky@localhost ( many skipped ) @@ -610,12 +614,15 @@ A driver that supports read/write variables will give results like this: Option: "0" ( more skipped ) +---- On the other hand, one that doesn't support them won't print anything: +---- $ upsrw fenton@gearbox ( nothing ) +---- `upsrw` requires administrator powers to change settings in the hardware. Refer to {linkman2}upsd.users{lm-s}upsd.users{lm-c}5{lm-e} for information on defining @@ -631,6 +638,7 @@ hardware/drivers support them. Use the -l command to list them, like this: +---- $ upscmd -l sparky@localhost Instant commands supported on UPS [sparky@localhost]: @@ -639,6 +647,7 @@ Use the -l command to list them, like this: calibrate.start - Start run time calibration calibrate.stop - Stop run time calibration ... +---- `upscmd` requires administrator powers to start instant commands. To define users and passwords in `upsd`, see @@ -734,6 +743,14 @@ Major release jumps are mostly due to large changes to the features list. There have also been a number of architectural changes which may not be noticeable to most users, but which can impact developers. +Since NUT v2.8.2 or so, development iterations have additional version +components, to account for the amount of commits on the main branch +(`master`) since the last known Git tag, and amount of commits on the +developed feature branch that are unique to it compared to main branch. +This allows for a reasonably growing version of stable baseline and +local development, so that experimental packages can be installed as +upgrades (or well-exposed downgrades). + Backwards and Forwards Compatibility ------------------------------------ diff --git a/docs/cables.txt b/docs/cables.txt index df4ca78204..4c3dca0d22 100644 --- a/docs/cables.txt +++ b/docs/cables.txt @@ -129,6 +129,7 @@ T700, T1000, T1500, T1500j, T700h, T1000h, T1500h, R1500, R1500j, R1500h, T2000, T2000j, T2400h, T2400h-NA, R3000 / R3000j, R3000h, R3000h-International, R3000h-NA, R6000h-NA, R6000i, R6000j. +---- UPS PC 9 pin connector 1 --------- 3 @@ -137,6 +138,7 @@ R3000h-International, R3000h-NA, R6000h-NA, R6000i, R6000j. 4 --------- 5 | 6 -/ 6 --------- 7 +---- Contributed by Kjell Claesson and Arnaud Quette. diff --git a/docs/config-notes.txt b/docs/config-notes.txt index c099e0ace3..a19332ac35 100644 --- a/docs/config-notes.txt +++ b/docs/config-notes.txt @@ -1,7 +1,7 @@ Configuration notes =================== -This chapter describe most of the configuration and use aspects of NUT, +This chapter describes most of the configuration and use aspects of NUT, including establishing communication with the device and configuring safe shutdowns when the UPS battery runs out of power. @@ -131,7 +131,7 @@ of the bundled services, which are enabled on a particular deployment. Driver configuration ~~~~~~~~~~~~~~~~~~~~ -Create one section per UPS in 'ups.conf' +Create one section per UPS in linkman:ups.conf[5] file. NOTE: The default path for a source installation is `/usr/local/ups/etc`, while packaged installation will vary. @@ -174,8 +174,8 @@ information on matching a specific device, or trying specific subdriver or protocol options with a currently unknown device. ====== -NOTE: On Windows systems, the second serial port (COM2), equivalent to -"/dev/ttyS1" on Linux, would be "\\\\.\\COM2". +NOTE: On Windows systems, the second serial port (`COM2`), equivalent to +`/dev/ttyS1` on Linux, would be `\\\\.\\COM2`. References: linkman:ups.conf[5], linkman:nutupsdrv[8], @@ -195,7 +195,7 @@ Starting the driver(s) in legacy operating systems Generally, you can just start the driver(s) for your hardware (all sections defined in 'ups.conf') using the following command: - upsdrvctl start + :; upsdrvctl start Make sure the driver doesn't report any errors. It should show a few details about the hardware and then enter the background. You @@ -344,8 +344,8 @@ use e.g. `cp -pf upsd.users.sample upsd.users` (as `root`) to start out with some annotated comments and adapt that to your deployment, the copied files should also get the expected safe permissions. - chown root:nut upsd.conf upsd.users - chmod 0640 upsd.conf upsd.users + :; chown root:nut upsd.conf upsd.users + :; chmod 0640 upsd.conf upsd.users References: man pages: linkman:upsd.conf[5], linkman:upsd.users[5], @@ -357,7 +357,7 @@ Starting the data server Start the network data server: - upsd + :; upsd Make sure it is able to connect to the driver(s) on your system. A successful run looks like this: @@ -408,7 +408,7 @@ Status data Make sure that the UPS is providing good status data. You can use the `upsc` command-line client for this: - upsc myupsname@localhost ups.status + :; upsc myupsname@localhost ups.status You should see just one line in response: @@ -428,7 +428,7 @@ All data Look at all of the status data which is being monitored. - upsc myupsname@localhost + :; upsc myupsname@localhost What happens now depends on the kind of device and driver you have. In the list, you should see `ups.status` with the same value you got @@ -633,12 +633,12 @@ Reload `upsd`. Depending on your configuration, you may be able to do this without stopping the `upsd` daemon process (if it had saved a PID file earlier): - upsd -c reload + :; upsd -c reload If that doesn't work (check the syslog), just restart it: - upsd -c stop - upsd + :; upsd -c stop + :; upsd For systems with integrated service management (Linux systemd, illumos/Solaris SMF) their corresponding `reload` or `refresh` @@ -684,8 +684,8 @@ use e.g. `cp -pf upsmon.conf.sample upsmon.conf` (as `root`) to start out with some annotated comments and adapt that to your deployment, the copied files should also get the expected safe permissions. - chown root:nut upsmon.conf - chmod 0640 upsmon.conf + :; chown root:nut upsmon.conf + :; chmod 0640 upsmon.conf This step has been placed early in the process so you secure this file before adding sensitive data in the next step. @@ -741,7 +741,7 @@ which does customized local shutdown tasks before calling `init` or Start upsmon ^^^^^^^^^^^^ - upsmon + :; upsmon If it complains about something, then check your configuration. @@ -844,14 +844,14 @@ restarts when power returns. The first step is to see how `upsdrvctl` will behave without actually turning off the power. To do so, use the `-t` argument: - upsdrvctl -t shutdown + :; upsdrvctl -t shutdown It will display the sequence without actually calling the drivers. You can finally test a forced shutdown sequence (FSD) using: - upsmon -c fsd + :; upsmon -c fsd This will execute a full shutdown sequence, as presented in <>, starting from the 3rd step. diff --git a/docs/config-prereqs.txt b/docs/config-prereqs.txt index 91b54d4d5a..c4c6c70d65 100644 --- a/docs/config-prereqs.txt +++ b/docs/config-prereqs.txt @@ -438,7 +438,9 @@ other described environments by adding a symlink `/usr/lib/ccache`: :; ln -s ../lib64/ccache/ "$ALTROOT"/usr/lib/ ------ -NOTE: For Jenkins agents, also need to install JDK 17 or newer, which is not +[NOTE] +====== +For Jenkins agents, also need to install JDK 17 or newer, which is not available for CentOS 6 nor 7 directly (in distribution packaging). Alternative packaging, such as Temurin from the Adoptium project, is possible (checked for at least CentOS 7), see @@ -452,6 +454,7 @@ baseurl=https://vault.centos.org/centos/$releasever/os/$basearch/ ---- lines if the `mirrorlist` ones do not suffice to find living mirrors (WARNING: the `/os/` part of the URL would vary for different repository types). +====== Arch Linux ~~~~~~~~~~ @@ -716,15 +719,19 @@ a reputable repository: https://sotirov-bg.net/slackpack/ and should cover most if not all of the dependencies required for NUT building (including PowerMan, IPMI etc.) -NOTE: If setting up a CI farm agent with builds in RAM disk, keep in mind that +[NOTE] +====== +If setting up a CI farm agent with builds in RAM disk, keep in mind that default mount options for `/dev/shm` preclude script execution. Either set up the agent in a non-standard fashion (to use another work area), or if this is -a dedicated machine -- relax the mount options in `/etc/fstab`. Here is an -example with `noexec` which we *must avoid* for such use-case: +a dedicated machine -- relax the mount options in `/etc/fstab`. + +Here is an example with `noexec` which we *must avoid* for such use-case: ---- :; mount | grep /dev/shm tmpfs on /dev/shm type tmpfs (rw,nosuid,nodev,noexec,relatime,inode64) ---- +====== FreeBSD 12.2 ~~~~~~~~~~~~ @@ -1267,13 +1274,16 @@ from third-party repositories (e.g. SFE) and/or build from sources. No pre-packaged `cppcheck` was found, either. -NOTE: For Jenkins agents, also need to `pkg install runtime/java/openjdk17` +[NOTE] +====== +For Jenkins agents, also need to `pkg install runtime/java/openjdk17` for JRE/JDK 17. Java 17 or 21 is required to run Jenkins agents after autumn 2024. If updating from older releases, you may need to update default implementation, e.g.: ---- :; pkg set-mediator -V 17 java ---- +====== OmniOS CE (as of release 151036) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1336,15 +1346,18 @@ Your OmniOS version may lack a pre-packaged libusb, however the binary build from contemporary OpenIndiana can be used (copy the header files and the library+symlinks for all architectures you would need). -NOTE: As of July 2022, a `libusb-1` package recipe was proposed for the +[NOTE] +====== +As of July 2022, a `libusb-1` package recipe was proposed for the `omnios-extra` repository (NUT itself and further dependencies may also appear there, per link:https://github.com/networkupstools/nut/issues/1498[issue #1498]), -and is available as of release 151046: +and is available as of release 151046 and later on: ------ :; pkg install \ libusb-1 ------ +====== You may need to set up `ccache` with the same `/usr/lib/ccache` dir used in other OS recipes. Assuming your Build Essentials pulled GCC 11 version, @@ -1380,21 +1393,24 @@ Note also that the minimal footprint nature of OmniOS CE precludes building any large scope easily, so avoid docs and "all drivers" unless you provide whatever they need to happen. -NOTE: For Jenkins agents, also need to `pkg install runtime/java/openjdk21` +[NOTE] +====== +For Jenkins agents, also need to `pkg install runtime/java/openjdk21` for JRE/JDK 17. Java 17 or 21 is required to run Jenkins agents after autumn 2024. If updating from older releases, you may need to update default implementation, e.g.: ---- :; pkg set-mediator -V 21 java ---- +====== Solaris 8 ~~~~~~~~~ -Builds for a platform as old as this are not currently covered by CI, however -since the very possibility of doing this was recently verified, some notes -follow. +Builds for a platform as old as this are not currently covered by regular +NUT CI farm runs, however since the very possibility of doing this was +recently verified, some notes follow. For context: Following a discussion in the mailing list starting at https://alioth-lists.debian.net/pipermail/nut-upsuser/2022-December/013051.html @@ -1489,11 +1505,14 @@ setup, and https://brew.sh if you want to install it on your MacOS system depending on architecture -- see https://docs.brew.sh/Installation for more details; find via `brew config | grep HOMEBREW_PREFIX: | awk '{print $2}'`). -NOTE: The quickest pre-configuration for `ci_build.sh` integration with this +[NOTE] +====== +The quickest pre-configuration for `ci_build.sh` integration with this non-default build system would be to add this line into your shell profile: ---- eval "$(brew shellenv)" ---- +====== NOTE: Homebrew is not the only build/packaging system available for MacOS, so NUT scripts do not make any assumptions nor try to find a build system @@ -1522,7 +1541,7 @@ On one test system, man page builds spewed warnings like due to incompatibility of older asciidoc with new Python syntax requirements, but seemed to produce reasonable results otherwise. -Note that ccache is installed in a different location than expected by default +Note that `ccache` is installed in a different location than expected by default in the `ci_build.sh` script, so if your system allows to add the symbolic link to `/opt/homebrew/opt/ccache/libexec` (`/usr/local/opt/ccache/libexec` on x86) as `/usr/lib/ccache` -- please do so as the easiest way out. @@ -1750,9 +1769,12 @@ Not installed above (yet?): Note that `ccache` symlinks for MSYS2 are installed into `/usr/lib/ccache/bin` directory (not plain `/usr/lib/ccache` as elsewhere). -NOTE: After you successfully build NUT (perhaps using `ci_build.sh`), if you +[NOTE] +====== +After you successfully build NUT (perhaps using `ci_build.sh`), if you install it into a prototype area by `make DESTDIR=... install` then you should add the third-party shared libraries involved, for that file set to be usable. + Something along these lines: ------ :; find "$DESTDIR" -name '*.exe' -type f | while read F ; do ldd "$F" \ @@ -1765,3 +1787,4 @@ problematic on that platform) may be needed in other directories, such as ------ :; ( cd "$DESTDIR/mingw64/bin/" && ln *.dll ../sbin && ln *.dll ../cgi-bin ) ------ +====== diff --git a/docs/configure.txt b/docs/configure.txt index dc0bcebfb6..50beca3354 100644 --- a/docs/configure.txt +++ b/docs/configure.txt @@ -12,10 +12,10 @@ and other dependencies on your build environment (referenced just a bit below). For common developer iterations, porting to new platforms, or in-place testing, running the `./ci_build.sh` script can be a helpful one-stop solution. -+ + The NUT linkdoc:packager-guide[Packager Guide], which presents the best practices for installing and integrating NUT, is also a good reading. -+ + The link:config-prereqs.txt[Prerequisites for building NUT on different OSes] document suggests prerequisite packages with tools and dependencies available and needed to build and test as much as possible of NUT on diff --git a/docs/daisychain.txt b/docs/daisychain.txt index c67d2875da..f46dcbe4ce 100644 --- a/docs/daisychain.txt +++ b/docs/daisychain.txt @@ -66,7 +66,7 @@ technology change (hybrid chain with UPS and PDU for example). Devices status handling ^^^^^^^^^^^^^^^^^^^^^^^ -To be clarified... +FIXME: To be clarified... Devices alarms handling @@ -77,7 +77,7 @@ which may evolve into `device.X.alarm`. If any of the devices has an alarm, the main `ups.status` will publish an `ALARM` flag. This flag is be cleared once all devices have no alarms anymore. -NOTE: ups.alarm behavior is not yet defined (all devices alarms vs. list of +NOTE: `ups.alarm` behavior is not yet defined (all devices alarms vs. list of device(s) that have alarms vs. nothing?) Example @@ -115,7 +115,7 @@ one master and two slaves: Information for developers ~~~~~~~~~~~~~~~~~~~~~~~~~~ -NOTE: these details are dedicated to the `snmp-ups` driver! +NOTE: These details are dedicated to the `snmp-ups` driver! In order to enable daisychain support for a range of devices, developers have to do two things: @@ -193,11 +193,11 @@ driver: * `device_alarm_init()`: clear the current alarm buffer * `device_alarm_commit(const int device_number)`: commit the current alarm -buffer to "device..ups.alarm", and increase the count of -alarms. If the current alarms buffer is empty, the count of alarm is -decreased, and the variable "device..ups.alarm" is removed -from publication. Once the alarm count reaches "0", the main (device.0) -ups.status will also remove the "ALARM" flag. + buffer to `device..ups.alarm`, and increase the count of + alarms. If the current alarms buffer is empty, the count of alarm is + decreased, and the variable `device..ups.alarm` is removed + from publication. Once the alarm count reaches "0", the main (`device.0`) + `ups.status` will also remove the "ALARM" flag. [NOTE] ====== diff --git a/docs/design.txt b/docs/design.txt index 85a8c054fb..a218d84248 100644 --- a/docs/design.txt +++ b/docs/design.txt @@ -219,8 +219,8 @@ delay the driver or server when waiting for a lock. In April 2003, the entire state management subsystem was removed and replaced with a single local socket. The drivers listen for connections and push updates asynchronously to any listeners. They also -recognize a few commands. Drivers also dampen updates, and only push -them out when something actually changes. +recognize a few commands. Drivers also dampen the flow of updates, and +only push them out when something actually changes. As a result, `upsd` no longer has to poll any files on the disk, and can just `select()` all of its file descriptors (fds) and wait for activity. diff --git a/docs/developer-guide.txt b/docs/developer-guide.txt index bd103ae851..d1795760be 100644 --- a/docs/developer-guide.txt +++ b/docs/developer-guide.txt @@ -12,7 +12,7 @@ NUT is both a powerful toolkit and framework that provides support for Power Devices, such as Uninterruptible Power Supplies, Power Distribution Units and Solar Controllers. -This document intend to describe how NUT is designed, and the way to +This document intends to describe how NUT is designed, and the way to develop new device drivers and client applications. @@ -96,17 +96,17 @@ Here is an example to setup a device simulation: + - now start NUT, at least `dummy-ups` and `upsd`: + - $ upsdrvctl start dummy - $ upsd + :; upsdrvctl start dummy + :; upsd + - and check the data: + - $ upsc dummy + :; upsc dummy ... + - you can also use `upsrw` to modify the data in memory: + - $ upsrw -s ups.status="OB LB" -u user -p password dummy + :; upsrw -s ups.status="OB LB" -u user -p password dummy + - or directly edit your copy of `/etc/nut/evolution500.seq`. In this case, modification will only apply according to the `TIMER` @@ -121,10 +121,10 @@ Simulated devices discovery Any simulation file that is saved in the sysconfig directory can be automatically discovered and configured using nut-scanner: -+ - $ nut-scanner -n - $ nut-scanner --nut_simulation_scan -+ +---- + :; nut-scanner -n + :; nut-scanner --nut_simulation_scan +---- [[dev-recording]] @@ -144,7 +144,7 @@ Its usage is the following: For example, to record information from the device 'myups' every 10 seconds: - nut-recorder.sh myups@localhost myups.seq 10 + :; nut-recorder.sh myups@localhost myups.seq 10 During the recording, you will want to generate power events, such as power failure and restoration. These will be tracked in the simulation files, and diff --git a/docs/developers.txt b/docs/developers.txt index fc61dcbfb5..baa2be1810 100644 --- a/docs/developers.txt +++ b/docs/developers.txt @@ -14,8 +14,9 @@ Use `snprintf()`. It's even provided with a compatibility module if the target system doesn't have it natively. If you use `snprintf()` to load some value into a buffer, make sure you -provide the format string. Don't use user-provided format strings, -since that's an easy way to open yourself up to an exploit. +provide the format string. Don't use user-provided format strings without +delicate verification, since that's an easy way to open yourself up to an +exploit. Don't use `strcat()`. We have a neat wrapper for `snprintf()` called `snprintfcat()` that allows you to append to `char *` with a format @@ -25,8 +26,8 @@ Error reporting ~~~~~~~~~~~~~~~ Don't call `syslog()` directly. Use `upslog_with_errno()` and `upslogx()`. -They may write to the syslog, stderr, or both as appropriate. This -means you don't have to worry about whether you're running in the +They may also write to the `syslog`, `stderr`, or both as appropriate. +This means you don't have to worry about whether you're running in the background or not. The `upslog_with_errno()` routine prints your message plus the string @@ -243,14 +244,16 @@ existing code on their workstations or to ensure support for new compilers and C standard revisions, e.g. save a local file like this to call the common script with pre-sets: - $ cat _fightwarn-gcc10-gnu17.sh - #!/bin/sh - - BUILD_TYPE=default-all-errors \ - CFLAGS="-Wall -Wextra -Werror -pedantic -std=gnu17" \ - CXXFLAGS="-Wall -Wextra -Werror -std=gnu++17" \ - CC=gcc-10 CXX=g++-10 \ - ./ci_build.sh +---- +$ cat _fightwarn-gcc10-gnu17.sh +#!/bin/sh + +BUILD_TYPE=default-all-errors \ +CFLAGS="-Wall -Wextra -Werror -pedantic -std=gnu17" \ +CXXFLAGS="-Wall -Wextra -Werror -std=gnu++17" \ +CC=gcc-10 CXX=g++-10 \ + ./ci_build.sh +---- ...and then execute it to prepare a workspace, after which you can go fixing bugs file-by-file running a `make` after each save to confirm @@ -271,15 +274,17 @@ For the `ci_build.sh` usage like above, one can instead pass the setting via `BUILD_WARNOPT=...`, and require that all emitted warnings are fatal for their build, e.g.: - $ cat _fightwarn-clang9-gnu11.sh - #!/bin/sh - - BUILD_TYPE=default-all-errors \ - BUILD_WARNOPT=hard BUILD_WARNFATAL=yes \ - CFLAGS="-std=gnu11" \ - CXXFLAGS="-std=gnu++11" \ - CC=clang-9 CXX=clang++-9 CPP=clang-cpp \ - ./ci_build.sh +---- +$ cat _fightwarn-clang9-gnu11.sh +#!/bin/sh + +BUILD_TYPE=default-all-errors \ +BUILD_WARNOPT=hard BUILD_WARNFATAL=yes \ +CFLAGS="-std=gnu11" \ +CXXFLAGS="-std=gnu++11" \ +CC=clang-9 CXX=clang++-9 CPP=clang-cpp \ + ./ci_build.sh +---- Finally, for refactoring effort geared particularly for fighting the warnings which exist in current codebase, the script contains some @@ -287,7 +292,7 @@ presets (which would evolve along with codebase quality improvements) as `BUILD_TYPE=fightwarn-gcc`, `BUILD_TYPE=fightwarn-clang` or plain `BUILD_TYPE=fightwarn`: - BUILD_TYPE=fightwarn-clang ./ci_build.sh + :; BUILD_TYPE=fightwarn-clang ./ci_build.sh As a rule of thumb, new contributions must not emit any warnings when built in GNU99 mode with a `minimal` "difficulty" level of warnings. @@ -545,9 +550,9 @@ directory of a project (such as NUT codebase). While `.gitignore` rules can take care of not adding your local configuration into the SCM, these locations can be wiped by a careless `git clean -fdX`. You are advised to explore configuring your IDE to store project configurations outside -the source codebase location, or to track such directories as `nbproject` -or `nb-cache` as a separate Git repository (not necessarily a submodule -of NUT nor really diligently tracked) to avoid such surprises. +the source codebase location, or to track such subdirectories as `nbproject` +or `nb-cache` or `.idea` as a separate Git repository (not necessarily a +submodule of NUT nor really diligently tracked) to avoid such surprises. IDE notes on Windows ~~~~~~~~~~~~~~~~~~~~ @@ -944,8 +949,8 @@ touch. If your function or variable names start pushing important code off the right margin of the screen, expect them to meet the byte chainsaw sooner or later. -All types defined with typedef should end in `_t`, because this is -easier to read, and it enables tools (such as indent and emacs) to +All types defined with `typedef` should end in `_t`, because this is +easier to read, and it enables tools (such as `indent` and `emacs`) to display the source code correctly. Indenting with tabs vs. spaces @@ -1066,7 +1071,7 @@ Whenever a function needs to satisfy a particular API, it can end up taking arguments that are not used in practice (think a too-trivial signal handler). While some compilers offer the facility of decorations like `__attribute__(unused)`, this proved not to be a portable solution. -Also the abilities of newer C++ standard revisions are of no help to +Also the abilities of newer C/C++ standard revisions are of no help to the vast range of existing systems that run NUT today and expect to be able to do so tomorrow (hence the required C99+ support noted above). @@ -1112,12 +1117,12 @@ Taking the first step is the hardest part, so PRs are welcome :) You can go a long way towards converting your source code to the NUT coding style by piping it through the following command: - indent -kr -i8 -T FILE -l1000 -nhnl + :; indent -kr -i8 -T FILE -l1000 -nhnl This next command does a reasonable job of converting most C++ style comments (but not URLs and DOCTYPE strings): - sed 's#\(^\|[ \t]\)//[ \t]*\(.*\)[ \t]*#/* \2 */#' + :; sed 's#\(^\|[ \t]\)//[ \t]*\(.*\)[ \t]*#/* \2 */#' Emacs users can adjust how tabs are displayed. For example, it is possible to set a tab stop to be 3 spaces, rather than the usual 8. @@ -1411,11 +1416,11 @@ Git access Anonymous Git checkouts are possible: - git clone git://github.com/networkupstools/nut.git + :; git clone git://github.com/networkupstools/nut.git or - git clone https://github.com/networkupstools/nut.git + :; git clone https://github.com/networkupstools/nut.git if it is necessary to get around a pesky firewall that blocks the native Git protocol. @@ -1423,7 +1428,7 @@ Git protocol. For a quicker checkout (when you don't need the entire repository history), you can limit the depth of the clone: - git clone --depth 1 git://github.com/networkupstools/nut.git + :; git clone --depth 1 git://github.com/networkupstools/nut.git Mercurial (hg) access ~~~~~~~~~~~~~~~~~~~~~ @@ -1450,7 +1455,7 @@ Be aware that the examples in the GitHub blog post might result in a checkout that includes all of the current branches, as well as the trunk. You are most likely interested in a command line similar to the following: - svn co https://github.com/networkupstools/nut/trunk nut-trunk-svn + :; svn co https://github.com/networkupstools/nut/trunk nut-trunk-svn Ignoring generated files ------------------------ @@ -1572,32 +1577,32 @@ stash pop+ to apply your saved changes. Here is an example workflow: ------------------------------------------------------------------------------ - git clone -o central git://github.com/networkupstools/nut.git + :; git clone -o central git://github.com/networkupstools/nut.git - cd nut - git remote add -f username git://github.com/username/nut.git + :; cd nut + :; git remote add -f username git://github.com/username/nut.git - git checkout master - git branch my-new-feature - git checkout my-new-feature + :; git checkout master + :; git branch my-new-feature + :; git checkout my-new-feature # Hack away - git add changed-file.c - git commit -s + :; git add changed-file.c + :; git commit -s # Fix a typo in a file or commit message: - git commit -s -a --amend + :; git commit -s -a --amend # Someone committed something to the central repository. Fetch it. - git fetch central - git rebase central/master + :; git fetch central + :; git rebase central/master # Publish your branch to your GitHub repository: - git push username my-new-feature + :; git push username my-new-feature ------------------------------------------------------------------------------ If you are new to Git, but are familiar with SVN, some of the following links diff --git a/docs/download.txt b/docs/download.txt index e9e9c525b9..b0f6b546a7 100644 --- a/docs/download.txt +++ b/docs/download.txt @@ -43,13 +43,13 @@ link:https://github.com/[GitHub]. To retrieve the current development tree, use the following command: - $ git clone git://github.com/networkupstools/nut.git + :; git clone git://github.com/networkupstools/nut.git -The configure script and its dependencies are not stored in Git. To generate +The `configure` script and its dependencies are not stored in Git. To generate them, ensure that autoconf, automake and libtool are installed, then run the following script in the directory you just checked out: - $ ./autogen.sh + :; ./autogen.sh NOTE: it is optionally recommended to have Python 2.x or 3.x, and Perl, to generate some files included into the `configure` script, presence is checked diff --git a/docs/features.txt b/docs/features.txt index 502e7fc88b..a258da704d 100644 --- a/docs/features.txt +++ b/docs/features.txt @@ -161,7 +161,7 @@ Monitoring diagrams These are the most common situations for monitoring UPS hardware. Other ways are possible, but they are mostly variations of these four. -NOTE: these examples show serial communications for simplicity, but USB or +NOTE: These examples show serial communications for simplicity, but USB or SNMP or any other monitoring is also possible. "Simple" configuration diff --git a/docs/hid-subdrivers.txt b/docs/hid-subdrivers.txt index 1657735423..cc3fb8260a 100644 --- a/docs/hid-subdrivers.txt +++ b/docs/hid-subdrivers.txt @@ -39,7 +39,7 @@ beeper enabled/disabled/muted status) can be read and written. These variables are usually grouped together and arranged in a hierarchical tree shape, similar to directories in a file system. This tree is called the "usage" tree. For example, here is part of the usage tree -for a typical APC device. Variable components are separated by ".". +for a typical APC device. Variable components are separated by `.`. Typical values for each variable are also shown for illustrative purposes. @@ -179,14 +179,14 @@ You should save this information to a file, e.g.: You can now create an initial "stub" subdriver for your device by using helper script `scripts/subdriver/gen-usbhid-subdriver.sh`. -NOTE: this only creates a driver code "stub" which needs to be further +NOTE: This only creates a driver code "stub" which needs to be further customized to be actually useful (see "Customization" below). Use the script as follows: scripts/subdriver/gen-usbhid-subdriver.sh < /tmp/info -where /tmp/info is the file where you previously saved the debugging +where `/tmp/info` is the file where you previously saved the debugging information. This script prompts you for a name for the subdriver; use only letters @@ -380,7 +380,7 @@ typedef struct { uint8_t reportId; // Report ID = 0x01 (1) // Collection: CA:UPS CP:OutletSystem CP:Outlet - int8_t POW_UPSOutletSystemOutletSwitchable; // Usage 0x0084006C: Switchable, Value = to + int8_t POW_UPSOutletSystemOutletSwitchable; // Usage 0x0084006C: Switchable, Value = to int8_t POW_UPSOutletSystemOutletDelayBeforeStartup; // Usage 0x00840056: Delay Before Startup, Value = -1 to 60 int8_t POW_UPSOutletSystemOutletDelayBeforeShutdown; // Usage 0x00840057: Delay Before Shutdown, Value = -1 to 60 int8_t POW_UPSOutletSystemOutletDelayBeforeReboot; // Usage 0x00840055: Delay Before Reboot, Value = -1 to 60 diff --git a/docs/macros.txt b/docs/macros.txt index b32da5b6db..d575f51931 100644 --- a/docs/macros.txt +++ b/docs/macros.txt @@ -1,75 +1,77 @@ NUT-specific autoconf macros ---------------------------- -The following NUT-specific autoconf macros are defined in the m4/ +The following NUT-specific autoconf macros are defined in the `m4/` directory. -- NUT_TYPE_SOCKLEN_T -- NUT_TYPE_UINT8_T -- NUT_TYPE_UINT16_T +*NUT_TYPE_SOCKLEN_T*:: +*NUT_TYPE_UINT8_T*:: +*NUT_TYPE_UINT16_T*:: Check for the corresponding type in the system header files, and - #define a replacement if necessary. - -- NUT_CHECK_LIBGD -- NUT_CHECK_LIBNEON -- NUT_CHECK_LIBNETSNMP -- NUT_CHECK_LIBPOWERMAN -- NUT_CHECK_LIBOPENSSL -- NUT_CHECK_LIBNSS -- NUT_CHECK_LIBUSB -- NUT_CHECK_LIBWRAP + `#define` a replacement if necessary. + +*NUT_CHECK_LIBGD*:: +*NUT_CHECK_LIBNEON*:: +*NUT_CHECK_LIBNETSNMP*:: +*NUT_CHECK_LIBPOWERMAN*:: +*NUT_CHECK_LIBOPENSSL*:: +*NUT_CHECK_LIBNSS*:: +*NUT_CHECK_LIBUSB*:: +*NUT_CHECK_LIBWRAP*:: +*et al*:: Determine the compiler flags for the corresponding library. On - success, set nut_have_libxxx="yes" and set LIBXXX_CFLAGS and - LIBXXX_LDFLAGS. On failure, set nut_have_libxxx="no". This macro + success, set `nut_have_libxxx="yes"` and set `LIBXXX_CFLAGS` and + `LIBXXX_LDFLAGS`. On failure, set `nut_have_libxxx="no"`. This macro can be run multiple times, but will do the checking only once. Here "xxx" should of course be replaced by the respective library name. - - The checks for each library grow organically to compensate for ++ +The checks for each library grow organically to compensate for various bugs in the libraries, pkg-config, etc. This is why we have a separate macro for each library. -- NUT_CHECK_IPV6 +*NUT_CHECK_IPV6*:: Check for various features required to compile the IPv6 support. - dnl Check for various features required for IPv6 support. Define a - preprocessor symbol for each individual feature (HAVE_GETADDRINFO, - HAVE_FREEADDRINFO, HAVE_STRUCT_ADDRINFO, HAVE_SOCKADDR_STORAGE, - SOCKADDR_IN6, IN6_ADDR, HAVE_IN6_IS_ADDR_V4MAPPED, - HAVE_AI_ADDRCONFIG). Also set the shell variable nut_have_ipv6=yes - if all the required features are present. Set nut_have_ipv6=no - otherwise. + Define a preprocessor symbol for each individual feature + (`HAVE_GETADDRINFO`, `HAVE_FREEADDRINFO`, `HAVE_STRUCT_ADDRINFO`, + `HAVE_SOCKADDR_STORAGE`, `SOCKADDR_IN6`, `IN6_ADDR`, + `HAVE_IN6_IS_ADDR_V4MAPPED`, `HAVE_AI_ADDRCONFIG`). ++ +Also set the shell variable `nut_have_ipv6=yes` if all the required + features are present. Set `nut_have_ipv6=no` otherwise. -- NUT_CHECK_OS +*NUT_CHECK_OS*:: Check for the exact system name and type. This was only used in the past to determine the packaging rule to be - used through the OS_NAME variable, but may be useful for other purposes + used through the `OS_NAME` variable, but may be useful for other purposes in the future. -- NUT_REPORT_FEATURE(FEATURE, VALUE, VARIABLE, DESCRIPTION) +*NUT_REPORT_FEATURE(FEATURE, VALUE, VARIABLE, DESCRIPTION)*:: Schedule a line for the end-of-configuration feature summary. The - FEATURE is a descriptive string such that the sentence "Checking - whether to FEATURE" makes sense, and VALUE describes the decision - taken (typically yes or no). The feature is also reported to the + 'FEATURE' is a descriptive string such that the sentence "Checking + whether to FEATURE" makes sense, and 'VALUE' describes the decision + taken (typically 'yes' or 'no'). The feature is also reported to the terminal. ++ +Also use 'VARIABLE' and 'DESCRIPTION' for defining `AM_CONDITIONAL` and + `AC_DEFINE` (only if `VALUE = "yes"`). + The 'VARIABLE' is of the form `WITH_`. - Also use VARIABLE and DESCRIPTION for defining AM_CONDITIONAL and - AC_DEFINE (only if VALUE = "yes"). VARIABLE is of the form 'WITH_'. - -- NUT_REPORT(FEATURE, VALUE) +*NUT_REPORT(FEATURE, VALUE)*:: Schedule a line for the end-of-configuration feature summary, without printing anything to the terminal immediately. -- NUT_PRINT_FEATURE_REPORT +*NUT_PRINT_FEATURE_REPORT*:: Print out a list of the features that have been reported by - previous NUT_REPORT_FEATURE macro calls. + previous `NUT_REPORT_FEATURE` macro calls. -- NUT_ARG_WITH(FEATURE, DESCRIPTION, DEFAULT) +*NUT_ARG_WITH(FEATURE, DESCRIPTION, DEFAULT)*:: - Declare a simple --with-FEATURE option with the given DESCRIPTION - and DEFAULT. Sets the variable nut_with_FEATURE. + Declare a simple `--with-FEATURE` option with the given 'DESCRIPTION' + and 'DEFAULT'. Sets the variable `nut_with_FEATURE`. diff --git a/docs/net-protocol.txt b/docs/net-protocol.txt index 577e29abaa..65d432401b 100644 --- a/docs/net-protocol.txt +++ b/docs/net-protocol.txt @@ -359,7 +359,7 @@ Response: This replaces the old "ENUM" command. -NOTE: this does not support the old "SELECTED" notation. You must +NOTE: This does not support the old "SELECTED" notation. You must request the current value separately. @@ -788,7 +788,7 @@ Dense lists ~~~~~~~~~~~ The LIST commands may be given the ability to handle options some day. -For example, "LIST VARS +DESC" would return the current value +For example, `LIST VARS +DESC` would return the current value like now, but it would also append the description of that variable. diff --git a/docs/new-clients.txt b/docs/new-clients.txt index 48cff0660e..7d7fdf3c6d 100644 --- a/docs/new-clients.txt +++ b/docs/new-clients.txt @@ -8,8 +8,8 @@ NUT (the GNU General Public License). If none of these suits you for technical or legal reasons, you can implement one easily using the <>. -The latter approach has been used to create the Python 'PyNUT' module, the -Nagios 'check_ups' plugin (and probably others), which can serve as a +The latter approach has been used to create the Python 'PyNUTClient' module, +the Nagios 'check_ups' plugin (and probably others), which can serve as a reference. C / C++ diff --git a/docs/new-drivers.txt b/docs/new-drivers.txt index b696141bc3..3ca3ca9c76 100644 --- a/docs/new-drivers.txt +++ b/docs/new-drivers.txt @@ -208,7 +208,7 @@ Setting flags ~~~~~~~~~~~~~ Some variables have special properties. They can be writable, and some -are strings. The ST_FLAG_* values can be used to tell upsd more about +are strings. The `ST_FLAG_*` values can be used to tell upsd more about what it can do. dstate_setflags("input.transfer.high", ST_FLAG_RW); @@ -283,7 +283,7 @@ variable naming scheme,nut-names] for more information. UPS alarms ---------- -These work like ups.status, and have three special functions which you +These work like `ups.status`, and have three special functions which you must use to manage them. alarm_init() -- before doing anything else @@ -343,56 +343,56 @@ Drivers which use serial port functions should include serial.h and use these functions (and cross-platform data types) whenever possible: - TYPE_FD - ++ Cross-platform data type to represent a serial-port connection. - ERROR_FD_SER - ++ Macro value representing an invalid serial-port connection. - VALID_FD_SER(TYPE_FD_SER fd) - ++ This macro evaluates to `true` if `fd` currently has a "valid" value (e.g. represents a connected device). You should invalidate the `fd` when you initialize the variable or close the connection, by assigning `fd = ERROR_FD`. - INVALID_FD_SER(TYPE_FD_SER fd) - ++ This macro evaluates to `true` if `fd` does not currently have a "valid" value. - TYPE_FD_SER ser_open(const char *port) - ++ This opens the port and locks it if possible, using one of fcntl, lockf, or uu_lock depending on what may be available. If something fails, it calls fatal for you. If it succeeds, it always returns the fd that was opened. - TYPE_FD_SER ser_open_nf(const char *port) - ++ This is a non-fatal version of ser_open(), that does not call fatal if something fails. - int ser_set_speed(TYPE_FD_SER fd, const char *port, speed_t speed) - ++ This sets the speed of the port and also does some basic configuring with tcgetattr and tcsetattr. If you have a special serial configuration (other than 8N1), then this may not be what you want. - ++ The port name is provided again here so failures in tcgetattr() provide a useful error message. This is the only place that will generate a message if someone passes a non-serial port /dev entry to your driver, so it needs the extra detail. - int ser_set_speed_nf(TYPE_FD_SER fd, const char *port, speed_t speed) - ++ This is a non-fatal version of ser_set_speed(), that does not call fatal if something fails. - int ser_set_dtr(TYPE_FD_SER fd, int state) - int ser_set_rts(TYPE_FD_SER fd, int state) - ++ These functions can be used to set the modem control lines to provide cable power on the RS232 interface. Use state = 0 to set the line to 0 and any other value to set it to 1. @@ -400,84 +400,84 @@ and any other value to set it to 1. - int ser_get_dsr(TYPE_FD_SER fd) - int ser_get_cts(TYPE_FD_SER fd) - int ser_get_dcd(TYPE_FD_SER fd) - ++ These functions read the state of the modem control lines. They will return 0 if the line is logic 0 and a non-zero value if the line is logic 1. - int ser_close(TYPE_FD_SER fd, const char *port) - ++ This function unlocks the port if possible and closes the fd. You should call this in your upsdrv_cleanup handler. - ssize_t ser_send_char(TYPE_FD_SER fd, unsigned char ch) - ++ This attempts to write one character and returns the return value from write. You could call write directly, but using this function allows for future error handling in one place. - ssize_t ser_send_pace(TYPE_FD_SER fd, useconds_t d_usec, const char *fmt, ...) - ++ If you need to send a formatted buffer with an intercharacter delay, use this function. There are a number of UPS controllers which can't take commands at the full speed that would normally be possible at a given bit rate. Adding a small delay usually turns a flaky UPS into a solid one. - ++ The return value is the number of characters that was sent to the port, -or -1 if something failed. +or '-1' if something failed. - ssize_t ser_send(TYPE_FD_SER fd, const char *fmt, ...) - ++ Like ser_send_pace, but without a delay. Only use this if you're sure that your UPS can handle characters at the full line rate. - ssize_t ser_send_buf(TYPE_FD_SER fd, const void *buf, size_t buflen) - ++ This sends a raw buffer to the fd. It is typically used for binary transmissions. It returns the results of the call to write. - ssize_t ser_send_buf_pace(TYPE_FD_SER fd, useconds_t d_usec, const void *buf, size_t buflen) - ++ This is just ser_send_buf with an intercharacter delay. - ssize_t ser_get_char(TYPE_FD_SER fd, void *ch, time_t d_sec, useconds_t d_usec) - ++ This will wait up to d_sec seconds + d_usec microseconds for one character to arrive, storing it at ch. It returns 1 on success, -1 if something fails and 0 on a timeout. - -NOTE: the delay value must not be too large, or your driver will not get ++ +NOTE: The delay value must not be too large, or your driver will not get back to the usual idle loop in main in time to answer the PINGs from upsd. That will cause an oscillation between staleness and normal behavior. - ssize_t ser_get_buf(TYPE_FD_SER fd, void *buf, size_t buflen, time_t d_sec, useconds_t d_usec) - ++ Like ser_get_char, but this one reads up to buflen bytes storing all of them in buf. The buffer is zeroed regardless of success or failure. It returns the number of bytes read, -1 on failure and 0 on a timeout. - ++ This is essentially a single read() function with a timeout. - ssize_t ser_get_buf_len(TYPE_FD_SER fd, void *buf, size_t buflen, time_t d_sec, useconds_t d_usec) - ++ Like ser_get_buf, but this one waits for buflen bytes to arrive, storing all of them in buf. The buffer is zeroed regardless of success or failure. It returns the number of bytes read, -1 on failure and 0 on a timeout. - ++ This should only be used for binary reads. See ser_get_line for protocols that are terminated by characters like CR or LF. - ssize_t ser_get_line(TYPE_FD_SER fd, void *buf, size_t buflen, char endchar, const char *ignset, time_t d_sec, useconds_t d_usec) - ++ This is the reading function you should use if your UPS tends to send responses like "OK\r" or "1234\n". It reads up to buflen bytes and stores them in buf, but it will return immediately if it encounters @@ -485,22 +485,22 @@ endchar. The endchar will not be stored in the buffer. It will also return if it manages to collect a full buffer before reaching the endchar. It returns the number of bytes stored in the buffer, -1 on failure and 0 on a timeout. - ++ If the character matches the ignset with strchr(), it will not be added to the buffer. If you don't need to ignore any characters, just pass it an empty string -- `""`. - ++ The buffer is always cleared and is always `null`-terminated. It does this by reading at most `(buflen - 1)` bytes. - -NOTE: any other data which is read after the endchar in the serial ++ +NOTE: Any other data which is read after the endchar in the serial buffer will be lost forever. As a result, you should not use this unless your UPS uses a polled protocol. - ++ Let's say your endchar is `\n` and your UPS sends `"OK\n1234\nabcd\n"`. This function will `read()` all of that, find the first `\n`, and stop there. Your driver will get `"OK"`, and the rest is gone forever. - ++ This also means that you should not "pipeline" commands to the UPS. Send a query, then read the response, then send the next query. @@ -509,56 +509,56 @@ Send a query, then read the response, then send the next query. const char *alertset, void handler(char ch), time_t d_sec, useconds_t d_usec) - ++ This is just like ser_get_line, but it allows you to specify a set of alert characters which may be received at any time. They are not added to the buffer, and this function will call your handler function, passing the character as an argument. - ++ Implementation note: this function actually does all of the work, and ser_get_line is just a wrapper that sets an empty alertset and a NULL handler. - ssize_t ser_flush_in(TYPE_FD_SER fd, const char *ignset, int verbose) - ++ This function will drain the input buffer. If verbose is set to a positive number, then it will announce the characters which have been read in the syslog. You should not set verbose unless debugging is enabled, since it could be very noisy. - ++ This function returns the number of characters which were read, so you can check for extra bytes by looking for a nonzero return value. Zero will also be returned if the read fails for some reason. - int ser_flush_io(TYPE_FD_SER fd) - ++ This function drains both the in- and output buffers. Return zero on success. - void ser_comm_fail(const char *fmt, ...) - ++ Call this whenever your serial communications fail for some reason. It takes a format string, so you can use variables and other things to clarify the error. This function does built-in rate-limiting so you can't spam the syslog. - ++ By default, it will write 10 messages, then it will stop and only write 1 in 100. This allows the driver to keep calling this function while the problem persists without filling the logs too quickly. - ++ In the old days, drivers would report a failure once, and then would be silent until things were fixed again. Users had to figure out what was happening by finding that single error message, or by looking at the repeated complaints from upsd or the clients. - ++ If your UPS frequently fails to acknowledge polls and this is a known situation, you should make a couple of attempts before calling this function. - -NOTE: this does not call dstate_datastale. You still need to do that. ++ +NOTE: This does not call dstate_datastale. You still need to do that. - void ser_comm_good(void) - ++ This will clear the error counter and write a "re-established" message to the syslog after communications have been lost. Your driver should call this whenever it has successfully contacted the UPS. A good place @@ -605,20 +605,22 @@ Function - is_usb_device_supported(usb_device_id_t *usb_device_id_list, USBDevice_t *device) - ++ Call this in your device opening / matching function. Pass your usb_device_id_t list structure, and a set of VendorID, DeviceID, as well as Vendor, Product and Serial strings, possibly also Bus, bcdDevice (device release number) and Device name on the bus strings, in the USBDevice_t fields describing the specific piece of hardware you are inspecting. - ++ This function returns one of the following value: - -- NOT_SUPPORTED (0), -- POSSIBLY_SUPPORTED (1, returned when the VendorID is matched, but the -DeviceID is unknown), -- or SUPPORTED (2). - ++ +-- + * NOT_SUPPORTED (0), + * POSSIBLY_SUPPORTED (1, returned when the VendorID is matched, + but the DeviceID is unknown), + * or SUPPORTED (2). +-- ++ For implementation examples, refer to the various USB drivers, and search for the above patterns. diff --git a/docs/nut-names.txt b/docs/nut-names.txt index 7c9e20e506..33487f0ff8 100644 --- a/docs/nut-names.txt +++ b/docs/nut-names.txt @@ -117,8 +117,8 @@ Variables device: General unit information ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -NOTE: some of these data will be redundant with ups.* information -during a transition period. The ups.* data will then be removed. +NOTE: Some of these data will be redundant with `ups.*` information +during a transition period. The `ups.*` data will then be removed. [options="header"] |==================================================================================== diff --git a/docs/nut-qa.txt b/docs/nut-qa.txt index ad50881fe8..babb204298 100644 --- a/docs/nut-qa.txt +++ b/docs/nut-qa.txt @@ -122,7 +122,7 @@ FIXME (POST): link:https://git.launchpad.net/ubuntu/+source/nut/tree/debian/tests/test-nut.py[The NUT testing script] is available in the link:https://code.edge.launchpad.net/qa-regression-testing[Ubuntu QA Regression Testing suite]. + - It installs NUT packages, configures it with the dummy-ups driver, changes +It installs NUT packages, configures it with the dummy-ups driver, changes a few data points and checks that these are well propagated with upsc. - similar approach is explored in NIT (NUT Integration Testing) suite, diff --git a/docs/packager-guide.txt b/docs/packager-guide.txt index 123ab417d0..b4a0cac504 100644 --- a/docs/packager-guide.txt +++ b/docs/packager-guide.txt @@ -29,7 +29,7 @@ Packaging is a final aim for software. It eases and completes the software integration into an OS, and allows users to have an easy software installation and support out of the box. -NOTE: making NUT packaging more uniform should help its documentation, +NOTE: Making NUT packaging more uniform should help its documentation, support and maintenance across the supported OSes. ------------------------------------------------------------------------ diff --git a/docs/security.txt b/docs/security.txt index 99e85b7ee7..3f140a5530 100644 --- a/docs/security.txt +++ b/docs/security.txt @@ -11,7 +11,7 @@ This chapter will present you these mechanisms, by increasing order of security level. This means that the more security you need, the more mechanisms you will have to apply. -NOTE: you may want to have a look at NUT Quality Assurance, since some +NOTE: You may want to have a look at NUT Quality Assurance, since some topics are related to NUT security and reliability. @@ -275,7 +275,7 @@ If the server is build with tcp-wrappers support enabled, it will check if the NUT username is allowed to connect from the client address through the `/etc/hosts.allow` and `/etc/hosts.deny` files. -NOTE: this will only be done for commands that require the user to be logged +NOTE: This will only be done for commands that require the user to be logged into the server. `hosts.allow`: diff --git a/docs/snmp-subdrivers.txt b/docs/snmp-subdrivers.txt index 71c779235b..5f3826152d 100644 --- a/docs/snmp-subdrivers.txt +++ b/docs/snmp-subdrivers.txt @@ -154,7 +154,7 @@ sysOID. For example: snmpwalk -Os -c foobar W.X.Y.Z .1.3.6.1.4.1.705.1 > snmpwalk-Os.log -NOTE: if the OID are only partially resolved (i.e, there are still parts +NOTE: If the OID are only partially resolved (i.e, there are still parts expressed in numeric form), then try using *-M* to point your .mib file. Then call the script using: diff --git a/docs/solaris-usb.txt b/docs/solaris-usb.txt index e96aad085f..7cb6b4138a 100644 --- a/docs/solaris-usb.txt +++ b/docs/solaris-usb.txt @@ -396,11 +396,15 @@ Additional tricks that can help involve `crontab` for regular automated checks if the device got lost. One is just an attempt to "clear" the service if its earlier startup failed (repetitively) so SMF gave up: - * * * * * svcadm clear innotech 2>&1 | grep -v 'is not in a maintenance' +---- +* * * * * svcadm clear innotech 2>&1 | grep -v 'is not in a maintenance' +---- Another is more complicated and involves some custom scripting: - 0,5,10,15,20,25,30,35,40,45,50,55 * * * * MODE=optional /etc/nut/reset-ups-usb-solaris.sh +---- +0,5,10,15,20,25,30,35,40,45,50,55 * * * * MODE=optional /etc/nut/reset-ups-usb-solaris.sh +---- ...where the script would be a copy (customized to your device(s) and connection points!) of `reset-ups-usb-solaris.sh.sample` from either From 9e95f09f062ecb8745d957497bdc9d5b59b8fb98 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 20:22:37 +0100 Subject: [PATCH 61/67] Various scripts/ asciidocs: reconcile markup (multi-paragraph lists, etc.) Signed-off-by: Jim Klimov --- scripts/Windows/README.adoc | 6 ++++++ scripts/fuse/README.adoc | 1 + scripts/hotplug/README.adoc | 1 + 3 files changed, 8 insertions(+) diff --git a/scripts/Windows/README.adoc b/scripts/Windows/README.adoc index bbf2255b5e..edb9a1fb98 100644 --- a/scripts/Windows/README.adoc +++ b/scripts/Windows/README.adoc @@ -111,11 +111,13 @@ When using the compilation approach, you would typically use the following and `PREFIX` values: - prefer either to ++ ------ :; export ARCH="x86_64-w64-mingw32" ------ + or ++ ------ :; export ARCH="i686-w64-mingw32" ------ @@ -128,6 +130,7 @@ or the `wget -c` used below would skip downloads that are already completed) - for either-`ARCH` build environment further set: ++ ------ :; export HOST_FLAG="--host=$ARCH" :; PREFIX="/usr/$ARCH" @@ -171,6 +174,7 @@ or ------ - on Debian/Ubuntu style systems also: ++ ------ :; BUILD_FLAG="--build=`dpkg-architecture -qDEB_BUILD_GNU_TYPE`" ------ @@ -178,6 +182,7 @@ or Hints for Redhat-style systems are wanted. - also export the following compilation flags: ++ ------ :; export CFLAGS="$CFLAGS -D_POSIX=1 -I${PREFIX}/include/" :; export CXXFLAGS="$CXXFLAGS -D_POSIX=1 -I${PREFIX}/include/" @@ -187,6 +192,7 @@ or - prepare the download and build area, e.g. to match copy-paste instructions below, it would be like: ++ ------ :; DLDIR=~/nut-win-deps :; WSDIR="$DLDIR"/"$ARCH" diff --git a/scripts/fuse/README.adoc b/scripts/fuse/README.adoc index 46e57e1008..8b963affed 100644 --- a/scripts/fuse/README.adoc +++ b/scripts/fuse/README.adoc @@ -30,6 +30,7 @@ Installation: on Debian-like systems, or `brew install --cask macfuse@dev` on MacOS with Homebrew community packaging. * Download and build the `execfuse` daemon: ++ ---- :; git clone https://github.com/vi/execfuse :; cd execfuse diff --git a/scripts/hotplug/README.adoc b/scripts/hotplug/README.adoc index a53b6dac46..6847046501 100644 --- a/scripts/hotplug/README.adoc +++ b/scripts/hotplug/README.adoc @@ -38,6 +38,7 @@ 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 ---- From 426df9b7db0436f9540941e17431811788319ff3 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 20:27:39 +0100 Subject: [PATCH 62/67] Various docs: spell "man pages" as two words Signed-off-by: Jim Klimov --- data/html/README.adoc | 3 ++- docs/FAQ.txt | 2 +- docs/config-prereqs.txt | 2 +- docs/configure.txt | 4 ++-- docs/man/pijuice.txt | 6 +++--- docs/packager-guide.txt | 6 +++--- docs/snmp.txt | 2 +- 7 files changed, 13 insertions(+), 12 deletions(-) diff --git a/data/html/README.adoc b/data/html/README.adoc index fdd6659885..e4a8f459db 100644 --- a/data/html/README.adoc +++ b/data/html/README.adoc @@ -84,7 +84,8 @@ Alias /nut/ /usr/local/nut/html/ - Make sure to restart your webserver. -- Configure the CGI scripts. Manpages can be found from: +- Configure the CGI scripts. Man pages can be found from: ++ ---- :; man -M /usr/local/nut/man/ upsstats.cgi :; man -M /usr/local/nut/man/ upsset.cgi diff --git a/docs/FAQ.txt b/docs/FAQ.txt index c45ac89ad2..5a193ef950 100644 --- a/docs/FAQ.txt +++ b/docs/FAQ.txt @@ -87,7 +87,7 @@ There can be due to various reasons. To fix it, check: - your firewall rules. Port '3493/tcp' must be opened to incoming connections, - your *tcp-wrappers* configuration (`hosts.allow` and `hosts.deny`) if used. -Refer to the linkman:upsd[8] and linkman:upsd.conf[5] manpages for more +Refer to the linkman:upsd[8] and linkman:upsd.conf[5] man pages for more information. == I get a 'not listening on...' error from upsd. diff --git a/docs/config-prereqs.txt b/docs/config-prereqs.txt index c4c6c70d65..858e7c9b7c 100644 --- a/docs/config-prereqs.txt +++ b/docs/config-prereqs.txt @@ -642,7 +642,7 @@ For NUT dependencies and build tools: # Note there is no direct "asciidoc" nor "a2x", just the competing project # "rubygem-asciidoctor" that NUT currently has no recipes for, so you can # not compile man/html/pdf docs here, per the default repository. See below -# for tools from alternative repositories, which seem to work well. Manpage +# for tools from alternative repositories, which seem to work well. Man page # compilation would require docbook-xml resources; older versions are in # this package https://slackbuilds.org/repository/15.0/system/docbook-xml/ # and recent ones are in not-installed part of main repository: diff --git a/docs/configure.txt b/docs/configure.txt index 50beca3354..260a452b59 100644 --- a/docs/configure.txt +++ b/docs/configure.txt @@ -267,7 +267,7 @@ The possible documentation type values are: * `html-single` for single page HTML, * `html-chunked` for multi-paged HTML, * `pdf` for a PDF file, and -* `man` for the usual manpages. +* `man` for the usual man pages. Other values understood for this option are listed below: @@ -280,7 +280,7 @@ Other values understood for this option are listed below: can not be generated. * A `--with-doc=no` quietly skips generation of all types of documentation, - including manpages. + including man pages. * A `--with-doc=skip` is used to configure some of the `make distcheck*` scenarios to re-use man page files built and distributed by the main diff --git a/docs/man/pijuice.txt b/docs/man/pijuice.txt index 5d415d2f7e..901847fc56 100644 --- a/docs/man/pijuice.txt +++ b/docs/man/pijuice.txt @@ -18,7 +18,7 @@ NOTE: This man page only documents the hardware-specific features of the linkman:nutupsdrv[8]. NOTE: This manual page was hastily adapted from related `asem` driver -manpage based on information from the original pull request, and so +man page based on information from the original pull request, and so may not fully apply to PiJuice HAT, patches from experts are welcome. SUPPORTED HARDWARE @@ -38,7 +38,7 @@ On the PiJuice HAT, this should be `/dev/i2c-1`. INSTALLATION ------------ -NOTE: This section was copied from `asem` driver manpage and may not fully +NOTE: This section was copied from `asem` driver man page and may not fully apply to PiJuice HAT, patches are welcome. This driver is specific to the Linux I2C API, and requires the lm_sensors @@ -61,7 +61,7 @@ DIAGNOSTICS KNOWN ISSUES AND BUGS --------------------- -NOTE: This section was copied from `asem` driver manpage and may not fully +NOTE: This section was copied from `asem` driver man page and may not fully apply to PiJuice HAT, patches are welcome. The driver shutdown function is not implemented, so other arrangements must be diff --git a/docs/packager-guide.txt b/docs/packager-guide.txt index b4a0cac504..4388a4e0fb 100644 --- a/docs/packager-guide.txt +++ b/docs/packager-guide.txt @@ -380,12 +380,12 @@ nut-server E) nut-cgi Deps: - Files: snmp-ups and powernet + manpages + Files: snmp-ups and powernet + man pages F) nut-doc: Deps: - Files: dummycons + manpage + Files: dummycons + man page G) nut-dev: @@ -395,7 +395,7 @@ nut-server H) nut-scanner: Deps: hard dependency on `libltdl`; recommends `libsnmp`, `libneon`, and the `libusb` variant (0.1 or 1.0) it was built against. - Files: nut-scanner tool and libnutscan + manpages + Files: nut-scanner tool and libnutscan + man pages Note: "nut" can be a meta package diff --git a/docs/snmp.txt b/docs/snmp.txt index 0e058761dd..befc333c5f 100644 --- a/docs/snmp.txt +++ b/docs/snmp.txt @@ -34,7 +34,7 @@ in NUT any SNMP Agent (embedded or on a host). The new snmp-ups driver now support multiple MIBS (SNMP structures declaration). For more information on snmp-ups, have a look at its -manpage (man 8 snmp-ups). +man page (man 8 snmp-ups). * Extending existing mib2nut information From f9e4950a16434951593d24227353a1f02702b5fb Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 6 Feb 2025 20:28:35 +0100 Subject: [PATCH 63/67] Various other asciidocs: reconcile markup (multi-paragraph lists, etc.) Signed-off-by: Jim Klimov --- data/html/README.adoc | 1 + lib/README.adoc | 4 ++-- tests/NIT/README.adoc | 4 ++-- 3 files changed, 5 insertions(+), 4 deletions(-) diff --git a/data/html/README.adoc b/data/html/README.adoc index e4a8f459db..422a944860 100644 --- a/data/html/README.adoc +++ b/data/html/README.adoc @@ -56,6 +56,7 @@ b) configure manually - Now edit your webserver configuration file, adding for example (for Apache): ++ ---- #Begin Section ScriptAlias /nut/cgi-bin/ /usr/local/nut/cgi-bin/ diff --git a/lib/README.adoc b/lib/README.adoc index 6e3fac7211..636795741c 100644 --- a/lib/README.adoc +++ b/lib/README.adoc @@ -45,7 +45,7 @@ To get LD_FLAGS, use: References: linkman:libupsclient-config[1] manual page, -NOTE: this feature may evolve (name change), or even disappear in the future. +NOTE: This feature may evolve (name change), or even disappear in the future. pkgconfig support ----------------- @@ -115,7 +115,7 @@ The same is also valid for other NUT libraries, such as libnutscan. Simply replace 'libupsclient' occurrences in the above example, by the name of the desired library (for example, 'libnutscan'). -NOTE: this is an alternate method. Use of PKG_CHECK_MODULES macro should be +NOTE: This is an alternate method. Use of PKG_CHECK_MODULES macro should be preferred. diff --git a/tests/NIT/README.adoc b/tests/NIT/README.adoc index 05be5a2d46..86511483da 100644 --- a/tests/NIT/README.adoc +++ b/tests/NIT/README.adoc @@ -19,7 +19,7 @@ it via files in standard path names. A sandbox prepared by this script can be used for `upsmon` testing: -```` +---- :; make check-NIT-sandbox-devel & # Wait for sandbox, e.g. test that "${NUT_CONFPATH}/NIT.env-sandbox-ready" @@ -32,4 +32,4 @@ A sandbox prepared by this script can be used for `upsmon` testing: "$NUT_STATEPATH" "$NUT_STATEPATH" 'dummy' "$NUT_PORT" \ 'dummy-admin' "${TESTPASS_UPSMON_PRIMARY}" \ > "${NUT_CONFPATH}/upsmon.conf" -```` +---- From 7d54b273bb4ffcb61dfd5aca6db9558eea3b61b9 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Fri, 7 Feb 2025 11:39:31 +0100 Subject: [PATCH 64/67] INSTALL.nut.adoc, docs/download.txt, docs/developers.txt: suggest fetching git tags to have a saner NUT_SEMVER in custom builds Signed-off-by: Jim Klimov --- INSTALL.nut.adoc | 21 +++++++++++++++++++-- docs/developers.txt | 18 +++++++++++++++--- docs/download.txt | 6 ++++++ 3 files changed, 40 insertions(+), 5 deletions(-) diff --git a/INSTALL.nut.adoc b/INSTALL.nut.adoc index e14ac66204..821ad2f543 100644 --- a/INSTALL.nut.adoc +++ b/INSTALL.nut.adoc @@ -488,11 +488,16 @@ copy the proposed-source URL of that "from" part. For example, in some PR this says `jimklimov:issue-1234` and links to `https://github.com/jimklimov/nut/tree/issue-1234`. For manual git-cloning, just paste that URL into the shell and replace -the `/tree/` with "`-b`" CLI option for branch selection, like this: +the `/tree/` with "`-b`" CLI option for branch selection; it also helps +to keep the workspace directory name dedicated to that PR, like this: :; cd /tmp ### Checkout https://github.com/jimklimov/nut/tree/issue-1234 - :; git clone https://github.com/jimklimov/nut -b issue-1234 + :; git clone https://github.com/jimklimov/nut -b issue-1234 nut-issue-1234 + :; cd nut-issue-1234 + ### OPTIONALLY fetch known git tags, so semantic versions look better + :; git fetch --tags --all + ### Proceed with build (common instructions below) Testing with CI helper ~~~~~~~~~~~~~~~~~~~~~~ @@ -509,6 +514,9 @@ An "in-place" _testing_ build and run would probably go along these lines: :; cd /tmp :; git clone -b master https://github.com/networkupstools/nut :; cd nut + ### OPTIONALLY fetch known git tags, so semantic versions look better + :; git fetch --tags --all + ### Proceed with build :; ./ci_build.sh inplace ### Temporarily stop your original drivers :; ./drivers/nutdrv_qx -a DEVNAME_FROM_UPS_CONF -d1 -DDDDDD \ @@ -563,6 +571,9 @@ This goes similar to usual build and install from Git: :; cd /tmp :; git clone https://github.com/networkupstools/nut :; cd nut + ### OPTIONALLY fetch known git tags, so semantic versions look better + :; git fetch --tags --all + ### Proceed with build :; ./autogen.sh :; ./configure --enable-inplace-runtime # --maybe-some-other-options :; make -j 4 all && make -j 4 check && sudo make install @@ -591,6 +602,9 @@ symlinks) and to get them started: :; cd /tmp :; git clone https://github.com/networkupstools/nut :; cd nut + ### OPTIONALLY fetch known git tags, so semantic versions look better + :; git fetch --tags --all + ### Proceed with build :; ./autogen.sh :; ./configure --enable-inplace-runtime # --maybe-some-other-options :; make -j 4 all && make -j 4 check && \ @@ -643,6 +657,9 @@ e.g.: :; git clone https://github.com/networkupstools/nut :; cd nut :; git checkout -b issue-1234 ### your PR branch name, arbitrary + ### OPTIONALLY fetch known git tags, so semantic versions look better + :; git fetch --tags --all + ### Proceed with build :; ./autogen.sh :; ./configure --enable-inplace-runtime # --maybe-some-other-options ### Iterate your code changes (e.g. PR draft), build and install with: diff --git a/docs/developers.txt b/docs/developers.txt index baa2be1810..f2f80b3e49 100644 --- a/docs/developers.txt +++ b/docs/developers.txt @@ -1430,6 +1430,13 @@ you can limit the depth of the clone: :; git clone --depth 1 git://github.com/networkupstools/nut.git + +OPTIONALLY you can then fetch known git tags, so semantic versions look +better (based off a recent release): + + :; cd nut + :; git fetch --tags --all + Mercurial (hg) access ~~~~~~~~~~~~~~~~~~~~~ @@ -1574,13 +1581,18 @@ If you haven't created a commit out of your local changes yet, and you want to fetch the latest code, you can also use +git stash+ before pulling, then +git stash pop+ to apply your saved changes. -Here is an example workflow: +Here is an example workflow (using a slightly older `git` command-line syntax, +so it works verbatim on more platforms): ------------------------------------------------------------------------------ :; git clone -o central git://github.com/networkupstools/nut.git :; cd nut - :; git remote add -f username git://github.com/username/nut.git + :; git remote add -f USERNAME git://github.com/USERNAME/nut.git + + ### OPTIONALLY you can then fetch known git tags, so semantic + ### versions look better (based off a recent release): + :; git fetch --tags --all :; git checkout master :; git branch my-new-feature @@ -1602,7 +1614,7 @@ Here is an example workflow: # Publish your branch to your GitHub repository: - :; git push username my-new-feature + :; git push USERNAME my-new-feature ------------------------------------------------------------------------------ If you are new to Git, but are familiar with SVN, some of the following links diff --git a/docs/download.txt b/docs/download.txt index b0f6b546a7..3b436aecff 100644 --- a/docs/download.txt +++ b/docs/download.txt @@ -45,6 +45,12 @@ To retrieve the current development tree, use the following command: :; git clone git://github.com/networkupstools/nut.git +OPTIONALLY you can then fetch known git tags, so semantic versions look +better (based off a recent release): + + :; cd nut + :; git fetch --tags --all + The `configure` script and its dependencies are not stored in Git. To generate them, ensure that autoconf, automake and libtool are installed, then run the following script in the directory you just checked out: From 5ab1adb344fa1b9f1e2a91389ab71686bffc0e14 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Fri, 7 Feb 2025 11:39:56 +0100 Subject: [PATCH 65/67] INSTALL.nut.adoc: suggest how to push back a locally fixed git branch Signed-off-by: Jim Klimov --- INSTALL.nut.adoc | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/INSTALL.nut.adoc b/INSTALL.nut.adoc index 821ad2f543..9e068fc76d 100644 --- a/INSTALL.nut.adoc +++ b/INSTALL.nut.adoc @@ -670,6 +670,13 @@ e.g.: sudo systemctl restart \ nut-driver-enumerator.service nut-monitor nut-server +Note that to contribute your work back to upstream NUT codebase, you would +need to create a "fork" of https://github.com/networkupstools/nut on GitHub, +then `git remote add USERNAME https://github.com/USERNAME/nut`, maybe refresh +the workspace index with `git fetch --all`, and finally `git push USERNAME` +(possibly follow further instructions from `git` tooling) to create the +pull request. For more details, see `docs/developers.txt` in NUT sources. + Next steps after an in-place upgrade ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From d0cc2db28309db817dd1b372a21d6d88b17f896c Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Fri, 7 Feb 2025 12:10:32 +0100 Subject: [PATCH 66/67] docs/download.txt: change wording and use asciidoc link to pass dblatex=>PDF generation Signed-off-by: Jim Klimov --- docs/download.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/download.txt b/docs/download.txt index 3b436aecff..4db4cfee2a 100644 --- a/docs/download.txt +++ b/docs/download.txt @@ -171,9 +171,9 @@ link:https://github.com/networkupstools/nut/wiki/Links-to-distribution-packaging - Windows (complete port, Beta): - * Current Appveyor CI builds are available as tarballs with binaries from - https://ci.appveyor.com/project/nut-travis/nut/build/artifacts -- but - it may be difficult to locate specifically the master-branch builds. + * Current regular CI builds are available as tarballs with binaries from + link:https://ci.appveyor.com/project/nut-travis/nut/build/artifacts[Appveyor + CI] -- but it may be difficult to locate specifically the master-branch builds. See link:https://github.com/networkupstools/nut/wiki/NUT-for-Windows[NUT for Windows wiki article] for these details, and more. * link:https://www.networkupstools.org/package/windows/NUT-Installer-2.6.5-6.msi[(OBSOLETE) Windows MSI installer 2.6.5-6] From 8aa8b08776322ba4b81c0cc2e2635fc61d3a8c4a Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Fri, 7 Feb 2025 15:54:15 +0100 Subject: [PATCH 67/67] docs/man/nut_usb_addvars.txt, docs/man/ups.conf.txt: fix links leading to libusb API docs with two underscores Signed-off-by: Jim Klimov --- docs/man/nut_usb_addvars.txt | 7 ++++++- docs/man/ups.conf.txt | 14 ++++++++++++-- 2 files changed, 18 insertions(+), 3 deletions(-) diff --git a/docs/man/nut_usb_addvars.txt b/docs/man/nut_usb_addvars.txt index 137d47972c..48477267da 100644 --- a/docs/man/nut_usb_addvars.txt +++ b/docs/man/nut_usb_addvars.txt @@ -142,4 +142,9 @@ For more details, including the currently supported values for your version of the library, see e.g.: * https://libusb.sourceforge.io/api-1.0/ -* link:https://libusb.sourceforge.io/api-1.0/group__libusb__lib.html[https://libusb.sourceforge.io/api-1.0/group\__libusb__lib.html] +* link:https://libusb.sourceforge.io/api-1.0/group\__libusb\__lib.html[https://libusb.sourceforge.io/api-1.0/group\__libusb__lib.html] + +/////////////////// +// EDITOR NOTE: There are no backslashes in the URL above, just that +// asciidoc sees them as "emphasis" markup, they had to be escaped. +/////////////////// diff --git a/docs/man/ups.conf.txt b/docs/man/ups.conf.txt index a29b399385..474d4c25be 100644 --- a/docs/man/ups.conf.txt +++ b/docs/man/ups.conf.txt @@ -199,7 +199,12 @@ For more details, including the currently supported values for your version of the library, see e.g.: * https://libusb.sourceforge.io/api-1.0/ -* https://libusb.sourceforge.io/api-1.0/group__libusb__lib.html +* link:https://libusb.sourceforge.io/api-1.0/group\__libusb\__lib.html[https://libusb.sourceforge.io/api-1.0/group\__libusb__lib.html] + +/////////////////// +// EDITOR NOTE: There are no backslashes in the URL above, just that +// asciidoc sees them as "emphasis" markup, they had to be escaped. +/////////////////// UPS FIELDS ---------- @@ -405,7 +410,12 @@ For more details, including the currently supported values for your version of the library, see e.g.: * https://libusb.sourceforge.io/api-1.0/ -* https://libusb.sourceforge.io/api-1.0/group__libusb__lib.html +* link:https://libusb.sourceforge.io/api-1.0/group\__libusb\__lib.html[https://libusb.sourceforge.io/api-1.0/group\__libusb__lib.html] + +/////////////////// +// EDITOR NOTE: There are no backslashes in the URL above, just that +// asciidoc sees them as "emphasis" markup, they had to be escaped. +/////////////////// INTEGRATION -----------