How-To Export IPFIX
Each fixbuf application must have a single fbInfoModel_t instance that represents the Information Elements that the application understands. The fbInfoModelAlloc() call allocates a new Information Model with the IANA-managed information elements (current as of the fixbuf release date) preloaded. Additional vendor-specific information elements may be added with fbInfoModelAddElement(), fbInfoModelAddElementArray(), fbInfoModelReadXMLFile(), and fbInfoModelReadXMLData().
To create an Exporter, first create an fbSession_t attached to the application's fbInfoModel_t to hold the Exporter's Transport Session state using fbSessionAlloc().
Then create an fbExporter_t to encapsulate the connection to the Collecting Process or the file on disk, using the fbExporterAllocFP(), fbExporterAllocFile(), fbExporterAllocNet(), or fbExporterAllocBuffer() calls.
With an fbSession_t and an fbExporter_t available, create a Buffer (fBuf_t) for writing via fBufAllocForExport().
Create and populate templates for addition to this session using fbTemplateAlloc() and fbTemplateAppendSpecArray(), fbTemplateAppendSpec(), fbTemplateAppend(), fbTemplateAppendArraySpecId(), or fbTemlateAppendSpecId(). The layout of the template usually matches the C struct that holds the record. For details see Template Definition.
Add the templates to the session via fbSessionAddTemplate(). Typically each template is added to the session twice, once as an internal template---which describes how the record appears in memory---and again as an external template---which describes how the record appears in the IPFIX message. A convenience function, fbSessionAddTemplatesForExport(), exists to do this for you.
In this tutorial, the output Buffer (the fBuf_t) is created before adding external Templates to the Session, and calling fbSessionAddTemplate() automatically adds the Templates to the Buffer. It is also possible to add Templates to a Session before creating the Buffer. In that case, one calls fbSessionExportTemplates() to add the Templates to the output Buffer. (fbSessionExportTemplates() writes all Templates to the output Buffer; calling it needlessly results in the Template definitions appearing multiple times in the output.)
To write data, set the internal and external template IDs with fBufSetInternalTemplate() and fBufSetExportTemplate() or with the convenience function fBufSetTemplatesForExport(). You can then use fBufAppend() to write records into IPFIX Messages and Messages to the output stream.
When exporting multiple record formats, you must call fBufSetTemplatesForExport() or the fBufSetInternalTemplate() and fBufSetExportTemplate() pair whenever the record format changes.
By default, fBufAppend() will emit an IPFIX Message to the output stream when the end of the message buffer is reached on write. The fBufSetAutomaticNextMessage() call can be used to modify this behavior, causing fBufAppend() to return FB_ERROR_EOM when at end of message. Use this if your application requires manual control of message export. In this case, fBufEmit() will emit a Message to the output stream. If your exporter was created via fbExporterAllocBuffer(), you may use fbExporterGetMsgLen() to get the message length.
If not in automatic mode and a session's templates do not fit into a single message, use fbSessionExportTemplate() to export each template individually instead of relying on fbSessionExportTemplates().
Manual control of message export is incompatible with template and information element metadata (fbSessionSetMetadataExportTemplates() and fbSessionSetMetadataExportElements()). There are several functions that may cause the metadata options records to be exported, and the Session must be free to create a new record set or template set as needed.
Complete sample_exporter.c program:
Previous: Using libfixbuf in Your Program | Next: IPFIX File Collectors
