nut-debian/docs/man/upscmd.txt
2011-01-26 10:35:08 +01:00

97 lines
2.7 KiB
Plaintext

UPSCMD(8)
=========
NAME
----
upscmd - UPS administration program for instant commands
SYNOPSIS
--------
*upscmd* -h
*upscmd* -l 'ups'
*upscmd* [-u 'username'] [-p 'password'] 'ups' 'command'
DESCRIPTION
-----------
*upscmd* allows you to invoke "instant commands" in your UPS hardware.
Not all hardware supports this, so check the list with -l to see if anything
will work on your equipment.
On hardware that supports it, you can use this program to start and stop
battery tests, invoke a front panel test (beep!), turn the load on or off,
and more.
OPTIONS
-------
*-h*::
Display the help message.
*-l* 'ups'::
Show the list of supported instant commands on that UPS. Some hardware
may not support any of them.
*-u* 'username'::
Set the username for the connection to the server. This is optional, and
you will be prompted for this when invoking a command if -u is not used.
*-p* 'password'::
Set the password to authenticate to the server. This is also optional
like -u, and you will be prompted for it if necessary.
'ups'::
Connect to this UPS. The format is `upsname[@hostname[:port]]`. The default
hostname is "localhost".
UNATTENDED MODE
---------------
If you run this program inside a shell script or similar to invoke
a command, you will need to specify all of the information on the command
line. This means using -u and -p. Otherwise it will put up a prompt and
your program will hang.
This is not necessary when displaying the list, as the username and
password are not required for read-only mode.
DANGEROUS COMMANDS
------------------
Some drivers like linkman:apcsmart[8] have built-in paranoia for the
dangerous commands like `load.off`. To make them actually turn off the
load, you will have to send the command twice within a short window.
That is, you will have to send it once, then send it again after 3
seconds elapse but before 15 seconds pass.
This paranoia is entirely defined within the driver. upsd and upscmd have
no control over the timing.
DIAGNOSTICS
-----------
upscmd won't work unless you provide a valid username and password. If
you get "access denied" errors, make sure that your linkman:upsd.users[5] has
an entry for you, and that the username you are using has permissions to
SET variables.
BUGS
----
There is currently no way to tell the user when the driver requires
confirmation to invoke a command such as `load.off`. Similarly, there is
not yet a way to tell the user if a command succeeds or fails.
This is on the list of things to fix in the future, so don't despair.
It involves magic cookies.
SEE ALSO
--------
linkman:upsd[8], linkman:upsrw[8]
INTERNET RESOURCES
------------------
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/