Introduce docs/man/clone-outlet.txt

Signed-off-by: Jim Klimov <[email protected]>

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	\

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 <[email protected]>
+
+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/

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