Advanced Usage

Relevant source files

The following files were used as context for generating this wiki page:

Purpose and Scope

This page serves as the user-facing entry point for operating core TLS capture beyond basic examples. It covers troubleshooting diagnostic workflows, production integration and deployment considerations, and provides a pointer to non-core modules such as NSS/NSPR, Bash, Zsh, MySQL/MariaDB, and PostgreSQL. As a parent page, it summarizes key concepts and directs readers to dedicated child pages for deep technical details.

Sources: cli/cmd/common_config_test.go:48-186

4.1. TLS Troubleshooting

When operating tls (OpenSSL/BoringSSL), gotls (Go native TLS), and gnutls probes across text, keylog, and pcapng modes, operators may encounter issues such as library/binary mismatches, version support limits, empty events, missing secrets, incomplete pcapng files, BTF failures, privilege errors, network interface issues, or destination routing errors.

For a comprehensive diagnostic checklist, step-by-step troubleshooting procedures, and resolution strategies, see TLS Troubleshooting.

Sources: cli/cmd/common_config_test.go:188-216

4.2. Integration and Deployment

Production deployments require robust configuration management, secure event forwarding, and efficient resource utilization. Core TLS capture supports forwarding captured events via --eventaddr, integrating with additive output mechanisms like eCaptureQ, and dynamic configuration via HTTP endpoints (confighttp). Operators must also handle sensitive capture artifacts securely and evaluate performance impact under high load.

Figure 4.2: Integration and deployment flow connecting configuration, probes, and output destinations.

Sources: cli/cmd/common_config_test.go:25-74

For production guidance, security best practices, and performance evaluation, see Integration and Deployment.

Sources: cli/cmd/common_config_test.go:25-74

4.3. Other Modules

While the core capability of ecapture centers on TLS interception, the codebase includes several non-core probes for specific auditing and monitoring use cases. These include:

Bash & Zsh: Command auditing probes (bashProbe, zshProbe) tracking shell execution and exit codes.
MySQL & PostgreSQL: Database query capture probes (mysqlProbe, postgresProbe) for SQL auditing.
NSS/NSPR: Network Security Services probe (nsprProbe) for NSS-based applications.

Figure 4.3: Non-core probe factory mapping and configuration initialization.

Sources: cli/cmd/bash.go:20-24, cli/cmd/mysqld.go:23-27, cli/cmd/postgres.go:23-27, cli/cmd/zsh.go:23-27, cli/cmd/common_config_test.go:30-37

For supported targets, configuration flags, and usage references for these probes, see Other Modules.

Sources: cli/cmd/bash.go:27-40, cli/cmd/mysqld.go:30-46, cli/cmd/postgres.go:30-41, cli/cmd/zsh.go:30-41, cli/cmd/zsh.go:38-41

进阶使用

目的与范围

本页面是操作核心 TLS 抓取的基础示例之外的用户入口，涵盖排错诊断工作流、生产集成与部署考量，并提供对非核心模块（如 NSS/NSPR、Bash、Zsh、MySQL/MariaDB 以及 PostgreSQL）的简要指向。作为父级页面，它总结了核心概念，并将读者引导至专用的子页面以获取深入的技术细节。

Sources: cli/cmd/common_config_test.go:48-186

4.1. TLS 故障排查

在文本、密钥日志（keylog）和 pcapng 模式下操作 tls（OpenSSL/BoringSSL）、gotls（Go 原生 TLS）以及 gnutls 探针时，操作员可能会遇到库或二进制文件不匹配、版本支持限制、空事件、缺失密钥、不完整的 pcapng 文件、BTF 失败、权限错误、网络接口问题或目标路由错误等问题。

有关全面的诊断检查表、逐步排查步骤以及解决方法，请参阅 TLS Troubleshooting。

Sources: cli/cmd/common_config_test.go:188-216

4.2. 集成与部署

生产部署需要健壮的配置管理、安全的事件转发以及高效的资源利用。核心 TLS 抓取支持通过 --eventaddr 转发捕获的事件、与附加输出机制（如 eCaptureQ）集成，以及通过 HTTP 端点（confighttp）进行动态配置。操作员还必须安全处理敏感的抓取产物，并在高负载下评估性能影响。

图 4.2：连接配置、探针与输出目标的集成与部署流。

Sources: cli/cmd/common_config_test.go:25-74

有关生产指南、安全最佳实践和性能评估，请参阅 Integration and Deployment。

Sources: cli/cmd/common_config_test.go:25-74