'\" t
.\"     Title: upsstats.cgi
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 06/21/2026
.\"    Manual: NUT Manual
.\"    Source: Network UPS Tools 2.8.5
.\"  Language: English
.\"
.TH "UPSSTATS\&.CGI" "8" "06/21/2026" "Network UPS Tools 2\&.8\&.5" "NUT Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
upsstats.cgi \- Web\-based UPS status viewer
.SH "SYNOPSIS"
.sp
\fBupsstats\&.cgi\fR
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.sp
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\&.
.sp .5v
.RE
.SH "DESCRIPTION"
.sp
\fBupsstats\&.cgi\fR 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\&.
.sp
These templates can also include references to \fBupsimage.cgi\fR(8) for graphical displays of battery charge levels, voltage readings, and the UPS load\&.
.sp
For details about configuring some popular web servers to run NUT CGI programs, please see the \fBupsset.conf\fR(5) page\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.sp
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)\&.
.sp .5v
.RE
.SH "ACCESS CONTROL"
.sp
upsstats will only talk to \fBupsd\fR(8) servers that have been defined in your \fBhosts.conf\fR(5)\&. If it complains that "Access to that host is not authorized", check that file first\&.
.SH "TEMPLATES"
.sp
The web page that is displayed is actually a template containing commands to upsstats which are replaced by status information\&.
.sp
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 \fBhosts.conf\fR(5)\&.
.sp
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 \fBhosts.conf\fR(5)\&.
.sp
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\&.
.sp
.if n \{\
.RS 4
.\}
.nf
\&.\&.\&./cgi\-bin/upsstats\&.cgi?template_single=custom\-s\&.html&template_list=custom\-l\&.html
.fi
.if n \{\
.RE
.\}
.sp
The format of these files, including the possible commands, is documented in \fBupsstats.html\fR(5)\&.
.SH "JSON OUTPUT"
.sp
In addition to processing HTML templates, \fBupsstats\&.cgi\fR can be invoked as a JSON API by adding the \fBjson\fR parameter to the query string (e\&.g\&., \fB?json\fR or \fB&json\fR)\&.
.sp
When this parameter is present, the CGI script bypasses all HTML template parsing and instead returns a JSON object\&.
.sp
The structure of the JSON output depends on whether the \fBhost\fR parameter is also provided:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBMulti\-host (Default):\fR
If no
\fBhost\fR
parameter is specified, the script returns a single JSON object containing an
\fB"devices"\fR
key\&. This key holds an array, with each element in the array being a JSON object representing a monitored UPS\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBSingle\-host Mode:\fR
If a
\fBhost\fR
parameter is provided (e\&.g\&.,
\fB?host=\fR\fBmyups@localhost\fR\fB&json\fR), the script returns a single JSON object for that UPS (it will not be wrapped in an "devices" array)\&.
.RE
.sp
In both modes, each UPS object includes:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBhost\fR: The UPS identifier (e\&.g\&., "myups@localhost")
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBdesc\fR: The host description from
hosts\&.conf
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBstatus_raw\fR: The raw status string (e\&.g\&., "OL")
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBstatus_parsed\fR: An array of human\-readable status strings (e\&.g\&., ["Online"])
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBvars\fR: An object containing the full tree of all available variables for that UPS (e\&.g\&., "battery\&.charge": "100", "ups\&.model": "\&...")
.RE
.SH "FILES"
.sp
\fBhosts.conf\fR(5), \fBupsstats.html\fR(5), upsstats\-single\&.html
.SH "SEE ALSO"
.sp
\fBupsimage.cgi\fR(8)
.SS "Internet resources:"
.sp
The NUT (Network UPS Tools) home page: https://www\&.networkupstools\&.org/historic/v2\&.8\&.5/