Imported Upstream version 2.6.0

docs/man/upscmd.txt

@@ -0,0 +1,96 @@
+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/