This version of the page reflects NUT release v2.8.1 with codebase commited 4ba352d8f at 2023-10-31T21:46:20+01:00
Options, features and capabilities in current development (and future releases) are detailed on the main site and may differ from ones described here.
This document is defined by RFC 9271 published by IETF at https://www.rfc-editor.org/info/rfc9271 and is referenced as the document of record for the variable names and the instant commands used in the protocol described by the RFC.
On behalf of the RFC, this document records the names of variables
describing the abstracted state of an UPS or similar power distribution
device, and the instant commands sent to the UPS using command INSTCMD,
as used in commands and messages between the Attachment Daemon (the upsd
in case of NUT implementation of the standard) and the clients.
This document defines the standard names of NUT commands and variables
(not to be confused with device status data described in
the docs/new-drivers.txt in NUT source codebase).
Developers should use the names recorded here, with dstate functions and data mappings provided in NUT drivers for interactions with power devices.
If you need to express a state which cannot be described by any existing
name, please make a request to the NUT developers' mailing list for
definition and assignment of a new name. Clients using unrecorded names
risk breaking at a future update. If you wish to experiment with new
concepts before obtaining your requested variable name, you should use
a name of the form experimental.x.y for those states.
Put another way: if you make up a name that is not in this list and it gets into the source code tree, and then the NUT community comes up with a better name later, clients that already use the undocumented variable will break when it is eventually changed. An explicitly "experimental" data point is less surprising in this regard.
Similarly, some source files (drivers/*-mib.c and drivers/*-hid.c)
may mention data point names following the pattern of unmapped.x.y.
These are generated by helper scripts which walk the reports from SNMP
and USB HID devices, respectively scripts/subdriver/gen-snmp-subdriver.sh
and scripts/subdriver/gen-usbhid-subdriver.sh, and assign names based on
strings in those reports. The unmapped entries should not be exposed in
"production" builds of the NUT drivers. They are an aid for developers to
know that such entries are served by their device, so an existing standard
NUT name can be assigned for the concept (or new name negotiated with the
community), but are normally hidden with #if WITH_UNMAPPED_DATA_POINTS
clauses which can be enabled in custom NUT builds by use of
./configure --with-unmapped-data-points option.
In the descriptions, "opaque" means programs should not attempt to parse the value for that variable as it may vary greatly from one UPS (or similar device) to the next. These strings are best handled directly by the user.