Skip to main content
Retis has some known limitations and behavioral characteristics you should be aware of when using the tool.

​
System Modifications

By default, Retis does not modify your system. This is intentional but may mean some prerequisites are missing.

​
Default Behavior

Retis avoids making system changes such as:
  • Loading kernel modules
  • Mounting filesystems
  • Changing system configuration
  • Adding firewall rules
This conservative approach ensures Retis doesn’t unexpectedly alter your system state.

​
Notable Examples

The nft (nftables) module requires a specific nftables rule to be present.Impact: Without this rule, no nft events will be reported.Workaround: Either:
  1. Use --allow-system-changes flag (see below)
  2. Manually configure the required nftables rule
The tracefs filesystem is not mounted by default on all systems.Impact: While not mandatory, tracefs access helps Retis better determine:
  • Available tracepoints
  • Traceable kernel functions
  • Available event fields
Workaround: Either:
  1. Use --allow-system-changes flag (see below)
  2. Manually mount tracefs:
mount -t tracefs none /sys/kernel/tracing

​
Allowing System Changes

Use the --allow-system-changes flag to permit Retis to make necessary modifications: 
retis collect --allow-system-changes -p nf_conntrack
See retis collect --help for details about what changes may be applied.

​
Packet Path Coverage

Retis operates primarily on struct sk_buff objects, limiting coverage of certain packet paths.

​
Locally Generated Traffic

Some parts of the path for locally generated traffic cannot be traced because they occur before sk_buff allocation. Examples:
  • Socket system calls (socket(), bind(), connect())
  • Data staging before packet creation
  • Some early protocol processing
Coverage starts at:
  • sk_buff allocation points
  • Protocol transmit functions that work with sk_buff

​
Impact

You may miss events for:
  • Application-level network operations
  • Early packet creation stages
  • Some loopback/local delivery paths
Workaround: Use complementary tracing tools (e.g., strace, perf) for application-level visibility.

​
Profile Combination

Combining multiple profiles may fail if flags are used multiple times or arguments are incompatible.

​
Issue

Profiles can specify overlapping or conflicting configuration: 
# May fail if profiles have conflicting options
retis collect --profile conn-track --profile drop-monitor
Common conflicts:
  • Duplicate probe specifications
  • Incompatible filter expressions
  • Overlapping collector configurations

​
Workaround

Instead of combining profiles, create a custom profile or specify options manually: 
# Manual specification
retis collect -p nf_conntrack -p kfree_skb_reason --skb-sections

​
Filtering and Tracking

​
Filter Visibility Requirement

Filtering and tracking only work if a packet is seen at least once in a form where it can be matched against the filter.
Example problem: Tracking SNATed packets only at skb:consume_skb with a filter on the original address won’t generate events. 
# Won't work: packet is already NATed at consume_skb
retis collect \
  --filter-ip 10.0.0.1 \
  -p skb:consume_skb
Why: At consume_skb, the packet’s source address has already been translated. The filter looking for 10.0.0.1 doesn’t match the translated address. Solution: Include probes where the packet appears in its original form: 
# Works: catches packet before and after NAT
retis collect \
  --filter-ip 10.0.0.1 \
  -p net:net_dev_start_xmit \
  -p skb:consume_skb

​
Filter Size Limit

eBPF filters are limited to 4096 instructions.
As explained in the filtering documentation, filters are compiled to eBPF instructions. Impact: Very complex filters may exceed the instruction limit: 
# May fail if too complex
retis collect \
  --filter-ip 10.0.0.1 \
  --filter-ip 10.0.0.2 \
  --filter-ip 10.0.0.3 \
  # ... many more conditions
Error message: 
Error: BPF filter too large (> 4096 instructions)
Workaround:
  1. Simplify the filter expression
  2. Split into multiple collection runs
  3. Use post-processing filters (Python, jq) instead

​
eBPF Limitations

​
Kernel Version Requirements

Retis requires modern eBPF features:
  • BPF Type Format (BTF)
  • CO-RE (Compile Once - Run Everywhere)
  • Modern BPF helpers
Minimum recommended: Linux 5.10+ Workaround for older kernels: Some features may work on older kernels, but functionality is limited. Check compatibility table in the documentation.

​
Verifier Constraints

The eBPF verifier may reject certain operations:
  • Very deep stack traces
  • Complex packet parsing
  • Large data structures
Symptom: Collection fails with verifier error messages. Workaround: Reduce collection scope: 
# Disable stack traces if they cause verifier issues
retis collect -p kfree_skb_reason  # without --stack

​
Performance Considerations

​
High Traffic Impact

Collecting events on high-traffic systems can impact performance and generate large data files.
Recommendations:
  1. Use filters to reduce event volume: 
    retis collect --filter-ip 192.168.1.1
  2. Limit collection time: 
    retis collect --timeout 10s
  3. Use specific probes instead of wildcards: 
    # Specific
retis collect -p kfree_skb_reason

# Avoid on production
retis collect -p 'net:*'  # Too many events

​
Event Loss

Under extreme load, events may be lost due to ring buffer overflow. Indicators:
  • Gaps in tracking sequences
  • Warning messages during collection
Workaround:
  • Increase ring buffer size (if supported)
  • Use more aggressive filtering
  • Reduce probe count

​
Data File Compatibility

​
Version Compatibility

Event file format may change between Retis versions. Recommendation: Use the same Retis version for collection and analysis: 
# Check version
retis --version

# Collection
retis collect ...

# Analysis (use same version)
retis print
retis sort

​
Platform Support

​
Architecture

Retis is primarily developed and tested on x86_64. Other architectures (ARM64, etc.) may have:
  • Limited testing
  • Architecture-specific issues
  • Missing features

​
Kernel Configuration

Retis requires specific kernel features:
  • CONFIG_BPF=y
  • CONFIG_BPF_SYSCALL=y
  • CONFIG_DEBUG_INFO_BTF=y
  • Tracepoint support
Workaround: If BTF is missing, some distributions provide BTF separately. Check your distribution’s documentation.

​
Getting Help

If you encounter limitations not listed here:
  1. Check the GitHub Issues
  2. Review the compatibility documentation
  3. Ask in the community channels
  4. File a new issue with:
    • Retis version (retis --version)
    • Kernel version (uname -r)
    • Reproduction steps
    • Error messages

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us