Skip to main content
The pcap command converts Retis events into pcap-ng format files that can be opened with tools like Wireshark or tcpdump.

​
Usage

retis pcap [INPUT] [OPTIONS]

​
Overview

The pcap command generates pcap-ng files from stored Retis events, optionally filtering by probe name. Each event’s packet data is extracted and written to the pcap file along with metadata embedded in custom blocks.

​
Arguments

​
INPUT
path
default:"retis.data"
Input file containing events to convert.Can be a single file or a range of rotated files.
retis pcap events.data
retis pcap  # Uses retis.data

​
Options

​
--out
path
Write the generated pcap output to a file.If not specified, output is written to stdout.
retis pcap --out capture.pcapng
retis pcap -o output.pcapng
​
--probe
string
Filter events from a specific probe.Probes follow the [TYPE:]TARGET pattern (same as retis collect).
retis pcap --probe tp:net:netif_receive_skb
retis pcap -p kretprobe:ovs_dp_upcall
​
--list-probes
boolean
List all probes available in the input file.Shows which probes have events with packet data that can be converted to pcap.
retis pcap --list-probes
retis pcap -l

​
Examples

# See which probes are in the capture
retis pcap --list-probes

​
Pcap-ng Format

The generated files use the pcap-ng format with the following features:

​
Interface Description Blocks

Fake interfaces are created for each probe point in the format {type}/{name}: 
kretprobe/ovs_dp_upcall
raw_tracepoint/net:netif_receive_skb

​
Enhanced Packet Blocks

Each packet includes:
  • Packet data (Ethernet frame)
  • Timestamp from the event
  • Comment with full event details
  • Custom UTF-8 option with complete event JSON

​
Schema Block

A custom block containing the JSON schema for Retis events is embedded at the start of the file.

​
List Probes Output

Example output from --list-probes: 
kretprobe:ovs_dp_upcall
raw_tracepoint:net:net_dev_start_xmit
raw_tracepoint:net:netif_receive_skb
raw_tracepoint:openvswitch:ovs_do_execute_action
raw_tracepoint:skb:kfree_skb

​
Wireshark Integration

The generated pcap files can be opened directly in Wireshark:
  1. Events appear as normal packets
  2. Full Retis event data is in packet comments
  3. Interface names show the probe points
  4. JSON event data is in custom options
# Generate and open
retis pcap -o trace.pcapng
wireshark trace.pcapng

​
Tcpdump Usage

Read pcap files with tcpdump: 
# From file
retis pcap -o trace.pcapng
tcpdump -nnr trace.pcapng

# From stdin
retis pcap | tcpdump -nnr -

# Filter in tcpdump
retis pcap | tcpdump -nnr - 'tcp port 443'

​
Requirements

For successful pcap generation:
  1. Events must have a packet section (raw packet data)
  2. Events must have a kernel section (probe information)
  3. Events must have a common section (timestamp, etc.)
Events without packet data are skipped and counted in statistics.

​
Statistics

At the end of processing, statistics are displayed: 
INFO  125 event(s) were processed
WARN  3 event(s) were skipped because of missing raw packet

​
Common Use Cases

​
Analyze with Wireshark

retis collect -f "tcp port 8080" -o capture.data
retis pcap capture.data -o analyze.pcapng
wireshark analyze.pcapng

​
Filter specific probe point

# Only get packets from receive path
retis pcap --probe net:netif_receive_skb -o rx-only.pcapng

​
Quick packet inspection

# Pipe through tcpdump for quick view
retis pcap events.data | tcpdump -nnr - -c 10

​
Export for external analysis

# Generate pcap for sharing
retis pcap --out evidence.pcapng

​
Limitations

  • Only events with packet data can be converted
  • Packet data must be complete (not truncated)
  • Requires kernel and common event sections
  • L2 header must be present in packet data

​
Error Messages

The specified probe with --probe doesn’t exist in the input file.Use --list-probes to see available probes.
No events in the file have the required packet data.Ensure you collected with a collector that captures packet data (e.g., skb).

​
See Also

  • collect - Collect events with packet data
  • print - View events in text format
  • sort - Sort events before conversion

Build docs developers (and LLMs) love

Get started for freeTalk to us