配置 Elasticsearch 输出

编辑

Elasticsearch 输出使用 Elasticsearch HTTP API 将事件直接发送到 Elasticsearch。

配置示例

output.elasticsearch:
  hosts: ["https://myEShost:9200"] 

要启用 SSL,请将 https 添加到 *hosts* 下定义的所有 URL。

当通过 elasticsearch 输出将数据发送到安全集群时,Auditbeat 可以使用以下任何一种身份验证方法:

  • 基本身份验证凭据(用户名和密码)。
  • 基于令牌(API 密钥)的身份验证。
  • 公钥基础设施 (PKI) 证书。

基本身份验证

output.elasticsearch:
  hosts: ["https://myEShost:9200"]
  username: "auditbeat_writer"
  password: "YOUR_PASSWORD"

API 密钥身份验证

output.elasticsearch:
  hosts: ["https://myEShost:9200"]
  api_key: "ZCV7VnwBgnX0T19fN8Qe:KnR6yE41RrSowb0kQ0HWoA"

PKI 证书身份验证

output.elasticsearch:
  hosts: ["https://myEShost:9200"]
  ssl.certificate: "/etc/pki/client/cert.pem"
  ssl.key: "/etc/pki/client/cert.key"

有关每种身份验证方法的详细信息,请参阅与 Elasticsearch 的安全通信

兼容性

编辑

此输出适用于所有兼容版本的 Elasticsearch。请参阅Elastic 支持矩阵

(可选)您可以设置 Auditbeat 仅连接到至少与 Beat 版本相同的实例。可以通过将 output.elasticsearch.allow_older_versions 设置为 false 来启用此检查。将此设置保留为默认值 true 可以避免在 Auditbeat 升级到高于 Elastic Stack 的版本后无法连接到 Elasticsearch 的问题。

配置选项

编辑

您可以在 auditbeat.yml 配置文件的 elasticsearch 部分中指定以下选项:

enabled

编辑

enabled 配置是一个布尔值设置,用于启用或禁用输出。如果设置为 false,则禁用输出。

默认值为 true

hosts

编辑

要连接的 Elasticsearch 节点列表。事件以轮询顺序分发到这些节点。如果一个节点变得无法访问,事件会自动发送到另一个节点。每个 Elasticsearch 节点都可以定义为 URLIP:PORT。例如:http://192.15.3.2https://es.found.io:9230192.24.3.2:9300。如果未指定端口,则使用 9200

当节点定义为 IP:PORT 时,*scheme* 和 *path* 取自protocolpath 配置选项。

output.elasticsearch:
  hosts: ["10.45.3.2:9220", "10.45.3.1:9230"] 
  protocol: https
  path: /elasticsearch

在前面的示例中,Elasticsearch 节点可在 https://10.45.3.2:9220/elasticsearchhttps://10.45.3.1:9230/elasticsearch 处访问。

compression_level

编辑

gzip 压缩级别。将此值设置为 0 将禁用压缩。压缩级别必须在 1 (最佳速度)到 9 (最佳压缩)的范围内。

提高压缩级别将减少网络使用量,但会增加 CPU 使用率。

默认值为 1

escape_html

编辑

配置字符串中的 HTML 转义。设置为 true 以启用转义。

默认值为 false

workerworkers

编辑

每个配置的主机将事件发布到 Elasticsearch 的工作线程数。这最好与启用的负载平衡模式一起使用。示例:如果您有 2 个主机和 3 个工作线程,则总共启动 6 个工作线程(每个主机 3 个)。

默认值为 1

loadbalance

编辑

loadbalance: true 设置时,Auditbeat 将连接到所有配置的主机,并通过所有连接并行发送数据。如果连接失败,则数据将发送到其余主机,直到可以重新建立连接。只要 Auditbeat 可以连接到至少一个配置的主机,数据就会继续发送。

loadbalance: false 设置时,Auditbeat 一次将数据发送到单个主机。目标主机从配置的主机列表中随机选择,所有数据都发送到该目标,直到连接失败,然后选择新的目标。只要 Auditbeat 可以连接到至少一个配置的主机,数据就会继续发送。

默认值为 true

output.elasticsearch:
  hosts: ["localhost:9200", "localhost:9201"]
  loadbalance: true

api_key

编辑

您可以使用 API 密钥来保护与 Elasticsearch 的通信,而不是使用用户名和密码。该值必须是 API 密钥的 ID,以及用冒号连接的 API 密钥:id:api_key

