Installation and Quick Start ​

This page provides instructions for installing eCapture and running your first capture. It covers system requirements, installation methods (binary download, Docker, source compilation), and basic usage examples to get started capturing SSL/TLS plaintext traffic.

For detailed information about compilation options and customization, see Compilation. For comprehensive CLI documentation, see Command Line Interface. For understanding the underlying architecture, see Architecture.

System Requirements ​

eCapture has specific kernel and architecture requirements due to its eBPF-based implementation:

Kernel Version Requirements ​

Additional Requirements ​

• Privileges: ROOT (superuser) permissions required
• BTF Support: Optional but recommended for CO-RE mode (better portability)
• Supported Platforms: Linux, Android
• Unsupported Platforms: Windows, macOS

BTF (BPF Type Format) support can be verified with:

# Check if kernel has BTF support
cat /boot/config-$(uname -r) | grep CONFIG_DEBUG_INFO_BTF
# Should output: CONFIG_DEBUG_INFO_BTF=y

System Architecture Detection Diagram ​

Sources: README.md:13-16, README_CN.md:14-17, .github/workflows/go-c-cpp.yml:10-127

Installation Methods ​

eCapture provides three primary installation methods: pre-built binary downloads, Docker containers, and source compilation.

Method 1: Binary Release Download ​

The simplest installation method is downloading pre-compiled binaries from GitHub releases.

Download and Extract ​

# Download latest release (replace VERSION with actual version, e.g., v0.8.6)
VERSION=v1.5.1
ARCH=amd64  # or arm64

# Download archive
wget https://github.com/gojue/ecapture/releases/download/${VERSION}/ecapture-${VERSION}-linux-${ARCH}.tar.gz

# Extract
tar -xzf ecapture-${VERSION}-linux-${ARCH}.tar.gz
cd ecapture-${VERSION}-linux-${ARCH}

# Verify
sudo ./ecapture --help

Binary Package Contents ​

Each release archive contains:

Architecture-Specific Binaries ​

Sources: README.md:48-56, README_CN.md:48-55, .github/workflows/release.yml:88-100

Method 2: Docker Container ​

Docker provides an isolated environment for running eCapture without installing dependencies on the host system.

Pull and Run Docker Image ​

# Pull latest image
docker pull gojue/ecapture:latest

# Run with required privileges
docker run --rm \
  --privileged=true \
  --net=host \
  -v /path/on/host:/path/in/container \
  gojue/ecapture:latest tls

# Example: Save output to host directory
docker run --rm \
  --privileged=true \
  --net=host \
  -v $(pwd)/captures:/captures \
  gojue/ecapture:latest tls --pcapfile=/captures/output.pcapng

Docker Build Process ​

The Docker image is built using a multi-stage process:

Docker Configuration Details:

• Base Image: Ubuntu 22.04 for building, Alpine for runtime
• Required Flags: --privileged=true (eBPF requires kernel access), --net=host (network monitoring)
• Volume Mounts: Use -v to save output files to host
• Multi-Architecture: Supports linux/amd64 and linux/arm64

Sources: README.md:58-70, README_CN.md:57-67, builder/Dockerfile:1-39

Method 3: Build from Source ​

Building from source allows customization and provides the latest development features.

Quick Build ​

# Clone repository
git clone https://github.com/gojue/ecapture.git
cd ecapture
git submodule update --init

# Install dependencies (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install -y \
  build-essential \
  pkgconf \
  libelf-dev \
  llvm-14 \
  clang-14 \
  linux-tools-common \
  linux-tools-generic \
  linux-source

# Set up environment
make env

# Build (includes both CO-RE and non-CO-RE)
make all

# Binary output location
./bin/ecapture --help

Build System Overview ​

Build Targets:

Cross-Compilation:

# Build for ARM64 on x86_64 host
CROSS_ARCH=arm64 make env
CROSS_ARCH=arm64 make all

# Build for Android
ANDROID=1 CROSS_ARCH=arm64 make nocore

Sources: Makefile:1-269, README.md:316-319, CHANGELOG.md:553-562, builder/init_env.sh:1-106

First Capture: TLS Module ​

After installation, verify eCapture is working by capturing SSL/TLS traffic.

Basic TLS Capture ​

The simplest capture command monitors all OpenSSL/BoringSSL encrypted traffic:

sudo ecapture tls

Expected Output Structure:

Example Output Walkthrough ​

2024-09-15T11:51:31Z INF AppName="eCapture(旁观者)"
2024-09-15T11:51:31Z INF Version=linux_arm64:0.8.6-20240915-d87ae48:5.15.0-113-generic
2024-09-15T11:51:31Z INF Listen=localhost:28256
2024-09-15T11:51:31Z WRN ========== module starting. ==========
2024-09-15T11:51:31Z INF Kernel Info=5.15.152 Pid=233698
2024-09-15T11:51:31Z INF BTF bytecode mode: CORE. btfMode=0
2024-09-15T11:51:31Z INF Hook masterKey function Functions=["SSL_get_wbio","SSL_in_before","SSL_do_handshake"]
2024-09-15T11:51:31Z INF target all process.

Output Field Explanations:

Understanding Captured Events ​

When traffic is captured, events appear with this structure:

