Installation and Quick Start ​

Purpose and Scope ​

This document guides you through installing eCapture and running your first SSL/TLS plaintext capture. It covers system requirements, installation methods (binary, Docker, package managers), and a basic capture workflow. For detailed information about specific modules and their capabilities, see Capture Modules. For command-line interface documentation, see Command Line Interface.

System Requirements ​

eCapture requires specific Linux kernel versions and permissions to function:

eCapture automatically detects whether your kernel supports BTF (BPF Type Format) and selects the appropriate eBPF bytecode mode (CO-RE or non-CO-RE). See eBPF Engine for details on bytecode selection.

Sources: README.md:14-16, README_CN.md:15-17

Installation Methods ​

Binary Installation ​

The simplest installation method is downloading pre-built ELF binaries from the GitHub releases page.

Installation Steps:

1. Download the appropriate release:

   bash

   # For x86_64
   wget https://github.com/gojue/ecapture/releases/download/v1.5.0/ecapture-v1.5.0-linux-x86_64.tar.gz
   
   # For aarch64
   wget https://github.com/gojue/ecapture/releases/download/v1.5.0/ecapture-v1.5.0-linux-arm64.tar.gz

2. Extract the archive:

   bash

   tar -zxvf ecapture-v*.tar.gz
   cd ecapture-v*-linux-*/

3. Verify installation:

   bash

   sudo ./ecapture --help

The binary is statically linked with libpcap and includes all necessary eBPF bytecode embedded via go-bindata (see assets/ebpf_probe.go). No additional dependencies are required.

Sources: README.md:50-56, CHANGELOG.md:140-195

Docker Installation ​

eCapture provides official Docker images for containerized deployment.

Installation Steps:

1. Pull the Docker image:

   bash

   docker pull gojue/ecapture:latest

2. Run eCapture in Docker:

   bash

   docker run --rm \
     --privileged=true \
     --net=host \
     -v /path/on/host:/data \
     gojue/ecapture tls -m pcap --pcapfile=/data/capture.pcapng

Docker Requirements:

• --privileged=true: Required for loading eBPF programs into the kernel
• --net=host: Required for capturing host network traffic
• Volume mount: Optional, for saving output files to the host filesystem

Sources: README.md:58-70, README_CN.md:58-67

Package Manager Installation ​

eCapture provides native packages for major Linux distributions.

Debian/Ubuntu:

# Download .deb package from releases
wget https://github.com/gojue/ecapture/releases/download/v1.5.0/ecapture_1.5.0_amd64.deb

# Install
sudo dpkg -i ecapture_1.5.0_amd64.deb

RHEL/Fedora:

# Download .rpm package from releases
wget https://github.com/gojue/ecapture/releases/download/v1.5.0/ecapture-1.5.0-1.x86_64.rpm

# Install
sudo rpm -ivh ecapture-1.5.0-1.x86_64.rpm

Sources: CHANGELOG.md:671-679, Diagram 6 from high-level architecture

Quick Start: First Capture ​

This section demonstrates capturing SSL/TLS plaintext from HTTPS traffic using the tls module.

Command Execution Flow ​

Basic TLS Capture ​

Command:

sudo ecapture tls

This command captures all SSL/TLS plaintext traffic on the system using OpenSSL/BoringSSL libraries.

Expected Output:

2024-09-15T11:51:31Z INF AppName="eCapture(旁观者)"
2024-09-15T11:51:31Z INF HomePage=https://ecapture.cc
2024-09-15T11:51:31Z INF Repository=https://github.com/gojue/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 INF BTF bytecode mode: CORE. btfMode=0
2024-09-15T11:51:31Z INF Module initialization. isReload=false moduleName=EBPFProbeOPENSSL
2024-09-15T11:51:31Z WRN OpenSSL/BoringSSL version not found, used default version OpenSSL Version=linux_default_3_0
2024-09-15T11:51:31Z INF BPF bytecode file is matched. bpfFileName=user/bytecode/openssl_3_0_0_kern_core.o
2024-09-15T11:51:31Z INF module started successfully. moduleName=EBPFProbeOPENSSL

2024-09-15T11:51:53Z ??? UUID:233851_233851_curl_5_1_172.16.71.1:51837, Name:HTTP2Request, Type:2
GET / HTTP/2
Host: google.com
User-Agent: curl/7.81.0

Sources: README.md:72-149, main.go:1-12

Understanding the Output ​

Each captured event displays:

The UUID format is: PID_TID_ProcessName_FD_Direction_RemoteAddress:Port

Sources: protobuf/PROTOCOLS.md:24-42, user/event/event_ssl.go

Additional Capture Examples ​

Capture with PCAP output:

sudo ecapture tls -m pcap -i eth0 --pcapfile=output.pcapng

This saves captured plaintext in pcapng format, compatible with Wireshark. The file includes Decryption Secrets Blocks (DSB) for TLS key logging.

Capture with keylog mode:

sudo ecapture tls -m keylog --keylogfile=keys.log

This extracts TLS master secrets and traffic secrets, compatible with SSLKEYLOGFILE format for use with tshark or Wireshark.

Filter by process ID:

sudo ecapture tls --pid=1234

Filter by user ID:

sudo ecapture tls --uid=1000

Sources: README.md:172-253, README_CN.md:150-220

Module Selection Reference ​

eCapture provides multiple specialized modules. Use ecapture <module> to start a specific module:

Available Modules:

For detailed module documentation, see Capture Modules.

Sources: README.md:152-161, cli/cmd/root.go, Diagram 1 from high-level architecture

Verifying Installation ​

To verify your eCapture installation:

1. Check version:

   bash

   sudo ecapture --version

2. Verify kernel compatibility:

   bash

   uname -r  # Should be 4.18+ (x86_64) or 5.5+ (aarch64)

3. Check BTF support:

   bash

   cat /boot/config-$(uname -r) | grep CONFIG_DEBUG_INFO_BTF
   # Should show: CONFIG_DEBUG_INFO_BTF=y

4. Test basic capture:

   bash

   # In terminal 1: Start capture
   sudo ecapture tls
   
   # In terminal 2: Generate HTTPS traffic
   curl https://www.example.com
   
   # Terminal 1 should display captured plaintext

Sources: README_CN.md:228-233, Dependencies and System Requirements

Troubleshooting Common Issues ​

For detailed troubleshooting, see Troubleshooting and FAQ.

Sources: README.md:14-16, Inferred from common eBPF issues

Next Steps ​

After successful installation and basic capture:

1. Explore output modes: Learn about text, pcap, and keylog modes in OpenSSL Module
2. Module-specific features: See Capture Modules for GoTLS, database auditing, and more
3. Advanced configuration: Review Configuration System for filtering, custom settings
4. Remote GUI: Consider eCaptureQ for graphical interface
5. Event forwarding: Integrate with external tools via WebSocket (Protobuf Integration)

Sources: Table of contents structure, README.md:287-305