Skip to main content
This guide will help you get started with Retis and trace your first packets in the Linux networking stack.

​
Prerequisites

Before you begin, make sure you have:
  • Retis installed (see Installation)
  • Root access or appropriate capabilities (CAP_SYS_ADMIN, CAP_BPF, CAP_SYSLOG)
  • A kernel that meets the requirements

​
Your First Trace

The entry point for most use cases is the collect command, which installs probes and gathers events for instant reporting or later processing.
1

Run a basic collection

Start collecting network events with default settings. If no collector is explicitly enabled, Retis will try to load all collectors that meet their requirements.
retis collect
You’ll see output similar to:
Collector(s) started: skb-tracking, skb, skb-drop, ovs, nft, ct
No probe(s) given: using tp:net:netif_receive_skb, tp:net:net_dev_start_xmit
7 probe(s) loaded
2

Generate some network traffic

Open another terminal and generate network traffic to see events:
ping -c 3 8.8.8.8
# or
curl https://example.com
3

View the events

Retis will display events in real-time. Press Ctrl+C to stop collection.

​
Filtering Packets

Tracing all packets can generate a lot of events. Use filters to focus on specific traffic. 
retis collect -f 'tcp port 443'

​
Metadata Filtering

You can also filter based on metadata like network namespace: 
retis collect -m 'sk_buff.dev.nd_net.net.ns.inum == 4026531840'

​
Saving Events for Later

To save events to a file for post-processing:
1

Collect and save events

Use the -o flag to save events to a file (defaults to retis.data):
retis collect -f 'tcp port 443' -o
To also see events in real-time while saving, add --print:
retis collect -f 'tcp port 443' -o --print
2

Review saved events

Use the print command to display saved events:
retis print

​
Using Specific Collectors

Collectors target specific areas of the networking stack. Enable specific collectors for focused tracing: 
retis collect -c skb,skb-drop

​
Available Collectors

CollectorData CollectedUse Case
skbPacket informationBasic packet data
skb-dropDrop reasonIdentify why packets are dropped
skb-trackingPacket tracking IDFollow packets through the stack
ovsOpenVSwitch dataOVS bridge and flow information
nftNftables contextFirewall rule matches
ctConntrack infoConnection tracking state
devNet deviceNetwork device details
nsNamespaceNetwork namespace info

​
Tracking Packets Through the Stack

Use the sort command to group and reorder events by packet, making it easy to follow a packet through different subsystems:
1

Collect with tracking enabled

retis collect --allow-system-changes -p ip_local_deliver \
    --nft-verdicts drop -f 'udp port 8080' -o --print
2

Sort events by packet

retis sort
Output shows packets grouped with indented child events:
136852156905 (3) [swapper/3] 0 [k] ip_local_deliver #1fdd03636dffff889641716940
  172.16.42.1.39677 > 172.16.42.2.8080 tos 0x0 ttl 64 id 17803
  ns 0x1/4026531833 if 2 (eth0) rxif 2
  ct_state NEW status 0x100 udp orig [172.16.42.1.39677 > 172.16.42.2.8080]
  ↳ 136852318052 (3) [swapper/3] 0 [k] __nft_trace_packet
      table firewalld (4) chain filter_INPUT_POLICIES (124) handle 284 drop
  ↳ 136852333279 (3) [swapper/3] 0 [tp] skb:kfree_skb drop (reason NETFILTER_DROP)
The sort command uses information from the skb-tracking and ovs collectors to identify and group events for the same packet.

​
Exporting to Pcap

Convert Retis events to pcap format for analysis with tools like Wireshark: 
retis -p generic collect -o
retis pcap --probe net:netif_receive_skb | tcpdump -nnr -

​
Using Profiles

Profiles provide predefined sets of CLI arguments for common use cases: 
# List available profiles
retis profile list

# Use a profile
retis -p generic collect

# Extend a profile with additional options
retis -p dropmon collect -p skb:consume_skb

​
Next Steps

Learn About Filtering

Master packet and metadata filtering for precise tracing

Explore Collectors

Deep dive into each collector’s capabilities

Use Profiles

Create custom profiles for your use cases

Post-Processing

Use Python bindings for custom analysis

Build docs developers (and LLMs) love

Get started for freeTalk to us