From 47a0de0fa9c4e6caf1f291eee73753e941776bb3 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Sat, 7 Sep 2024 15:16:17 +0200 Subject: [PATCH] Introduce docs/man/clone-outlet.txt Signed-off-by: Jim Klimov --- docs/man/Makefile.am | 9 ++- docs/man/clone-outlet.txt | 140 ++++++++++++++++++++++++++++++++++++++ docs/nut.dict | 2 +- 3 files changed, 147 insertions(+), 4 deletions(-) create mode 100644 docs/man/clone-outlet.txt diff --git a/docs/man/Makefile.am b/docs/man/Makefile.am index 3b62b95261..a7b5d3781a 100644 --- a/docs/man/Makefile.am +++ b/docs/man/Makefile.am @@ -487,7 +487,8 @@ SRC_SERIAL_PAGES = \ bicker_ser.txt \ blazer-common.txt \ blazer_ser.txt \ - clone.txt \ + clone.txt \ + clone-outlet.txt \ dummy-ups.txt \ etapro.txt \ everups.txt \ @@ -534,7 +535,8 @@ MAN_SERIAL_PAGES = \ bestfcom.8 \ bicker_ser.8 \ blazer_ser.8 \ - clone.8 \ + clone.8 \ + clone-outlet.8 \ dummy-ups.8 \ etapro.8 \ everups.8 \ @@ -584,7 +586,8 @@ HTML_SERIAL_MANS = \ bestfcom.html \ bicker_ser.html \ blazer_ser.html \ - clone.html \ + clone.html \ + clone-outlet.html \ dummy-ups.html \ etapro.html \ everups.html \ diff --git a/docs/man/clone-outlet.txt b/docs/man/clone-outlet.txt new file mode 100644 index 0000000000..f16f849eb8 --- /dev/null +++ b/docs/man/clone-outlet.txt @@ -0,0 +1,140 @@ +CLONE-OUTLET(8) +=============== + +NAME +---- + +clone-outlet - clone an UPS outlet as if it were an UPS (monitoring only) + +SYNOPSIS +-------- + +*clone-outlet* -h + +*clone-outlet* -a 'UPS_NAME' ['OPTIONS'] + +NOTE: This man page only documents the specific features of the +clone-outlet driver. For information about the core driver, see +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] +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). + +Remote clients like `upsmon` can `MONITOR` the device entry presented by the +data server with this driver. + +EXTRA ARGUMENTS +--------------- + +This driver supports the following settings: + +*prefix*='outlet.N':: +Required. Specify the outlet prefix as known on the original driver. +The subset of data points reported by the "real" UPS driver for the actual device +on this prefix would be reported as data points of the virtual UPS maintained by +this driver. + +IMPLEMENTATION +-------------- + +The port specification in the linkman:ups.conf[5] should reference the +local driver socket (or Windows named pipe) that the "real" UPS driver +is using. For example: + +------ + [realups] + driver = usbhid-ups + port = auto + + [clone-outlet-1] + driver = clone-outlet + port = usbhid-ups-realups + prefix = "outlet.1" + desc = "Outlet 1 of the Real UPS" + [...] +------ + +The driver internally interprets "real" driver's information about shutdown +delay and shutdown timer, whole UPS status and this outlet's status, and +relays other data points as they were. + +If the outlet supports and reports a delayed power-off, the virtual UPS would +issue an FSD `ups.status` for its clients to shut down safely. + + +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. + +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. + +CAVEATS +------- + +The clone UPS will follow the status on the real UPS driver. You can only +make the clone UPS shutdown earlier than the real UPS driver, not later. +If the real UPS driver initiates a shutdown, the clone-outlet UPS driver +will immediately follow. + +Be aware that the commands to shutdown/restart an outlet on the real UPS +drivers are not affected, so if you tell the real UPS driver to shutdown +the outlet of the clone UPS driver immediately, your clients will lose +power without warning. A delayed outlet power-off should propagate as FSD, +and the delay should be sufficiently long to allow for client shutdowns. + +If you use service management frameworks like systemd or SMF to manage the +dependencies between driver instances and other units, then you may have +to set up special dependencies (e.g. with systemd "drop-in" snippet files) +to queue your `clone` drivers to start after the "real" device drivers. + +////////////////////////////////////// +TODO later: declare the driver as "optional", see +https://github.com/networkupstools/nut/issues/1389 +////////////////////////////////////// + +AUTHOR +------ + +Arjen de Korte + +SEE ALSO +-------- + +linkman:upscmd[1], +linkman:upsrw[1], +linkman:ups.conf[5], +linkman:clone[8], +linkman:nutupsdrv[8] + +Dummy driver: +~~~~~~~~~~~~~ + +The "repeater" mode of 'dummy-ups' driver is in some ways similar to the +'clone' and 'clone-outlet' drivers, by relaying information from a locally +or remotely running "real" device driver (and NUT data server). + +linkman:dummy-ups[8] + +Internet Resources: +~~~~~~~~~~~~~~~~~~~ + +The NUT (Network UPS Tools) home page: https://www.networkupstools.org/ diff --git a/docs/nut.dict b/docs/nut.dict index 7c89cc5c82..46a395154f 100644 --- a/docs/nut.dict +++ b/docs/nut.dict @@ -1,4 +1,4 @@ -personal_ws-1.1 en 3214 utf-8 +personal_ws-1.1 en 3215 utf-8 AAC AAS ABI