C. NUT command and variable naming scheme

RFC 9271 Recording Document

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.