有关更多信息,请参阅使用 API 密钥授予访问权限

username

编辑

用于连接到 Elasticsearch 的基本身份验证用户名。

此用户需要将事件发布到 Elasticsearch 所需的权限。要创建这样的用户,请参阅创建 *发布* 用户

password

编辑

用于连接到 Elasticsearch 的基本身份验证密码。

parameters

编辑

要在索引操作中通过 URL 传递的 HTTP 参数字典。

protocol

编辑

Elasticsearch 可访问的协议名称。选项为:httphttps。默认值为 http。但是,如果您为 hosts 指定 URL,则 protocol 的值将被您在 URL 中指定的任何 scheme 覆盖。

path

编辑

附加到 HTTP API 调用的 HTTP 路径前缀。这对于 Elasticsearch 在自定义前缀下导出 API 的 HTTP 反向代理之后侦听的情况非常有用。

headers

编辑

要添加到 Elasticsearch 输出创建的每个请求的自定义 HTTP 标头。示例

output.elasticsearch.headers:
  X-My-Header: Header contents

可以通过用逗号分隔的方式为同一个标头名称指定多个标头值。

proxy_disable

编辑

如果设置为 true,则所有代理设置(包括 HTTP_PROXYHTTPS_PROXY 变量)都将被忽略。

proxy_url

编辑

连接到 Elasticsearch 服务器时要使用的代理的 URL。该值必须是完整的 URL。如果未通过配置文件指定值,则使用代理环境变量。有关环境变量的更多信息,请参阅Go 文档

proxy_headers

编辑

在 CONNECT 请求期间发送到代理的其他标头。

index

编辑

要写入事件的索引目标。可以指向索引别名数据流。使用每日索引时,这将是索引名称。默认值为 "auditbeat-%{[agent.version]}-%{+yyyy.MM.dd}",例如,"auditbeat-8.17.0-2024-12-13"。如果您更改此设置,还需要配置 setup.template.namesetup.template.pattern 选项(请参阅Elasticsearch 索引模板)。

如果您正在使用预构建的 Kibana 仪表板,还需要设置 setup.dashboards.index 选项(请参阅Kibana 仪表板)。

启用索引生命周期管理 (ILM) 时,默认的 index"auditbeat-%{[agent.version]}-%{+yyyy.MM.dd}-%{index_num}",例如,"auditbeat-8.17.0-2024-12-13-000001"。启用 ILM 时,将忽略自定义 index 设置。如果您要将事件发送到支持索引生命周期管理的集群,请参阅索引生命周期管理 (ILM),了解如何更改索引名称。

您可以通过使用格式字符串来访问任何事件字段,从而动态设置索引。例如,此配置使用自定义字段 fields.log_type 来设置索引:

output.elasticsearch:
  hosts: ["https://127.0.0.1:9200"]
  index: "%{[fields.log_type]}-%{[agent.version]}-%{+yyyy.MM.dd}" 

我们建议在名称中包含 agent.version,以避免升级时出现映射问题。

使用此配置,所有带有 log_type: normal 的事件都将发送到名为 normal-8.17.0-2024-12-13 的索引,所有带有 log_type: critical 的事件都将发送到名为 critical-8.17.0-2024-12-13 的索引。

要了解如何向事件添加自定义字段,请参阅fields 选项。

有关其他动态设置索引的方法,请参阅indices 设置。

indices

编辑

索引选择器规则数组。每个规则指定用于匹配规则的事件的索引。在发布期间,Auditbeat 使用数组中的第一个匹配规则。规则可以包含条件、基于格式字符串的字段和名称映射。如果缺少 indices 设置或没有规则匹配,则使用index 设置。

index 类似,定义自定义的 indices 将禁用索引生命周期管理 (ILM)

规则设置

index
要使用的索引格式字符串。如果此字符串包含字段引用,例如 %{[fields.name]},则这些字段必须存在,否则规则将失败。
mappings
一个字典,它将 index 返回的值映射到一个新名称。
default
如果 mappings 未找到匹配项,则使用的默认字符串值。
when
为了执行当前规则必须成功的条件。处理器支持的所有条件也在此处支持。

以下示例根据 message 字段是否包含指定的字符串来设置索引

