WAND Network Research Group University of Waikato Crest Of Arms


Libflowmanager is a library designed to facilitate performing flow-based measurement tasks using packet-based inputs, particularly packet trace files. It is based on the libtrace trace processing library.

In particular, libflowmanager will match individual packets to flows, maintain a table of currently active flows and report flows as expired after an appropriate amount of idle time.

Libflowmanager also provides an API for reordering TCP packets based on sequence number. Trace files typically record packets chronologically but out-of-order packets can be a nuisance for many measurement applications.

The latest version is 3.0.0 -- Released on 2017/06/02.

The previous version is 2.0.5 -- you will need to install this version if you are using software that depends on libflowmanager but is not yet compatible with the libflowmanager 3 API.

NEW: From libflowmanager 2.0.5 onwards, the libflowmanager source code is licensed under the LGPL v3.

All releases of libflowmanager prior to 2.0.5 are licensed under the GPL v2.

Recent changes:

  • MAJOR API CHANGE: The previous libflowmanager API was not thread-safe and therefore was not suitable for use with parallel libtrace. The API has therefore been re-written; the old lfm_* functions have been replaced with a FlowManager class that implements the same methods as public member functions. There can be multiple instances of a FlowManager class in an application, e.g. one per packet processing thread. Porting existing programs from libflowmanager 2 to libflowmanager 3 should not be too difficult: the README and example programs have been updated to demonstrate how to use the new API.

Older changes:

  • Expiry list management is now handled using a series of plugins. This allows users to easily implement and deploy new flow expiry algorithms.
  • Added a new "fixed inactivity" expiry plugin.
  • Added a new config option for setting the amount of time to retain TCP flows that are in a TIMEWAIT state: LFM_CONFIG_TIMEWAIT_THRESHOLD.
  • Redefined the meanings of "server" and "client" for a given flow. The server is now the recipient of the first packet and the client is now always the sender of the first packet.
  • Added functions to the flowId class that will return the "local" or "external" IP addresses or ports. These behave exactly the same as the old "client" and "server" functions, respectively.
  • Added a new API function: lpi_foreach_flow. This function allows you to run a specific function against every flow currently in the active flow list.
  • Added a new API function: lpi_release_flow. This will free the Flow structure for an expired flow, rather than the user having to delete the Flow manually when they are done with it.
  • Fixed bug that was causing the two halves of a bidirectional IPv6 flow to be treated as separate flows.
  • Improved performance by reducing the number of map lookups per packet.
  • Added a new config option to create TCP flows based on non-SYN packets.
  • Changed mechanism for determining server/client endpoints for a flow. Direction 0 is now treated as client-to-server and Direction 1 is server-to-client traffic.
  • Unique flow Ids are now 64 bit values.
  • Added support for IPv6 flows.
  • Slight API change to get_client_ip_str() and get_server_ip_str() functions.
  • Restructured source code directories and added an example program that demonstrates the libflowmanager API.
  • Tweaked flow expiry rules: UDP flows expire after 2 minutes rather than 2 minutes 20 secs, and TCP half-closed connections expired after 4 minutes.
  • Fixed bug where libflowmanager would not link correctly with C++ programs.
  • Some other minor bug fixes - see the included ChangeLog for details.


Libflowmanager requires the following libraries:

Libflowmanager has been developed and tested on the Linux operating system and Mac OS X (10.11).


API notes are included in the README file that accompanies the source code. These notes point out the most important issues to be aware of when developing code using the library.

Additional detailed documentation can be found within the source code itself.


We are very interested in hearing feedback on libflowmanager. If you have any requests or comments, or wish to report a bug, please email contact@wand.net.nz.