nut/docs/man/upscmd.txt

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.

Moreover, if you run this program inside a shell script or similar, you
should only consider using output from stdout, not stderr.

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/