Supported Trace Formats

Format	URI	Input	Output	Notes
Live pcap interface	pcapint:<interface>	Yes	Yes
pcap trace file	pcapfile:<filename>	Yes	Yes
pcag-ng trace file	pcapng:<filename>	Yes	Yes	Read support added in libtrace 4.0.2, write support added in libtrace 4.0.6
ERF trace file	erf:<filename>	Yes	Yes
DAG device	dag:<device location>	Yes	Yes	Requires DAG hardware capture card and libraries
Native Linux interface	int:<interface>	Yes	Yes	Only available on Linux
Native Linux interface (ring buffers)	ring:<interface>	Yes	Yes	Only available on Linux -- requires Libtrace 3.0.16 or later
Data Plane Development Kit (DPDK)	dpdk:<PCI address>	Yes	Yes	Requires a DPDK compatible NIC + additional setup
Data Plane Development Kit (DPDK) virtual device	dpdkvdev:<device type>,iface=<device name>	Yes	Yes
Native BSD interface	bpf:<interface>	Yes	No	Only available on BSD or Mac OS X
TSH trace file	tsh:<filename>	Yes	No
FR+ trace file	fr+:<filename>	Yes	No
Legacy DAG ATM trace file	legacyatm:<filename>	Yes	No
Legacy DAG POS trace file	legacypos:<filename>	Yes	No
Legacy DAG Ethernet trace file	legacyeth:<filename>	Yes	No
Legacy DAG NZIX trace file	legacynzix:<filename>	Yes	No
ATM cell header trace file	atmhdr:<filename>	Yes	No
RT network protocol	rt:<host>:<port>	Yes	No
nDAG protocol	ndag:<interface>,<multicast group>,<port>	Yes	No
nDAG protocol via DPDK	dpdkndag:<PCI address>	Yes	No	Only available on Linux -- experimental (requires additional setup)
nDAG protocol via TCP	ndagtcp:<interface>,<listen address>,<port>	Yes	No	Added in libtrace 4.0.23
TZSP	tzsplive:<host>:<port>	Yes	Yes	Added in libtrace 4.0.7
XDP	xdp:<interface>	Yes	Yes	Added in libtrace 4.0.14
ETSI LI live handover	etsilive:<ip address>:<port>	Yes	No	Added in libtrace 4.0.4
ETSI LI trace file	etsifile:<filename>	Yes	Yes	Added in libtrace 4.0.21

Libtrace input and output sources are specified using URIs which describe both the format and location of the trace, interface or device in question. To do so, simply append the location of the trace file, interface or device to the URI for the appropriate format as specified in the table above.

For example, pcapfile:sample.pcap.gz describes the PCAP trace file called sample.pcap.gz. dag:/dev/dag0 describes the DAG device present at /dev/dag0. int:eth0 is the URI for the Linux interface eth0.

URIs that include a filename usually accept '-' to represent stdin, e.g. erf:- will read ERF records from stdin.

Per format notes

PCAP

• There are three pcap formats supported by libtrace: pcapfile, pcapint and pcap. Generally you want to use pcapfile if reading or writing pcap trace files and pcapint if reading or writing from a live pcap interface.
• pcapfile and pcapint have been implemented directly within libtrace, whereas pcap uses the libpcap API. We recommend against using pcap wherever possible.
• Most pcap-based utilities, including tcpdump, tcptrace and snort, do not support compressed trace files so you may need to decompress the trace first. For example, "zcat foo.pcap.gz | tcpdump -r-" will do this for tcpdump.

PCAP NG

• pcapng refers to the next generation pcap format that is used as the default output format by Wireshark.

DAG capture card (dag:)

• Requires the Dag API from Endace.
• Anyone experiencing problems with using DAG cards for libtrace may wish to read over our DAG Notes, which describes the libtrace DAG support in more detail.

ERF Trace file (erf:)

• Supports a maximum of 4 interfaces, by convention 0 for outgoing, 1 for incoming, 2 for other, and 3 is unused.
• There is at least one traceset which is known to have an ERF type of "0", just to be annoying, libtrace attempts to account for this.
• Does NOT require the dag API to read erf (and compressed erf) traces.

