UPSSTATS.CGI(8)
===============

NAME
----

upsstats.cgi - Web-based UPS status viewer

SYNOPSIS
--------

*upsstats.cgi*

NOTE: As a CGI program, this should be invoked through your web server.
If you run it from the command line, it will either complain about
unauthorized access or spew a bunch of HTML at you.

DESCRIPTION
-----------

*upsstats.cgi*
uses template files to build web pages containing status information
from UPS hardware.  It can repeat sections of those template files to
monitor several devices simultaneously, or focus on a single UPS.

These templates can also include references to linkman:upsimage.cgi[8]
for graphical displays of battery charge levels, voltage readings, and
the UPS load.

ACCESS CONTROL
--------------

upsstats will only talk to linkman:upsd[8] servers that have been defined
in your linkman:hosts.conf[5].  If it complains that "Access to that host
is not authorized", check that file first.

TEMPLATES
---------

The web page that is displayed is actually a template containing
commands to `upsstats` which are replaced by status information.

The default file used for the overview of devices is `upsstats.html`.

When monitoring a single UPS, the file displayed is
`upsstats-single.html`.

The format of these files, including the possible commands, is
documented in linkman:upsstats.html[5].

JSON OUTPUT
-----------

In addition to processing HTML templates, *upsstats.cgi* can be
invoked as a JSON API by adding the *json* parameter to the
query string (e.g., *?json* or *&json*).

When this parameter is present, the CGI script bypasses all HTML
template parsing and instead returns a JSON object.

The structure of the JSON output depends on whether the *host*
parameter is also provided:

* *Multi-host (Default):*
    If no *host* parameter is specified, the script returns a
    single JSON object containing an *"devices"* key. This key
    holds an array, with each element in the array being a JSON
    object representing a monitored UPS.

* *Single-host Mode:*
    If a *host* parameter is provided (e.g.,
    *?host=myups@localhost&json*), the script returns a single
    JSON object for that UPS (it will not be wrapped in an
    "devices" array).

In both modes, each UPS object includes:

* *host*: The UPS identifier (e.g., "myups@localhost")
* *desc*: The host description from ``hosts.conf``
* *status_raw*: The raw status string (e.g., "OL")
* *status_parsed*: An array of human-readable status strings
  (e.g., ["Online"])
* *vars*: An object containing the full tree of all available
  variables for that UPS (e.g., "battery.charge": "100",
  "ups.model": "...")

FILES
-----

linkman:hosts.conf[5], linkman:upsstats.html[5], upsstats-single.html

SEE ALSO
--------

linkman:upsimage.cgi[8]

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

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