Dependencies and System Requirements ​

This page documents the system requirements, dependencies, and toolchain prerequisites for building and running eCapture. It covers kernel version requirements, supported architectures, build-time tooling, runtime dependencies, and Go package dependencies.

For information about the build process itself, see Build System. For installation instructions, see Installation and Quick Start.

Overview ​

eCapture has distinct requirements for build-time (compiling eBPF programs and Go binary) and runtime (executing the compiled binary). The system supports two compilation modes with different requirements:

• CO-RE (Compile Once - Run Everywhere): Requires BTF-enabled kernels (≥5.2) at runtime, but produces portable binaries
• Non-CO-RE: Requires kernel headers at build-time, produces kernel-specific binaries for older systems

Kernel Requirements ​

Minimum Kernel Versions ​

eCapture requires different minimum kernel versions depending on CPU architecture and compilation mode:

Critical Constraint: ARM64 support requires kernel 5.5 or newer regardless of compilation mode. This is enforced at runtime and documented in README.md:14.

Compilation Mode Requirements ​

The kernel version detection and handling is implemented in variables.mk:1-20 which sets KERNEL_LESS_5_2_PREFIX for kernels < 5.2. The runtime selection logic is in pkg/util/kernel/kernel.go.

BTF (BPF Type Format) Support ​

BTF is required for CO-RE mode. The runtime detection determines which bytecode variant to load:

Runtime Bytecode Selection Flow

Detection Implementation: The Module base class implements BTF detection in its initialization sequence. The file /sys/kernel/btf/vmlinux is checked using standard file existence checks. The btfMode field in the module struct stores the selected mode (0=CORE, 1=NON_CORE).

Bytecode Location: All variants are embedded in the binary via go-bindata at user/bytecode/ and selected at runtime based on kernel capabilities.

Sources: pkg/util/kernel/kernel.go, user/module/module.go, Makefile:122-134

Supported Architectures ​

Architecture detection is handled in variables.mk:25-35 which sets TARGET_ARCH, GOARCH, LINUX_ARCH, and LIBPCAP_ARCH based on uname -m or CROSS_ARCH environment variable. The Android build target is specified via Makefile:253-265 and uses non-CO-RE bytecode exclusively.

Sources: .github/workflows/go-c-cpp.yml:59-65, .github/workflows/release.yml:93-97, builder/init_env.sh:43-61

Build-Time Dependencies ​

Required Compilers and Tools ​

The following table lists all build-time dependencies with minimum versions:

Version Enforcement:

Build-time version checks are implemented in functions.mk:13-35:

• Clang: CLANG_VERSION >= 9 (extracted from clang --version)
• Go: GO_VERSION_MAJ=1 and GO_VERSION_MIN >= 24 (from go version)

The minimum Go version is declared in go.mod:3 as go 1.24.3. CI workflows use Go 1.24.6 as specified in .github/workflows/go-c-cpp.yml:15 and .github/workflows/release.yml:19.

Tool Symlinks:

The build system expects tools to be available without version suffixes. The builder/init_env.sh:75-79 script creates symlinks:

sudo ln -s /usr/bin/clang-14 /usr/bin/clang
sudo ln -s /usr/bin/llc-14 /usr/bin/llc
sudo ln -s /usr/bin/llvm-strip-14 /usr/bin/llvm-strip

Sources: .github/workflows/go-c-cpp.yml:16-24, .github/workflows/release.yml:17-19, functions.mk:13-35, go.mod:3, builder/init_env.sh:72-79

Kernel Headers (Non-CO-RE Only) ​

For non-CO-RE builds, kernel headers matching the target kernel are required. The build system searches for headers in multiple locations:

Header paths used during compilation Makefile:154-161:

• -I $(KERN_SRC_PATH)/arch/$(LINUX_ARCH)/include
• -I $(KERN_BUILD_PATH)/arch/$(LINUX_ARCH)/include/generated
• -I $(KERN_SRC_PATH)/include
• -I $(KERN_BUILD_PATH)/include/generated/uapi

Sources: Makefile:98-104, Makefile:146-183, builder/init_env.sh:81-89

Cross-Compilation Dependencies ​

