dummy-ups(8)

1DUMMY-UPS(8)                      NUT Manual                      DUMMY-UPS(8)
2
3
4

NAME

6       dummy-ups - Driver for multi-purpose UPS emulation
7

NOTE

9       This man page only documents the specific features of the dummy-ups
10       driver. For information about the core driver, see nutupsdrv(8).
11

DESCRIPTION

13       This program is a multi-purpose UPS emulation tool. Its general
14       behavior depends on the running mode: "dummy" ("dummy-once" or
15       "dummy-loop"), or "repeater".
16
17   Dummy Mode
18       In this mode, dummy-ups looks like a standard NUT device driver to
19       upsd(8) and allows one to change any value for testing purposes. It is
20       both interactive, controllable through the upsrw(1) and upscmd(1)
21       commands (or equivalent graphical tool), and batchable through script
22       files. It can be configured, launched and used as any other "real" NUT
23       driver. This mode is mostly useful for development and testing
24       purposes.
25
26           Note
27           See below about the differences of dummy-once vs. dummy-loop modes
28           — the former may be more suitable for "interactive" uses and tests.
29
30   Repeater Mode
31       In this mode, dummy-ups acts as a NUT client, simply forwarding data.
32       This can be useful for supervision purposes. This mode can also allow
33       some load sharing between several upsd instances communicating with
34       ultimate NUT clients, with a "central" one using a point-to-point
35       communication with the UPS. This arrangement can also help with
36       networked UPSes, whose network management cards can be overwhelmed with
37       a farm of servers directly polling SNMP or other protocols every few
38       seconds.
39

IMPLEMENTATION

41       The port specification in ups.conf depends on the running mode, and
42       allows the driver to select the right mode of operation.
43
44       Since NUT v2.8.0, the mode specification in ups.conf allows users to
45       override the mode of operation which would be otherwise guessed by the
46       driver.
47
48   Dummy Mode
49       In this context, port in the ups.conf block defines a file name for the
50       dummy-ups to read data from. This can either be an absolute or a
51       relative path name. In the latter case the NUT sysconfig directory
52       (i.e. /etc/nut, /usr/local/ups/etc, ...) is prepended.
53
54       Since NUT v2.8.0 two aspects of this mode are differentiated:
55
56       •   dummy-once reads the specified file once to the end (interrupting
57           for TIMER lines, etc.) and does not re-process it until the
58           filesystem timestamp of the data file is changed; this reduces
59           run-time stress if you test with a lot of dummy devices, and allows
60           use/test cases to upsrw variables into the driver instance — and
61           they remain in memory until the driver is restarted (or the file is
62           touched or modified);
63
64           Since NUT v2.8.0 dummy-once is assigned by default to files with a
65           *.dev naming pattern.
66
67       •   dummy-loop reads the specified file again and again, with a short
68           sleep between the processing cycles; for sequence files using a
69           TIMER keyword (see below), or for use/test cases which modify file
70           contents with external means, this allows an impression of a device
71           whose state changes over time.
72
73           Before NUT v2.8.0 this was the only aspect, so a simple dummy mode
74           value maps to this behavior for backwards compatibility.
75
76           Since NUT v2.8.0 dummy-loop is assigned by default to files with a
77           *.seq naming pattern, and dummy is assigned by default to files
78           with other naming patterns that the driver could not classify.
79
80           Note
81           Said defaulting based on filename pattern can break third-party
82           test scripts which earlier expected *.dev files to work as a
83           looping sequence with a TIMER keywords to change values slowly. Now
84           such files should get processed to the end once.
85
86           Specify mode=dummy-loop driver option or rename the data file used
87           in the port option for legacy behavior.
88
89           Use/Test-cases which modified such files content externally should
90           not be impacted.
91
92       For instance:
93
94           [dummy1]
95                   driver = dummy-ups
96                   port = evolution500.seq
97                   desc = "dummy-ups in dummy-loop mode"
98
99           [dummy2]
100                   driver = dummy-ups
101                   port = epdu-managed.dev
102                   desc = "dummy-ups in dummy-once mode"
103
104       This file is generally named something.dev or something.seq. It
105       contains a list of all valid variables and associated values (you can
106       later use upsrw only to modify values of these variables), and has the
107       same format as an upsc(8) dump (<varname>: <value>). So you can easily
108       create definition files from an existing UPS using upsc > file.dev.
109
110       Note that the Network UPS project provides an extensive DDL (Devices
111       Dumps Library) with files which can be used for modelling real devices.
112       Entries for the DDL library are best prepared with the
113       tools/nut-ddl-dump.sh script from NUT sources instead of plain upsc, to
114       provide some additional data points from other NUT clients as well.
115
116       The file can also be empty, in which case only a basic set of data is
117       available: device.*, driver.*, ups.mfr, ups.model, ups.status as filled
118       by the driver itself.
119
120       Some sample definition files are available in the data directory of the
121       NUT source tree, and generally in the sysconfig or share directory of
122       your system distribution.
123
124       Since dummy-ups will usually loop on reading this file, you can
125       dynamically modify it with some external process to "interact" with the
126       driver. This will avoid message spam into your system log files, if you
127       are using NUT default configuration.
128
129           Note
130           By default since NUT v2.8.0, it will not loop on files in
131           dummy-once mode, e.g. those with a .dev extension, unless their
132           timestamp changes.
133
134       You can also use the TIMER <seconds> instruction to create scheduled
135       event sequences (such files are traditionally named with the .seq
136       extension). For example, the following sequence will loop on switching
137       ups.status between "OL", "OB" and "OB LB" every minute:
138
139           ups.status: OL
140           TIMER 60
141           ups.status: OB
142           TIMER 60
143           ups.status: OB LB
144           TIMER 60
145
146       It is wise to end the script for dummy-loop mode with a TIMER keyword.
147       Otherwise dummy-ups will directly go back to the beginning of the file
148       and, in particular, forget any values you could have just set with
149       upsrw.
150
151       Note that to avoid CPU overload with an infinite loop, the driver
152       "sleeps" a bit between file-reading cycles (currently this delay is
153       hardcoded to one second), independently of (and/or in addition to) any
154       TIMER keywords.
155
156   Repeater Mode
157       In this context, port in the ups.conf block is the name of a remote
158       UPS, using the NUT format, i.e.:
159
160           <upsname>@<hostname>[:<port>]
161
162       For instance:
163
164           [repeater]
165                   driver = dummy-ups
166                   port = ups1@remotehost
167                   desc = "dummy-ups in repeater mode"
168
169       Unlike UPS specifications in the rest of NUT, the @hostname portion is
170       not optional - it is the @ character which enables Repeater Mode. To
171       refer to an UPS on the same host as dummy-ups, use port =
172       upsname@localhost.
173
174       Note that to avoid CPU overload with an infinite loop, the driver
175       "sleeps" a bit between data-requesting cycles (currently this delay is
176       hardcoded to one second), so propagation of data updates available to a
177       remote upsd may lag by this much.
178

