Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
UPSCMD(8)			   NUT Manual			       UPSCMD(8)

NAME
     upscmd  -	Network  UPS Tools device/driver instant commands administration
     tool

SYNOPSIS
     upscmd -h

     upscmd -l ups

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

DESCRIPTION
     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  any-
     thing 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
     -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 de-
	 fault hostname is "localhost".

COMMON OPTIONS
     -h
	 Show the command-line help message.

     -D
	 Raise the debugging level. Use this option multiple times for more  de-
	 tails. Overrides the optional NUT_DEBUG_LEVEL environment variable.

     -V
	 Show  NUT version banner. More details may be available if you also ex-
	 port 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 vari-
	 able.

UNATTENDED MODE
     If you run this program inside a shell script or similar to invoke  a  com-
     mand,  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 pro-
     gram will hang.

     This is not necessary when displaying the list, as the username  and  pass-
     word 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 apcsmart(8) have built-in paranoia for the dangerous com-
     mands 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 sec-
     onds 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 upsd.users(5) has an  entry
     for  you,	and that the username you are using has permissions to SET vari-
     ables.

     upscmd without -w would somewhat confusingly show "OK"  meaning  just  that
     the  data server connection was established, and the server did not immedi-
     ately 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.

BUGS
     There is currently no way to tell the user when the driver requires confir-
     mation 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.

SEE ALSO
     upsd(8), upsrw(8)

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

Network UPS Tools 2.8.5.	   08/04/2026			       UPSCMD(8)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=upscmd&sektion=8&manpath=FreeBSD+Ports+15.1.quarterly>

home | help