Support new NUT vocabulary in nutconf

[jimklimov]

Follow up from #2290 and #2283 which provided initial integration of nutconf related codebase from 2013 into modern NUT of 2024.

To complete a milestone in finite time, this effort had to cut some corners - including not updating the list of supported configuration key words which were added since 2013 (approx. NUT v2.6.5).

Probably augeas lenses files (and their difference over time) would help identify the missing keywords. Also a good moment to make sure those know all the needed words :)

UPDATE:

Bookmarking a helpful spell to see each driver option key word in its documentation and source context (remove && continue to see EVERYTHING including keywords covered by the nutconf class):

:; ( cd scripts/augeas && python ./gen-nutupsconf-aug.py.in )

:; grep -E '[=|] "' scripts/augeas/nutupsconf.aug.in | awk '{print $NF}' | tr -d '"' \
  | while read O ; do echo "=== $O :" ; \
    grep -w '"'"$O"'"' ./include/nutconf.hpp && continue ; \
    grep -A10 -w "$O" ./docs/man/*.txt || echo '!!! UNDOCUMENTED !!!' ; \
    echo "-----"; grep -A10 -w '"'"$O"'"' ./drivers/*.{c,h} || echo '!!! NOT USED IN CODE !!!' ; \
    echo "-----"; echo "" ; done | less

UPDATE:

Notification keywords and obsolete terminology will be addressed shortly.

Note that structured configuration files (with sections) are handled by GenericConfiguration descendants and for all/most key words there are getters/setters in the classes, while information is stored in a nested map.

Conversely, unstructured key-value(s) configs like class UpsmonConfiguration : public Serialisable with variables for configurable items and enums to constrain some of the choices, and related class UpsmonConfigParser : public NutConfigParser for generic R/W, are handled by common/nutconf.cpp and common/nutwriter.cpp (as serialization of an object like UpsmonConfiguration::Monitor into a string). See e.g. common/nutconf.cpp => UpsmonConfigParser::onParseDirective for keyword vocabulary, or common/nutconf.cpp => UpsmonConfiguration::NotifyTypeFromString() vs. common/nutwriter.cpp => NotifyFlagsStrings.initFlagStrings() for enum to string (and the other way) conversions.

One big wad of changes to address later is in include/nutconf.hpp, namely class UpsConfiguration which lists all words that can appear in ups.conf - and this area saw progress over the decade since nutconf was initially written. Similarly for UpsdUsersConfiguration - but not likely much changed there.

In many daemon configs, a debug_min would be useful.

Another wad is tools/nutconf/nutconf-cli with nut-scanner related options (add simulated devices, revise options for SNMP auth, and others). Note that the tool directly uses libnutscan methods, e.g. does not call the CLI tool as a separate program. Maybe needs refinement to use device names with type, e.g. "nutdev-snmp-1" not "nutdev-1", like the CLI tool does - see #2247.

Generally for NUT daemons it can help to compare man pages and/or sample configs between v2.6.5 tag and current code-base.

A script would be helpful to extract keywords expected by C++ (getters/setters) and defined by ADD_VAR/ADD_FLAG in driver sources, to either generate a C++ source file (e.g. to #include into the build) or at least to compare for sanity-checking (but maintain manually to keep API stable).

As a point for comparison, augeas lens files are generated during each build by parsing NUT sources for keywords.