Pcap

Probe filtering

Retis supports generating pcapng files from collected events by running the pcap subcommand. It does so in two distinct ways:

  • Generating a pcap file from events at a particular probe.
  • Generating a pcap file from all events

If --probe option is used, the resulting capture will only contain packets that were seen on that probe.

If --probe is not used, packets from all probes will be mixed together.

In the resulting pcap file, the interface information attached to the packets indicates the probe where it was captured at.

Wireshark / tshark support

The pcapng file generated by Retis contains some extra information that Wireshark and tshark are able to read and interpret using the Retis wireshark plugin.

This information is just skipped if the capture file is read by a client that does not support it, such as tcpdump.

Installing the wireshark plugin

To install the Wireshark plugin, install the required build-dependencies, e.g:

dnf install -y gcc make pkg-config wireshark-devel json-c-devel

And then run:

make wireshark-install

Wireshark version greater or equal to 4.3 is required.

Using the Wireshark plugin

By just installing the Retis Wireshark plugin, event metadata will be displayed alongside each packet.

However, the Retis Wireshark plugin registers the Retis protocol dynamically (after reading the first block with the json-schema definition), and this comes with a limitation: tshark display filters do not work. The reason is that tshark evaluates the filter before starting the packet dissection.

To solve this important use-case, the Retis Wireshark plugin has one "Preference" called retis.schema that allows users to provide the json schema manually to the plugin. Using this option, tshark can be used to filter on retis data, e.g:

tshark -r some.pcap -o "retis.schema:schema.json" -Y 'retis.ct.state=="new"'

The schema file can be generated using retis schema.

TCP sequence analysis

Retis captures will contain the same packet multiple times because Retis generates events from many probes and the same packet can go through the same probe multiple times.

For that reason, Wireshark's TCP Sequence Analysis can incorrectly flag some packets as duplicates. This feature can be disabled via the “Analyze TCP sequence numbers” TCP dissector preference (or by adding -o tcp.analyze_sequence_numbers:false) to the wireshark or tshark command line.

Internals: Pcap-ng custom blocks and options

Retis uses pcap-ng's extensibility to add two extra pieces of information in custom blocks and options that use the custom PEN 70000.

  • Schema block: The first event in the capture is a custom block that contains the json-schema (2020-12) of the Retis event.
  • Event option: Alongside each packet, Retis inserts a custom option with the json encoded event.

With this information, and the Retis Wireshark plugin, all the metadata captured by Retis can be displayed in Wireshark.