upsstats.html - Man Page

This file, and a similarly structured upsstats-single​.html for certain use-cases, are used by upsstats.cgi(8) to generate NUT CGI status pages​. Certain commands are recognized, and will be replaced with various status elements on the fly​.

As a bit of a safety check, the file must start with @NUT_UPSSTATS_TEMPLATE@ command​.

For details about configuring some popular web servers to run NUT CGI programs, please see the upsset.conf(5) page​.

Commands can be placed anywhere on a line, but must start and end with @​.

Any extra characters before or after the commands will be passed through unchanged​.

It is allowed to use more than one command on a single line, as long as each command has its own start and end character​.

If you need to use the @ sign, use HTML entity @ to prevent it from being treated as a start character​.

Some commands begin blocks — sections of the template that will be included, excluded, or repeated depending on certain parameters​.

@IFSUPP ambient​.humidity@
@IFSUPP ambient​.temperature@
This UPS knows both ambient temperature and humidity​.
@ELSE@
@IFSUPP ambient​.humidity@
This UPS only knows ambient humidity​.
@ELSE@
@IFSUPP ambient​.temperature@
This UPS only knows ambient temperature​.
@ELSE@
This UPS knows nothing, how annoying​.
@ENDIF@

@NUT_UPSSTATS_TEMPLATE [args]@

The template file MUST start exactly with @NUT_UPSSTATS_TEMPLATE@ or @NUT_UPSSTATS_TEMPLATE Some text@ so that upsstats.cgi(8) is not coerced into showing arbitrary files​.

Currently the command and its arguments are otherwise ignored; templates shipped with NUT use the argument values "default" and "single" effectively as a comment for debugging/troubleshooting​.

@UPSSTATSPATH filename@

URI to the upsstats.cgi(8) program placed into HTML references​. Default is the program’s name, making it a link relative to the currently displayed page in the browser​.

May have to include the platform-specific program file name extension, like @UPSSTATSPATH upsstats​.cgi​.exe@

@UPSIMAGEPATH filename@

URI to the upsimage.cgi(8) program placed into HTML references​. Default is the program’s name, making it a link relative to the currently displayed page in the browser​.

May have to include the platform-specific program file name extension, like @UPSIMAGEPATH upsimage​.cgi​.exe@

@AMBTEMP@

Insert the ambient temperature in the current temperature scale​.

@DATE format@

Insert the current date and time​. The format string is passed to strftime, so almost anything is possible​. See strftime(3) for possible values​.

@DEGREES@

Insert the entity for degrees (°) and either C or F depending on the current temperature scale​.

@HOST@

Insert the designation of the host being monitored, like myups@localhost​.

@HOSTDESC@

Insert the host’s description from hosts.conf(5)​.

@HOSTLINK@

Insert a HTML link to upsstats.cgi(8) with the "host" variable set to the current UPS​. This is only useful within a FOREACHUPS block​.

@TREELINK [Link text]@

Insert a HTML link to upsstats.cgi(8) with the "host" variable set to the current UPS and "treemode" enabled to show all data points as an HTML page​. This is primarily useful within a FOREACHUPS block, but also as an upsstats-single​.html footer​. If some "Link text" is not provided, it defaults to "All data"​.

@TREELINK_JSON [Link text]@

Insert a HTML link to upsstats.cgi(8) with the "host" variable set to the current UPS and "treemode" enabled to show all data points as a JSON document​. This is primarily useful within a FOREACHUPS block, but also as an upsstats-single​.html footer​. If some "Link text" is not provided, it defaults to "JSON"​.

@IMG varname @

Insert an IMG SRC to upsimage.cgi(8) for one of these status variables:

battery​.charge

Battery charge — a percentage

battery​.voltage

The charge on the battery in volts

input​.frequency

Incoming utility frequency (Hz)

input​.voltage

Incoming utility voltage

input​.L1-L2​.voltage

Incoming voltage, L1-L2 (3phase)

input​.L2-L3​.voltage

Incoming voltage, L2-L3 (3phase)

input​.L3-L1​.voltage

Incoming voltage, L3-L1 (3phase)

output​.frequency

Outgoing utility frequency (Hz)

output​.voltage

Outgoing voltage (from the UPS)

output​.L1-L2​.voltage

Outgoing voltage, L1-L2 (3phase)

output​.L2-L3​.voltage

Outgoing voltage, L2-L3 (3phase)

output​.L3-L1​.voltage

Outgoing voltage, L3-L1 (3phase)

output​.L1​.power​.percent

UPS load, L1 (3phase)

output​.L2​.power​.percent

UPS load, L2 (3phase)

output​.L3​.power​.percent

UPS load, L3 (3phase)

ups​.load

UPS load — percentage

ups​.temperature

UPS temperature

extra is where you can put additional definitions​. Right now the valid definitions are colors for various parts of the bars drawn by upsimage.cgi(8)​. Possible color names are:

back_col

background color

scale_num_col

scale number color

summary_col

summary color (number at the bottom)

ok_zone_maj_col

major scale color for the normal ("ok") zone

ok_zone_min_col

minor scale color for the normal ("ok") zone

neutral_zone_maj_col

major scale color for the neutral zone

neutral_zone_min_col

minor scale color for the neutral zone

warn_zone_maj_col

major scale color for the warning zone

warn_zone_min_col

minor scale color for the warning zone

bar_col

the color of the bar in the middle

All colors are hex triplets — e​.g​. 0xff0000 is red, 0x00ff00 is green, and 0x0000ff is blue​.

Examples:

@IMG battery​.charge@
@IMG battery​.charge back_col=0xff00ff bar_col=0xaabbcc@
@IMG input​.voltage ok_zone_maj_col=0x123456@

@REFRESH@

Insert the META header magic for refreshing the page if that variable has been set by the browser​. This needs to be in the HEAD section of the page​.

@STATUS separator@, @STATUS@

Expand the abbreviations in the ups​.status variable — OL becomes "On line", OB becomes "On battery", and so on​. Reported values are separated by the specified optional separator (<br/> if not specified), which starts at the next character after the "STATUS<space>" (e​.g​. a @STATUS @ directive might be used to avoid any separation, or @STATUS @ to separate by spaces​.

@STATUSCOLOR@

Insert red, green, or yellow color triplets depending on the severity of the current UPS status​. Normal operations are green, warnings like voltage trim/boost or "off" are yellow, and other events like being on battery or having a low battery are red​.

@VAR varname@

Insert the current value of the status variable varname on the host being monitored, or "Not supported"​.

@RUNTIME@

Inserts the current runtime, in hh:mm:ss format​.

@TEMPC@

Use the Celsius scale for temperature data (default)​.

@TEMPF@

Use the Fahrenheit scale for temperature data​.

@UPSTEMP@

Insert the UPS temperature in the current scale​.

@BATTTEMP@

Insert the battery temperature in the current scale​.

@UTILITYCOLOR@

Obsoleted​. Use IFBETWEEN instead (see example in upsstats​.html)​.

@VERSION@

Insert the version number of the software​.

upsstats.cgi(8) will also open a file called upsstats-single​.html if you call it with host= set in the query URL​. That file uses the same rules and techniques as documented here​.

upsstats.cgi(8), upsimage.cgi(8)

hosts.conf(5), nut(7), upsstats.cgi(8).