upsc - Man Page

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

upsc [-j] ups [variable]

upsc [-j] -c ups

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

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

-L host

As above, list all UPS names configured at host, including their description 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 upsname[@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​.

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

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

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

upsc will either print a list of UPS names, a list of all supported variables 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​.

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

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

blazer_ser(8), blazer_usb(8), collectd.conf(5), dummy-ups(8), failover(8), genericups(8), meanwell_ntu(8), nut(7), nutdrv_qx(8), NUT-Monitor(8), nut-upower(8), nutupsdrv(8), tripplite_usb(8), upscli_init_default_connect_timeout(3), ups.conf(5), upsd(8), upslog(8), upsmon(8).