Wazuh 5.0 Indexer Connector 配置完全指南indexerXML 解析、TLS 双向认证与 OpenSearch 高可用写入【免费下载链接】wazuhWazuh - The Open Source Security Platform. Unified XDR and SIEM protection for endpoints and cloud workloads.项目地址: https://gitcode.com/GitHub_Trending/wa/wazuh本指南以 Wazuh 5.0 Indexer Connector 模块的官方配置参考docs/ref/modules/indexer_connector/configuration.md为主体完整讲解 manager 端indexer配置块的每一个参数、TLS 证书体系、keystore 凭据存储以及连通性验证、证书管理与故障排查的完整实操流程。读完本文你将能够从零配置一个安全的生产级 Wazuh Manager → Wazuh IndexerOpenSearch数据通道并理解连接池、健康监控、负载均衡与批量写入等底层机制对配置决策的影响。1. 模块定位取代 Filebeat 的共享库Indexer Connector 不是独立守护进程而是一个被多个进程链接的共享库libindexer_connector源码位于 src/shared_modules/indexer_connector/负责 Wazuh Manager 与 Wazuh IndexerOpenSearch之间的全部数据索引操作——它是 Wazuh 5.0 中 Filebeat 的替代实现见 模块总览。它主要服务于三类写入方Vulnerability Scanner将 CVE 检测结果索引到wazuh-states-vulnerabilitiesInventory Sync将代理资产状态索引到wazuh-states-inventory-*与wazuh-states-fim-*Engine索引 SCA 结果及其它引擎生成的事件。库根据使用场景提供两个类公开 API 见 include/indexerConnector.hpp类模式队列适用场景IndexerConnectorSync同步内存最大 10 MB低延迟、有界写入Vulnerability Scanner / Inventory SyncIndexerConnectorAsync异步内存按字节限界max_queue_bytes非阻塞写入Engine缓冲事件在关闭时丢弃配置本文的主角indexerXML 块最终会被解析并转换为 JSON 配置对象传入上述构造器——因此理解 XML 参数与 JSON 字段的对应关系是正确配置的前提。2. Manager 配置总览配置文件/var/wazuh-manager/etc/wazuh-manager.confXML Sectionindexer内部选项Internal Options无——Indexer Connector 没有专属于自己的local_internal_options.conf选项连接与批量索引行为完全由 XML 配置及各调用模块的专用设置控制。Indexer Connector 配置的作用是建立到一个或多个 Indexer 节点的 TLS 加密连接用于数据索引与威胁情报源feed同步。必填约束hosts与ssl均为必填项。解析器在两者缺失或为空时会直接报错——这一点与源码实现完全一致indexerConnectorSyncImpl.hpp 中if (!config.contains(hosts) || config.at(hosts).empty())会抛出IndexerConnectorException(No hosts found in the configuration)。2.1 hostsIndexer 节点 URL 列表每个节点用一个host子元素指定。默认值无必填配置允许值http://address:port或https://address:port形式的 URL注意至少定义一个 host必须以http://或https://开头且包含端口号连接器会对所有列出的 host 做负载均衡并在某个节点不可用时自动故障转移failover。示例hosts hosthttps://127.0.0.1:9200/host /hosts2.2 sslTLS/SSL 配置块。默认值无即使为空也要求存在该配置块允许值包含子选项certificate_authorities、certificate、key注意即使不做任何 TLS 校验解析器也要求该块存在。从源码看indexerConnectorSyncImpl.hpp 中只有当config.contains(ssl)时才会读取三个子项同时 QA 测试配置如 test_initialize_indexer_connector/config.json中可以看到hosts与空ssl并存是合法的开发形态。2.2.1 certificate_authorities用于校验 Indexer TLS 证书的一个或多个 CA 证书路径每个 CA 用一个ca子元素列出。默认值无允许值PEM 编码 CA 证书路径相对或绝对注意省略该项将禁用服务端证书校验生产环境不推荐路径在启动时必须在磁盘上真实存在。源码在解析单个 CA 路径时会先检查std::filesystem::exists文件不存在直接抛异常The CA root certificate file: path does not exist.配置多个ca时源码通过Utils::CertHelper::mergeCaRootCertificates将多个根证书合并后使用。示例ssl certificate_authorities ca/var/wazuh-manager/etc/certs/root-ca.pem/ca /certificate_authorities /ssl2.2.2 certificatemanager 用于与 Indexer 做**双向认证mTLS**的客户端 TLS 证书路径。默认值无允许值PEM 编码证书路径相对或绝对注意当 Indexer 要求客户端证书认证时必填路径在启动时必须存在。2.2.3 key与客户端证书配对的私钥路径。默认值无允许值PEM 编码私钥路径相对或绝对注意指定了certificate则必须指定key路径在启动时必须存在。在源码中ssl.certificate与ssl.key最终会传入SecureCommunication::builder().sslCertificate(...).sslKey(...)连同caRootCertificate一起构建 TLS 通道见 indexerConnectorAsyncImpl.hpp。3. Indexer 凭据写入 Keystore 而非配置文件如果 Wazuh Indexer 启用了用户名/密码认证例如内置admin用户不要把凭据明文写进配置文件应存入 Wazuh Keystorewazuh-manager-keystore -f indexer -k username -v admin wazuh-manager-keystore -f indexer -k password -v passwordIndexer Connector 会在启动时自动从 keystore 的indexer列族column family读取这两个值。源码证据indexerConnectorAsyncImpl.hpp 定义了列族与键名常量INDEXER_COLUMN {indexer}、USER_KEY {username}、PASSWORD_KEY {password}构造器通过Keystore::get(INDEXER_COLUMN, USER_KEY)/Keystore::get(INDEXER_COLUMN, PASSWORD_KEY)读取同步与异步实现各有一份见 indexerConnectorSyncImpl.hpp凭据通过 HTTP Basic Auth 附加到每个请求m_secureCommunication.basicAuth(username : password)。从 keystore 模块文档 可以补充两点重要细节密钥存储在 RocksDB 数据库queue/keystore/即安装目录下的/var/wazuh-manager/queue/keystore/所有值落盘前均以 AES-256-CBC 加密密码等敏感值支持从 stdin 或文件安全传入避免出现在 shell 历史中echo MySecretPassword | wazuh-manager-keystore -f indexer -k password wazuh-manager-keystore -f indexer -k password -vp /path/to/secret.txt兜底行为若 keystore 中username/password均为空连接器会回退到默认凭据wazuh-manager/wazuh-manager并打印告警日志源码见 indexerConnectorAsyncImpl.hpp。生产环境务必显式写入真实凭据。4. 配置示例可直接复制4.1 单节点 TLS单 Indexer 节点的基本配置mTLS 全量证书indexer hosts hosthttps://127.0.0.1:9200/host /hosts ssl certificate_authorities ca/var/wazuh-manager/etc/certs/root-ca.pem/ca /certificate_authorities certificate/var/wazuh-manager/etc/certs/manager.pem/certificate key/var/wazuh-manager/etc/certs/manager-key.pem/key /ssl /indexer4.2 多节点集群高可用多个 Indexer 节点的高可用配置——连接器会在节点间做负载均衡并在节点不可用时故障转移indexer hosts hosthttps://10.0.0.1:9200/host hosthttps://10.0.0.2:9200/host hosthttps://10.0.0.3:9200/host /hosts ssl certificate_authorities ca/var/wazuh-manager/etc/certs/root-ca.pem/ca /certificate_authorities certificate/var/wazuh-manager/etc/certs/manager.pem/certificate key/var/wazuh-manager/etc/certs/manager-key.pem/key /ssl /indexer4.3 多个 CA 证书当 Indexer 节点证书来自不同 CA 时逐个列出indexer hosts hosthttps://indexer1.example.com:9200/host hosthttps://indexer2.example.com:9200/host /hosts ssl certificate_authorities ca/var/wazuh-manager/etc/certs/root-ca-1.pem/ca ca/var/wazuh-manager/etc/certs/root-ca-2.pem/ca /certificate_authorities certificate/var/wazuh-manager/etc/certs/manager.pem/certificate key/var/wazuh-manager/etc/certs/manager-key.pem/key /ssl /indexer4.4 开发/测试环境无 TLS 校验警告仅限隔离的开发环境使用生产环境严禁。indexer hosts hosthttp://127.0.0.1:9200/host /hosts ssl !-- 空 SSL 块为必填但表示不做任何校验 -- /ssl /indexer该形态与仓库中的开发/QA 配置一致例如 test_initialize_indexer_connector/config.json 中的{name: ..., enabled: yes, hosts: [http://localhost:9200]}。5. XML 与内部 JSON 配置的映射参数、默认值与校验范围indexerXML 块会被解析为 JSON 配置对象传给连接器JSON 中还有一批只能由引擎内部选项 / 模块内部选项注入的字段。理解这些字段的默认值与校验边界有助于在压测与调优时精准定位参数。5.1 引擎侧Engine / Async 连接器内部选项引擎的配置默认值与可调范围定义于 src/engine/source/conf/src/conf.cpp键名定义于 conf/keys.hpp内部选项键对应 JSON 字段默认值说明analysisd.indexer_queue_max_bytesmax_queue_bytes64 MB异步内存队列字节上限超出后丢弃新事件并计数analysisd.indexer_bulk_max_bytesbulk_max_bytes8 MB每个 bulk 请求的目标字节阈值analysisd.indexer_flush_intervalflush_interval_seconds20空闲多少秒后自动刷新analysisd.indexer_max_retry_delaymax_retry_delay_seconds15 s指数退避的最大延迟上限这些选项同时支持环境变量覆盖WAZUH_INDEXER_*系列并在 src/engine/source/main.cpp 中被严格校验analysisd.indexer_bulk_max_bytes必须在64 KB 100 MB之间否则启动报错analysisd.indexer_flush_interval必须在1 3600秒之间analysisd.indexer_max_retry_delay必须在1 3600秒之间且连接器内部还要求max_retry_delay_seconds 基础退避延迟 1 秒见 indexerConnectorAsyncImpl.hpp错误日志队列analysisd.indexer_logger_queue_size默认 8上限 1024与线程数analysisd.indexer_logger_threads默认 1上限 16同样参与该校验。5.2 wazuh_modules 侧Sync 连接器内部选项同步连接器的批量参数由调用模块通过local_internal_options.conf的wazuh_modules段配置Vulnerability Scannerwm_vulnerability_scanner.cwazuh_modules.indexer_bulk_size_bytes默认10 MB范围 4096 100 MBwazuh_modules.indexer_flush_interval默认20 秒范围 1 3600。Inventory Syncwm_inventory_sync.cwazuh_modules.inventory_sync_indexer_bulk_size_bytes默认10 MB范围 4096 100 MBwazuh_modules.inventory_sync_indexer_flush_interval默认20 秒范围 1 3600。5.3 底层行为健康监控、负载均衡与重试连接器运行时行为详见 模块 README与配置决策直接相关健康监控后台健康监控线程每 60 秒对所有配置的 host 轮询/_cat/health将节点标记为可用/不可用实现见src/monitoring.hpp负载均衡服务选择器serverSelector.hpp在可用节点间做 round-robin 轮询——所以多节点配置不仅是容灾也是写入吞吐的横向扩展手段批量刷新同步模式缓冲最多 10 MB 序列化事件后按 Bulk API 批量提交空闲 20 秒也会自动刷新异步模式由后台线程按bulk_max_bytes阈值批量刷新413 处理Indexer 返回 HTTP 413Payload Too Large时同步模式将批次拆分后立即重发异步模式将 bulk 大小阈值减半后立即重发两者都不进入退避等待指数退避重试对瞬时故障HTTP 429、连接错误异步模式另含 HTTP 409 文档版本冲突使用带抖动的指数退避exponentialBackoff.hpp——第 1 次失败固定等待 1 秒此后每次翻倍并随机抖动封顶于max_retry_delay_seconds默认 15 秒重试成功或异步收到非 cluster-blocked 响应后失败计数清零异步队列易失性异步队列仅存于内存manager 停止或重启时缓冲事件直接丢弃、不会重试——需要可靠投递的场景应评估这一取舍。6. 验证连通性手动测试到 Indexer 的连通性curl --cacert /var/wazuh-manager/etc/certs/root-ca.pem \ --cert /var/wazuh-manager/etc/certs/manager.pem \ --key /var/wazuh-manager/etc/certs/manager-key.pem \ https://127.0.0.1:9200/_cluster/health期望响应中包含status: green或yellow。启用认证时加上 Basic Authcurl --cacert /var/wazuh-manager/etc/certs/root-ca.pem \ --cert /var/wazuh-manager/etc/certs/manager.pem \ --key /var/wazuh-manager/etc/certs/manager-key.pem \ -u admin:password \ https://127.0.0.1:9200/_cluster/health提示连接器健康监控线程正是对/_cat/health做轮询因此该命令返回的 HTTP 状态码尤其 401 与证书错误能直接复现连接器内部健康检查的失败路径。7. 证书管理7.1 生成自签名证书仅用于测试# 生成 CA openssl req -x509 -new -nodes -newkey rsa:4096 \ -keyout root-ca-key.pem -out root-ca.pem -days 3650 # 生成 manager 证书 openssl req -new -nodes -newkey rsa:4096 \ -keyout manager-key.pem -out manager.csr # 用 CA 签名 openssl x509 -req -in manager.csr -CA root-ca.pem \ -CAkey root-ca-key.pem -CAcreateserial \ -out manager.pem -days 365生产环境请使用正规 CA 签发的证书并确保 Indexer 节点证书的 SAN 包含 manager 实际访问的 IP/主机名——否则会出现SSL peer certificate or SSH remote key was not OK类错误见 testtool 排查表。7.2 证书权限确保属主与权限正确chown root:wazuh-manager /var/wazuh-manager/etc/certs/*.pem chmod 640 /var/wazuh-manager/etc/certs/*-key.pem chmod 644 /var/wazuh-manager/etc/certs/*.pem私钥*-key.pem应保持 640 且属主为root:wazuh-manager其余证书 644 即可。私钥泄露意味着任何持有者都能冒充 manager 向 Indexer 写入数据。8. 故障排查8.1 连接失败先测网络连通性再测 TLS 握手# 测试网络连通性 telnet 127.0.0.1 9200 # 测试 TLS 握手 openssl s_client -connect 127.0.0.1:9200 -CAfile /var/wazuh-manager/etc/certs/root-ca.pem查看 manager 日志连接器日志带(indexer-connector)标签形如vulnerability-scanner(indexer-connector)tail -f /var/wazuh-manager/logs/wazuh-manager.log | grep -i indexer8.2 证书错误# 检查证书有效期 openssl x509 -in /var/wazuh-manager/etc/certs/manager.pem -noout -dates # 用 CA 验证证书 openssl verify -CAfile /var/wazuh-manager/etc/certs/root-ca.pem \ /var/wazuh-manager/etc/certs/manager.pem证书相关报错常见两类原因证书已过期/不在有效期内或 CA 链不完整导致验证失败。若证书 SAN 不包含目标地址即使验证通过握手仍会失败。8.3 认证错误# 列出 keystore 条目 wazuh-manager-keystore -l # 用 curl 验证 curl -u admin:password https://127.0.0.1:9200/_cat/health连接器将 keystore 读取的凭据用于 Basic Auth因此 curl 用同一凭据能得到与连接器一致的认证结果。若 keystore 中无凭据连接器会静默回退到默认的wazuh-manager凭据注意核对这一点。8.4 配置校验重启前校验配置/var/wazuh-manager/bin/wazuh-logtest-config9. 性能考量9.1 连接池Indexer Connector 会维持到所有已配置 host 的持久连接。大规模部署建议使用多个 Indexer 节点分散写入负载在日志中监控连接池使用情况日志标签(indexer-connector)必要时调整 Indexer 端线程池设置对应引擎侧analysisd.indexer_bulk_max_bytes等批量参数也要一并校准。9.2 负载均衡连接器在可用节点间采用 round-robin 负载均衡serverSelector.hpp。为达到最优性能生产环境至少使用 3 个 Indexer 节点确保到所有节点的网络延迟相近持续监控各节点健康状态——健康监控线程每 60 秒轮询一次/_cat/health故障节点会从轮询池中摘除。9.3 异步队列的容量权衡异步模式下max_queue_bytes默认 64 MB决定了突发流量下内存缓冲的上限超出后新事件被丢弃并计数可通过IndexerConnectorAsync::getQueueSize()/getDroppedEvents()观测见 indexerConnector.hpp。调大该值可减少丢事件但会增加内存占用且队列易失——重启即清空。10. 测试工具与 QA 佐证仓库提供了indexer_connector_toolCLI 测试工具testtool/README.md可离线验证连接器配置与写入行为# 构建 make indexer_connector_tool -j$(nproc) # 同步推送事件 ./indexer_connector_tool push-events -c config.json -e events.json # 异步推送事件等待 5 秒后退出 ./indexer_connector_tool push-events -c config.json -e events.json -m async -w 5其配置文件字段与本文第 5 节的 JSON 字段一一对应hosts、username、password、ssl.certificate_authorities、ssl.certificate、ssl.key、max_queue_bytes、bulk_max_bytes、flush_interval_seconds、max_retry_delay_seconds是验证 manager 配置映射关系的极佳参考。此外qa/test_data/下按场景组织的测试配置413 拆分、索引不存在、shard 限制、映射更新等可帮助理解各类错误处理路径。11. 相关参考Indexer Connector 模块总览与架构 —— 模块工作方式、同步/异步刷新行为、重试与退避细节、写入的索引清单Keystore 模块 —— keystore 完整用法与加密存储细节Vulnerability Scanner 配置 —— 复用 Indexer 连接获取威胁情报 feed 的模块Manager 配置参考 —— 全部 manager 配置选项索引indexer段即出自本文适用范围说明本文配置路径/var/wazuh-manager/etc/wazuh-manager.conf与命令wazuh-manager-keystore基于 Wazuh 5.0 文档与源码约定仓库中的etc/wazuh-manager.conf为源树内参考模板实际部署时以安装生成的运行时配置文件为准。所有参数默认值与校验范围均取自当前仓库源码conf.cpp、main.cpp、wm_vulnerability_scanner.c。【免费下载链接】wazuhWazuh - The Open Source Security Platform. Unified XDR and SIEM protection for endpoints and cloud workloads.项目地址: https://gitcode.com/GitHub_Trending/wa/wazuh创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考