Provided by: nut-server_2.7.2-4ubuntu1_i386 bug

NAME

       belkinunv - Driver for Belkin "Universal UPS" and compatible

NOTE

       This man page only documents the hardware-specific features of the
       belkin driver. For information about the core driver, see nutupsdrv(8).

SUPPORTED HARDWARE

       The belkinunv driver is known to work with the Belkin Universal UPS
       models F6C800-UNV and F6C120-UNV, 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-SER and so
       forth). However, some Belkin models, such as the Regulator Pro, are
       supported by the belkin(8) driver, and the Home Office models are
       supported using the genericups(8) driver with upstype=7.

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 -k option. Instead, the -x wait option is provided as a
       workaround.

       When called with the -x wait option, belkinunv 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-only, and just
       before the system would normally be halted: check /etc/killpower (or
       similar) to see if this shutdown was caused by upsmon(8), and if yes,
       call belkinunv -x wait. If AC power comes back on, belkinunv 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 -x wait
       option, this causes belkinunv 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 -x options are provided to fine-tune this behavior. See
       the options below for detailed descriptions. See the examples below for
       examples of how to use belkinunv in shutdown and startup scripts.

OPTIONS

       See also nutupsdrv(8) for generic options. Never use the -k option with
       this driver; it does not work properly.

       -x wait[=level]
           When this option is used, belkinunv 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 level is specified, it
           also waits until the battery charge reaches at least the given
           level in percent. Then, and only then, belkinunv exits. In
           addition, while belkinunv 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.

       -x nohang
           This option only has an effect when used in conjunction with the -x
           wait option. It causes belkinunv to exit if a connection with the
           UPS cannot be established or is lost, instead of retrying forever,
           which is the default behavior. The -x nohang 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).

       -x flash
           This option only has an effect when used in conjunction with the -x
           wait 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—2 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.

       -x silent
           This option only has an effect when used in conjunction with the -x
           wait option. It suppresses the status line which belkinunv would
           normally print.

       -x dumbterm
           This option only has an effect when used in conjunction with the -x
           wait option. It changes the way in which belkinunv 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 -x
           dumbterm option is given, each status update is written on a new
           line.

VARIABLES

       battery.charge, battery.runtime
           not supported by all hardware.

       battery.voltage, battery.voltage.nominal, input.frequency,
       input.frequency.nominal
           e.g. 60 for 60Hz

       input.sensitivity
           writable: normal/medium/low

       input.transfer.high
           writable: high transfer voltage point in V

       input.transfer.low
           writable: low transfer voltage point in V

       input.voltage, input.voltage.maximum, input.voltage.minimum,
       input.voltage.nominal, output.frequency, output.voltage,
       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.

       ups.firmware, ups.load, ups.model, ups.power.nominal
           e.g. 800 for an 800VA system

       ups.status
           a list of flags; see the status flags below.

       ups.temperature
           not supported by all hardware.

       ups.test.result, ups.delay.restart
           time to restart (read only)

       ups.delay.shutdown
           time to shutdown (read only). This is always a multiple of 60
           seconds.

       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.

COMMANDS

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

       reset.input.minmax
           Reset the variables input.voltage.minimum and
           input.voltage.maximum.

       shutdown.reboot
           Shut down load immediately for about 1—2 minutes.

       shutdown.reboot.graceful
           After 40 second delay, shut down load for about 1—2 minutes.

       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.

       test.battery.start, test.battery.stop
           Start/stop 10 second battery test.

       test.failure.start, test.failure.stop
           Start/stop "deep" battery test.

STATUS FLAGS

       OB
           load is on battery, including during tests

       OFF
           load is off

       OL
           load is online

       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.

       OVER
           overload

       OVERHEAT
           overheat

       COMMFAULT
           UPS fault

       LB
           low battery

       CHRG
           charging

       DEPLETED
           the battery is depleted. When the UPS raises this flag, it
           simultaneously switches off the load.

       RB
           replace battery

EXAMPLES

       Here is an example for how belkinunv 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-only,
       and just before the computer halts. Note that belkinunv must be
       installed in a directory which is still readable at that point.

           # 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

       And here is an example of how to use belkinunv 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.

           # 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

EXIT STATUS

       When used normally, belkinunv forks into the background and its
       diagnostics are the same as for all NUT drivers, see nutupsdrv(8).

       When used with the -x wait option, the exit status is normally 0. If
       the -x nohang option has also been specified, an exit status of 1
       indicates that communication with the UPS was lost. If the -x flash
       option has been specified, an exit status of 2 indicates that the timed
       shutdown has failed.

EXTRA ARGUMENTS

       This driver does not support any extra settings in ups.conf(5).

SEE ALSO

   The core driver:
       nutupsdrv(8)

   Internet resources:
       ·   The NUT (Network UPS Tools) home page:
           http://www.networkupstools.org/

       ·   The documentation for the protocol used by this UPS:
           belkin-universal-ups.html

AUTHOR

       Peter Selinger <selinger@users.sourceforge.net>