upscmd - Man Page

upscmd -h

upscmd -l ups

upscmd [-u username] [-p password] [-w] [-t <timeout>] ups command

upscmd allows you to invoke "instant commands" in your UPS hardware​. It sends commands via the server upsd(8) to your driver, which manages the hardware for you​. You must use credentials defined in upsd.users(5) file on that data server with appropriate permissions​.

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

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

-w

Wait for the completion of command execution by the driver and return its actual result from the device​. Note that this feature requires that both upsd(8) and the driver support TRACKING (NUT version 2​.8​.0 or higher), or it will otherwise fail​.

The command will also block until an actual result is provided from the driver, or the timeout is reached (see -t)​.

-t seconds

Set a timeout when using -w​. Defaults to 10 seconds​.

ups

Connect to this UPS​. The format is upsname[@hostname[:port]]​. The default hostname is "localhost"​.

-h

Show the command-line help message​.

-D

Raise the debugging level​. Use this option multiple times for more details​. Overrides the optional NUT_DEBUG_LEVEL environment variable​.

-V

Show NUT version banner​. More details may be available if you also export NUT_DEBUG_LEVEL=1 or greater verbosity level​.

-W secs

Set the timeout for initial network connections (by default they are indefinitely non-blocking, or until the system interrupts the attempt)​. Overrides the optional NUT_DEFAULT_CONNECT_TIMEOUT environment variable​.

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

Some drivers like 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​.

upscmd won’t work unless you provide a valid username and password​. If you get "access denied" errors, make sure that your upsd.users(5) has an entry for you, and that the username you are using has permissions to SET variables​.

upscmd without -w would somewhat confusingly show "OK" meaning just that the data server connection was established, and the server did not immediately reject the request due to e​.g​. unknown instant command name​. If you care to know the actual results, do use the -w (-t NUM) option(s) to wait for them​.

There is currently no way to tell the user when the driver requires confirmation to invoke a command such as load​.off​.

This is on the list of things to fix in the future, so don’t despair​. It involves magic cookies​.

upsd(8), upsrw(8)

al175(8), blazer_ser(8), blazer_usb(8), clone(8), clone-outlet(8), dummy-ups(8), failover(8), huawei-ups2000(8), meanwell_ntu(8), must_ep2000pro(8), nut(7), nutdrv_qx(8), NUT-Monitor(8), nutupsdrv(8), oneac(8), powervar_cx_ser(8), powervar_cx_usb(8), safenet(8), upsd(8), upslog(8), upsmon(8), upsrw(8), upsset.cgi(8).