DMF Implementation notes

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