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 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 linkman:upsd[8] from its linkman: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`.

COMMON OPTIONS
--------------

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

EXAMPLES
--------

To list all variables on an UPS named "myups" on a host
called "mybox", with linkman: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 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
linkman: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
--------

linkman:upslog[8],
linkman:ups.conf[5],
linkman:upsd[8]

Internet resources:
~~~~~~~~~~~~~~~~~~~

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