Cross-compilation requires architecture-specific toolchains:

Sources: .github/workflows/go-c-cpp.yml:19, builder/init_env.sh:46-58

Go Dependencies ​

Core Dependencies ​

The project uses Go 1.24.3 as specified in go.mod:3. Major dependencies by category:

eBPF and Program Management

Network and Protocol Handling

CLI and API Framework

Dependency Details:

The following dependencies form the core infrastructure of eCapture:

1. cilium/ebpf v0.18.0 go.mod:6

   • Core eBPF library providing:
     • ebpf.CollectionSpec: Loads eBPF program bytecode
     • ebpf.Map: BPF map operations (read/write/update)
     • btf.Spec: CO-RE relocation handling for kernel structure compatibility
   • Used in all modules for low-level eBPF interactions

2. gojue/ebpfmanager v0.5.0 go.mod:8

   • Lifecycle management wrapper implementing:
     • manager.Manager: Orchestrates multiple probes and maps
     • manager.Probe: Uprobe/kprobe attachment metadata
     • manager.InitWithOptions(): eBPF program loading and verification
   • Abstracts cilium/ebpf complexity in user/module/module.go

3. cfc4n/gopacket v1.1.20 go.mod:60

   • Fork of google/gopacket with PCAP-NG DSB support
   • Key types:
     • layers.Ethernet, layers.IPv4: Packet construction
     • pcapgo.NgWriter: PCAP-NG file writing with decryption secrets
   • Used in user/module/probe_openssl.go and user/module/probe_gotls.go for pcap mode

4. jschwinger233/elibpcap v1.0.2 go.mod:10

   • BPF filter compiler wrapping libpcap's pcap_compile()
   • Function: NewBPFFilter(expr string) ([]bpf.RawInstruction, error)
   • Translates tcpdump-style expressions (e.g., "tcp port 443") into BPF bytecode
   • Used in user/module/probe_tc.go for packet filtering

5. shuLhan/go-bindata v4.0.0 go.mod:12

   • Build-time tool embedding eBPF .o files as Go byte arrays
   • Generates assets/ebpf_probe.go containing Asset(name string) ([]byte, error)
   • Invoked by Makefile:164-171 targets assets and assets_noncore

6. spf13/cobra v1.9.1 go.mod:13

   • CLI framework defining command tree:
     • rootCmd in cli/cmd/root.go
     • Module subcommands: tlsCmd, gotlsCmd, bashCmd in cli/cmd/
   • Provides flag parsing and help generation

7. gin-gonic/gin v1.10.0 go.mod:7

   • HTTP server framework for remote configuration API
   • Router defined in cli/cmd/root.go
   • Default listen address: localhost:28256
   • API endpoints documented in docs/remote-config-update-api.md

8. google.golang.org/protobuf v1.36.6 go.mod:19

   • Protocol buffer runtime for event serialization
   • Schema: protobuf/log.proto defining LogEntry, Event messages
   • Used in WebSocket event forwarding to eCaptureQ GUI

9. golang.org/x/crypto v0.45.0 go.mod:16

   • TLS structure definitions (tls.ConnectionState, tls.Config)
   • Used in user/config/config_gotls.go for Go binary symbol parsing

10. golang.org/x/net v0.47.0 go.mod:17

    • HTTP/2 framing: http2.Framer, http2.Frame
    • Used in pkg/event_processor/ for HTTP/2 request/response parsing

Sources: go.mod:3-20, go.sum:1-200

Indirect Dependencies ​

Critical indirect dependencies include:

Sources: go.mod:22-58

Runtime Dependencies ​

Minimal Runtime Requirements ​

The compiled ecapture binary has no runtime dependencies beyond kernel features:

Static Linking: The binary is statically linked with libpcap via CGO flags in functions.mk:48-53:

CGO_CFLAGS='-I$(CURDIR)/lib/libpcap/'
CGO_LDFLAGS='-L$(CURDIR)/lib/libpcap/ -lpcap -static'
LDFLAGS='-linkmode=external -extldflags -static'

This produces a self-contained binary with no shared library dependencies. Verification: ldd ecapture should show "not a dynamic executable".