Native Linux interface (int:)

• Currently supports a fast way of retrieving the timestamp of the packet from kernel space using ancillary data.
• Supports uploading bpf filters into the kernel since 3.0.5+
• Supports only incoming and outgoing direction, attempts to set other directions will fail. (3.0.3+)
• Currently the default if you just provide an interface name for the URI without explicitly defining the format.

Native Linux interface (ring:)

• Provides much better performance than int:. To use, you must provide the full URI when describing the input source (e.g. "ring:eth0", rather than just "eth0").
• Supports all the same features as int:

Data Plane Development Kit (dpdk:)

• Requires DPDK to be installed and kernel modules to be loaded
• Better performance than int: and ring: under the correct conditions.
• Each per-packet thread is bound to a CPU core and will poll waiting for packets to arrive. This means 100% CPU on these cores.
• You can only use a single instance of the dpdk: format at a given time - that is you can listen to a single interface or write to a single interface but not both.
  • As of libtrace 4.0.16 you can open multiple DPDK interfaces within the same application, however, you still cannot open the same interface for both reading and writing.

For more information please read over the DPDK Notes, which describes the libtrace DPDK support in more detail.

Data Plane Development Kit virtual devices (dpdkvdev:)

• Allows use of DPDK on a virtual interface, e.g. for experimenting with DPDK without actual DPDK-compatible hardware (or having to assign interfaces to DPDK).
• "device type" refers to the name of the software driver that you want to use on your virtual interface, such as net_pcap0 for the pcap driver or net_tap0 for the TAP driver.
• "device name" is the name of the virtual device you want to capture packets from (or write packets to). This interface must already exist on your system as a veth interface. See https://github.com/LibtraceTeam/libtrace/blob/master/test/netns-env.sh for an example on how to create virtual devices on Linux.

BSD BPF Interface (bpf:)

• Currently supports capture, but not writing.

RT protocol

• libtrace does not (yet?) support RT output.
• The protocol specification may eventually be made available so people can write their own servers.

Network DAG (nDAG)

• libtrace does not support nDAG output.
• This format is designed to receive ERF records over a network from a host running an nDAG multicaster (such as the tracemcast tool).
• nDAG works best when used with the parallel API.

Network DAG over DPDK (dpdkndag:)

• Capture only, no output support.
• This format allows users to use a DPDK-capable interface to intercept and decode ERF records being exported by an nDAG multicaster.

Network DAG over TCP (ndagtcp:)

• Capture only, no output support.
• This format is designed to receive ERF records over a network from a host running the traceucast tool.

TZSP streams (tzsplive:)

• When reading, the host and port refer to the interface and port that you want to listen on for TZSP-encapsulated packets.
• When writing, the host and port refer to the TZSP listener that you want to transmit the encapsulated packets to.

XDP (xdp:)

• When reading, Libtrace will try to locate its eBPF program and automatically load it. If it cannot be found the default Libbpf eBPF program will be loaded. Libtrace allows for a user to supply an eBPF program if required, this can be loaded using the URI xdp:ebpf_file:ebpf_program:<interface>
• When writing, Libtrace only accepts the URI xdp:<interface>
• Simultaneous reading and writing from the same interface with XDP is not supported.

For more information please read over the XDP Notes, which describes the libtrace XDP support in more detail.

ETSI LI file (etsifile:)

• When writing, this format only supports conversion from etsilive: inputs, i.e. it cannot convert a pcap to valid ETSI encoded records.
• The format portion of the URI must ALWAYS be provided, i.e. etsifile:<filename>, not just <filename>

ETSI LI live (etsilive:)

• Intended for receiving LI handovers produced by OpenLI (https://openli.nz), but in theory should work with any other ETSI-compliant LI system.
• Libtrace will listen on the provided IP address and port for a TCP connection from the LI mediation function.
• Will respond to keep-alive messages from the mediator.