2024-09-15T11:51:53Z ??? UUID:233851_233851_curl_5_1_172.16.71.1:51837, Name:HTTP2Request, Type:2, Length:304

Frame Type	=>	HEADERS
header field ":method" = "GET"
header field ":path" = "/"
header field ":authority" = "google.com"

Event UUID Format: {pid}_{pid}_{comm}_{fd}_{direction}_{remote_addr}:{remote_port}

Sources: README.md:72-149, README_CN.md:73-126

Common Usage Patterns ​

Capture Modes ​

eCapture TLS module supports three output modes:

Text Mode (Default) ​

Direct plaintext output to console or file:

# Output to console
sudo ecapture tls

# Output to file
sudo ecapture tls > capture_output.txt

# With specific PID filter
sudo ecapture tls --pid=1234

PCAP Mode ​

Save as packet capture file for Wireshark analysis:

# Basic pcap capture
sudo ecapture tls -m pcap -i eth0 --pcapfile=capture.pcapng

# With network filter
sudo ecapture tls -m pcap -i eth0 --pcapfile=https.pcapng tcp port 443

# Multiple interfaces
sudo ecapture tls -m pcap -i eth0,wlan0 --pcapfile=multi.pcapng

PCAP Filter Syntax: Supports tcpdump/BPF filter expressions (e.g., host 192.168.1.1 and tcp port 443)

Keylog Mode ​

Export TLS master secrets for offline decryption:

# Generate keylog file
sudo ecapture tls -m keylog --keylogfile=tls_keys.log

# Use with tshark for real-time decryption
sudo ecapture tls -m keylog --keylogfile=keys.log &
tshark -o tls.keylog_file:keys.log -Y http -T fields -e http.file_data -f "port 443" -i eth0

Sources: README.md:172-253, README_CN.md:150-219, CHANGELOG.md:688-757

Module Selection ​

eCapture provides specialized modules for different targets:

Quick Module Examples:

# Capture bash commands
sudo ecapture bash

# Capture MySQL queries
sudo ecapture mysqld

# Capture Go TLS traffic
sudo ecapture gotls --elfpath=/path/to/go/binary

Sources: README.md:151-161, README_CN.md:128-139, main.go:1-11

Verification and Troubleshooting ​

Verify Installation ​

# Check version
sudo ecapture --version

# Display help
sudo ecapture --help

# Test module availability
sudo ecapture tls --help

Common Issues ​

Issue: "Kernel version too low" ​

Solution: Verify kernel version meets minimum requirements:

uname -r
# Should be >= 4.18 for x86_64, >= 5.5 for aarch64

Issue: "Permission denied" ​

Solution: eCapture requires ROOT privileges:

# Use sudo
sudo ecapture tls

# Or check capabilities
sudo setcap cap_sys_admin,cap_bpf+ep ./ecapture
./ecapture tls

Issue: "OpenSSL version not found" ​

Solution: eCapture will use default version. You can specify library path:

# Auto-detect from ld.so.conf
sudo ecapture tls

# Manually specify library
sudo ecapture tls --libssl=/usr/lib/x86_64-linux-gnu/libssl.so.3

# For static binaries
sudo ecapture tls --libssl=/path/to/static/binary

Issue: "BTF not available" ​

Solution: Non-CO-RE mode automatically selected. For better compatibility:

# Install linux-headers
sudo apt-get install linux-headers-$(uname -r)

# Or use non-CO-RE build explicitly
# (Binary includes both modes, selects automatically)

Sources: README.md:163-170, .github/workflows/go-c-cpp.yml:16-33

Environment Setup Script ​

For development environments, eCapture provides an automated setup script:

# Run initialization script (Ubuntu only)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/gojue/ecapture/master/builder/init_env.sh)"

Script Actions:

1. Detects Ubuntu version and sets appropriate clang version
2. Installs build dependencies (clang, llvm, linux-source, gcc cross-compilers)
3. Extracts and prepares kernel headers
4. Installs Go 1.24.6
5. Clones eCapture repository
6. Configures cross-compilation support

Supported Ubuntu Versions:

Sources: builder/init_env.sh:1-106

CI/CD Build Verification ​

eCapture uses GitHub Actions for continuous integration. The build process validates:

Build Validation:

• Native Compilation: Both x86_64 and aarch64 runners
• Cross-Compilation: Bidirectional (x86_64 ↔ aarch64)
• Multiple Modes: CO-RE and non-CO-RE on both architectures
• Android Support: Non-CO-RE for Android with BoringSSL focus
• Code Quality: golangci-lint and race detector tests

Sources: .github/workflows/go-c-cpp.yml:1-128, .github/workflows/release.yml:1-129

Next Steps ​

After completing installation and running your first capture:

• Explore CLI Options: See Command Line Interface for detailed flag documentation
• Understand Architecture: Learn how eCapture works in Architecture
• Module Deep Dives:
  • OpenSSL Module for TLS/SSL capture details
  • GoTLS Module for Go-specific captures
  • System Audit Modules for bash/database auditing
• Output Formats: See Output Formats for PCAP, keylog, and text mode details
• Custom Builds: Refer to Build System for compilation customization
• Dependencies: Check Dependencies and System Requirements for detailed prerequisites

Sources: README.md:1-335, README_CN.md:1-315, CHANGELOG.md:1-100