Skip to main content
All the following requirements apply to commands collecting events, such as the collect sub-command.

​
Runtime Requirements

To collect events with Retis, the following requirements must be met:
1

Linux Capabilities

The Retis binary needs the following capabilities:
  • CAP_SYS_ADMIN
  • CAP_BPF
  • CAP_SYSLOG
See Running as non-root for details on setting capabilities.
2

Kernel Configuration

The running kernel must be compiled with the required kernel config options.
3

Kernel Debug Files

Retis requires access to:
  • /sys/kernel/btf - For parsing kernel functions and types
  • /proc/kallsyms - For kernel symbol information
4

Tracefs Mount

tracefs should be mounted to one of:
  • /sys/kernel/tracing (preferred)
  • /sys/kernel/debug/tracing
This allows filtering functions and events. Alternatively, use --allow-system-changes to let Retis mount tracefs automatically.

​
Kernel Kconfig Options

In order to collect events, Retis requires the following options to be set in the running kernel: 
CONFIG_BPF_SYSCALL=y
CONFIG_DEBUG_FS=y
CONFIG_DEBUG_INFO_BTF=y
CONFIG_KALLSYMS_ALL=y
CONFIG_KPROBES=y
CONFIG_PERF_EVENTS=y

​
Option Details

OptionPurpose
CONFIG_BPF_SYSCALLEnable BPF syscall for loading eBPF programs
CONFIG_DEBUG_FSProvide debugfs filesystem support
CONFIG_DEBUG_INFO_BTFInclude BTF (BPF Type Format) debug information
CONFIG_KALLSYMS_ALLExport all kernel symbols for tracing
CONFIG_KPROBESEnable kernel probes for dynamic tracing
CONFIG_PERF_EVENTSRequired for retrieving stack traces and performance events
Most modern Linux distributions enable these options by default. You can check your kernel’s configuration in /boot/config-$(uname -r) or /proc/config.gz.

​
Build Requirements

If you’re building Retis from source, you’ll need additional dependencies. See the From Sources section in the installation guide for details. Key build dependencies include:
  • rust >= 2021
  • clang
  • jq
  • libelf development files
  • libpcap development files
  • llvm
  • make
  • pkg-config
  • Python 3 development files (for Python feature support)

​
Supported Operating Systems

The following operating systems are known to be compatible with Retis. This list is not exhaustive, and Retis should be able to run on other distributions that meet the requirements.
Operating SystemNotes
FedoraAll officially supported versions including Rawhide
RHEL 9
CentOS Stream 9
RHEL 8>= 8.6
CentOS Stream 8>= 8.6
Ubuntu Jammy
For RHEL 8 and CentOS Stream 8, version 8.6 or later is required to ensure all necessary kernel features are available.

​
Verification

To verify your system meets the requirements:
1

Check kernel configuration

# Check if BTF is available
ls /sys/kernel/btf/vmlinux

# Check if kallsyms is available
cat /proc/kallsyms | head
2

Verify tracefs mount

mount | grep tracefs
# Should show tracefs mounted at /sys/kernel/tracing or /sys/kernel/debug/tracing
3

Test Retis

# Try running Retis with minimal permissions
retis --help

# Test collection (requires root or capabilities)
sudo retis collect --timeout 1

​
Troubleshooting

​
Missing BTF Information

If /sys/kernel/btf/vmlinux is not available, your kernel was not compiled with CONFIG_DEBUG_INFO_BTF. You’ll need to:
  • Upgrade to a newer kernel that includes BTF
  • Rebuild your kernel with BTF support enabled

​
Tracefs Not Mounted

If tracefs is not mounted, you can:
  • Mount it manually: sudo mount -t tracefs none /sys/kernel/tracing
  • Use the --allow-system-changes flag to let Retis mount it automatically

​
Permission Denied

If you encounter permission errors:
  • Run Retis with sudo for full access
  • Set the required capabilities (see Running as non-root)
  • Ensure tracefs is readable by your user (it’s typically root-only)

Build docs developers (and LLMs) love

Get started for freeTalk to us