upsstats.cgi - Man Page

Web-based UPS status viewer

Synopsis

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.

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 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 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 upsd(8) servers that have been defined in your 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 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 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 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": "...")