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* is a read-only NUT client which
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.

For details about configuring some popular web servers to run NUT CGI
programs, please see the linkman:upsset.conf[5] page.

NOTE: On platforms with required program file name extensions, like Windows,
you may have to use e.g. a `*.cgi.exe` extension for the programs in HTML
template files (`UPSSTATSPATH`, `UPSIMAGEPATH`).

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`.
An alternate template may be provided by `&template_list=...` CGI
query option; relevant file must be allowed via `CUSTOM_TEMPLATE_LIST`
option in linkman:hosts.conf[5].

When monitoring a single UPS, the file displayed is
`upsstats-single.html`.
An alternate template may be provided by `&template_single=...` CGI
query option; relevant file must be allowed via `CUSTOM_TEMPLATE_SINGLE`
option in linkman:hosts.conf[5].

Alternate templates must be structured similarly to default ones,
located in the same directory, and contain `.htm` in the file name.
You can specify in the query string part of the URI (for example,
in your local `index.html` and/or added cells of `header.html`) as e.g.

------
.../cgi-bin/upsstats.cgi?template_single=custom-s.html&template_list=custom-l.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/
