diff --git a/.github/workflows/test_role_beats.yml b/.github/workflows/test_role_beats.yml index 6c0741e2..93556f02 100644 --- a/.github/workflows/test_role_beats.yml +++ b/.github/workflows/test_role_beats.yml @@ -15,6 +15,7 @@ on: pull_request: paths: - 'roles/beats/**' + - '!roles/beats/**/*.md' - '.github/workflows/test_role_beats.yml' - 'molecule/beats_**' diff --git a/README.md b/README.md index f4252d72..3cdbaca3 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ Every role is documented with all variables, please refer to the documentation f > [!NOTE] > Some roles have fixed requirements that you must observe. Please have a look at the [requirements](docs/01-requirements.md) before using the collection. (There is a high probability that some of them will be refactored soon) -* [Beats](docs/role-beats.md) +* [Beats](roles/beats/README.md) * [Elasticsearch](docs/role-elasticsearch.md) * [Kibana](docs/role-kibana.md) * [Logstash](roles/logstash/README.md) diff --git a/docs/getting-started.md b/docs/getting-started.md index dc49fb40..8174daa2 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -47,7 +47,7 @@ Or refer to the role with the FQCN of the role. Roles ------- -* [Beats](role-beats.md) +* [Beats](../roles/beats/README.md) * [Elasticsearch](role-elasticsearch.md) * [Kibana](role-kibana.md) * [Logstash](../roles/logstash/README.md) diff --git a/docs/role-beats.md b/docs/role-beats.md index 5d742c82..14df7b01 100644 --- a/docs/role-beats.md +++ b/docs/role-beats.md @@ -1,124 +1,5 @@ -Ansible Role: Beats -========= +# Beats role -![Test Role Beats](https://github.com/netways/ansible-collection-elasticstack/actions/workflows/test_role_beats.yml/badge.svg) +The Beats role documentation now lives with the role itself: -This role installs and configures Beats. You can use it as a standalone role or combine it with our other roles managing the Elastic Stack. - -Requirements ------------- - -You need to have the beats you want to install available in your software repositories. We provide a [role](./role-repos.md) for just that but if you have other ways of managing software, just make sure it's available. Alternatively you can install the Beats yourself. - -* `community.crypto` collection: ansible-galaxy collection install community.crypto - -Role Variables --------------- - -* *beats_filebeat*: Install and manage filebeat (Default: `true`) -* *beats_filebeat_enable*: Automatically start Filebeat (Default: `true`) -* *beats_filebeat_output*: Set to `logstash` or `elasticsearch`. (default: `logstash`) -* *beats_filebeat_elastic_monitoring*: `filebeat` monitoring over `Elastic Stack monitoring features` (default: `false`) -* *beats_filebeat_syslog_udp*: Use UDP Syslog input (Default: `false`) -* *beats_filebeat_syslog_udp_port*: Port of UDP Syslog input (Default: `514`) -* *beats_filebeat_syslog_tcp*: Use TCP Syslog input (Default: `false`) -* *beats_filebeat_syslog_tcp_port*: Port of TCP Syslog input (Default: `514`) -* *beats_filebeat_log_input*: Enable Logfile reading (Default: `true`) -* *beats_filebeat_mysql_slowlog_input*: Enable MySQL/MariaDB slow query log collection incl. multiline (Default: `false`) -* *beats_filebeat_log_inputs*: Logfiles to read (Default: see below) - -Default of `beats_filebeat_log_inputs` - -``` - messages: - name: messages - paths: - - /var/log/messages -``` - -You can optionally add `fields` to every input as well. You can also add a `multiline` section with options (`type`, `pattern`, `negate` and `match` so far) - -Here's a longer example for an input: -``` -beats_filebeat_log_inputs: - messages: - name: messages - paths: - - /var/log/messages - - /var/log/secure - - /var/log/httpd/*access_log* - multiline: - type: pattern - pattern: '^[[:space:]]+(at|\.{3})[[:space:]]+\b|^Caused by:' - negate: false - match: after -``` -* *beats_filebeat_journald*: Enable collection of JournalD logs (default: `false`) - available since Filebeat 7.16 -* *beats_filebeat_journald_inputs*: List of journald inputs. Use for different filters on events. You can add a list of `include_matches` entries for filtering. -Default of `beats_filebeat_journald_inputs`: -``` -beats_filebeat_journald_inputs: - everything: - id: everything -``` -* *beats_filebeat_docker*: Enable collection of Docker logs (default: `false`) **ONLY WORKS ON RELEASE 7 SO FAR** -* *beats_filebeat_docker_ids*: IDs of containers to collect. (default: `*`) - -* *beats_filebeat_loadbalance*: Enable loadbalancing for Filebeats Logstash output (default: `true`) -* *beats_filebeat_modules*: **EXPERIMENTAL**: Give a list of modules to enable. (default: none) - -* *beats_auditbeat*: Install and manage filebeat (Default: `false`) -* *beats_auditbeat_output*: Output for Auditbeat Set to `logstash` or `elasticsearch`. (default: `elasticsearch`) -* *beats_auditbeat_enable*: Automatically start Auditbeat (Default: `true`) -* *beats_auditbeat_setup*: Run Auditbeat Setup (Default: `true`) (Only works with Elasticsearch output) -* *beats_auditbeat_loadbalance*: Enable loadbalancing for Auditbeats Logstash output (default: `true`) - -* *beats_metricbeat*: Enable installation and management of Metricbeat (Default: `false`) -* *beats_metricbeat_enable*: Start Metricbeat automatically (Default: `true`) -* *beats_metricbeat_output*: Set to `logstash` or `elasticsearch`. (default: `elasticsearch`) -* *beats_metricbeat_modules*: List of modules to enable. (Default: `- system`) -* *beats_metricbeat_loadbalance*: Enable loadbalancing for Metricbeats Logstash output (default: `true`) - -* *beats_security*: Activate TLS for connections to targets. Can either be use with our other roles and `elasticstack_full_stack` to automatically create certificates or `beats_tls*` variables for custom certificates. (default: `false`) -* *beats_target_hosts*: Only use when this role is used standalone. When used in combination with our other roles, the target hosts will be determined automatically. Use a YAML list. (default: `- localhost`) -* *elasticstack_elasticsearch_http_port*: Port of Elasticsearch to send events to (Default: `9200`) -* *elasticstack_beats_port*: Port of Logstash to send events to (Default: `5044`) -* *beats_logging*: Where to log (Default: `file`) -* *beats_loglevel*: Level of logging (for all beats) (Default: `info`) -* *beats_logpath*: If logging to file, where to put logfiles (Default: `/var/log/beats`) -* *beats_fields*: Fields that are added to every input in the configuration - -The following variables only apply if you use this role together with our other Elastic Stack roles. - -* *elasticstack_full_stack*: Use `elasticsearch` as well (default: `false`) -* *elasticstack_variant*: Define which variant of elastic stack to use. (default: `elastic`) -* *elasticstack_ca_dir*: Directory where on the Elasticsearch CA host certificates are stored. This is only useful in connection with out other Elastic Stack related roles. (default: `/opt/es-ca`) -* *elasticstack_ca_pass*: Password for Elasticsearch CA (default: `PleaseChangeMe`) -* *elasticstack_initial_passwords*: Path to file with initical elasticsearch passwords (default: `/usr/share/elasticsearch/initial_passwords`) -* *elasticstack_version*: Install specific version (Default: none. Possible values: e.g. `7.10.1` or `latest`) - -If you want to use this role with your own TLS certificates, use these variables. - -* *beats_ca_dir*: Path to custom CA certificates and keys (default: none - if not set will be filled with different values depending on which Stack variant is used) -* *beats_tls_key*: Path to the keyfiles (default: `{{ beats_ca_dir }}/{{ ansible_hostname }}.key`) -* *beats_tls_cert*: Path to the certificate (default: `{{ beats_ca_dir }}/{{ ansible_hostname }}.crt`) -* *beats_tls_key_passphrase*: Passphrase of the keyfile (default: `BeatsChangeMe`) -* *beats_cert_validity_period*: number of days that the generated certificates are valid (default: 1095). -* *beats_cert_expiration_buffer*: Ansible will renew the beats certificate if its validity is shorter than this value, which should be number of days. (default: 30) -* *beats_cert_will_expire_soon*: Set it to true to renew beats certificate (default: `false`), Or run the playbook with `--tags renew_beats_cert` to do that. -* *beats_tls_cacert*: Path to the CA.crt (default: `{{ beats_ca_dir }}/ca.crt`) - -## Usage - -``` -- name: Install Elastic Beats - hosts: beats-hosts - collections: - - netways.elasticstack - vars: - elasticsearch_jna_workaround: true - elasticsearch_disable_systemcallfilterchecks: true - roles: - - repos - - beats -``` +**➜ [roles/beats/README.md](../roles/beats/README.md)** diff --git a/roles/beats/README.md b/roles/beats/README.md new file mode 100644 index 00000000..1ab4c2d1 --- /dev/null +++ b/roles/beats/README.md @@ -0,0 +1,96 @@ +# Ansible Role: Beats + +Installs and configures the Elastic [Beats](https://www.elastic.co/beats) — +Filebeat, Auditbeat and Metricbeat — on Linux systems. The role can run +standalone or together with the other Elastic Stack roles. Beats can ship to +Logstash or directly to Elasticsearch. + +## Requirements + +* The `community.crypto` collection (used to check certificate expiration). +* The Beats you want to install must be available in your software repositories — + use the [`repos`](../repos) role or provide them yourself. + +## Example + +```yaml +- name: Install Beats + hosts: beats + collections: + - netways.elasticstack + roles: + - repos + - beats +``` + +## Filebeat inputs + +Filebeat can read from several sources (log files, syslog, journald, Docker, +modules). For the structure of `beats_filebeat_log_inputs`, +`beats_filebeat_journald_inputs` and the other input variables, see the +[Filebeat inputs documentation](docs/filebeat-inputs.md). + +## Tags + +Run only parts of the role with `--tags`: + +* `configuration` (alias `beats_configuration`) — (re)write the Filebeat and Auditbeat configuration without installing. Use `beats_filebeat_configuration` or `beats_auditbeat_configuration` to limit it to one of them. +* `certificates` — only generate and distribute the TLS certificates. +* `renew_beats_cert` / `renew_ca` — force renewal of the Beats certificate. + + +## Role variables + +| Variable | Type | Default | Choices | Description | +|----------|------|---------|---------|-------------| +| `beats_filebeat` | `bool` | `true` | — | Install and manage Filebeat. | +| `beats_auditbeat` | `bool` | `false` | — | Install and manage Auditbeat. | +| `beats_metricbeat` | `bool` | `false` | — | Install and manage Metricbeat. | +| `beats_target_hosts` | `list` of `str` | `['localhost']` | — | Hosts the Beats ship to. Only used when the role runs standalone; with the other Elastic Stack roles the targets are determined automatically. | +| `beats_fields` | `list` of `str` | N/A | — | Fields added to every input, given as a list of "key: value" strings (the global counterpart to the per-input fields). Unset by default. See the Filebeat inputs documentation. | +| `beats_logging` | `str` | `"file"` | — | Where the Beats log. Set to "file" to log into beats_logpath; any other value leaves the Beats built-in logging. | +| `beats_loglevel` | `str` | `"info"` | — | Log level for all Beats. | +| `beats_logpath` | `str` | `"/var/log/beats"` | — | Directory for the log files when beats_logging is "file". | +| `beats_filebeat_enable` | `bool` | `true` | — | Start and enable the Filebeat service. | +| `beats_filebeat_output` | `str` | `"logstash"` | `logstash`, `elasticsearch` | Where Filebeat sends its events. | +| `beats_filebeat_elastic_monitoring` | `bool` | `false` | — | Report Filebeat monitoring data through the Elastic Stack monitoring features. | +| `beats_filebeat_loadbalance` | `bool` | `true` | — | Enable load balancing for the Filebeat Logstash output. | +| `beats_filebeat_log_input` | `bool` | `true` | — | Read log files with the inputs from beats_filebeat_log_inputs. | +| `beats_filebeat_log_inputs` | `dict` | `{'messages': {'paths': ['/var/log/messages', '/var/log/syslog']}}` | — | Log files to read, keyed by a free name that becomes the filestream id. Each entry has paths and optional fields and multiline settings. See the Filebeat inputs documentation. | +| `beats_filebeat_syslog_tcp` | `bool` | `false` | — | Enable a TCP syslog input. | +| `beats_filebeat_syslog_tcp_port` | `int` | `514` | — | Port of the TCP syslog input. | +| `beats_filebeat_syslog_udp` | `bool` | `false` | — | Enable a UDP syslog input. | +| `beats_filebeat_syslog_udp_port` | `int` | `514` | — | Port of the UDP syslog input. | +| `beats_filebeat_journald` | `bool` | `false` | — | Collect logs from journald. Available since Filebeat 7.16. | +| `beats_filebeat_journald_inputs` | `dict` | `{'everything': {'id': 'everything'}}` | — | Journald inputs, keyed by a free name. Each entry has an id and optional include_matches filters. See the Filebeat inputs documentation. | +| `beats_filebeat_docker` | `bool` | `false` | — | Collect Docker container logs. Only works on Elastic Stack release 7. | +| `beats_filebeat_docker_ids` | `str` | `"*"` | — | IDs of the containers to collect logs from. | +| `beats_filebeat_mysql_slowlog_input` | `bool` | `false` | — | Collect the MySQL/MariaDB slow query log, including multiline handling. | +| `beats_filebeat_modules` | `list` of `str` | N/A | — | List of Filebeat modules to enable (experimental). Unset by default. | +| `beats_auditbeat_enable` | `bool` | `true` | — | Start and enable the Auditbeat service. | +| `beats_auditbeat_output` | `str` | `"elasticsearch"` | `logstash`, `elasticsearch` | Where Auditbeat sends its events. | +| `beats_auditbeat_setup` | `bool` | `true` | — | Run the Auditbeat setup (index management and pipelines). Only effective with the elasticsearch output. | +| `beats_auditbeat_loadbalance` | `bool` | `true` | — | Enable load balancing for the Auditbeat Logstash output. | +| `beats_metricbeat_enable` | `bool` | `true` | — | Start and enable the Metricbeat service. | +| `beats_metricbeat_output` | `str` | `"elasticsearch"` | `logstash`, `elasticsearch` | Where Metricbeat sends its events. | +| `beats_metricbeat_modules` | `list` of `str` | `['system']` | — | Metricbeat modules to enable. | +| `beats_metricbeat_loadbalance` | `bool` | `true` | — | Enable load balancing for the Metricbeat Logstash output. | +| `beats_security` | `bool` | `false` | — | Activate TLS for the connections to the targets. Works with the other roles and elasticstack_full_stack to create certificates automatically, or with the beats_tls_* variables for custom certificates. | +| `beats_ca_dir` | `str` | N/A | — | Base directory for custom CA certificates and keys. Unset by default; the role fills it depending on the stack variant (/opt/ca standalone, or /etc/beats/certs in a full stack). | +| `beats_tls_key` | `str` | `"{{ beats_ca_dir | default('') }}/{{ inventory_hostname }}-beats.key"` | — | Path to the private key file for custom certificates. | +| `beats_tls_cert` | `str` | `"{{ beats_ca_dir | default('') }}/{{ inventory_hostname }}-beats.crt"` | — | Path to the certificate for custom certificates. | +| `beats_tls_cacert` | `str` | `"{{ beats_ca_dir | default('') }}/ca.crt"` | — | Path to the CA certificate for custom certificates. | +| `beats_tls_key_passphrase` | `str` | `"BeatsChangeMe"` | — | Passphrase of the private key. | +| `beats_cert_validity_period` | `int` | `1095` | — | Number of days the generated certificates are valid. | +| `beats_cert_expiration_buffer` | `str` | `"+30d"` | — | Renew the certificate when it would expire within this period. Uses the community.crypto check_period format (e.g. "+30d"), not a plain number. | +| `beats_cert_will_expire_soon` | `bool` | `false` | — | Set to true to force renewal of the Beats certificate. Alternatively run the playbook with the renew_beats_cert tag. | + + + +## Shared variables + +This role also uses the collection-wide `elasticstack_*` variables (e.g. +`elasticstack_full_stack`, `elasticstack_variant`, `elasticstack_ca_host`, +`elasticstack_ca_pass`, `elasticstack_release`, `elasticstack_version`, +`elasticstack_elasticsearch_http_port`, `elasticstack_beats_port`). They are +documented centrally with the [elasticsearch role](../../docs/role-elasticsearch.md). diff --git a/roles/beats/defaults/main.yml b/roles/beats/defaults/main.yml index ae7b8d9b..8d1bd6c7 100644 --- a/roles/beats/defaults/main.yml +++ b/roles/beats/defaults/main.yml @@ -12,9 +12,9 @@ beats_loglevel: info # Use TLS without Elastic X-Pack # -beats_tls_key: "{{ beats_ca_dir }}/{{ inventory_hostname }}-beats.key" -beats_tls_cert: "{{ beats_ca_dir }}/{{ inventory_hostname }}-beats.crt" -beats_tls_cacert: "{{ beats_ca_dir }}/ca.crt" +beats_tls_key: "{{ beats_ca_dir | default('') }}/{{ inventory_hostname }}-beats.key" +beats_tls_cert: "{{ beats_ca_dir | default('') }}/{{ inventory_hostname }}-beats.crt" +beats_tls_cacert: "{{ beats_ca_dir | default('') }}/ca.crt" beats_tls_key_passphrase: BeatsChangeMe # Filebeat specific # @@ -28,7 +28,6 @@ beats_filebeat_syslog_tcp_port: 514 beats_filebeat_log_input: true beats_filebeat_log_inputs: messages: - name: messages paths: - /var/log/messages - /var/log/syslog diff --git a/roles/beats/docs/filebeat-inputs.md b/roles/beats/docs/filebeat-inputs.md new file mode 100644 index 00000000..cede2166 --- /dev/null +++ b/roles/beats/docs/filebeat-inputs.md @@ -0,0 +1,148 @@ +# Filebeat inputs # + +Filebeat can read from several sources. Each source is turned into a Filebeat +input by the role. This document describes the variables that configure them. +For the meaning of the individual Filebeat options, follow the links to the +official Filebeat documentation. + +## Log files ## + +Set with `beats_filebeat_log_input` (default `true`) and `beats_filebeat_log_inputs`. + +`beats_filebeat_log_inputs` is a **dictionary keyed by a free name**. That key +becomes the id of the generated +[`filestream`](https://www.elastic.co/docs/reference/beats/filebeat/filebeat-input-filestream) +input (`-filestream`) — there is no separate `name` field. Each entry needs +`paths`; `fields` and `multiline` are optional. + +The default reads the system log: + +```yaml +beats_filebeat_log_inputs: + messages: + paths: + - /var/log/messages + - /var/log/syslog +``` + +A longer example with several paths and multiline handling: + +```yaml +beats_filebeat_log_inputs: + messages: + paths: + - /var/log/messages + - /var/log/secure + - /var/log/httpd/*access_log* + multiline: + type: pattern + pattern: '^[[:space:]]+(at|\.{3})[[:space:]]+\b|^Caused by:' + negate: false + match: after +``` + +`multiline` maps directly to the Filebeat multiline parser (`type`, `pattern`, +`negate`, `match`). See +[Manage multiline messages](https://www.elastic.co/docs/reference/beats/filebeat/multiline-examples). + +## Fields ## + +There are two ways to add fields, and they use **different shapes**: + +* **Per input** — the optional `fields` inside a log input is a **dictionary** + (`key: value`), added only to that input: + + ```yaml + beats_filebeat_log_inputs: + messages: + paths: + - /var/log/messages + fields: + environment: production + ``` + +* **Globally** — `beats_fields` is a **list of `"key: value"` strings**. In the + current templates it is added to the log, TCP and UDP inputs; the journald, + Docker and MySQL slow-log inputs do not receive it: + + ```yaml + beats_fields: + - "environment: production" + - "team: platform" + ``` + +## Syslog over TCP/UDP ## + +Enable a listening syslog input with `beats_filebeat_syslog_tcp` / +`beats_filebeat_syslog_udp` and set the port with `beats_filebeat_syslog_tcp_port` +/ `beats_filebeat_syslog_udp_port` (both default `514`). They become a +[`tcp`](https://www.elastic.co/docs/reference/beats/filebeat/filebeat-input-tcp) +or [`udp`](https://www.elastic.co/docs/reference/beats/filebeat/filebeat-input-udp) +input listening on `0.0.0.0:`. The global `beats_fields` are applied here too. + +```yaml +beats_filebeat_syslog_tcp: true +beats_filebeat_syslog_tcp_port: 514 +``` + +## Journald ## + +Enable with `beats_filebeat_journald` (default `false`, available since Filebeat +7.16) and configure inputs with `beats_filebeat_journald_inputs`. + +This is a **dictionary keyed by a free name**. Unlike the log inputs, here the +key is only a label — the input's id comes from the `id` field, which each entry +needs. `include_matches` is optional and is itself a dictionary whose values are +the match expressions. + +```yaml +beats_filebeat_journald_inputs: + everything: + id: everything + ssh-only: + id: ssh-only + include_matches: + unit: '_SYSTEMD_UNIT=sshd.service' +``` + +See the +[`journald`](https://www.elastic.co/docs/reference/beats/filebeat/filebeat-input-journald) +input. + +## Docker ## + +Enable with `beats_filebeat_docker` (default `false`) and select containers with +`beats_filebeat_docker_ids` (default `*`). **Only works on Elastic Stack release +7.** Docker metadata is added automatically. + +```yaml +beats_filebeat_docker: true +beats_filebeat_docker_ids: "*" +``` + +## MySQL/MariaDB slow log ## + +Set `beats_filebeat_mysql_slowlog_input` to `true` to collect +`/var/log/mysql/*-slow.log` with the matching multiline pattern already +configured. The events are tagged with `mysql.logtype: slowquery`. + +## Modules ## + +`beats_filebeat_modules` is a list of Filebeat module names to enable +(**experimental**, unset by default). The role runs `filebeat modules enable` +and sets up their ingest pipelines. + +On Elastic Stack release 8 and newer (`elasticstack_release > 7`), enabling any +modules also deploys a predefined **System module** configuration to +`modules.d/system.yml`, which collects the syslog files (`/var/log/syslog`, +`/var/log/messages`) through the system module's `syslog` fileset. + +```yaml +beats_filebeat_modules: + - system + - nginx +``` + +See the +[Filebeat modules](https://www.elastic.co/docs/reference/beats/filebeat/filebeat-modules) +reference for the available modules. diff --git a/roles/beats/meta/argument_specs.yml b/roles/beats/meta/argument_specs.yml new file mode 100644 index 00000000..e36abaee --- /dev/null +++ b/roles/beats/meta/argument_specs.yml @@ -0,0 +1,276 @@ +--- +# Role argument specification for the beats role. +# This is the single source of truth for the role's variables: Ansible validates +# the supplied values against it at role start, and ansible-docsmith renders the +# README variable reference and the comments in defaults/main.yml from it. +# +# Only beats_* variables live here. The shared elasticstack_* variables are +# documented centrally with the elasticstack role. + +argument_specs: + main: + short_description: Install and configure Elastic Beats + description: + - Installs and configures Filebeat, Auditbeat and Metricbeat on Linux systems. + - >- + Can run standalone or together with the other Elastic Stack roles. Beats + can ship to Logstash or directly to Elasticsearch. + - >- + The complex Filebeat input structures (log, syslog, journald, docker, + modules) are described in the Filebeat inputs documentation. + author: + - NETWAYS GmbH + + options: + + # ----- Which Beats to manage ----- + beats_filebeat: + type: bool + default: true + description: Install and manage Filebeat. + + beats_auditbeat: + type: bool + default: false + description: Install and manage Auditbeat. + + beats_metricbeat: + type: bool + default: false + description: Install and manage Metricbeat. + + # ----- General ----- + beats_target_hosts: + type: list + elements: str + default: + - localhost + description: >- + Hosts the Beats ship to. Only used when the role runs standalone; with + the other Elastic Stack roles the targets are determined automatically. + + beats_fields: + type: list + elements: str + description: >- + Fields added to every input, given as a list of "key: value" strings + (the global counterpart to the per-input fields). Unset by default. + See the Filebeat inputs documentation. + + # ----- Logging ----- + beats_logging: + type: str + default: file + description: >- + Where the Beats log. Set to "file" to log into beats_logpath; any other + value leaves the Beats built-in logging. + + beats_loglevel: + type: str + default: info + description: Log level for all Beats. + + beats_logpath: + type: str + default: /var/log/beats + description: Directory for the log files when beats_logging is "file". + + # ----- Filebeat ----- + beats_filebeat_enable: + type: bool + default: true + description: Start and enable the Filebeat service. + + beats_filebeat_output: + type: str + choices: + - logstash + - elasticsearch + default: logstash + description: Where Filebeat sends its events. + + beats_filebeat_elastic_monitoring: + type: bool + default: false + description: Report Filebeat monitoring data through the Elastic Stack monitoring features. + + beats_filebeat_loadbalance: + type: bool + default: true + description: Enable load balancing for the Filebeat Logstash output. + + beats_filebeat_log_input: + type: bool + default: true + description: Read log files with the inputs from beats_filebeat_log_inputs. + + beats_filebeat_log_inputs: + type: dict + default: + messages: + paths: + - /var/log/messages + - /var/log/syslog + description: >- + Log files to read, keyed by a free name that becomes the filestream id. + Each entry has paths and optional fields and multiline settings. See the + Filebeat inputs documentation. + + beats_filebeat_syslog_tcp: + type: bool + default: false + description: Enable a TCP syslog input. + + beats_filebeat_syslog_tcp_port: + type: int + default: 514 + description: Port of the TCP syslog input. + + beats_filebeat_syslog_udp: + type: bool + default: false + description: Enable a UDP syslog input. + + beats_filebeat_syslog_udp_port: + type: int + default: 514 + description: Port of the UDP syslog input. + + beats_filebeat_journald: + type: bool + default: false + description: Collect logs from journald. Available since Filebeat 7.16. + + beats_filebeat_journald_inputs: + type: dict + default: + everything: + id: everything + description: >- + Journald inputs, keyed by a free name. Each entry has an id and optional + include_matches filters. See the Filebeat inputs documentation. + + beats_filebeat_docker: + type: bool + default: false + description: Collect Docker container logs. Only works on Elastic Stack release 7. + + beats_filebeat_docker_ids: + type: str + default: "*" + description: IDs of the containers to collect logs from. + + beats_filebeat_mysql_slowlog_input: + type: bool + default: false + description: Collect the MySQL/MariaDB slow query log, including multiline handling. + + beats_filebeat_modules: + type: list + elements: str + description: List of Filebeat modules to enable (experimental). Unset by default. + + # ----- Auditbeat ----- + beats_auditbeat_enable: + type: bool + default: true + description: Start and enable the Auditbeat service. + + beats_auditbeat_output: + type: str + choices: + - logstash + - elasticsearch + default: elasticsearch + description: Where Auditbeat sends its events. + + beats_auditbeat_setup: + type: bool + default: true + description: Run the Auditbeat setup (index management and pipelines). Only effective with the elasticsearch output. + + beats_auditbeat_loadbalance: + type: bool + default: true + description: Enable load balancing for the Auditbeat Logstash output. + + # ----- Metricbeat ----- + beats_metricbeat_enable: + type: bool + default: true + description: Start and enable the Metricbeat service. + + beats_metricbeat_output: + type: str + choices: + - logstash + - elasticsearch + default: elasticsearch + description: Where Metricbeat sends its events. + + beats_metricbeat_modules: + type: list + elements: str + default: + - system + description: Metricbeat modules to enable. + + beats_metricbeat_loadbalance: + type: bool + default: true + description: Enable load balancing for the Metricbeat Logstash output. + + # ----- Security / TLS ----- + beats_security: + type: bool + default: false + description: >- + Activate TLS for the connections to the targets. Works with the other + roles and elasticstack_full_stack to create certificates automatically, + or with the beats_tls_* variables for custom certificates. + + beats_ca_dir: + type: str + description: >- + Base directory for custom CA certificates and keys. Unset by default; the + role fills it depending on the stack variant (/opt/ca standalone, or + /etc/beats/certs in a full stack). + + beats_tls_key: + type: str + default: "{{ beats_ca_dir | default('') }}/{{ inventory_hostname }}-beats.key" + description: Path to the private key file for custom certificates. + + beats_tls_cert: + type: str + default: "{{ beats_ca_dir | default('') }}/{{ inventory_hostname }}-beats.crt" + description: Path to the certificate for custom certificates. + + beats_tls_cacert: + type: str + default: "{{ beats_ca_dir | default('') }}/ca.crt" + description: Path to the CA certificate for custom certificates. + + beats_tls_key_passphrase: + type: str + default: BeatsChangeMe + description: Passphrase of the private key. + + beats_cert_validity_period: + type: int + default: 1095 + description: Number of days the generated certificates are valid. + + beats_cert_expiration_buffer: + type: str + default: "+30d" + description: >- + Renew the certificate when it would expire within this period. Uses the + community.crypto check_period format (e.g. "+30d"), not a plain number. + + beats_cert_will_expire_soon: + type: bool + default: false + description: >- + Set to true to force renewal of the Beats certificate. Alternatively run + the playbook with the renew_beats_cert tag.