output.elasticsearch:
  hosts: ["https://127.0.0.1:9200"]
  indices:
    - index: "warning-%{[agent.version]}-%{+yyyy.MM.dd}"
      when.contains:
        message: "WARN"
    - index: "error-%{[agent.version]}-%{+yyyy.MM.dd}"
      when.contains:
        message: "ERR"

此配置会生成名为 warning-8.17.0-2024-12-13error-8.17.0-2024-12-13 的索引(如果未找到匹配项,则加上默认索引)。

以下示例通过获取 index 格式字符串返回的名称并将其映射到用于索引的新名称来设置索引

output.elasticsearch:
  hosts: ["https://127.0.0.1:9200"]
  indices:
    - index: "%{[fields.log_type]}"
      mappings:
        critical: "sev1"
        normal: "sev2"
      default: "sev3"

此配置会生成名为 sev1sev2sev3 的索引。

mappings 设置简化了配置,但仅限于字符串值。您不能在映射对中指定格式字符串。

用于索引生命周期管理的配置选项。

有关详细信息,请参阅 索引生命周期管理 (ILM)

pipeline

编辑

一个格式字符串值,指定要将事件写入的摄取管道。

output.elasticsearch:
  hosts: ["https://127.0.0.1:9200"]
  pipeline: my_pipeline_id

有关详细信息,请参阅使用摄取管道解析数据

您可以通过使用格式字符串访问任何事件字段来动态设置摄取管道。例如,此配置使用自定义字段 fields.log_type 来设置每个事件的管道

output.elasticsearch:
  hosts: ["https://127.0.0.1:9200"]
  pipeline: "%{[fields.log_type]}_pipeline"

使用此配置,所有 log_type: normal 的事件都将发送到名为 normal_pipeline 的管道,所有 log_type: critical 的事件都将发送到名为 critical_pipeline 的管道。

要了解如何向事件添加自定义字段,请参阅fields 选项。

有关动态设置摄取管道的其他方法,请参阅 pipelines 设置。

pipelines

编辑

管道选择器规则的数组。每个规则都指定用于匹配该规则的事件的摄取管道。在发布期间,Auditbeat 使用数组中第一个匹配的规则。规则可以包含条件、基于格式字符串的字段和名称映射。如果缺少 pipelines 设置或没有规则匹配,则使用pipeline 设置。

规则设置

pipeline
要使用的管道格式字符串。如果此字符串包含字段引用,例如 %{[fields.name]},则这些字段必须存在,否则规则将失败。
mappings
一个字典,它将 pipeline 返回的值映射到一个新名称。
default
如果 mappings 未找到匹配项,则使用的默认字符串值。
when
为了执行当前规则必须成功的条件。处理器支持的所有条件也在此处支持。

以下示例根据 message 字段是否包含指定的字符串将事件发送到特定的管道

output.elasticsearch:
  hosts: ["https://127.0.0.1:9200"]
  pipelines:
    - pipeline: "warning_pipeline"
      when.contains:
        message: "WARN"
    - pipeline: "error_pipeline"
      when.contains:
        message: "ERR"

以下示例通过获取 pipeline 格式字符串返回的名称并将其映射到用于管道的新名称来设置管道

output.elasticsearch:
  hosts: ["https://127.0.0.1:9200"]
  pipelines:
    - pipeline: "%{[fields.log_type]}"
      mappings:
        critical: "sev1_pipeline"
        normal: "sev2_pipeline"
      default: "sev3_pipeline"

使用此配置,所有 log_type: critical 的事件都将发送到 sev1_pipeline,所有 log_type: normal 的事件都将发送到 sev2_pipeline,所有其他事件都将发送到 sev3_pipeline

有关摄取管道的更多信息,请参阅使用摄取管道解析数据

max_retries

编辑

在发布失败后重试发布事件的次数。在指定的重试次数之后,通常会丢弃事件。

max_retries 设置为小于 0 的值可重试直到发布所有事件。

默认值为 3。

bulk_max_size

编辑

单个 Elasticsearch 批量 API 索引请求中要批量处理的最大事件数。默认值为 1600。

可以将事件收集到批次中。Auditbeat 会将从队列中读取的、大于 bulk_max_size 的批次拆分为多个批次。

指定较大的批次大小可以通过降低发送事件的开销来提高性能。但是,较大的批次大小也会增加处理时间,这可能会导致 API 错误、连接终止、发布请求超时,并最终导致吞吐量降低。

bulk_max_size 设置为小于或等于 0 的值会禁用批次拆分。禁用拆分时,队列会决定批次中包含的事件数。

