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

FreeBSD Manual Pages

  
 
  

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

NAME
     upsc - Lightweight read-only NUT client

SYNOPSIS
     upsc [-j] -l | -L [host]

     upsc [-j] ups [variable]

     upsc [-j] -c ups

DESCRIPTION
     upsc  is provided as a quick way to poll the status of a UPS server. It can
     be used inside shell scripts and other programs  that  need  UPS  data  but
     don't want to include the full interface.

OPTIONS
     -j
	 Output  the  results in JSON format. This will bypass the standard text
	 output and print a JSON object to stdout. The structure of the JSON de-
	 pends on the mode:

	 `upsc -j -l`: Returns a JSON array of UPS names.
	 `upsc -j -L`: Returns a JSON object mapping UPS names to their descriptions.
	 `upsc -j <ups>`: Returns a JSON object of all variables and their values.
	 `upsc -j <ups> <variable>`: Returns a single JSON string (the value).
	 `upsc -j -c <ups>`: Returns a JSON array of client addresses.

     -l host
	 List all UPS names configured at host, one name per line. The	hostname
	 defaults to "localhost". You may optionally add a colon and a port num-
	 ber.

     -L host
	 As  above,  list  all UPS names configured at host, including their de-
	 scription provided by the remote  upsd(8)  from  its  ups.conf(5).  The
	 hostname  defaults to "localhost". You may optionally add a colon and a
	 port number to override the default port.

     -c ups
	 Lists each client connected on ups, one name per line.

     ups
	 Display the status of that UPS. The  format  for  this  option  is  up-
	 sname[@hostname[:port]]. The default hostname is "localhost".

     variable
	 Display the value of this variable only. By default, upsc retrieves the
	 list of variables from the server and then displays the value for each.
	 This  option  may be useful in shell scripts to save an additional pipe
	 into grep.

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.

EXAMPLES
     To list all variables on an UPS named "myups" on  a  host	called	"mybox",
     with upsd(8) running on port 1234:

	 :; upsc myups@mybox:1234
	 battery.charge: 100.0
	 battery.voltage: 13.9
	 battery.voltage.nominal: 13.6
	 . . .

     To retrieve all variables for "myups" as a JSON object:

	 :; upsc -j myups@mybox:1234
	 {
	   "battery.charge": "100.0",
	   "battery.voltage": "13.9",
	   "battery.voltage.nominal": "13.6",
	   ...
	 }

     To list the UPSes configured on this system, along with their descriptions:

	 :; upsc -L
	 apc: Back-UPS 500
	 ppro2: Patriot Pro II

     To retrieve the status for all UPSes connected to mybox, using Bourne-shell
     syntax:

	 :; for UPS in `upsc -l mybox:1234`; do
	     upsc $UPS ups.status
	 done

     To list clients connected on "myups":

	 :; upsc -c myups
	 127.0.0.1
	 ::1
	 192.168.1.2

SCRIPTED MODE
     If you run this program inside a shell script or similar to get the list of
     devices  and  variables, you should only consider using output from stdout,
     not stderr.

DIAGNOSTICS
     upsc will either print a list of UPS names, a list of all	supported  vari-
     ables  and  their values on the UPS, or an error message. If you do receive
     an error, make sure you have specified a valid UPS  on  the  command  line,
     that upsd(8) is really running on the other host, and that no firewalls are
     blocking you.

HISTORY
     Earlier  versions of this program used the upsfetch library and UDP sockets
     to talk to upsd. This version of upsc uses the new upsclient library, which
     only talks TCP. This is why upsct no longer exists.

SEE ALSO
     upslog(8), ups.conf(5), upsd(8)

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

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

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

home | help