Capability Checking: The capability check is implemented in cli/cmd/root.go using Linux capability syscalls. The check distinguishes between CAP_BPF (preferred on 5.8+) and CAP_SYS_ADMIN (required on older kernels).

Kernel Feature Requirements by Module ​

Module-specific kernel configuration requirements:

Required Kernel Config Symbols

Module Requirements Table:

Config Verification: Check current kernel config with:

grep -E "CONFIG_(UPROBE|KPROBES|BPF|NET_CLS_BPF)" /boot/config-$(uname -r)

All modules require CONFIG_BPF_SYSCALL=y as the base requirement.

Sources: user/module/probe_openssl.go:1-50, user/module/probe_tc.go:1-50, kern/tc_kern.c:1-30

Compilation Modes Comparison ​

CO-RE vs Non-CO-RE ​

Compilation Flag Differences:

CO-RE Makefile:122-134:

clang -target bpfel -D__TARGET_ARCH_$(LINUX_ARCH) \
  -D__BPF_TRACING__ -DCORE \
  -I/usr/include/$(LINUX_ARCH)-linux-gnu \
  -g -O2 -c kern/openssl_kern.c -o openssl_kern_core.o

Non-CO-RE Makefile:146-166:

clang -D__KERNEL__ -D__ASM_SYSREG_H \
  -I $(KERN_SRC_PATH)/arch/$(LINUX_ARCH)/include \
  -I $(KERN_BUILD_PATH)/include/generated \
  -I $(KERN_SRC_PATH)/include \
  -I $(KERN_BUILD_PATH)/include/generated/uapi \
  -g -O2 -emit-llvm -c kern/openssl_kern.c -o - | \
llc -march=bpf -filetype=obj -o openssl_kern_noncore.o

Key difference: CO-RE uses -target bpfel for direct BPF output, while non-CO-RE uses LLVM IR (-emit-llvm) then llc for compilation. Non-CO-RE includes explicit kernel header paths.

Bytecode Embedding: Both variants are embedded via go-bindata in Makefile:243-249 and stored in assets/ebpf_probe.go. Runtime selection occurs in module initialization.

Sources: Makefile:122-183, variables.mk:1-50

Development Environment Setup ​

Automated Setup (Ubuntu) ​

The project provides builder/init_env.sh for automated environment setup:

Version-specific clang selection in builder/init_env.sh:16-39:

• Ubuntu 20.04 (Focal): clang-10, llvm-10
• Ubuntu 22.04 (Jammy): clang-12, llvm-12
• Ubuntu 23.04 (Lunar): clang-15, llvm-15
• Ubuntu 23.10 (Mantic): clang-15, llvm-15
• Ubuntu 24.04 (Noble): clang-18, llvm-18

The script creates symlinks /usr/bin/clang → /usr/bin/clang-N to ensure consistent naming.

Go Installation: The script downloads Go 1.24.6 from https://golang.google.cn/dl/go1.24.6.linux-{amd64,arm64}.tar.gz (using Chinese mirror) as shown in builder/init_env.sh:63-64 and builder/init_env.sh:94-97, then extracts to /usr/local/go.

Sources: builder/init_env.sh:1-106

Manual Setup ​

For manual setup, install these package groups:

Essential Tools:

sudo apt-get install build-essential pkgconf libelf-dev libssl-dev

LLVM Toolchain (version-specific):

# Ubuntu 22.04 and later
sudo apt-get install llvm-14 clang-14

# Create version-agnostic symlinks (required by Makefile)
sudo ln -sf /usr/bin/clang-14 /usr/bin/clang
sudo ln -sf /usr/bin/llc-14 /usr/bin/llc
sudo ln -sf /usr/bin/llvm-strip-14 /usr/bin/llvm-strip

Kernel Tools:

sudo apt-get install linux-tools-common linux-tools-generic flex bison

Cross-Compilation (optional):

# For arm64 target on x86_64 host
sudo apt-get install gcc-aarch64-linux-gnu

# For x86_64 target on arm64 host (Ubuntu 24.04+)
sudo apt-get install gcc-x86-64-linux-gnu

Kernel Headers (for non-CO-RE mode only):

