Imported Upstream version 2.6.0

docs/man/clone.txt

@@ -0,0 +1,115 @@
+CLONE(8)
+========
+
+NAME
+----
+clone - UPS driver clone
+
+NOTE
+----
+This man page only documents the specific features of the
+clone 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
+was a normal UPS.
+
+EXTRA ARGUMENTS
+---------------
+This driver supports the following settings:
+
+*load.off*='command'::
+Recommended.  Set the command on the "real" UPS driver that will be used to
+switch off the outlet.  You need both *load.off* and *load.on* in
+order to power cycle the outlet.  Otherwise, shutting down the clients
+powered by an outlet is a one way street (see <<_important,IMPORTANT>>).
+
+*load.on*='command'::
+Recommended.  Set the command on the "real" UPS driver that will be used to
+switch on the outlet.  You need both *load.off* and *load.on* in
+order to power cycle the outlet.  Otherwise, shutting down the clients
+powered by an outlet is a one way street (see <<_important,IMPORTANT>>).
+
+*load.status*='value'::
+Recommended.  Set the variable on the "real" UPS driver that will be used
+to indicate the outlet status (i.e. on/off).  If not specified, the clone
+driver will attempt to keep track of the outlet status, but this is less
+reliable.
+
+*offdelay*='num'::
+Set the timer (in seconds) before the outlet is turned off after the
+shutdown condition (+OB LB+) for this outlet is met or a command to shutdown
+was issued.  Defaults to 120 seconds.
+
+*ondelay*='num'::
+Set the timer (in seconds) for the outlet to switch on in case the power
+returns after the oulet has been switched off.  Defaults to 30 seconds.
+
+*mincharge*='value'::
+Set the remaining battery level when the clone UPS switches to LB
+(percent).
+
+*minruntime*='value'::
+Set the remaining battery runtime when the clone UPS switches to LB
+(seconds).
+
+IMPLEMENTATION
+--------------
+The port specification in the linkman:ups.conf[5] reference the driver
+socket that the "real" UPS driver is using. For example:
+
+  [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
+     [...]
+
+IMPORTANT
+---------
+Unlike a real UPS, you should *not* configure a upsmon master for this
+driver.  When a upsmon master 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 master.
+
+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 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, your clients will lose power without
+warning.
+
+AUTHOR
+------
+Arjen de Korte <adkorte-guest@alioth.debian.org>
+
+SEE ALSO
+--------
+
+linkman:upscmd[1],
+linkman:upsrw[1],
+linkman:ups.conf[5],
+linkman:nutupsdrv[8]
+
+Internet Resources:
+~~~~~~~~~~~~~~~~~~~
+The NUT (Network UPS Tools) home page: http://www.networkupstools.org/