nut/docs/man/clone.txt

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 outlet 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 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 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.

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 <adkorte-guest@alioth.debian.org>

SEE ALSO
--------

linkman:upscmd[1],
linkman:upsrw[1],
linkman:ups.conf[5],
linkman:nutupsdrv[8]

Dummy driver:
~~~~~~~~~~~~~

The "repeater" mode of 'dummy-ups' driver is in some ways similar to the
'clone' driver, 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: http://www.networkupstools.org/