DMF Implementation notes - networkupstools/nut GitHub Wiki
Implementation notes
See also: DMF (Data Mapping File) spec and DMF Implementation status
For snmp-ups driver
General considerations
On the hard-coded mapping structures conversion to DMF
Some of the current hard-coded mapping structure are still using lot of "#define". This will make the conversion process harder, and was already tracked as NUT Github #153: Simplify the current SNMP data mapping
On the selection of a JSON library
A lot of care MUST be taken when selecting the JSON library that will be used for implementing DMF reading in NUT. This library MUST be:
- Mature: i.e. complete, well tested and widely adopted
- License compatible with NUT: preferably under GPLv2+, to make packagers and distributors life easier
- Widely available, which means:
- packaged for the main Linux distributions
- available as packages (better) or binaries for Windows and Mac OS X
Needed NUT source-code modifications
configure.ac and m4 macro
These will need to test for the JSON library availability. In case these are not available, an error should be notified and the configure process will disable the build of generic drivers. Question: do we still want to have a minimal implementation? For example, keep an IETF (RFC-1628) MIB for "snmp-ups" available hard-coded...
SNMP Manifest file and generation script
As presented in SNMP discovery / DMF matching strategy above, an SNMP manifest file will be needed!
This SNMP manifest file is a compilation of the information needed by the "snmp-ups" driver and "nut-scanner", to match the right DMF for a specific device. Otherwise, "snmp-ups" MIB autodetection (and also "nut-scanner") would first have to go through all DMFs prior to actually starting autodetection of which MIB DMF is to be used (too time consuming). A tool (gen_dmf_manifest script) that automatically extracts sysOIDs from DMF, and build this manifest, will be needed.
mib2nut_info_t aphel_genesisII = { "aphel_genesisII", EATON_APHEL_MIB_VERSION, "", APHEL1_OID_MODEL_NAME, eaton_aphel_genesisII_mib, APHEL1_SYSOID };
mib2nut_info_t aphel_revelation = { "aphel_revelation", EATON_APHEL_MIB_VERSION, "", APHEL2_OID_MODEL_NAME, eaton_aphel_revelation_mib, APHEL2_SYSOID };
mib2nut_info_t eaton_marlin = { "eaton_epdu", EATON_MARLIN_MIB_VERSION, "", EATON_MARLIN_OID_MODEL_NAME, eaton_marlin_mib, EATON_MARLIN_SYSOID };
mib2nut_info_t pulizzi_switched1 = { "pulizzi_switched1", EATON_PULIZZI_SW_MIB_VERSION, "", EATON_PULIZZI_SWITCHED1_SYSOID, eaton_pulizzi_switched_mib, EATON_PULIZZI_SWITCHED1_SYSOID };
mib2nut_info_t pulizzi_switched2 = { "pulizzi_switched2", EATON_PULIZZI_SW_MIB_VERSION, "", EATON_PULIZZI_SWITCHED1_SYSOID, eaton_pulizzi_switched_mib, EATON_PULIZZI_SWITCHED2_SYSOID };
The following mapping table will help the creation of the gen_dmf_manifest script. This script will have to be generic enough to address the different generic driver. Implementation can use whatever scripted language, such as Shell, Perl, Python...
Such implementation already exist:
- SNMP information extractor: automatically generates SNMP information for nut-scanner at pre-configure, build or distribution time.
- USB information extractor: automatically generates USB information for nut-scanner at build or distribution time.
Mapping table between DMF and mib2nut_info_t
This will be used to create the SNMP manifest file (snmp_manifest.dmf)
| DMF field | mib2nut_info_t | Comments |
|---|---|---|
| global->Identifier | mib_name | Identifier of the DMF |
| global->Version | mib_version | Version of the DMF |
| NULL | oid_pwr_status | To be discarded |
| DMF entry->device.model | oid_auto_check | Secondary matching data |
| ... | snmp_info | Pointer to the loaded DMF structure |
| global->sysObjectID | sysOID | Primary matching data |
| NULL | alarms_info | To be discarded |
| global->Protocol | N/A | Implicit, through generating structures for snmp-ups driver |
Reference: https://github.com/networkupstools/nut/blob/eaton-epdus/drivers/snmp-ups.h#L112
Mapping table between DMF and snmp_info_t
| DMF field | oid2info field | Comments |
|---|---|---|
| value lookup structure name | info_lkp_t name | |
| ProtocolValue | oid_value | OID value |
| NUTValue | info_value | INFO_* value |
| ProtocolConversionFunction | N/A | Doesn't exist yet for snmp-ups |
| NUTConversionFunction | N/A | Doesn't exist yet for snmp-ups |
Reference:https://github.com/networkupstools/nut/blob/eaton-epdus/drivers/snmp-ups.h#L102