backoff.init

编辑

在网络错误后尝试重新连接到 Elasticsearch 之前等待的秒数。等待 backoff.init 秒后,Auditbeat 会尝试重新连接。如果尝试失败,则退避计时器会呈指数级增加,最高可达 backoff.max。成功连接后,退避计时器会重置。默认值为 1s

backoff.max

编辑

在网络错误后尝试连接到 Elasticsearch 之前等待的最大秒数。默认值为 60s

idle_connection_timeout

编辑

空闲连接在关闭自身之前保持空闲的最大时间。零表示没有限制。格式为 Go 语言持续时间(例如,60s 为 60 秒)。默认值为 3s。

timeout

编辑

Elasticsearch 请求的 http 请求超时时间(以秒为单位)。默认值为 90。

allow_older_versions

编辑

默认情况下,Auditbeat 希望 Elasticsearch 实例的版本相同或更新,以提供最佳体验。我们建议您连接到相同的版本,以确保 Auditbeat 使用的所有功能在您的 Elasticsearch 实例中都可用。

您可以禁用检查,例如在更新 Elastic Stack 期间,以便数据收集可以继续进行。

用于 HTTPS 连接的 SSL 参数(例如要使用的证书颁发机构)的配置选项。如果缺少 ssl 部分,则主机 CA 将用于与 Elasticsearch 的 HTTPS 连接。

有关详细信息,请参阅 保护与 Elasticsearch 的通信指南或 SSL 配置参考

kerberos

编辑

用于 Kerberos 身份验证的配置选项。

有关详细信息,请参阅Kerberos

non_indexable_policy

编辑

指定当 Elasticsearch 集群显式拒绝文档时(例如,在映射冲突时)的行为。

drop
编辑

默认行为,当事件被 elasticsearch 显式拒绝时,它将被丢弃。

output.elasticsearch:
  hosts: ["https://127.0.0.1:9200"]
  non_indexable_policy.drop: ~
dead_letter_index
编辑

此功能为测试版,可能会发生更改。与官方 GA 功能相比,设计和代码不太成熟,并且按原样提供,不提供任何担保。Beta 功能不受官方 GA 功能的支持 SLA 的约束。

在显式拒绝时,此策略将在下一个批次中重试事件。但是,目标索引将更改为指定的索引。此外,事件的结构将更改为以下字段

message
包含原始事件的转义 json。
error.type
包含状态代码
error.message
包含 Elasticsearch 返回的状态,描述原因
index
将拒绝的事件发送到的索引。
output.elasticsearch:
  hosts: ["https://127.0.0.1:9200"]
  non_indexable_policy.dead_letter_index:
    index: "my-dead-letter-index"

preset

编辑

要应用于输出配置的性能预设。

output.elasticsearch:
  hosts: ["https://127.0.0.1:9200"]
  preset: balanced

性能预设根据所需的性能目标应用一组配置覆盖。如果设置了性能预设,它将覆盖其他配置标志,以匹配该预设的建议设置。有效选项包括:* balanced:一般效率的良好起点 * throughput:适用于高数据量,可能会增加 CPU 和内存要求 * scale:减少大型低吞吐量部署中的环境资源使用 * latency:最大程度地缩短新数据在 Elasticsearch 中变为可见的时间 * custom:直接应用用户配置,不进行任何覆盖

如果未指定,则默认值为 custom

预设代表基于预期目标的当前建议;它们的效果可能会在版本之间更改,以更好地适应这些目标。当前,预设具有以下效果

preset balanced throughput scale latency

bulk_max_size

1600

1600

1600

50

worker

1

4

1

1

queue.mem.events

3200

12800

3200

4100

queue.mem.flush.min_events

1600

1600

1600

2050

queue.mem.flush.timeout

10 秒

5 秒

20 秒

1 秒

compression_level

1

1

1

1

idle_connection_timeout

3 秒

15 秒

1 秒

60 秒

Elasticsearch API

编辑

Auditbeat 将使用 Elasticsearch 中的 _bulk API,事件将按照它们到达发布管道的顺序发送,单个 _bulk 请求可能包含来自不同输入/模块的事件。临时失败会重试。

将检查每个事件的状态代码并按如下方式处理

  • < 300: 事件被计为 events.acked
  • 409 (冲突): 事件被计为 events.duplicates
  • 429 (请求过多): 事件被计为 events.toomany
  • > 399< 500: 将应用 non_indexable_policy