Configuration System ​

The Configuration System in eCapture provides a flexible, hierarchical approach to managing settings for different capture modules. It defines a common interface (IConfig) that all module configurations must implement, while allowing module-specific extensions. The system supports both compile-time configuration via CLI flags and runtime updates via HTTP API.

For information about the Module System that consumes these configurations, see Module System and Lifecycle. For CLI command structure, see Command Line Interface.

Configuration Architecture ​

The configuration system uses an interface-based design with a base implementation and module-specific extensions:

Sources: user/config/iconfig.go:24-70, user/config/iconfig.go:95-112, user/config/config_gotls.go:77-94

IConfig Interface ​

The IConfig interface defines the contract that all configuration implementations must satisfy:

Sources: user/config/iconfig.go:24-70

BaseConfig Structure ​

BaseConfig provides the base implementation of IConfig with common fields shared across all modules:

Key Fields:

• Pid/Uid: Process and user filters passed to eBPF programs via constant editors user/module/probe_openssl.go:366-394
• PerCpuMapSize: Controls eBPF map buffer size for event data user/config/iconfig.go:178-184
• BtfMode: Determines whether to use CO-RE (BTF-enabled) or non-CO-RE bytecode user/module/imodule.go:154-169
• LoggerAddr/EventCollectorAddr: Separate destinations for logs vs captured events cli/cmd/root.go:146-147
• EcaptureQ: Enables local server mode for remote client connections cli/cmd/root.go:149

Sources: user/config/iconfig.go:95-112, user/config/iconfig.go:114-211

Module-Specific Configurations ​

Each capture module extends BaseConfig with module-specific settings:

OpensslConfig ​

Configuration for OpenSSL/BoringSSL TLS capture:

type OpensslConfig struct {
    BaseConfig
    Openssl      string  // libssl.so path
    CGroupPath   string  // cgroup path for filtering
    Model        string  // "text", "pcap", "keylog"
    KeylogFile   string  // Output file for TLS keys
    PcapFile     string  // Output file for packets
    Ifname       string  // Network interface for TC
    SslVersion   string  // OpenSSL version string
    PcapFilter   string  // BPF filter expression
    IsAndroid    bool    // Android detection flag
    AndroidVer   string  // Android version
}

Sources: cli/cmd/tls.go:26, cli/cmd/tls.go:51-58, user/module/probe_openssl.go:126-174

GoTLSConfig ​

Configuration for Go TLS capture with ELF analysis:

type GoTLSConfig struct {
    BaseConfig
    Path                  string              // Go binary path
    PcapFile              string
    KeylogFile            string
    Model                 string
    Ifname                string
    PcapFilter            string
    goElf                 *elf.File           // Parsed ELF file
    Buildinfo             *buildinfo.BuildInfo // Go build metadata
    ReadTlsAddrs          []int               // Uprobe addresses for Read
    GoTlsWriteAddr        uint64              // Uprobe address for Write
    GoTlsMasterSecretAddr uint64              // Uprobe address for master secrets
    IsPieBuildMode        bool                // PIE detection
    goSymTab              *gosym.Table        // Go symbol table
}

Key Feature: Check() method performs extensive ELF analysis to locate function addresses user/config/config_gotls.go:103-213

Sources: user/config/config_gotls.go:77-94, cli/cmd/gotls.go:26, cli/cmd/gotls.go:43-48

Other Module Configurations ​

Configuration Lifecycle ​

The configuration flows through multiple stages from CLI input to module consumption:

Sources: cli/cmd/root.go:156-175, cli/cmd/root.go:249-403, user/module/probe_openssl.go:109-176, user/module/probe_openssl.go:361-395

Configuration Transfer to Modules ​

The setModConfig function transfers global settings to module-specific configurations:

Transfer Logic:

1. Global command-line flags (pid, uid, debug, etc.) are parsed into globalConf cli/cmd/root.go:134-153
2. Module-specific flags are parsed into module config (e.g., oc for OpenSSL) cli/cmd/tls.go:51-58
3. setModConfig() copies global settings to module config cli/cmd/root.go:156-175
4. Build-time constant ByteCodeFiles determines bytecode file mode cli/cmd/root.go:167-174

Sources: cli/cmd/root.go:156-175, cli/cmd/root.go:134-153

Configuration Validation ​

Each module configuration implements a Check() method to validate settings before initialization:

OpensslConfig Validation ​

• Validates capture model (text/pcap/keylog) cli/cmd/tls.go:53
• Checks file paths (keylog file, pcap file) user/module/probe_openssl.go:130-148
• Detects OpenSSL version via ELF analysis user/module/probe_openssl.go:178-278
• Selects appropriate eBPF bytecode file user/module/probe_openssl.go:179-278

GoTLSConfig Validation ​

The most complex validation process:

Key Validation Steps:

