libtrace is a library for trace processing. It supports multiple input methods, including device capture, raw and gz-compressed trace, and sockets; and multiple input formats, including pcap and DAG.
Libtrace 4, which adds support for parallelism in both packet capture and processing, is now beta!
Learn more about the new parallel API and how to use it from the HOWTO on the libtrace wiki.
Note that libtrace 4 is intended to be entirely backwards-compatible with libtrace 3, so let us know if any of your existing code breaks as well.
Libtrace is now on GitHub. If you add a feature to libtrace that you think would benefit the libtrace community, please send us a pull request.
Nevil Brownlee has kindly written excellent libtrace bindings for both the Ruby and Python languages, allowing for rapid prototyping of passive measurement applications. You can download ruby-libtrace and python-libtrace from here. Comprehensive documentation and examples are also available for both the ruby and python bindings.
Christoph Dwertmann has created libtrace RPM packages for both Centos and Fedora. The RPM packages can be downloaded from this location.
Libtrace packages are also available in the official Debian and Ubuntu repositories. Stable versions of these packages often lag behind the latest release by several versions, however. The package names are libtrace3 (the main library), libtrace3-dev (the development headers), libtrace-tools (the tool binaries), libwandio1-dev (libwandio) and libpacketdump3 (libpacketdump). The libtrace package is maintained by Matt Brown.
A libtrace package is also available for Gentoo - thanks to Tim Harder for creating and maintaining the Gentoo package.
If you have used libtrace in work that you intend to publish, the best way to reference libtrace is to cite the paper "Libtrace: A Packet Capture and Analysis Library" by S. Alcock, P. Lorier and R. Nelson.
The libtrace wiki is the definitive source of information regarding how to use libtrace, including descriptions of the tools that come bundled with libtrace and instructions on how to perform a variety of common tasks. Doxygen generated documentation is also available online.
Libtrace 3 is not backwards compatible with libtrace 2. See our Porting to libtrace 3 guide.
Supported Trace Formats
|PCAP trace file||Yes||Yes|
|ERF trace file||Yes||Yes|
|DAG live capture||Yes||Yes|
|Native Linux interface||Yes||Yes|
|Native BSD interface||Yes||Yes|
|Legacy ATM trace file||Yes||No|
|Legacy Ethernet trace file||Yes||No|
|Legacy POS trace file||Yes||No|
|ATM cell header file||Yes||No|
|TSH/FR+ trace file||Yes||No|
Trace file I/O
Libtrace can natively read and write compressed trace files. The supported compression formats are gzip, bzip2, lzma and lzo (lzo support is write only). To speed up file operations, compression and decompression is performed using a separate thread, resulting in significant performance gains for analysis tasks where the I/O is the limiting factor (most simple analysis tasks are I/O-limited).
NEW in 3.0.14 - the I/O functionality used by libtrace is now available as the libwandio shared library (included with libtrace). Now users can easily use libwandio to perform threaded reading and writing of any type of compressed file, not just trace files.
Programs written using libtrace are capture format agnostic. This means that they can be run against an input from any supported capture source without requiring any code modification. The same program will work just as well when reading from a PCAP trace file as it would reading from a live DAG capture.
Libtrace can also seamlessly convert packets from one format to another without any special effort on the part of the user.
The libtrace API allows users to directly access the protocol header for any layer at or below the transport layer, automatically decoding and skipping any intermediate headers. There are both functions for accessing the header that is present at a given layer (e.g. the transport layer) and functions for finding the header for a specific protocol (if present).
Supported headers include:
- VLAN (802.1q)
- IPv4, IPv6
- ICMP, ICMP6
Libtrace also detects and handles edge-cases that occur when decoding protocol headers such as fragmentation, header truncation and tunneling.
Libtrace comes bundled with a series of tools that perform most common trace manipulation tasks. These include:
- traceanon - anonymises trace files
- traceconvert - converts a trace from one format to another
- tracediff - reports differences between two trace files
- traceends - summarises traffic sent and received by endpoints
- tracefilter - applies a BPF filter to a trace
- tracemerge - merges multiple trace inputs into a single trace
- tracepktdump - displays packet contents in a readable format, similar to tcpdump
- tracereplay - replays a trace file using original timing
- tracereport - produces a variety of reports on a trace
- tracertstats - produces stats about an input trace in real time
- tracesplit - splits trace files
- tracesplit_dir - splits trace files based on packet direction
- tracestats - summarises number of bytes and packets matching BPF filters
- tracesummary - summarises the basic stats for a trace
- tracetop - reports the busiest flows over time, similar to ntop
- tracetopends - reports the busiest endpoints in a trace
Libtrace includes a library called libpacketdump which can parse packets
and display the packet contents in a nice human-readable form. The output is
similar to that produced by tcpdump, although the formatting is somewhat more
verbose. Libpacketdump forms the core of the tracepktdump tool, but can also be
used in libtrace programs (for example, to dump a packet that has unexpected
values in a header).
Download the tarball, unpack, and run
./configure ; make ; make installlibtrace will install into /usr/local by default. Bearing that in mind, you will probably need to update your library search path to point at /usr/local/lib, if it doesn't already:
echo /usr/local/lib >> /etc/ld.so.conf ldconfig
There are some configure-time options you can use, aside from the usual configure options for prefix and so on:
libpacketdump: this is a library to enable rapid debugging of network packets. It will dump out the contents of a libtrace_packet_t to stdout, parsing any layers (such as ethernet or TCP) that it knows about. It is built in a module fashion, so adding support for newer protocols is trivial. We have a tcpdump-like replacement called tracepktdump that uses libpacketdump.
Some of the tools have external dependancies such as libgdchart - if these libraries are not present on your system, the parts of the tool that depend on it will not be included.
DAG support: If you have a DAG card, and wish to compile libtrace with support for native reads from DAG cards, use the --with-dag option:
--with-dag=DIR include DAG support (located in directory DIR, if supplied)
Note: Older Distributions may have trouble reading large pcap files using the pcap: file parser. Use the internal "pcapfile:" parser instead.
We are very interested in hearing feedback on libtrace. If you have any requests or comments, or wish to report a bug, please email email@example.com