libfixbuf aims to be a compliant implementation of the IPFIX Protocol,
as defined in the "Specification of the IPFIX Protocol for the Exchange of
Flow Information" (RFC 7011). It supports the information model
defined in "Information Model for IP Flow Information Export"
(RFC 7012), extended as proposed by "Bidirectional Flow Export using
IPFIX" (RFC 5103) to support information elements for representing biflows.

libfixbuf supports UDP, TCP, SCTP, TLS over TCP, and Spread as transport
protocols. Support for DTLS over UDP and DTLS over SCTP is forthcoming. It
also supports operation as an IPFIX File Writer or IPFIX File Reader as
defined in "An IPFIX-Based File Format" (draft-trammell-ipfix-file, current
revision -05).

libfixbuf version 1.0 supports structured data elements as described in
"Export of Structured Data in IPFIX" (RFC 6313).
This adds the ability to export basicLists,
subTemplateLists, and subTemplateMultiLists.

libfixbuf version 1.4 adds support for exporting type information for IPFIX
elements as described in "Exporting Type Information for IPFIX Information
Elements. (RFC 5610)."  This expands the definition of an Information Element
in the Information Model.  In addition to the PEN, length, name, and ID, an
Information Element can also have a data type, description, range, semantics,
and units.  An Options Template can be exported to define Information Element
Type Records.  New API Functions have been added to create and write these
types of Options Records, as well as collect elements of this type so that
Information Elements may be added to the Information Model as we receive 
them from the Exporting process.  See public.h for more information. 

As of version 1.0, libfixbuf has support for NetFlow V9.  libfixbuf converts
the NetFlow v9 to IPFIX by changing the version number, and dropping the
sysUpTime from the header.  In order for tools to properly make use of
Information Elements that are offsets of the sysUpTime (flowStartSysUpTime),
libfixbuf adds Information Element 160, systemInitTimeMilliseconds, to any
template (and corresponding records) that contain either flowStartSysUpTime or
flowEndSysUpTime.
For any element that does not exist in libfixbuf's default Information Model
(above ID 346), libfixbuf will convert this Information Element to
"ciscoNetflowGeneric" (ID 9999) in the template.  The only exceptions are the
"NF_F_FW_EXT_EVENT" and "NF_F_FW_EVENT", often exported from Cisco's ASA Device
(https://www.cisco.com/en/US/docs/security/asa/asa82/netflow/netflow.html), which
will be converted to separate elements 9997 and 9998 respectively.  Similarly,
the Cisco ASA will often export elements 40001, 40002, 40003, and 40004.
These elements are substituted with the IPFIX elements 225, 226, 227, and 228
respectively.

Version 1.4 adds support for NetFlow v9 options template and record retrieval 
and conversion to IPFIX.  The options scope type is converted to IE, 
messageScope.

To disable NetFlow v9 log messages such as sequence number mismatch
messages and record count discrepancy
messages, run `make clean`, `CFLAGS="-DFB_SUPPRESS_LOGS=1" make -e`,
`make install` when installing libfixbuf.

Version 1.6 adds support for translating sFlow into IPFIX.  libfixbuf
only supports sFlow v5. libfixbuf will process Flow Samples (1), 
Extended Flow Samples (3), Counter Samples (2), and 
Extended Counter Samples (4).  Any other format will return 
an FB_ERROR_SFLOW.  Fixbuf translates sFlow records into a fixed IPFIX
record for flow and counter records.  A full description of the fields
fixbuf exports for sFlow records is located in include/fixbuf/public.h.

libfixbuf's public API is defined in public.h; see the documentation of
that file for general documentation on getting started with libfixbuf, as
well as detailed documentation on the public API calls and data types.

libfixbuf API documentation is available in doc/html.

Two command line tools to view the contents of an IPFIX file are available
from the separate fixbuf-tools package
(https://tools.netsa.cert.org/fixbuf-tools/): ipfix2json produces JSON and
ipfixDump produces human-readable text.  (ipfixDump was distributed as part of
libfixbuf in the libfixbuf-2.3.x and libfixbuf-2.4.x releases and previously
as part of YAF.)

A Python API to libfixbuf is available in the pyfixbuf package, distributed
separately (https://tools.netsa.cert.org/pyfixbuf/).

Building
--------

libfixbuf uses a reasonably standard autotools-based build system.
The customary build procedure (./configure && make
&& make install) should work in most environments.

libfixbuf requires glib-2.0 version 2.18 or later.  glib is available
on most modern Linux distributions and BSD ports collections, or in
source form from https://www.gtk.org/.

libfixbuf automatically uses the getaddrinfo(3) facility and the
accompanying dual IPv4/IPv6 stack support if present. getaddrinfo(3)
must be present to export or collect flows over IPv6.

libfixbuf does not build with SCTP support by default. The --with-sctp
option must be given to the libfixbuf ./configure script to include SCTP
support. Also note that SCTP requires kernel support, and applications
built against libfixbuf with libsctp may fail at runtime if that kernel
support is not present.

libfixbuf does not build with TLS support by default. The --with-openssl option
must be given to the libfixbuf ./configure script to include TLS support.

If the information model in src/ipfix.xml changes, xsltproc is a
prerequisite for re-creating the infomodel data structure.

Known Issues
------------

The following are known issues with libfixbuf as of version 1.0.0:

 * There is no support for DTLS over UDP or DTLS over SCTP transport.

 * There is no support for application-selectable SCTP stream assignment
   or SCTP partial reliability. Templates are sent reliably on stream 0,
   and data sets are sent reliably on stream 1.

 * There is no automatic support for periodic template retransmission
   or periodic template expiration as required when transporting IPFIX
   over UDP. Applications using libfixbuf to transport IPFIX messages
   over UDP must maintain these timeouts and manually manage the session.

Copyright
---------

@DISTRIBUTION_STATEMENT_BEGIN@
libfixbuf 2.5

Copyright 2024 Carnegie Mellon University.

NO WARRANTY. THIS CARNEGIE MELLON UNIVERSITY AND SOFTWARE ENGINEERING
INSTITUTE MATERIAL IS FURNISHED ON AN "AS-IS" BASIS. CARNEGIE MELLON
UNIVERSITY MAKES NO WARRANTIES OF ANY KIND, EITHER EXPRESSED OR
IMPLIED, AS TO ANY MATTER INCLUDING, BUT NOT LIMITED TO, WARRANTY OF
FITNESS FOR PURPOSE OR MERCHANTABILITY, EXCLUSIVITY, OR RESULTS
OBTAINED FROM USE OF THE MATERIAL. CARNEGIE MELLON UNIVERSITY DOES NOT
MAKE ANY WARRANTY OF ANY KIND WITH RESPECT TO FREEDOM FROM PATENT,
TRADEMARK, OR COPYRIGHT INFRINGEMENT.

Licensed under a GNU-Lesser GPL 3.0-style license, please see
LICENSE.txt or contact [email protected] for full terms.

[DISTRIBUTION STATEMENT A] This material has been approved for public
release and unlimited distribution.  Please see Copyright notice for
non-US Government use and distribution.

This Software includes and/or makes use of Third-Party Software each
subject to its own license.

DM24-1020
@DISTRIBUTION_STATEMENT_END@