How-To Export and Read Enterprise Element Definitions
What is RFC 5610?
RFC 5610 provides a mechanism to export full type information for Information Elements from the IPFIX Information Model. Libfixbuf version 1.4 and later provides API functions to create IPFIX Option Template/Records that can encode the full set of properties for the definition of an Information Element in order for a Collecting Process to be able to know how to decode data that contains enterprise-specific Information Elements.
RFC 5610 Exporters
To create a new enterprise-specific Information Element, the Exporting Process should define a new information element using the FB_IE_INIT_FULL() macro to provide the name, private enterprise number, id, length, description, data type, and units of the information element. The Information Elements should then be added to the Information Model using fbInfoModelAddElement() or fbInfoModelAddElementArray(). Alternatively, a file or a string containing an XML registry that describes Information Elements may be parsed and loaded into the Information Model using fbInfoModelReadXMLFile() or fbInfoModelReadXMLData().
Once an enterprise-specific information element exists, there are two ways to export that information. The simplest way is to configure automated enterprise-specific information element information export. This is done by calling fbSessionSetMetadataExportElements() with the enabled parameter set to TRUE. Once this has been set, the full set of information elements in the information model that have a non-zero Private Enterprise Number will be exported every time template records are exported (fbSessionExportTemplates()).
The other option is to export the information element options records manually. An information element options template can then be created using fbInfoElementAllocTypeTemplate(). This creates an option template that contains all of the necessary properties to define an Information Element:
- privateEnterpriseNumber
- informationElementId
- informationElementDataType
- informationElementSemantics
- informationElementUnits
- informationElementRangeBegin
- informationElementRangeEnd
- informationElementName
- informationElementDescription
Then the template can be added to the session using fbSessionAddTemplate(). You will need to add it twice, once as an internal template, and once as an external template. Create the exporter and fbuf as described above for the necessary mode of transport. Then, to write out an information element options record, use fbInfoElementWriteOptionsRecord(), using the template IDs returned by the fbSessionAddTemplate() calls as the internal and export template IDs, passing it a pointer to the information element you want to export. For example:
The Options Record will automatically be appended to the fbuf and will be sent upon calling fBufEmit().
RFC 5610 - Collector Usage
In order to collect the above Options records, the collecting process may use fBufSetAutomaticElementInsert() after creating an fBuf to automatically insert any information elements into the Information Model. For security reasons, libfixbuf does not add elements whose informationElementName already exists in the model, whose (privateEnterpriseNumber, informationElementId) pair already exists in the model, or whose privateEnterpriseNumber is 0 or FB_IE_PEN_REVERSE. libfixbuf also rejects elements whose name is unusually long.
Alternatively, the collecting process may manually define the above Options Template and provide a template callback function (via fbSessionAddNewTemplateCallback()) to collect and add each element to the Information Model using fbInfoElementAddOptRecElement() and fbTemplateIsMetadata().
Previous: Lists in IPFIX | Next: Complete Programs
