How-To Collect IPFIX over UDP
We recommend using TCP over UDP for network IPFIX transport, since UDP is not a reliable transport protocol, and therefore cannot guarantee the delivery of messages. libfixbuf stores sequence numbers and reports potential loss of messages. Templates over UDP must be re-sent at regular intervals. Fixbuf does not automatically retransmit messages at regular intervals; it is left to the application author to call fbSessionExportTemplates(). In accordance with RFC 7011, the templates should be resent at least three times in the Template refresh timeout period. Make sure the record size does not exceed the path MTU. libfixbuf will return an error if the message exceeds the path MTU.
A UDP collector session is associated with a unique IP, port, observation domain triplet. UDP sessions timeout after 30 minutes of inactivity. When a session times out, all Templates and state are discarded, this includes any related NetFlow v9 templates and/or state. libfixbuf will discard any data records for which it does not contain a Template. Template IDs are unique per UDP session. Once Templates are refreshed, old templates may not be used or referenced by the collecting session. A UDP collector manages multiple sessions on one collector and fBuf. If the application is using the fbListenerAppInit_fn and fbListenerAppFree_fn functions to maintain context per session, it is necessary to call fbCollectorGetContext() after each call to fBufNext() to receive the correct context pointer (as opposed to calling it after fbListenerWait() returns in the TCP case). If the application needs to manage context PER SESSION, the application must turn on multi-session mode w/ fbCollectorSetUDPMultiSession() (this allows for backwards compatibility with old applications.) Previously, the appinit() function was called only from fbListenerAlloc() for UDP connections, which did not allow the application the peer information. The appinit() function is now called during fbListenerAlloc() (with a NULL peer address) and also when a new UDP connection is made to the collector, giving the application veto power over session creation. If the application does not call fbCollectorSetUDPMultiSession(), the application will not receive the callback to its appinit() function, which only allows the application to set one context pointer on all sessions. Likewise, appfree() is only called once, when the collector is freed, if not in multi-session mode. If the application is in multi-session mode, appfree() will be called once for each session when the collector is freed AND anytime a session is timed out.
Note: If the appinit() function returns FALSE, libfixbuf will reject any subsequent messages from the peer address, observation domain until the timeout period has expired. If the appinit() function should reject a "connection" the application should set the error code to FB_ERROR_NLREAD and return FALSE. Example usage:
To only accept IPFIX from one host without using the appinit() and appfree() functions, it is encouraged to use fbCollectorSetAcceptOnly(). UDP messages received from other hosts will return FB_ERROR_NLREAD. The application should ignore errors with this error code by clearing the error and calling fBufNext().
Previous: Network Collectors | Next: NetFlow v9 Collectors