sudo apt-get install linux-source
cd /usr/src
sudo tar -xf linux-source-*.tar.bz2
cd linux-source-*/

# Prepare headers for native architecture
sudo make oldconfig
sudo make prepare

# For cross-compilation, prepare target architecture headers
sudo make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- prepare

Go Installation:

# Download and install Go 1.24.3 or newer
wget https://go.dev/dl/go1.24.6.linux-amd64.tar.gz
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.24.6.linux-amd64.tar.gz

# Add to PATH
export PATH=$PATH:/usr/local/go/bin

Sources: .github/workflows/go-c-cpp.yml:16-33, builder/init_env.sh:72-106

Docker Build Environment ​

The project provides a Dockerfile for containerized builds:

The multi-stage build builder/Dockerfile:1-39:

1. Builder stage: Full toolchain on Ubuntu 22.04
2. Release stage: Minimal Alpine image with static binary

Build for multiple architectures:

docker buildx build --platform linux/amd64,linux/arm64 -t ecapture:latest .

Sources: builder/Dockerfile:1-39, .github/workflows/release.yml:101-129

Verification Commands ​

After setup, verify dependencies:

# Check tool versions (enforced by functions.mk:13-35)
clang --version          # Should be >= 9.0
go version               # Should be >= 1.24.3 (go.mod:3)
llc --version            # Should match clang version
llvm-strip --version     # Should match clang version
bpftool version          # Any version

# Check BTF support (runtime, required for CO-RE)
ls -l /sys/kernel/btf/vmlinux  # Should exist for CO-RE mode
file /sys/kernel/btf/vmlinux   # Should show "BTF data"

# Check eBPF kernel configs (from /boot/config-$(uname -r))
grep CONFIG_BPF_SYSCALL /boot/config-$(uname -r)     # Must be =y (all modules)
grep CONFIG_UPROBE_EVENTS /boot/config-$(uname -r)   # =y (TLS/audit modules)
grep CONFIG_KPROBES /boot/config-$(uname -r)         # =y (connection tracking)
grep CONFIG_NET_CLS_BPF /boot/config-$(uname -r)     # =y (TC packet capture)
grep CONFIG_NET_SCH_INGRESS /boot/config-$(uname -r) # =y (TC ingress qdisc)

# Verify static linking (should show "not a dynamic executable")
ldd ./bin/ecapture
# Expected output: "not a dynamic executable" or "statically linked"

# Check libpcap static library presence (build-time only)
ls -l ./lib/libpcap/libpcap.a

# Verify Go dependencies
go mod verify  # Should show "all modules verified"

Runtime Capability Verification:

# Check process capabilities (requires root or CAP_SYS_ADMIN)
sudo ./bin/ecapture --help
# Should not show capability errors

# For kernel 5.8+, check for CAP_BPF and CAP_PERFMON
sudo setcap cap_sys_admin,cap_bpf,cap_perfmon=eip ./bin/ecapture
getcap ./bin/ecapture

Build System Verification:

# Run environment check from Makefile
make env
# Should display all variables (CLANG_VERSION, GO_VERSION, KERN_RELEASE, etc.)

# Test CO-RE build
make clean
make all

# Test non-CO-RE build
make clean
make nocore

Sources: functions.mk:2-39, go.mod:3, Makefile:19-64, README.md:14-16

Common Issues ​

Clang Version Too Old ​

Problem: Build fails with "you MUST use clang 9 or newer"

Solution: Install a newer clang version and create symlinks builder/init_env.sh:75-79:

sudo apt-get install clang-14 llc-14 llvm-strip-14
sudo ln -sf /usr/bin/clang-14 /usr/bin/clang

Missing Kernel Headers ​

Problem: Non-CO-RE build fails with "linux source not found"

Solution: Install and prepare kernel headers Makefile:98-104:

sudo apt-get install linux-source
cd /usr/src && sudo tar -xf linux-source-*.tar.bz2
cd linux-source-*/ && sudo make prepare

Go Version Too Old ​

Problem: Build fails with "you MUST use golang 1.24 or newer"

Solution: Download Go 1.24.6+ from golang.org/dl and update PATH.

Sources: functions.mk:13-35, Makefile:98-104, builder/init_env.sh:72-89