1
.TH BELKINUNV 8 "Sun Dec 7 2003" "" "Network UPS Tools (NUT)"
3
belkinunv \- Driver for Belkin "Universal UPS" and compatible
5
This man page only documents the hardware\(hyspecific features of the
6
belkin driver. For information about the core driver, see
10
The belkinunv driver is known to work with the Belkin Universal UPS
11
models F6C800\(hyUNV and F6C120\(hyUNV, and is expected to work with other
12
Belkin Universal UPS models. The driver only supports serial
13
communication, not USB.
15
The Trust UPS and older Belkin units are not supported by this driver,
16
and neither are the Belkin Home Office models (F6H500\(hySER and so
17
forth). However, some Belkin models, such as the Regulator Pro, are
18
supported by the \fBbelkin\fP(8) driver, and the Home Office models
19
are supported using the \fBgenericups\fP(8) driver with
22
.SH SOFT SHUTDOWN WORKAROUND
23
One problem with the Belkin Universal UPS is that it cannot enter a
24
soft shutdown (shut down the load until AC power returns) unless the
25
batteries are completely depleted. Thus, one cannot just shut off the
26
UPS after operating system shutdown; it will not come back on when the
27
power comes back on. Therefore, the belkinunv driver should never be
28
used with the \fB\-k\fP option. Instead, the \fB\-x wait\fP option is
29
provided as a workaround.
31
When called with the \fB\-x wait\fP option, \fBbelkinunv\fP behaves as
32
a standalone program (i.e., it does not fork into the background). It
33
performs one simple task: it connects to the UPS, waits for AC power
34
to return, and then exits with status 0.
36
This is meant to be used in a shutdown script as follows: during a
37
shutdown, after all filesystems have been remounted read\(hyonly, and
38
just before the system would normally be halted: check /etc/killpower
39
(or similar) to see if this shutdown was caused by \fBupsmon\fP(8),
40
and if yes, call \fBbelkinunv \-x wait\fP. If AC power comes back on,
41
\fBbelkinunv\fP exits, and things should be arranged so that the
42
system reboots in this case. If AC power does not come back on, the
43
UPS will eventually run out of batteries, kill the computer's power
44
supply, and go into soft shutdown mode, which means everything will
45
reboot properly when the power returns. In either case, a deadlock is
48
In addition, if an optional integer argument is given to the \fB\-x
49
wait\fP option, this causes \fBbelkinunv\fP to wait not only for AC
50
power to be present, but also for the battery charge to reach the
51
given level. I use this as part of my startup scripts, to ensure that
52
the batteries are sufficiently charged before the computer continues
53
booting. This should be put very early in the startup script, before
54
any filesystems are mounted read/write, and before any filesystem
57
Several other \fB\-x\fP options are provided to fine\(hytune this
58
behavior. See OPTIONS below for detailed descriptions. See EXAMPLES
59
below for examples of how to use \fBbelkinunv\fP in shutdown and
63
See also \fBnutupsdrv\fP(8) for generic options. Never use the
64
\fB\-k\fP option with this driver; it does not work properly.
66
.B \-x wait[=\fIlevel\fP]
67
When this option is used, \fBbelkinunv\fP does not fork into the
68
background, but behaves as a standalone program. It connects to the UPS and
69
waits until AC power is present. If \fIlevel\fP is specified, it also
70
waits until the battery charge reaches at least the given level in
71
percent. Then, and only then, \fBbelkinunv\fP exits. In addition,
72
while \fBbelkinunv\fP runs in this mode, it displays a status line
73
with information on the UPS status and battery level. This is intended
74
for use in the computer's shutdown and startup scripts, as described
75
under SOFT SHUTDOWN WORKAROUND above.
78
This option only has an effect when used in conjunction with the \fB\-x
79
wait\fP option. It causes \fBbelkinunv\fP to exit if a connection with
80
the UPS cannot be established or is lost, instead of retrying forever,
81
which is the default behavior. The \fB\-x nohang\fP option should be
83
script, to ensure the computer remains bootable even if the UPS has
84
been disconnected during the power failure (for instance, you attached
85
your computer to a generator, carried it to a neighbor's house, or
89
This option only has an effect when used in conjunction with the \fB\-x
90
wait\fP option. It causes the UPS load to be shut off for a short time
91
("flashed") just after the AC power has returned and the requested
92
battery level (if any) has been attained. This is useful if slaves are
93
attached to this UPS; the flash will cause all of them to reboot. Note
94
that, due to the design of the Belkin UPS hardware, the load shutdown lasts
95
ca. 1\(hy2 minutes; a shorter flash cannot be performed reliably. Also,
96
the computers will reboot at the scheduled time, on battery power if
97
necessary, even if AC power fails again in the meantime. This should
98
not be a problem, as your startup scripts can catch this situation.
101
This option only has an effect when used in conjunction with the \fB\-x
102
wait\fP option. It suppresses the status line which \fBbelkinunv\fP
103
would normally print.
106
This option only has an effect when used in conjunction with the \fB\-x
107
wait\fP option. It changes the way in which \fBbelkinunv\fP prints its
108
status line. Normally, terminal control sequences are used to
109
overwrite the same line with new status information, each time the
110
status is updated. This may not work on all terminals. If the \fB\-x
111
dumbterm\fP option is given, each status update is written on a new
120
not supported by all hardware.
124
.B battery.voltage.nominal
126
.B driver.version.internal
130
.B input.frequency.nominal
134
writable: normal/medium/low
136
.B input.transfer.high
137
writable: high transfer voltage point in V
139
.B input.transfer.low
140
writable: low transfer voltage point in V
144
.B input.voltage.maximum
146
.B input.voltage.minimum
148
.B input.voltage.nominal
155
writable. Values: yes/no. This variable determines whether the panel
157
on or off. Note that the beeper is automatically turned back on at the
158
next event (AC failure, battery test, etc). It can be turned off when
159
it is already beeping. Also, the beeper can't be turned off during a
160
critical event (low battery).
169
e.g. 800 for an 800VA system
172
a list of flags; see STATUS FLAGS below.
175
not supported by all hardware.
180
time to restart (read only)
182
.B ups.timer.shutdown
183
time to shutdown (read only). This is always a multiple of 60 seconds.
186
ONLINE/OFFLINE/LINEINT. This describes the basic layout of this UPS
187
(for GUI clients which want to draw an animated picture of power
188
flow). An offline UPS has a direct connection from AC input to AC
189
output, and also a connection from AC input to the battery, and from
190
the battery to AC output. An online UPS lacks the direct connection
191
from AC input to AC output, whereas a line interactive UPS lacks the
192
connection from AC input to the battery.
197
.B beeper.on, beeper.off
198
turn the panel beeper on or off. Note that the beeper is automatically
199
turned back on at the next event (AC failure, battery test, etc). It
200
can be turned off when it is already beeping. Also, the beeper can't
201
be turned off during a critical event (low battery).
203
.B reset.input.minmax
204
reset the variables \fBinput.voltage.minimum\fP and
205
\fBinput.voltage.maximum\fP.
208
shut down load immediately for ca. 1\(hy2 minutes
210
.B shutdown.reboot.graceful
211
after 40 second delay, shut down load for ca. 1\(hy2 minutes
214
shut down load immediately and stay off. The only way it can be turned
215
back on is by manually pressing the front panel button.
217
.B test.battery.start, test.battery.stop
218
start/stop 10 second battery test
220
.B test.failure.start, test.failure.stop
221
start/stop "deep" battery test
227
load is on battery, including during tests
236
AC failure. Note that this refers to the AC input, and thus it is not
237
the same as "OB". An AC failure can occur at any time, for instance,
238
during a battery test, or when the UPS load is off.
256
the battery is depleted. When the UPS raises this flag, it
257
simultaneously switches off the load.
264
Here is an example for how \fBbelkinunv\fP should be used in a
265
computer's shutdown script. These commands should go in the very last
266
part of the shutdown script, after all file systems have been mounted
267
read\(hyonly, and just before the computer halts. Note that
268
\fBbelkinunv\fP must be installed in a directory which is still
269
readable at that point.
272
# NEAR END OF SHUTDOWN SCRIPT:
273
# if shutdown was caused by UPS, perform Belkin UPS workaround.
274
if [ \-f /etc/killpower ] ; then
275
echo "Waiting for AC power, or for UPS batteries to run out..."
276
/usr/bin/belkinunv \-x wait /dev/ttyS1
278
# we get here if the power came back on. Reboot.
279
echo "Power is back. Rebooting..."
284
And here is an example of how to use \fBbelkinunv\fP in the startup
285
script. These commands should go near the beginning of the startup
286
script, before any file systems are mounted read/write, and before any
287
file system integrity checks are done.
290
# NEAR BEGINNING OF STARTUP SCRIPT:
291
# if we are recovering from a power failure, wait for the UPS to
292
# charge to a comfortable level before writing anything to disk
293
if [ \-f /etc/killpower ] ; then
294
echo "Waiting for UPS battery charge to reach 60%..."
295
/usr/bin/belkinunv \-x wait=60 \-x nohang /dev/ttyS1
300
When used normally, \fBbelkinunv\fP forks into the background and its
301
diagnostics are the same as for all NUT drivers, see
304
When used with the \fB\-x wait\fP option, the exit status is normally
305
0. If the \fB\-x nohang\fP option has also been specified, an exit
306
status of 1 indicates that communication with the UPS was lost. If the
307
\fB\-x flash\fP option has been specified, an exit status of 2
308
indicates that the timed shutdown has failed.
311
This driver does not support any extra settings in \fBups.conf\fP(5).
314
.SS The documentation for the protocol used by this UPS:
315
belkin\(hyuniversal\(hyups.html
320
.SS Internet resources:
321
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/
325
Peter Selinger <selinger@users.sourceforge.net>
added
removed
man/belkinunv.8