INTERACTION

180       Once the driver is loaded in dummy mode, you can change any variables,
181       except those of the driver.* and server.* collections. You can do this
182       by either editing the definition file, or use the upsrw(1) and
183       upscmd(1) commands.
184
185       Note that in simulation mode, new variables can be added on the fly,
186       but only by adding these to the definition file (and waiting for it to
187       be re-read). That is, the driver should not allow to define a new
188       variable via upsrw.
189
190       Conversely, if you need to remove a variable (such as transient ones,
191       like ups.alarm), simply update these by setting an empty value. As a
192       result, they will get removed from the data.
193
194       In repeater mode, the driver acts according to the capabilities of the
195       UPS, and so supports the same instant commands and settable values.
196

BACKGROUND

198       Dummy Mode was originally written in one evening to replace the
199       previous dummycons testing driver, which was too limited, and required
200       a terminal for interaction.
201
202       dummy-ups is useful for NUT client development, and other testing
203       purposes.
204
205       It also helps the NUT Quality Assurance effort, by automating some
206       tests on the NUT framework.
207
208       It now offers a repeater mode. This will help in building the Meta UPS
209       approach, which allows one to build a virtual device, composed of
210       several other devices (either UPS, PDUs), or perhaps represent the same
211       device which supports several communication protocols and different
212       media (Serial, USB, SNMP...)
213

BUGS

215       Instant commands are not yet supported in Dummy Mode, and data need
216       name/value checking enforcement, as well as boundaries or enumeration
217       definition.
218

CAVEATS

220       If you use service management frameworks like systemd or SMF to manage
221       the dependencies between driver instances and the data server, and some
222       of these drivers are dummy-ups in repeater mode representing data from
223       another driver running on the same system, then you may have to set up
224       special dependencies (e.g. with systemd "drop-in" snippet files) to
225       allow your nut-server to start after the "real" device drivers and
226       before such repeater drivers (without a responding server, they would
227       fail to start anyway). This may also need special care in upsd.conf
228       and/or ups.conf files to not block the system start-up for too long
229       while the repeater driver has not started.
230

AUTHOR

232       Arnaud Quette
233