Skip to main content
Retis can generate pcapng files from collected events using the pcap subcommand, enabling analysis with standard tools like Wireshark, tshark, and tcpdump.

​
Basic Usage

Generate a pcapng file from all collected events: 
retis collect -c ping -c 5 1.1.1.1
retis pcap -o capture.pcapng

​
Probe Filtering

Retis supports two modes for generating PCAP files:

​
Filter by Specific Probe

Generate a capture containing only packets seen at a particular probe: 
retis pcap --probe net:net_dev_start_xmit -o xmit.pcapng
The interface information in the resulting PCAP file indicates the probe where each packet was captured.

​
All Probes

Without the --probe option, packets from all probes are included: 
retis pcap -o all_probes.pcapng
Packets from all probes will be mixed together in the output file. The same packet may appear multiple times if it traversed multiple probes.

​
Wireshark Integration

The pcapng files generated by Retis contain extended metadata that Wireshark and tshark can interpret using the Retis Wireshark plugin.
Clients that don’t support the Retis plugin (like tcpdump) will skip the extra metadata and read the standard PCAP data.

​
Installing the Wireshark Plugin

Install required build dependencies:Fedora/RHEL:
dnf install -y gcc make pkg-config wireshark-devel json-c-devel
Ubuntu/Debian:
apt-get install -y gcc make pkg-config libwireshark-dev libjson-c-dev
Install the plugin: 
make wireshark-install
Wireshark version >= 4.3 is required.

​
Using the Wireshark Plugin

Once installed, the plugin automatically displays Retis event metadata alongside each packet in Wireshark.

​
Display Filters in tshark

The plugin registers the Retis protocol dynamically after reading the JSON schema. This creates a limitation: tshark display filters don’t work by default because filters are evaluated before packet dissection. Solution: Provide the JSON schema manually using the retis.schema preference: 
# Generate schema
retis schema -o schema.json

# Use with tshark filters
tshark -r capture.pcapng -o "retis.schema:schema.json" -Y 'retis.ct.state=="new"'

tshark -r capture.pcapng \
  -o "retis.schema:schema.json" \
  -Y 'retis.ct.state=="new"'

​
TCP Sequence Analysis

Retis captures contain the same packet multiple times because:
  • Events are generated from many probes
  • The same packet can traverse the same probe multiple times
This causes Wireshark’s TCP Sequence Analysis to incorrectly flag packets as duplicates. Workaround: Disable TCP sequence analysis: 
# Edit → Preferences → Protocols → TCP
# Uncheck "Analyze TCP sequence numbers"

​
Complete Workflow Example

# 1. Collect events
retis collect -c ping -c 5 1.1.1.1

# 2. Generate schema for tshark filters
retis schema -o schema.json

# 3. Export to PCAP
retis pcap -o capture.pcapng

# 4. Analyze with tshark
tshark -r capture.pcapng \
  -o "retis.schema:schema.json" \
  -o tcp.analyze_sequence_numbers:false \
  -Y 'retis.ct.state=="new"'

# 5. Or open in Wireshark
wireshark capture.pcapng

​
PCAP-NG Internals

Retis uses PCAP-NG extensibility features to embed Retis-specific data using custom PEN 70000.

​
Custom Blocks and Options

The first event in the capture is a custom block containing the JSON Schema (2020-12) definition of Retis events.This allows the Wireshark plugin to dynamically understand the event structure.
Each packet has a custom option containing the JSON-encoded Retis event.This includes all metadata captured by Retis (kernel symbols, connection tracking state, SKB tracking, etc.).

​
Compatibility

The custom blocks and options follow the PCAP-NG specification for vendor extensions:
  • Tools that don’t recognize custom PEN 70000 blocks safely ignore them
  • Standard PCAP fields (packet data, timestamps, interface) remain accessible
  • Files work with tcpdump, tshark, Wireshark, and other PCAP-NG compatible tools

​
Common Use Cases

retis collect -p nf_conntrack
retis pcap -o ct_debug.pcapng
wireshark ct_debug.pcapng
# Filter in Wireshark: retis.ct

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us