328 lines
11 KiB
Groff
328 lines
11 KiB
Groff
|
.TH BELKINUNV 8 "Sun Dec 7 2003" "" "Network UPS Tools (NUT)"
|
||
|
|
.SH NAME
|
||
|
|
belkinunv \- Driver for Belkin "Universal UPS" and compatible
|
||
|
|
.SH NOTE
|
||
|
|
This man page only documents the hardware\(hyspecific features of the
|
||
|
|
belkin driver. For information about the core driver, see
|
||
|
|
\fBnutupsdrv\fP(8).
|
||
|
|
|
||
|
|
.SH SUPPORTED HARDWARE
|
||
|
|
The belkinunv driver is known to work with the Belkin Universal UPS
|
||
|
|
models F6C800\(hyUNV and F6C120\(hyUNV, and is expected to work with other
|
||
|
|
Belkin Universal UPS models. The driver only supports serial
|
||
|
|
communication, not USB.
|
||
|
|
|
||
|
|
The Trust UPS and older Belkin units are not supported by this driver,
|
||
|
|
and neither are the Belkin Home Office models (F6H500\(hySER and so
|
||
|
|
forth). However, some Belkin models, such as the Regulator Pro, are
|
||
|
|
supported by the \fBbelkin\fP(8) driver, and the Home Office models
|
||
|
|
are supported using the \fBgenericups\fP(8) driver with
|
||
|
|
\fIupstype=7\fP.
|
||
|
|
|
||
|
|
.SH SOFT SHUTDOWN WORKAROUND
|
||
|
|
One problem with the Belkin Universal UPS is that it cannot enter a
|
||
|
|
soft shutdown (shut down the load until AC power returns) unless the
|
||
|
|
batteries are completely depleted. Thus, one cannot just shut off the
|
||
|
|
UPS after operating system shutdown; it will not come back on when the
|
||
|
|
power comes back on. Therefore, the belkinunv driver should never be
|
||
|
|
used with the \fB\-k\fP option. Instead, the \fB\-x wait\fP option is
|
||
|
|
provided as a workaround.
|
||
|
|
|
||
|
|
When called with the \fB\-x wait\fP option, \fBbelkinunv\fP behaves as
|
||
|
|
a standalone program (i.e., it does not fork into the background). It
|
||
|
|
performs one simple task: it connects to the UPS, waits for AC power
|
||
|
|
to return, and then exits with status 0.
|
||
|
|
|
||
|
|
This is meant to be used in a shutdown script as follows: during a
|
||
|
|
shutdown, after all filesystems have been remounted read\(hyonly, and
|
||
|
|
just before the system would normally be halted: check /etc/killpower
|
||
|
|
(or similar) to see if this shutdown was caused by \fBupsmon\fP(8),
|
||
|
|
and if yes, call \fBbelkinunv \-x wait\fP. If AC power comes back on,
|
||
|
|
\fBbelkinunv\fP exits, and things should be arranged so that the
|
||
|
|
system reboots in this case. If AC power does not come back on, the
|
||
|
|
UPS will eventually run out of batteries, kill the computer's power
|
||
|
|
supply, and go into soft shutdown mode, which means everything will
|
||
|
|
reboot properly when the power returns. In either case, a deadlock is
|
||
|
|
avoided.
|
||
|
|
|
||
|
|
In addition, if an optional integer argument is given to the \fB\-x
|
||
|
|
wait\fP option, this causes \fBbelkinunv\fP to wait not only for AC
|
||
|
|
power to be present, but also for the battery charge to reach the
|
||
|
|
given level. I use this as part of my startup scripts, to ensure that
|
||
|
|
the batteries are sufficiently charged before the computer continues
|
||
|
|
booting. This should be put very early in the startup script, before
|
||
|
|
any filesystems are mounted read/write, and before any filesystem
|
||
|
|
checks are performed.
|
||
|
|
|
||
|
|
Several other \fB\-x\fP options are provided to fine\(hytune this
|
||
|
|
behavior. See OPTIONS below for detailed descriptions. See EXAMPLES
|
||
|
|
below for examples of how to use \fBbelkinunv\fP in shutdown and
|
||
|
|
startup scripts.
|
||
|
|
|
||
|
|
.SH OPTIONS
|
||
|
|
See also \fBnutupsdrv\fP(8) for generic options. Never use the
|
||
|
|
\fB\-k\fP option with this driver; it does not work properly.
|
||
|
|
.TP 12
|
||
|
|
.B \-x wait[=\fIlevel\fP]
|
||
|
|
When this option is used, \fBbelkinunv\fP does not fork into the
|
||
|
|
background, but behaves as a standalone program. It connects to the UPS and
|
||
|
|
waits until AC power is present. If \fIlevel\fP is specified, it also
|
||
|
|
waits until the battery charge reaches at least the given level in
|
||
|
|
percent. Then, and only then, \fBbelkinunv\fP exits. In addition,
|
||
|
|
while \fBbelkinunv\fP runs in this mode, it displays a status line
|
||
|
|
with information on the UPS status and battery level. This is intended
|
||
|
|
for use in the computer's shutdown and startup scripts, as described
|
||
|
|
under SOFT SHUTDOWN WORKAROUND above.
|
||
|
|
.TP
|
||
|
|
.B \-x nohang
|
||
|
|
This option only has an effect when used in conjunction with the \fB\-x
|
||
|
|
wait\fP option. It causes \fBbelkinunv\fP to exit if a connection with
|
||
|
|
the UPS cannot be established or is lost, instead of retrying forever,
|
||
|
|
which is the default behavior. The \fB\-x nohang\fP option should be
|
||
|
|
used in a startup
|
||
|
|
script, to ensure the computer remains bootable even if the UPS has
|
||
|
|
been disconnected during the power failure (for instance, you attached
|
||
|
|
your computer to a generator, carried it to a neighbor's house, or
|
||
|
|
whatever).
|
||
|
|
.TP
|
||
|
|
.B \-x flash
|
||
|
|
This option only has an effect when used in conjunction with the \fB\-x
|
||
|
|
wait\fP option. It causes the UPS load to be shut off for a short time
|
||
|
|
("flashed") just after the AC power has returned and the requested
|
||
|
|
battery level (if any) has been attained. This is useful if slaves are
|
||
|
|
attached to this UPS; the flash will cause all of them to reboot. Note
|
||
|
|
that, due to the design of the Belkin UPS hardware, the load shutdown lasts
|
||
|
|
ca. 1\(hy2 minutes; a shorter flash cannot be performed reliably. Also,
|
||
|
|
the computers will reboot at the scheduled time, on battery power if
|
||
|
|
necessary, even if AC power fails again in the meantime. This should
|
||
|
|
not be a problem, as your startup scripts can catch this situation.
|
||
|
|
.TP
|
||
|
|
.B \-x silent
|
||
|
|
This option only has an effect when used in conjunction with the \fB\-x
|
||
|
|
wait\fP option. It suppresses the status line which \fBbelkinunv\fP
|
||
|
|
would normally print.
|
||
|
|
.TP
|
||
|
|
.B \-x dumbterm
|
||
|
|
This option only has an effect when used in conjunction with the \fB\-x
|
||
|
|
wait\fP option. It changes the way in which \fBbelkinunv\fP prints its
|
||
|
|
status line. Normally, terminal control sequences are used to
|
||
|
|
overwrite the same line with new status information, each time the
|
||
|
|
status is updated. This may not work on all terminals. If the \fB\-x
|
||
|
|
dumbterm\fP option is given, each status update is written on a new
|
||
|
|
line.
|
||
|
|
.PD
|
||
|
|
|
||
|
|
.SH VARIABLES:
|
||
|
|
.TP 12
|
||
|
|
.B battery.charge
|
||
|
|
.TP
|
||
|
|
.B battery.runtime
|
||
|
|
not supported by all hardware.
|
||
|
|
.TP
|
||
|
|
.B battery.voltage
|
||
|
|
.TP
|
||
|
|
.B battery.voltage.nominal
|
||
|
|
.TP
|
||
|
|
.B driver.version.internal
|
||
|
|
.TP
|
||
|
|
.B input.frequency
|
||
|
|
.TP
|
||
|
|
.B input.frequency.nominal
|
||
|
|
e.g. 60 for 60Hz
|
||
|
|
.TP
|
||
|
|
.B input.sensitivity
|
||
|
|
writable: normal/medium/low
|
||
|
|
.TP
|
||
|
|
.B input.transfer.high
|
||
|
|
writable: high transfer voltage point in V
|
||
|
|
.TP
|
||
|
|
.B input.transfer.low
|
||
|
|
writable: low transfer voltage point in V
|
||
|
|
.TP
|
||
|
|
.B input.voltage
|
||
|
|
.TP
|
||
|
|
.B input.voltage.maximum
|
||
|
|
.TP
|
||
|
|
.B input.voltage.minimum
|
||
|
|
.TP
|
||
|
|
.B input.voltage.nominal
|
||
|
|
.TP
|
||
|
|
.B output.frequency
|
||
|
|
.TP
|
||
|
|
.B output.voltage
|
||
|
|
.TP
|
||
|
|
.B ups.beeper.status
|
||
|
|
writable. Values: enabled/disabled/muted. This variable controls the
|
||
|
|
state of the panel beeper. Enabled means sound when the alarm is
|
||
|
|
present, disabled means never sound, and muted means the sound is
|
||
|
|
temporarily disabled until the alarm would normally stop sounding. In
|
||
|
|
the muted state, the beeper is automatically turned back on at the
|
||
|
|
next event (AC failure, battery test, etc). Also, the beeper can't be
|
||
|
|
turned off during a critical event (low battery). Note that not all
|
||
|
|
UPS models support the "disabled" state.
|
||
|
|
.TP
|
||
|
|
.B ups.firmware
|
||
|
|
.TP
|
||
|
|
.B ups.load
|
||
|
|
.TP
|
||
|
|
.B ups.model
|
||
|
|
.TP
|
||
|
|
.B ups.power.nominal
|
||
|
|
e.g. 800 for an 800VA system
|
||
|
|
.TP
|
||
|
|
.B ups.status
|
||
|
|
a list of flags; see STATUS FLAGS below.
|
||
|
|
.TP
|
||
|
|
.B ups.temperature
|
||
|
|
not supported by all hardware.
|
||
|
|
.TP
|
||
|
|
.B ups.test.result
|
||
|
|
.TP
|
||
|
|
.B ups.delay.restart
|
||
|
|
time to restart (read only)
|
||
|
|
.TP
|
||
|
|
.B ups.delay.shutdown
|
||
|
|
time to shutdown (read only). This is always a multiple of 60 seconds.
|
||
|
|
.TP
|
||
|
|
.B ups.type
|
||
|
|
ONLINE/OFFLINE/LINEINT. This describes the basic layout of this UPS
|
||
|
|
(for GUI clients which want to draw an animated picture of power
|
||
|
|
flow). An offline UPS has a direct connection from AC input to AC
|
||
|
|
output, and also a connection from AC input to the battery, and from
|
||
|
|
the battery to AC output. An online UPS lacks the direct connection
|
||
|
|
from AC input to AC output, whereas a line interactive UPS lacks the
|
||
|
|
connection from AC input to the battery.
|
||
|
|
.PD
|
||
|
|
|
||
|
|
.SH COMMANDS:
|
||
|
|
.TP 12
|
||
|
|
.B beeper.enable, beeper.disable, beeper.mute
|
||
|
|
enable, disable or mute the panel beeper. Note that if the beeper is
|
||
|
|
muted, it is automatically turned back on at the next event (AC failure,
|
||
|
|
battery test, etc). Also, the beeper can't be turned muted during a
|
||
|
|
critical event (low battery).
|
||
|
|
.TP
|
||
|
|
.B reset.input.minmax
|
||
|
|
reset the variables \fBinput.voltage.minimum\fP and
|
||
|
|
\fBinput.voltage.maximum\fP.
|
||
|
|
.TP
|
||
|
|
.B shutdown.reboot
|
||
|
|
shut down load immediately for ca. 1\(hy2 minutes
|
||
|
|
.TP
|
||
|
|
.B shutdown.reboot.graceful
|
||
|
|
after 40 second delay, shut down load for ca. 1\(hy2 minutes
|
||
|
|
.TP
|
||
|
|
.B shutdown.stayoff
|
||
|
|
shut down load immediately and stay off. The only way it can be turned
|
||
|
|
back on is by manually pressing the front panel button.
|
||
|
|
.TP
|
||
|
|
.B test.battery.start, test.battery.stop
|
||
|
|
start/stop 10 second battery test
|
||
|
|
.TP
|
||
|
|
.B test.failure.start, test.failure.stop
|
||
|
|
start/stop "deep" battery test
|
||
|
|
.PD
|
||
|
|
|
||
|
|
.SH STATUS FLAGS:
|
||
|
|
.TP 12
|
||
|
|
.B OB
|
||
|
|
load is on battery, including during tests
|
||
|
|
.TP
|
||
|
|
.B OFF
|
||
|
|
load is off
|
||
|
|
.TP
|
||
|
|
.B OL
|
||
|
|
load is online
|
||
|
|
.TP
|
||
|
|
.B ACFAIL
|
||
|
|
AC failure. Note that this refers to the AC input, and thus it is not
|
||
|
|
the same as "OB". An AC failure can occur at any time, for instance,
|
||
|
|
during a battery test, or when the UPS load is off.
|
||
|
|
.TP
|
||
|
|
.B OVER
|
||
|
|
overload
|
||
|
|
.TP
|
||
|
|
.B OVERHEAT
|
||
|
|
overheat
|
||
|
|
.TP
|
||
|
|
.B COMMFAULT
|
||
|
|
UPS fault
|
||
|
|
.TP
|
||
|
|
.B LB
|
||
|
|
low battery
|
||
|
|
.TP
|
||
|
|
.B CHRG
|
||
|
|
charging
|
||
|
|
.TP
|
||
|
|
.B DEPLETED
|
||
|
|
the battery is depleted. When the UPS raises this flag, it
|
||
|
|
simultaneously switches off the load.
|
||
|
|
.TP
|
||
|
|
.B RB
|
||
|
|
replace battery
|
||
|
|
.PD
|
||
|
|
.SH EXAMPLES
|
||
|
|
|
||
|
|
Here is an example for how \fBbelkinunv\fP should be used in a
|
||
|
|
computer's shutdown script. These commands should go in the very last
|
||
|
|
part of the shutdown script, after all file systems have been mounted
|
||
|
|
read\(hyonly, and just before the computer halts. Note that
|
||
|
|
\fBbelkinunv\fP must be installed in a directory which is still
|
||
|
|
readable at that point.
|
||
|
|
|
||
|
|
.nf
|
||
|
|
# NEAR END OF SHUTDOWN SCRIPT:
|
||
|
|
# if shutdown was caused by UPS, perform Belkin UPS workaround.
|
||
|
|
if [ \-f /etc/killpower ] ; then
|
||
|
|
echo "Waiting for AC power, or for UPS batteries to run out..."
|
||
|
|
/usr/bin/belkinunv \-x wait /dev/ttyS1
|
||
|
|
|
||
|
|
# we get here if the power came back on. Reboot.
|
||
|
|
echo "Power is back. Rebooting..."
|
||
|
|
reboot
|
||
|
|
fi
|
||
|
|
.fi
|
||
|
|
|
||
|
|
And here is an example of how to use \fBbelkinunv\fP in the startup
|
||
|
|
script. These commands should go near the beginning of the startup
|
||
|
|
script, before any file systems are mounted read/write, and before any
|
||
|
|
file system integrity checks are done.
|
||
|
|
|
||
|
|
.nf
|
||
|
|
# NEAR BEGINNING OF STARTUP SCRIPT:
|
||
|
|
# if we are recovering from a power failure, wait for the UPS to
|
||
|
|
# charge to a comfortable level before writing anything to disk
|
||
|
|
if [ \-f /etc/killpower ] ; then
|
||
|
|
echo "Waiting for UPS battery charge to reach 60%..."
|
||
|
|
/usr/bin/belkinunv \-x wait=60 \-x nohang /dev/ttyS1
|
||
|
|
fi
|
||
|
|
.fi
|
||
|
|
.SH EXIT STATUS
|
||
|
|
|
||
|
|
When used normally, \fBbelkinunv\fP forks into the background and its
|
||
|
|
diagnostics are the same as for all NUT drivers, see
|
||
|
|
\fBnutupsdrv\fP(8).
|
||
|
|
|
||
|
|
When used with the \fB\-x wait\fP option, the exit status is normally
|
||
|
|
0. If the \fB\-x nohang\fP option has also been specified, an exit
|
||
|
|
status of 1 indicates that communication with the UPS was lost. If the
|
||
|
|
\fB\-x flash\fP option has been specified, an exit status of 2
|
||
|
|
indicates that the timed shutdown has failed.
|
||
|
|
.SH EXTRA ARGUMENTS
|
||
|
|
|
||
|
|
This driver does not support any extra settings in \fBups.conf\fP(5).
|
||
|
|
.SH SEE ALSO
|
||
|
|
|
||
|
|
.SS The documentation for the protocol used by this UPS:
|
||
|
|
belkin\(hyuniversal\(hyups.html
|
||
|
|
|
||
|
|
.SS The core driver:
|
||
|
|
\fBnutupsdrv\fP(8)
|
||
|
|
|
||
|
|
.SS Internet resources:
|
||
|
|
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/
|
||
|
|
|
||
|
|
.SH AUTHOR
|
||
|
|
|
||
|
|
Peter Selinger <selinger@users.sourceforge.net>
|