dummy-ups - Man Page

In this mode, dummy-ups looks like a standard NUT device driver to upsd(8) and allows one to change any value for testing purposes​.

It is both interactive, controllable through the upsrw(8) and upscmd(8) 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​.

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

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

Since NUT v2​.8​.0 two aspects of this mode are differentiated:

• dummy-once reads the specified file once to the end (interrupting for TIMER lines, etc​.) and does not re-process it until the filesystem timestamp of the data file is changed; this reduces run-time stress if you test with a lot of dummy devices, and allows use/test cases to upsrw variables into the driver instance — and they remain in memory until the driver is restarted (or the file is touched or modified);

  Since NUT v2​.8​.0 dummy-once is assigned by default to files with a *​.dev naming pattern​.

• dummy-loop reads the specified file again and again, with a short sleep between the processing cycles; for sequence files using a TIMER keyword (see below), or for use/test cases which modify file contents with external means, this allows an impression of a device whose state changes over time​.

  Before NUT v2​.8​.0 this was the only aspect, so a simple dummy mode value maps to this behavior for backwards compatibility​.

  Since NUT v2​.8​.0 dummy-loop is assigned by default to files with a *​.seq naming pattern, and dummy is assigned by default to files with other naming patterns that the driver could not classify​.

For instance:

        [dummy1]
                driver = dummy-ups
                port = evolution500​.seq
                desc = "dummy-ups in dummy-loop mode"

        [dummy2]
                driver = dummy-ups
                port = epdu-managed​.dev
                desc = "dummy-ups in dummy-once mode"

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 upsc(8) data dump (<varname>: <value>)​. 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 DDL (Devices Dumps Library) with files which can be used for modelling real devices​. Entries for the DDL library are best prepared with the tools/nut-ddl-dump​.sh script from NUT sources instead of plain upsc, to provide some additional data points from other NUT clients as well​.

The file can also be empty, in which case only a basic set of data is 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​.

Since dummy-ups will usually loop on reading this file, you can dynamically modify it with some external process to "interact" with the driver​. This will avoid message spam into your system log files, if you are using NUT default configuration​.

You can also use the TIMER <seconds> instruction to create scheduled event sequences (such files are traditionally named with the ​.seq extension)​. For example, the following sequence will loop on switching ups​.status between "OL", "OB" and "OB LB" every minute:

ups​.status: OL
TIMER 60
ups​.status: OB
TIMER 60
ups​.status: OB LB
TIMER 60

It is wise to end the script for dummy-loop mode with a TIMER keyword​. Otherwise dummy-ups will directly go back to the beginning of the file 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 and possibly the common pollinterval setting​.

Another, more recently introduced instruction is ALARM, which allows the simulation of UPS alarms in much the same way they would be raised by real driver implementations​. Modern drivers decouple alarm states from the ups​.status variable, and raising ALARM by setting it as a status token is discouraged in favor of using modern, common functions for raising alarms within the driver code​.

The ALARM instruction is intended to simulate this behavior as closely as possible​. The value following an ALARM instruction is treated as the alarm message and is eventually published as the ups​.alarm variable, with the ALARM token also set in ups​.status by internal driver mechanisms, rather than by directly manipulating the variable​. Multiple ALARM instructions will have their messages combined into the ups​.alarm variable, just as would happen with real driver logic​.

Conversely, any ALARM instruction on its own will clear active alarm states​. See below for an example of setting and resetting alarms:

ALARM [UPS too warm to charge]
ALARM [UPS circuit is overheating]
TIMER 5
ALARM
TIMER 5
ALARM [UPS too cold to charge]

In this context, port in the ups​.conf block is the name of the target UPS, using the NUT format, i​.e​.:

<upsname>@<hostname>[:<port>]

For instance:

[repeater]
        driver = dummy-ups
        port = ups1@remotehost
        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 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 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 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​.

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 socket (or named Windows pipe) locally, and allow users to group clients to a particular outlet of a device and deal with this output as if it were a normal UPS​. Notably, in this mode the dummy-ups driver is a client to the networked NUT protocol and can relay information of local or remotely served devices, and requires a running NUT data server upsd to represent the "real" device for this to work​.

clone(8), clone-outlet(8)

The NUT (Network UPS Tools) home page: https://www​.networkupstools​.org/historic/v2​.8​.5/