Skip to main content
The skb collector provides insights into the struct sk_buff kernel data structure, which holds metadata and data for networking packets.

​
Overview

The skb collector is one of the most fundamental collectors in Retis. It extracts detailed information from socket buffers (skbs), which are the primary data structure used by the Linux kernel for packet processing.

​
What Data is Retrieved

The skb collector retrieves:
  • Packet data: Raw packet content (always included)
  • VLAN information: Hardware-accelerated VLAN metadata (always included)
  • Metadata: Length, hash, priority, and flags (optional)
  • Data reference: Clone information, user counts, reference counts (optional)
  • GSO information: Generic Segmentation Offload details (optional)

​
Probe Installation

The skb collector does not install any probes itself. It only retrieves data when a struct sk_buff * is available in probe arguments.
This is done automatically. For example, if the skb collector is enabled and a probe is added (manually, by a profile, or by another collector) on kfree_skb_reason, the skb collector will generate events with data from the skb given as an argument to that function.

​
Command-Line Options

​
--skb-sections

Comma-separated list of extra information to collect from skbs.
​
--skb-sections
string
default:"packet,vlan"
Control which parts of the skb metadata to retrieve and export in events.Supported values:
  • meta: Include skb metadata information (len, data_len, hash, etc.)
  • dataref: Include data & refcnt information (cloned, users, data refs, etc.)
  • gso: Include Generic Segmentation Offload (GSO) information
  • all: All of the above
Always retrieved:
  • Packet section (raw packet data)
  • VLAN offloading metadata
Deprecated values (ignored):
  • eth, arp, ip, tcp, udp, icmp: These are part of the raw packet
  • dev, ns: These are now separate collectors

​
Event Sections Produced

The skb collector produces the following event sections:

​
skb Event Section

  • VLAN hardware acceleration: Displays VLAN metadata that’s accelerated (not in packet)
  • Metadata: Checksum status, hash, lengths, priority, flags
  • Data reference: Clone status, user count, reference counts
  • GSO information: Type, flags, fragments, segments, size
See skb event documentation for detailed format.

​
packet Event Section

Contains the parsed packet data including:
  • Layer 2 (Ethernet) information
  • Layer 3 (IP/ARP/IPv6) information
  • Layer 4 (TCP/UDP/ICMP) information
See packet event documentation for detailed format.

​
Usage Examples

​
Basic Usage

Collect with default skb sections (packet + VLAN): 
retis collect -c skb

​
Include Metadata

Collect skb metadata in addition to packet data: 
retis collect -c skb --skb-sections meta

​
Include All Information

Collect all available skb information: 
retis collect -c skb --skb-sections all

​
Multiple Sections

Select specific sections: 
retis collect -c skb --skb-sections meta,dataref,gso

​
With Custom Probes

Add probes to specific functions: 
# Probe packet drop and consume functions
retis collect -c skb -p skb:kfree_skb -p consume_skb

# Probe TCP functions
retis collect -c skb -p tcp_v4_rcv -p tcp_sendmsg

​
With Filtering

Combine with packet filters: 
# Filter by protocol and port
retis collect -c skb --skb-sections all -f 'tcp port 443'

# Filter by network namespace
retis collect -c skb -m 'sk_buff.dev.nd_net.net.ns.inum == 4026531840'

​
Example Output

Here’s an example of output with metadata enabled: 
202388856790511 [ping] 3215414 [tp] net:net_dev_queue #b81253ea5defffff977be5ec6f80 (skb 18446629157470561024) n 0
  if 178 (p1_r) 172.200.0.2 > 172.200.0.3 ttl 64 tos 0x0 id 22378 off 0 [DF] len 84 proto ICMP (1) type 8 code 0
  skb [csum none hash 0x12345678 priority 0]
Breaking down this output:
  • Tracking ID: #b81253ea5defffff977be5ec6f80
  • SKB address: 18446629157470561024
  • Interface: 178 (p1_r)
  • Packet info: ICMP echo request from 172.200.0.2 to 172.200.0.3
  • SKB metadata: Checksum status, hash, priority

​
Integration with Other Collectors

The skb collector works well with:

​
skb-tracking

Track packets through the stack: 
retis collect -c skb,skb-tracking -o events.json
retis sort events.json

​
skb-drop

Investigate packet drops: 
retis collect -c skb,skb-drop --skb-sections all -f 'tcp'
This combination shows both the packet content and why it was dropped.

​
ct (Conntrack)

See connection tracking state: 
retis collect -c skb,ct --skb-sections meta
Shows packet data alongside conntrack information.

​
nft (Netfilter)

Trace packets through firewall rules: 
retis collect -c skb,nft --skb-sections all --allow-system-changes
Shows which firewall rules packets traverse.

​
dev

Include network device information: 
retis collect -c skb,dev --skb-sections meta
Adds device names and interface indices.

​
ns

Track packets across namespaces: 
retis collect -c skb,ns --skb-sections meta
Includes network namespace information.

​
Understanding SKB Metadata

​
Checksum Status

The collector reports checksum information in different formats:
  • csum none: No checksum computed
  • csum unnecessary: Checksum verified by hardware
  • csum partial: Partial checksum (needs completion)
  • csum complete: Full checksum available

​
Flags

Common flags reported:
  • cloned: SKB has been cloned
  • nohdr: No header references

​
Data References

With --skb-sections dataref:
  • fclone: Fast clone count
  • users: Number of users holding references
  • dataref: Reference count for data buffer

​
GSO Information

With --skb-sections gso:
  • type: GSO type (see SKBFL_* in kernel’s skbuff.h)
  • flags: GSO flags (see SKB_GSO_*)
  • frags: Number of fragments
  • segs: Number of segments
  • size: GSO segment size

​
Technical Details

​
Kernel Types

The skb collector activates when these types appear in probe arguments:
  • struct sk_buff *

​
eBPF Implementation

The collector uses eBPF hooks that:
  1. Detect struct sk_buff * in probe arguments
  2. Read configured sections from a config map
  3. Extract requested data from the skb structure
  4. Generate raw event sections for userspace processing
Configuration is passed to eBPF via a shared map created in userspace.

​
Source Code References

  • Collector implementation: retis/src/collect/collector/skb/skb.rs
  • eBPF hook: retis/src/collect/collector/skb/bpf/skb_hook.bpf.c
  • Event factory: retis/src/collect/collector/skb/bpf.rs

​
Best Practices

  1. Start minimal: Use default sections first, add more only when needed
  2. Combine with filtering: Large packet captures can be overwhelming
  3. Use with tracking: Enable skb-tracking to follow packets through the stack
  4. Consider performance: More sections mean more data extracted and stored
  5. Match your investigation: Choose sections based on what you’re debugging

​
Common Use Cases

​
Debugging Packet Drops

retis collect -c skb,skb-drop --skb-sections all

​
Performance Analysis

retis collect -c skb --skb-sections gso,meta -p net:net_dev_start_xmit

​
Connection Tracking Issues

retis collect -c skb,ct --skb-sections meta -f 'tcp'

​
Namespace Debugging

retis collect -c skb,ns,dev --skb-sections meta

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us