UPSSTATS.CGI(8)

📦
version 2.8.5 · 17 versions
, in fedora 43, fedora 44

✨ UPSSTATS.CGI(8) — the NUT manual, but make it cute ✨

okay bestie, welcome to upsstats.cgi(8) from the NUT Manual 💖 this is the page that tells you all about the little CGI script that serves up your UPS status like it's a feed, and honestly? she's iconic.

🌸 NAME 🌸

upsstats.cgi — a web-based UPS status viewer, no cap 👑

🎀 SYNOPSIS 🎀

upsstats.cgi
Note, and this is important: as a CGI program, this is meant to be invoked through your web server. If you run it straight from the command line, it will either complain about unauthorized access or spew a bunch of HTML at you. Like, pick a struggle. 😭 It's giving "I only work at parties."

💅 DESCRIPTION 💅

upsstats.cgi is a read-only NUT client, and the way she works is so smart — she uses template files to build web pages stuffed with status information from UPS hardware. Periodt.

She can repeat sections of those template files to monitor several devices at the same time, or she can lock in and focus on a single UPS. Both vibes are valid. ✨

These templates can also include references to upsimage.cgi(8) for graphical displays of battery charge levels, voltage readings, and the UPS load. Art. 🎨

Wanna know how to configure some popular web servers to run NUT CGI programs? The details live over in the upsset.conf(5) page. Go read her. 🫶

Note bestie: on platforms that require 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). She's just built different on those platforms, okay? 🙈

🔐 ACCESS CONTROL 🔐

upsstats will only talk to upsd(8) servers that have been defined in your hosts.conf(5). She does not do strangers, she does not do mystery hosts. 🚫

If she complains that "Access to that host is not authorized", check that file first. That's the vibe check and you failed it, sorry. 💀

🦋 TEMPLATES 🦋

So the web page that actually gets displayed? It's not a plain page — it's a template containing commands to upsstats which get replaced by status information. Sneaky. Iconic. Main character energy. ✨

The default file used for the overview of devices is upsstats.html. An alternate template may be provided by the &template_list=... CGI query option — and heads up, the relevant file must be allowed via the CUSTOM_TEMPLATE_LIST option in hosts.conf(5). Permission slip required. 🎀

When monitoring a single UPS, the file displayed is upsstats-single.html. An alternate template may be provided by the &template_single=... CGI query option — and again, the relevant file must be allowed via the CUSTOM_TEMPLATE_SINGLE option in hosts.conf(5). Rules are rules. 💅

Alternate templates must be structured similarly to the default ones, located in the same directory, and contain .htm in the file name. You can specify them 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). iykyk 📖

🌈 JSON OUTPUT 🌈

Plot twist, bestie — 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). Yes, she contains multitudes. 👑

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

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 🍓

⭐ SEE ALSO ⭐

🌐 Internet resources: 🌐

and that's the whole page bestie, you ate it, no crumbs 💖 this was Network UPS Tools 2.8.5, dated 10/07/2026 — go forth and monitor those UPSes, you absolute legend 🫶✨👑

📦 where this page comes from