1. Binary existence: Check Go binary path exists user/config/config_gotls.go:105-116
2. Build info extraction: Parse Go build metadata user/config/config_gotls.go:119-122
3. Architecture validation: Ensure binary matches host architecture user/config/config_gotls.go:130-150
4. PIE detection: Check for Position Independent Executable mode user/config/config_gotls.go:155-162
5. Symbol resolution: Locate crypto/tls function addresses user/config/config_gotls.go:169-211
6. RET instruction finding: Identify return addresses for uretprobe hooks user/config/config_gotls.go:219-285

Sources: user/config/config_gotls.go:103-213, user/config/config_gotls.go:219-285, user/config/config_gotls.go:350-446

Runtime Configuration Updates ​

eCapture supports runtime configuration updates via HTTP API without restarting the capture:

Runtime Update Flow:

1. HTTP server listens on configured address (default: 127.0.0.1:28256) cli/cmd/root.go:77
2. Client sends new configuration via HTTP POST cli/cmd/root.go:313-322
3. New config is sent to reRloadConfig channel cli/cmd/root.go:310
4. Main loop receives config update signal cli/cmd/root.go:368-384
5. Current module is closed gracefully cli/cmd/root.go:387-390
6. Module is reinitialized with new config cli/cmd/root.go:392-395
7. Module starts with updated settings cli/cmd/root.go:358-362

Limitations:

• Module type cannot be changed (e.g., cannot switch from tls to bash)
• Requires graceful cleanup of eBPF resources
• Brief capture interruption during reload

Sources: cli/cmd/root.go:309-322, cli/cmd/root.go:349-396, cli/cmd/root.go:77

Configuration Usage in Modules ​

Modules access configuration throughout their lifecycle:

During Initialization ​

Sources: user/module/probe_openssl.go:109-176, user/module/probe_openssl.go:126-154

During eBPF Setup ​

Configurations are passed to eBPF programs via constant editors:

func (m *MOpenSSLProbe) constantEditor() []manager.ConstantEditor {
    return []manager.ConstantEditor{
        {
            Name:  "target_pid",
            Value: uint64(m.conf.GetPid()),
        },
        {
            Name:  "target_uid",
            Value: uint64(m.conf.GetUid()),
        },
        {
            Name:  "less52",
            Value: kernelLess52,  // Based on kernel version check
        },
    }
}

Sources: user/module/probe_openssl.go:361-395

During Runtime ​

Modules continuously reference configuration for:

• Output formatting: Check GetHex() for hexadecimal output user/module/imodule.go:416-425
• Capture model: Determine how to process events (text/pcap/keylog) user/module/probe_openssl.go:287-296
• File paths: Write to configured output files user/module/probe_openssl.go:575-580
• Filter settings: Respect PID/UID filters user/module/probe_openssl.go:382-392

Sources: user/module/imodule.go:416-425, user/module/probe_openssl.go:287-296

Configuration Constants and Modes ​

TLS Capture Models ​

Sources: user/config/iconfig.go:73-79

BTF Modes ​

BTF Detection Logic:

1. Check if running in container user/module/imodule.go:175-178
2. Check for /sys/kernel/btf/vmlinux existence user/module/imodule.go:180-186
3. Default to CO-RE if BTF found, non-CO-RE otherwise user/module/imodule.go:154-189

Sources: user/config/iconfig.go:82-86, user/module/imodule.go:173-190

Bytecode File Modes ​

Build-Time Selection:

• Set via ByteCodeFiles variable during compilation cli/cmd/root.go:57
• Determines which bytecode files are embedded by go-bindata cli/cmd/root.go:167-174

Sources: user/config/iconfig.go:89-93, cli/cmd/root.go:57, cli/cmd/root.go:167-174

Configuration Serialization ​

All configurations implement Bytes() for JSON serialization:

func (c *BaseConfig) Bytes() []byte {
    b, e := json.Marshal(c)
    if e != nil {
        return []byte{}
    }
    return b
}

Use Cases:

• Logging: Configuration logged at startup cli/cmd/root.go:298-307
• Reloading: New configuration logged before reload cli/cmd/root.go:394
• Debugging: Configuration can be inspected via JSON output

Sources: user/config/iconfig.go:205-211, user/config/config_gotls.go:448-454

Configuration Best Practices ​

1. Always validate in Check(): Catch configuration errors before eBPF initialization
2. Use embedded BaseConfig: Reuse common functionality instead of reimplementing
3. Respect EnableGlobalVar(): Check kernel version before using global variables user/config/iconfig.go:194-203
4. Handle BTF gracefully: Support both CO-RE and non-CO-RE modes user/module/imodule.go:154-169
5. Provide sensible defaults: Use constants like DefaultMapSizePerCpu user/config/config_gotls.go:99
6. Document module-specific fields: Clear comments help users understand options

Sources: user/config/iconfig.go:194-203, user/module/imodule.go:154-169, user/config/config_gotls.go:97-101