Requirements and Installation ​

Purpose and Scope ​

This page defines the host environment requirements, kernel configurations, privilege requirements (root or Linux capabilities), and installation procedures required to run eCapture. It details the runtime dependencies for the three core TLS capture modules (tls for OpenSSL/BoringSSL, gotls for Go native TLS, and gnutls for GnuTLS) and explains the interface prerequisites specific to pcapng capture modes.

Sources: docs/compilation.md:26-37, docs/minimum-privileges.md:5-34

Supported Platforms and Architectures ​

eCapture relies on eBPF uprobes, tracepoints, and Traffic Control (TC) hooks, which impose strict kernel version and architecture constraints.

Sources: docs/compilation.md:28-30, docs/minimum-privileges.md:124-126

Kernel and BTF Requirements ​

eCapture operates in two bytecode modes: CO-RE (Compile Once – Run Everywhere) using BPF Type Format (BTF) and non-CO-RE (fallback compilation using local kernel headers).

BTF Detection Logic ​

At startup, eCapture checks whether kernel BTF is enabled by inspecting /sys/kernel/btf/vmlinux or scanning fallback directories for kernel ELF images via checkKernelBTF() pkg/util/ebpf/bpf.go:89-98. If BTF is absent, it falls back to inspecting kernel configuration files (/proc/config.gz, /boot/config-*) for CONFIG_DEBUG_INFO_BTF pkg/util/ebpf/bpf_linux.go:28-31.

Sources: pkg/util/ebpf/bpf.go:89-143, pkg/util/ebpf/bpf_linux.go:48-80

Mandatory Kernel Configurations ​

Regardless of BTF, the target kernel must have the following options enabled, verified by IsEnableBPF() pkg/util/ebpf/bpf.go:146-170:

• CONFIG_BPF
• CONFIG_UPROBES
• CONFIG_ARCH_SUPPORTS_UPROBES

Sources: pkg/util/ebpf/bpf.go:30-44, pkg/util/ebpf/bpf.go:146-170

Privileges, Root, and Capabilities ​

Loading eBPF programs, attaching uprobes to shared libraries, and binding TC classifiers require elevated privileges.

Linux Capabilities Breakdown ​

Starting with Linux 5.8, eBPF privileges were unbundled from CAP_SYS_ADMIN. The required capabilities vary by kernel version and operating mode:

Sources: docs/minimum-privileges.md:5-34

Capability Assignment via setcap ​

To run eCapture without full root or sudo privileges, assign extended attributes to the binary:

# For kernel >= 5.8 in pcapng mode
sudo setcap 'cap_bpf,cap_perfmon,cap_net_admin,cap_sys_ptrace=eip' /usr/local/bin/ecapture

# Verify capabilities
getcap /usr/local/bin/ecapture

Sources: docs/minimum-privileges.md:45-73

Sources: docs/minimum-privileges.md:120-135

pcapng Interface Prerequisites ​

When operating in pcapng mode (-m pcap or -m pcapng), eCapture intercepts network packets via Traffic Control (TC) ebpf hooks on a specified network interface (-i <interface>) and injects decrypted payload secrets into a Decryption Secrets Block (DSB).

• Prerequisites:
  • CAP_NET_ADMIN capability (or running as root).
  • A valid, active network interface name (e.g., eth0, ens160, wlan0).
  • When running inside Docker, --net=host is mandatory to access and attach TC filters to host network interfaces.

Sources: docs/minimum-privileges.md:13-34, docs/minimum-privileges.md:113-118

Module-Specific Prerequisites ​

The three core TLS capture modules target different underlying runtimes and shared library implementations:

1. tls (OpenSSL and BoringSSL):
   • Targets dynamic libraries: libssl.so (OpenSSL 1.0.x, 1.1.x, 3.0+) or BoringSSL (Android / Chrome / custom binaries).
   • Requires symbol resolution for functions such as SSL_do_handshake, SSL_read, and SSL_write.
2. gotls (Go Native TLS):
   • Targets compiled Go binaries using crypto/tls.
   • Requires DWARF symbol tables or function table offsets to locate internal Go TLS structures (e.g., crypto/tls.(*Conn).read / write).
3. gnutls (GnuTLS):
   • Targets applications linked against libgnutls.so.
   • Requires compatible version bindings for GnuTLS handshake and record-layer state functions.

Sources: docs/compilation.md:132-154

Installation and Compilation from Source ​

eCapture is built using Go and Clang/LLVM.

Build Toolchain Prerequisites ​

• Golang: 1.26.0 or newer
• Clang / LLVM: 9.0 or newer (LLVM 18 required for LoongArch64)
• CMake: 3.18.4 or newer
• Libelf: libelf-dev

Compilation Commands ​

git clone --recurse-submodules https://github.com/gojue/ecapture.git
cd ecapture
make
bin/ecapture

Sources: docs/compilation.md:33-67