From 1f0189d2d4633f0a44d9e738d1a835b9c6b50530 Mon Sep 17 00:00:00 2001 From: Ron Cohen Date: Thu, 22 Feb 2018 13:54:48 +0100 Subject: [PATCH] More generic docs for use in APM Server (#6184) * Use specific beat name's instead of 'the Beat' * Dont show Logstash info unless it's supported. * Make the index pattern decoupled from the beat name * Make it possible to skip the pipeline docs in output.elasticsearch * Introduce beat_default_index_prefix. * Use name of beat in shared-kibana-config.asciidoc * Add .\ for PS instruction and make it possible to remove logstash mention. * Introduce 'has_ml_jobs' * Added `html_docs` to .gitignore * Better outputconfig for Elasticsearch only beats. * Less blamy wording * Only talk about Filebeat for filebeat docs * Update the rest of the max_retries sections to only talk about Filebeat for filebeat * Special case for apm-server as it was only introduced in 6.0 * expand beat_default_index_prefix use (#2) --- .gitignore | 1 + auditbeat/docs/index.asciidoc | 2 + filebeat/docs/index.asciidoc | 2 + heartbeat/docs/index.asciidoc | 2 + libbeat/docs/command-reference.asciidoc | 10 ++++- libbeat/docs/dashboards.asciidoc | 10 ++--- libbeat/docs/dashboardsconfig.asciidoc | 2 +- libbeat/docs/index.asciidoc | 3 +- libbeat/docs/loggingconfig.asciidoc | 13 +++--- libbeat/docs/outputconfig.asciidoc | 52 +++++++++++++++++----- libbeat/docs/processors-using.asciidoc | 2 +- libbeat/docs/repositories.asciidoc | 2 +- libbeat/docs/security/basic-auth.asciidoc | 26 +++++------ libbeat/docs/security/user-access.asciidoc | 20 ++++----- libbeat/docs/shared-env-vars.asciidoc | 4 +- libbeat/docs/shared-kibana-config.asciidoc | 12 ++++- libbeat/docs/shared-path-config.asciidoc | 12 ++--- libbeat/docs/shared-ssl-config.asciidoc | 2 + libbeat/docs/shared-template-load.asciidoc | 35 +++++++++++---- libbeat/docs/template-config.asciidoc | 12 +++-- metricbeat/docs/index.asciidoc | 2 + packetbeat/docs/index.asciidoc | 2 + winlogbeat/docs/index.asciidoc | 2 + 23 files changed, 156 insertions(+), 74 deletions(-) diff --git a/.gitignore b/.gitignore index fa69db58a988..56e3cccf372b 100644 --- a/.gitignore +++ b/.gitignore @@ -7,6 +7,7 @@ /*/logs /*/fields.yml /*/*.template*.json +**/html_docs # Files .DS_Store diff --git a/auditbeat/docs/index.asciidoc b/auditbeat/docs/index.asciidoc index 73e9d0836b4e..cbe41fbd61bc 100644 --- a/auditbeat/docs/index.asciidoc +++ b/auditbeat/docs/index.asciidoc @@ -10,6 +10,8 @@ include::{asciidoc-dir}/../../shared/attributes.asciidoc[] :beatname_pkg: {beatname_lc} :github_repo_name: beats :discuss_forum: beats/{beatname_lc} +:beat_default_index_prefix: {beatname_lc} +:has_ml_jobs: yes include::../../libbeat/docs/shared-beats-attributes.asciidoc[] diff --git a/filebeat/docs/index.asciidoc b/filebeat/docs/index.asciidoc index 4d7bc88b56a3..47f4a65d8351 100644 --- a/filebeat/docs/index.asciidoc +++ b/filebeat/docs/index.asciidoc @@ -10,6 +10,8 @@ include::{asciidoc-dir}/../../shared/attributes.asciidoc[] :beatname_pkg: {beatname_lc} :github_repo_name: beats :discuss_forum: beats/{beatname_lc} +:beat_default_index_prefix: {beatname_lc} +:has_ml_jobs: yes include::../../libbeat/docs/shared-beats-attributes.asciidoc[] diff --git a/heartbeat/docs/index.asciidoc b/heartbeat/docs/index.asciidoc index 00931d0f44d7..7dd3af34e97a 100644 --- a/heartbeat/docs/index.asciidoc +++ b/heartbeat/docs/index.asciidoc @@ -10,6 +10,8 @@ include::{asciidoc-dir}/../../shared/attributes.asciidoc[] :beatname_pkg: heartbeat-elastic :github_repo_name: beats :discuss_forum: beats/{beatname_lc} +:beat_default_index_prefix: {beatname_lc} +:has_ml_jobs: yes include::../../libbeat/docs/shared-beats-attributes.asciidoc[] diff --git a/libbeat/docs/command-reference.asciidoc b/libbeat/docs/command-reference.asciidoc index a8e4cda293d1..9a21516acedc 100644 --- a/libbeat/docs/command-reference.asciidoc +++ b/libbeat/docs/command-reference.asciidoc @@ -19,7 +19,15 @@ :keystore-command-short-desc: Manages the <> :modules-command-short-desc: Manages configured modules :run-command-short-desc: Runs {beatname_uc}. This command is used by default if you start {beatname_uc} without specifying a command + +ifeval::["{has_ml_jobs}"=="yes"] :setup-command-short-desc: Sets up the initial environment, including the index template, Kibana dashboards (when available), and machine learning jobs (when available) +endif::[] + +ifeval::["{has_ml_jobs}"!="yes"] +:setup-command-short-desc: Sets up the initial environment, including the index template, Kibana dashboards (when available) +endif::[] + :test-command-short-desc: Tests the configuration :version-command-short-desc: Shows information about the current version @@ -31,7 +39,7 @@ Command reference ++++ -{beatname_uc} provides a command-line interface for running the Beat and +{beatname_uc} provides a command-line interface for starting {beatname_uc} and performing common tasks, like testing configuration files and loading dashboards. The command-line also supports <> for controlling global behaviors. diff --git a/libbeat/docs/dashboards.asciidoc b/libbeat/docs/dashboards.asciidoc index 5547343f821a..3c76c4d91cad 100644 --- a/libbeat/docs/dashboards.asciidoc +++ b/libbeat/docs/dashboards.asciidoc @@ -9,20 +9,16 @@ //// include::../../libbeat/docs/dashboards.asciidoc[] ////////////////////////////////////////////////////////////////////////// - {beatname_uc} comes packaged with example Kibana dashboards, visualizations, and searches for visualizing {beatname_uc} data in Kibana. Before you can use -the dashboards, you need to create the index pattern, +{beatname_lc}-*+, and +the dashboards, you need to create the index pattern, +{beat_default_index_prefix}-*+, and load the dashboards into Kibana. To do this, you can either run the `setup` command (as described here) or <> in the +{beatname_lc}.yml+ config file. -NOTE: Starting with Beats 6.0.0, the dashboards are loaded via the Kibana API. -This requires a Kibana endpoint configuration. You should have configured the -endpoint earlier when you -<<{beatname_lc}-configuration,configured {beatname_uc}>>. If you didn't, -configure it now. +This requires a Kibana endpoint configuration. If you didn't already configure +a Kibana endpoint, see <<{beatname_lc}-configuration,configured {beatname_uc}>> Make sure Kibana is running before you perform this step. If you are accessing a secured Kibana instance, make sure you've configured credentials as described in diff --git a/libbeat/docs/dashboardsconfig.asciidoc b/libbeat/docs/dashboardsconfig.asciidoc index 3dd255009a50..dd5e255d22fc 100644 --- a/libbeat/docs/dashboardsconfig.asciidoc +++ b/libbeat/docs/dashboardsconfig.asciidoc @@ -20,7 +20,7 @@ To load the dashboards, you can either enable dashboard loading in the run the `setup` command. Dashboard loading is disabled by default. When dashboard loading is enabled, {beatname_uc} uses the Kibana API to load the -sample dashboards. Dashboard loading is only attempted at Beat startup. +sample dashboards. Dashboard loading is only attempted when {beatname_uc} starts up. If Kibana is not available at startup, {beatname_uc} will stop with an error. To enable dashboard loading, add the following setting to the config file: diff --git a/libbeat/docs/index.asciidoc b/libbeat/docs/index.asciidoc index e3e0cda0fd63..368e41c43f6e 100644 --- a/libbeat/docs/index.asciidoc +++ b/libbeat/docs/index.asciidoc @@ -10,7 +10,8 @@ include::{asciidoc-dir}/../../shared/attributes.asciidoc[] :beatname_pkg: {beatname_lc} :github_repo_name: beats :discuss_forum: beats/{beatname_lc} - +:beat_default_index_prefix: {beatname_lc} +:has_ml_jobs: yes include::../../libbeat/docs/shared-beats-attributes.asciidoc[] diff --git a/libbeat/docs/loggingconfig.asciidoc b/libbeat/docs/loggingconfig.asciidoc index 753a6641c280..eeaff84cb6a6 100644 --- a/libbeat/docs/loggingconfig.asciidoc +++ b/libbeat/docs/loggingconfig.asciidoc @@ -14,7 +14,7 @@ == Configure logging The `logging` section of the +{beatname_lc}.yml+ config file contains options -for configuring the Beats logging output. The logging system can write logs to +for configuring the logging output. The logging system can write logs to the syslog or rotate log files. If logging is not explicitly configured the file output is used. @@ -67,7 +67,7 @@ Minimum log level. One of `debug`, `info`, `warning`, or `error`. The default log level is `info`. `debug`:: Logs debug messages, including a detailed printout of all events -flushed by the Beat. Also logs informational messages, warnings, errors, and +flushed. Also logs informational messages, warnings, errors, and critical errors. When the log level is `debug`, you can specify a list of <> to display debug messages for specific components. If no selectors are specified, the `*` selector is used to display debug messages @@ -84,9 +84,9 @@ published. Also logs any warnings, errors, or critical errors. [[selectors]] ==== `logging.selectors` -The list of debugging-only selector tags used by different Beats components. Use `*` -to enable debug output for all components. For example add `publish` to display -all the debug messages related to event publishing. When starting the Beat, +The list of debugging-only selector tags used by different {beatname_uc} components. +Use `*` to enable debug output for all components. For example add `publish` to display +all the debug messages related to event publishing. When starting {beatname_lc}, selectors can be overwritten using the `-d` command line option (`-d` also sets the debug log level). @@ -123,8 +123,7 @@ the <> section for details. [float] ==== `logging.files.name` -The name of the file that logs are written to. By default, the name of the Beat -is used. +The name of the file that logs are written to. The default is '{beatname_lc}'. [float] ==== `logging.files.rotateeverybytes` diff --git a/libbeat/docs/outputconfig.asciidoc b/libbeat/docs/outputconfig.asciidoc index 0618724aad2f..676bd1b37e0f 100644 --- a/libbeat/docs/outputconfig.asciidoc +++ b/libbeat/docs/outputconfig.asciidoc @@ -13,6 +13,12 @@ [[configuring-output]] == Configure the output +ifdef::only-elasticsearch[] +You configure {beatname_uc} to write to Elasticsearch by setting options +in the `output.elasticsearch` section of the +{beatname_lc}.yml+ config file +endif::[] + +ifndef::only-elasticsearch[] You configure {beatname_uc} to write to a specific output by setting options in the `output` section of the +{beatname_lc}.yml+ config file. Only a single output may be defined. @@ -26,6 +32,8 @@ The following topics describe how to configure each supported output: * <> * <> +endif::[] + [[elasticsearch-output]] === Configure the Elasticsearch output @@ -33,7 +41,7 @@ The following topics describe how to configure each supported output: Elasticsearch ++++ -When you specify Elasticsearch for the output, the Beat sends the transactions directly to Elasticsearch by using the Elasticsearch HTTP API. +When you specify Elasticsearch for the output, {beatname_uc} sends the transactions directly to Elasticsearch by using the Elasticsearch HTTP API. Example configuration: @@ -222,6 +230,7 @@ output.elasticsearch: message: "ERR" ------------------------------------------------------------------------------ +ifndef::no-pipeline[] ===== `pipeline` A format string value that specifies the ingest node pipeline to write events to. @@ -266,15 +275,20 @@ output.elasticsearch: when.equals: fields.type: "normal" ------------------------------------------------------------------------------ +endif::[] ===== `max_retries` The number of times to retry publishing an event after a publishing failure. After the specified number of retries, the events are typically dropped. -Some Beats, such as Filebeat, ignore the `max_retries` setting and retry until all -events are published. +ifeval::["{beatname_lc}" == "filebeat"] +Filebeat will ignore the `max_retries` setting and retry until all +events are published. +endif::[] +ifeval::["{beatname_lc}" != "filebeat"] Set `max_retries` to a value less than 0 to retry until all events are published. +endif::[] The default is 3. @@ -282,9 +296,8 @@ The default is 3. The maximum number of events to bulk in a single Elasticsearch bulk API index request. The default is 50. -If the Beat sends single events, the events are collected into batches. If the Beat publishes -a large batch of events (larger than the value specified by `bulk_max_size`), the batch is -split. +Events can be collected into batches. {beatname_uc} will split batches larger than `bulk_max_size` +into multiple batches. Specifying a larger batch size can improve performance by lowering the overhead of sending events. However big batch sizes can also increase processing times, which might result in @@ -307,6 +320,7 @@ Elasticsearch. See <> for more information. +ifndef::only-elasticsearch[] [[logstash-output]] === Configure the Logstash output @@ -515,10 +529,14 @@ The number of seconds to wait for responses from the Logstash server before timi The number of times to retry publishing an event after a publishing failure. After the specified number of retries, the events are typically dropped. -Some Beats, such as Filebeat, ignore the `max_retries` setting and retry until all -events are published. +ifeval::["{beatname_lc}" == "filebeat"] +Filebeat will ignore the `max_retries` setting and retry until all +events are published. +endif::[] +ifeval::["{beatname_lc}" != "filebeat"] Set `max_retries` to a value less than 0 to retry until all events are published. +endif::[] The default is 3. @@ -706,10 +724,15 @@ brokers, topics, partition, and active leaders to use for publishing. The number of times to retry publishing an event after a publishing failure. After the specified number of retries, the events are typically dropped. -Some Beats, such as Filebeat, ignore the `max_retries` setting and retry until all + +ifeval::["{beatname_lc}" == "filebeat"] +Filebeat will ignore the `max_retries` setting and retry until all events are published. +endif::[] +ifeval::["{beatname_lc}" != "filebeat"] Set `max_retries` to a value less than 0 to retry until all events are published. +endif::[] The default is 3. @@ -928,13 +951,18 @@ The Redis connection timeout in seconds. The default is 5 seconds. The number of times to retry publishing an event after a publishing failure. After the specified number of retries, the events are typically dropped. -Some Beats, such as Filebeat, ignore the `max_retries` setting and retry until all -events are published. +ifeval::["{beatname_lc}" == "filebeat"] +Filebeat will ignore the `max_retries` setting and retry until all +events are published. +endif::[] +ifeval::["{beatname_lc}" != "filebeat"] Set `max_retries` to a value less than 0 to retry until all events are published. +endif::[] The default is 3. + ===== `bulk_max_size` The maximum number of events to bulk in a single Redis request or pipeline. The default is 2048. @@ -1162,3 +1190,5 @@ When specified, the `cloud.auth` overwrites the `output.elasticsearch.username` `output.elasticsearch.password` settings. Because the Kibana settings inherit the username and password from the Elasticsearch output, this can also be used to set the `setup.kibana.username` and `setup.kibana.password` options. + +endif::[] diff --git a/libbeat/docs/processors-using.asciidoc b/libbeat/docs/processors-using.asciidoc index 3afc7501ca78..9b96d837dc22 100644 --- a/libbeat/docs/processors-using.asciidoc +++ b/libbeat/docs/processors-using.asciidoc @@ -543,7 +543,7 @@ default. For example, FileBeat enables the `container` indexer, which indexes pod metadata based on all container IDs, and a `logs_path` matcher, which takes the `source` field, extracts the container ID, and uses it to retrieve metadata. -The configuration below enables the processor when the Beat is run as a pod in +The configuration below enables the processor when {beatname_lc} is run as a pod in Kubernetes. [source,yaml] diff --git a/libbeat/docs/repositories.asciidoc b/libbeat/docs/repositories.asciidoc index 7221a5b4b373..64e9058bd4a5 100644 --- a/libbeat/docs/repositories.asciidoc +++ b/libbeat/docs/repositories.asciidoc @@ -88,7 +88,7 @@ install {beatname_uc} by running: sudo apt-get update && sudo apt-get install {beatname_pkg} -------------------------------------------------- -. To configure the Beat to start automatically during boot, run: +. To configure {beatname_uc} to start automatically during boot, run: + ["source","sh",subs="attributes"] -------------------------------------------------- diff --git a/libbeat/docs/security/basic-auth.asciidoc b/libbeat/docs/security/basic-auth.asciidoc index 85fd6decfbf1..ece4ce31665f 100644 --- a/libbeat/docs/security/basic-auth.asciidoc +++ b/libbeat/docs/security/basic-auth.asciidoc @@ -12,23 +12,23 @@ To configure authentication credentials for {beatname_uc}: `monitor` cluster privileges, and `read`, `write`, and `create_index` privileges for the indices that {beatname_uc} creates. You can create roles from the **Management / Roles** UI in {kib} or through the `role` API. -For example, the following request creates a ++{beatname_lc}_writer++ role: +For example, the following request creates a ++{beat_default_index_prefix}_writer++ role: + ["source","sh",subs="attributes,callouts"] --------------------------------------------------------------- -POST _xpack/security/role/{beatname_lc}_writer +POST _xpack/security/role/{beat_default_index_prefix}_writer { "cluster": ["manage_index_templates", "monitor"], "indices": [ { - "names": [ "{beatname_lc}-*" ], <1> + "names": [ "{beat_default_index_prefix}-*" ], <1> "privileges": ["write","create_index"] } ] } --------------------------------------------------------------- <1> If you use a custom {beatname_uc} index pattern, specify that pattern -instead of the default ++{beatname_lc}-*++ pattern. +instead of the default ++{beat_default_index_prefix}-*++ pattern. . Assign the writer role to the user that {beatname_uc} will use to connect to {es}: @@ -36,15 +36,15 @@ instead of the default ++{beatname_lc}-*++ pattern. .. To authenticate as a native user, create a user for the {beatname_uc} to use internally and assign it the writer role. You can create users from the **Management / Users** UI in {kib} or through the `user` API. For example, the -following request creates a ++{beatname_lc}_internal++ user that has the -++{beatname_lc}_writer++ role: +following request creates a ++{beat_default_index_prefix}_internal++ user that has the +++{beat_default_index_prefix}_writer++ role: + ["source","sh",subs="attributes,callouts"] --------------------------------------------------------------- -POST /_xpack/security/user/{beatname_lc}_internal +POST /_xpack/security/user/{beat_default_index_prefix}_internal { "password" : "x-pack-test-password", - "roles" : [ "{beatname_lc}_writer"], + "roles" : [ "{beat_default_index_prefix}_writer"], "full_name" : "Internal {beatname_uc} User" } --------------------------------------------------------------- @@ -56,7 +56,7 @@ the user by the distinguished name that appears in its certificate. -- ["source","yaml",subs="attributes,callouts"] --------------------------------------------------------------- -{beatname_lc}_writer: +{beat_default_index_prefix}_writer: - "cn=Internal {beatname_uc} User,ou=example,o=com" --------------------------------------------------------------- For more information, see @@ -68,14 +68,14 @@ in the {beatname_uc} configuration file: .. To use basic authentication, configure the `username` and `password` settings. For example, the following {beatname_uc} output configuration -uses the native ++{beatname_lc}_internal++ user to connect to {es}: +uses the native ++{beat_default_index_prefix}_internal++ user to connect to {es}: + ["source","js",subs="attributes,callouts"] -------------------------------------------------- output.elasticsearch: hosts: ["localhost:9200"] - index: "{beatname_lc}" - username: "{beatname_lc}_internal" + index: "{beat_default_index_prefix}" + username: "{beat_default_index_prefix}_internal" password: "x-pack-test-password" -------------------------------------------------- @@ -86,7 +86,7 @@ output.elasticsearch: -------------------------------------------------- output.elasticsearch: hosts: ["localhost:9200"] - index: "{beatname_lc}" + index: "{beat_default_index_prefix}" ssl.certificate: "/etc/pki/client/cert.pem" <1> ssl.key: "/etc/pki/client/cert.key" -------------------------------------------------- diff --git a/libbeat/docs/security/user-access.asciidoc b/libbeat/docs/security/user-access.asciidoc index 28626afc6771..e2a6d53bf5e8 100644 --- a/libbeat/docs/security/user-access.asciidoc +++ b/libbeat/docs/security/user-access.asciidoc @@ -8,39 +8,39 @@ and `view_index_metadata` privileges on the {beatname_uc} indices: . Create a role that has the `read` and `view_index_metadata` privileges for the {beatname_uc} indices. You can create roles from the **Management > Roles** UI in {kib} or through the `role` API. -For example, the following request creates a ++{beatname_lc}_reader++ +For example, the following request creates a ++{beat_default_index_prefix}_reader++ role: + -- ["source","sh",subs="attributes,callouts"] --------------------------------------------------------------- -POST _xpack/security/role/{beatname_lc}_reader +POST _xpack/security/role/{beat_default_index_prefix}_reader { "indices": [ { - "names": [ "{beatname_lc}-*" ], <1> + "names": [ "{beat_default_index_prefix}-*" ], <1> "privileges": ["read","view_index_metadata"] } ] } --------------------------------------------------------------- <1> If you use a custom {beatname_uc} index pattern, specify that pattern -instead of the default ++{beatname_lc}-*++ pattern. +instead of the default ++{beat_default_index_prefix}-*++ pattern. -- . Assign your users the reader role so they can access the {beatname_uc} indices: .. If you're using the `native` realm, you can assign roles with the **Management > Users** UI in {kib} or through the `user` API. For -example, the following request grants ++{beatname_lc}_user++ the -++{beatname_lc}_reader++ role: +example, the following request grants ++{beat_default_index_prefix}_user++ the +++{beat_default_index_prefix}_reader++ role: + -- ["source", "sh", subs="attributes,callouts"] --------------------------------------------------------------- -POST /_xpack/security/user/{beatname_lc}_user +POST /_xpack/security/user/{beat_default_index_prefix}_user { "password" : "x-pack-test-password", - "roles" : [ "{beatname_lc}_reader"], + "roles" : [ "{beat_default_index_prefix}_reader"], "full_name" : "{beatname_uc} User" } --------------------------------------------------------------- @@ -48,12 +48,12 @@ POST /_xpack/security/user/{beatname_lc}_user .. If you're using the LDAP, Active Directory, or PKI realms, you assign the roles in the `role_mapping.yml` configuration file. For example, the following snippet grants ++{beatname_uc} User++ -the ++{beatname_lc}_reader++ role: +the ++{beat_default_index_prefix}_reader++ role: + -- ["source", "yaml", subs="attributes,callouts"] --------------------------------------------------------------- -{beatname_lc}_reader: +{beat_default_index_prefix}_reader: - "cn={beatname_uc} User,dc=example,dc=com" --------------------------------------------------------------- For more information, see diff --git a/libbeat/docs/shared-env-vars.asciidoc b/libbeat/docs/shared-env-vars.asciidoc index d04b7b6df033..496f6aa480c7 100644 --- a/libbeat/docs/shared-env-vars.asciidoc +++ b/libbeat/docs/shared-env-vars.asciidoc @@ -49,7 +49,7 @@ If you need to use a literal `${` in your configuration file then you can write `$${` to escape the expansion. After changing the value of an environment variable, you need to restart -the Beat to pick up the new value. +{beatname_uc} to pick up the new value. [NOTE] ================================== @@ -104,7 +104,7 @@ output.elasticsearch: hosts: '${ES_HOSTS}' ------------------------------------------------------------------------------- -When the Beat loads the config file, it resolves the environment variable and +When {beatname_uc} loads the config file, it resolves the environment variable and replaces it with the specified list before reading the `hosts` setting. NOTE: Do not use double-quotes (`"`) to wrap regular expressions, or the backslash (`\`) will be interpreted as an escape character. diff --git a/libbeat/docs/shared-kibana-config.asciidoc b/libbeat/docs/shared-kibana-config.asciidoc index 41e0586894c5..d373a5bc0b3d 100644 --- a/libbeat/docs/shared-kibana-config.asciidoc +++ b/libbeat/docs/shared-kibana-config.asciidoc @@ -12,8 +12,16 @@ [[setup-kibana-endpoint]] == Set up the Kibana endpoint -Starting with Beats 6.0.0, the Kibana dashboards are loaded into Kibana +ifeval::["{beatname_lc}" == "apm-server"] +The Kibana dashboards are loaded into Kibana via the Kibana API. +This requires a Kibana endpoint configuration. +endif::[] + +ifeval::["{beatname_lc}" != "apm-server"] +Starting with {beatname_uc} 6.0.0, the Kibana dashboards are loaded into Kibana via the Kibana API. This requires a Kibana endpoint configuration. +endif::[] + You configure the endpoint in the `setup.kibana` section of the +{beatname_lc}.yml+ config file. @@ -89,7 +97,7 @@ under a custom prefix. ==== `setup.kibana.ssl.enabled` Enables {beatname_uc} to use SSL settings when connecting to Kibana via HTTPS. -If you configure the Beat to connect over HTTPS, this setting defaults to +If you configure {beatname_uc} to connect over HTTPS, this setting defaults to `true` and {beatname_uc} uses the default SSL settings. Example configuration: diff --git a/libbeat/docs/shared-path-config.asciidoc b/libbeat/docs/shared-path-config.asciidoc index f08d2810c681..073f9015fc58 100644 --- a/libbeat/docs/shared-path-config.asciidoc +++ b/libbeat/docs/shared-path-config.asciidoc @@ -14,10 +14,12 @@ == Set up project paths The `path` section of the +{beatname_lc}.yml+ config file contains configuration -options that define where the Beat looks for its files. For example, all Beats -look for the Elasticsearch template file in the configuration path, Filebeat and -Winlogbeat look for their registry files in the data path, and all Beats write -their log files in the logs path. +options that define where {beatname_lc} looks for its files. For example, {beatname_uc} +looks for the Elasticsearch template file in the configuration path and writes +log files in the logs path. +ifeval::["{beatname_lc}"=="filebeat" or "{beatname_lc}"=="winlogbeat"] +Filebeat and Winlogbeat look for their registry files in the data path. +endif::[] Please see the <> section for more details. @@ -87,7 +89,7 @@ path.data: /var/lib/beats [float] ==== `logs` -The logs path for a {beatname_uc} installation. This is the default location for the Beat's +The logs path for a {beatname_uc} installation. This is the default location for {beatname_uc}'s log files. If not set by a CLI flag or in the configuration file, the default for the logs path is a `logs` subdirectory inside the home path. diff --git a/libbeat/docs/shared-ssl-config.asciidoc b/libbeat/docs/shared-ssl-config.asciidoc index 2aa6f3b81101..e813bedf909e 100644 --- a/libbeat/docs/shared-ssl-config.asciidoc +++ b/libbeat/docs/shared-ssl-config.asciidoc @@ -15,7 +15,9 @@ output.elasticsearch.ssl.certificate: "/etc/pki/client/cert.pem" output.elasticsearch.ssl.key: "/etc/pki/client/cert.key" ---- +ifndef::only-elasticsearch[] Also see <>. +endif::[] Example Kibana endpoint config with SSL enabled: diff --git a/libbeat/docs/shared-template-load.asciidoc b/libbeat/docs/shared-template-load.asciidoc index 20fb21e49227..7312da1f06c5 100644 --- a/libbeat/docs/shared-template-load.asciidoc +++ b/libbeat/docs/shared-template-load.asciidoc @@ -31,14 +31,23 @@ configuring template loading options in the {beatname_uc} configuration file. You can also set options to change the name of the index and index template. +ifndef::only-elasticsearch[] NOTE: A connection to Elasticsearch is required to load the index template. If the output is Logstash, you must <>. +endif::[] For more information, see: -* <> +ifdef::only-elasticsearch[] +* <> +* <> +endif::[] + +ifndef::only-elasticsearch[] +* <> * <> - required for Logstash output +endif::[] [[load-template-auto]] ==== Configure template loading @@ -104,10 +113,13 @@ See <> for the full list of configuration options. ==== Load the template manually To load the template manually, run the <> command. A -connection to Elasticsearch is required. If Logstash output is enabled, you need +connection to Elasticsearch is required. +ifndef::only-elasticsearch[] +If Logstash output is enabled, you need to temporarily disable the Logstash output and enable Elasticsearch by using the `-E` option. The examples here assume that Logstash output is enabled. You can omit the `-E` flags if Elasticsearch output is already enabled. +endif::[] If you are connecting to a secured Elasticsearch cluster, make sure you've configured credentials as described in <<{beatname_lc}-configuration>>. @@ -117,6 +129,14 @@ Elasticsearch, see <>. To load the template, use the appropriate command for your system. +ifndef::only-elasticsearch[] +:disable_logstash: {sp}-E output.logstash.enabled=false +endif::[] + +ifdef::only-elasticsearch[] +:disable_logstash: +endif::[] + ifdef::allplatforms[] ifeval::["{requires-sudo}"=="yes"] @@ -126,17 +146,16 @@ include::./shared-note-sudo.asciidoc[] endif::[] *deb and rpm:* - ["source","sh",subs="attributes"] ---- -{beatname_lc} setup --template -E output.logstash.enabled=false -E 'output.elasticsearch.hosts=["localhost:9200"]' +{beatname_lc} setup --template{disable_logstash} -E 'output.elasticsearch.hosts=["localhost:9200"]' ---- *mac:* ["source","sh",subs="attributes"] ---- -./{beatname_lc} setup --template -E output.logstash.enabled=false -E 'output.elasticsearch.hosts=["localhost:9200"]' +./{beatname_lc} setup --template{disable_logstash} -E 'output.elasticsearch.hosts=["localhost:9200"]' ---- @@ -146,7 +165,7 @@ ifeval::["{beatname_lc}"!="auditbeat"] ["source","sh",subs="attributes"] ---------------------------------------------------------------------- -docker run {dockerimage} setup --template -E output.logstash.enabled=false -E 'output.elasticsearch.hosts=["localhost:9200"]' +docker run {dockerimage} setup --template{disable_logstash} -E 'output.elasticsearch.hosts=["localhost:9200"]' ---------------------------------------------------------------------- @@ -165,7 +184,7 @@ and run: ["source","sh",subs="attributes,callouts"] ---------------------------------------------------------------------- -PS > {beatname_lc} setup --template -E output.logstash.enabled=false -E 'output.elasticsearch.hosts=["localhost:9200"]' +PS > .{backslash}{beatname_lc} setup --template{disable_logstash} -E 'output.elasticsearch.hosts=["localhost:9200"]' ---------------------------------------------------------------------- @@ -192,7 +211,7 @@ PS > Invoke-RestMethod -Method Delete "http://localhost:9200/{beatname_lc}-*" ---------------------------------------------------------------------- -This command deletes all indices that match the pattern +{beatname_lc}-*+. +This command deletes all indices that match the pattern +{beat_default_index_prefix}-*+. Before running this command, make sure you want to delete all indices that match the pattern. diff --git a/libbeat/docs/template-config.asciidoc b/libbeat/docs/template-config.asciidoc index 85b79fc3746d..68e5f5612af5 100644 --- a/libbeat/docs/template-config.asciidoc +++ b/libbeat/docs/template-config.asciidoc @@ -8,10 +8,14 @@ mappings in Elasticsearch. If template loading is enabled (the default), {beatname_uc} loads the index template automatically after successfully connecting to Elasticsearch. +ifndef::only-elasticsearch[] + NOTE: A connection to Elasticsearch is required to load the index template. If the output is Logstash, you must <>. +endif::[] + You can adjust the following settings to load your own template or overwrite an existing one. @@ -19,7 +23,7 @@ existing one. you must <>. *`setup.template.name`*:: The name of the template. The default is -+{beatname_lc}+. The Beat version is always appended to the given ++{beatname_lc}+. The {beatname_uc} version is always appended to the given name, so the final name is +{beatname_lc}-%\{[beat.version]\}+. // Maintainers: a backslash character is required to escape curly braces and @@ -29,9 +33,9 @@ name, so the final name is +{beatname_lc}-%\{[beat.version]\}+. // the example as expected. *`setup.template.pattern`*:: The template pattern to apply to the default index -settings. The default pattern is +{beatname_lc}-\*+. The Beat version is always +settings. The default pattern is +{beat_default_index_prefix}-\*+. The {beatname_uc} version is always included in the pattern, so the final pattern is -+{beatname_lc}-%\{[beat.version]\}-*+. The wildcard character `-*` is used to ++{beat_default_index_prefix}-%\{[beat.version]\}-*+. The wildcard character `-*` is used to match all daily indices. + Example: @@ -39,7 +43,7 @@ Example: ["source","yaml",subs="attributes"] ---------------------------------------------------------------------- setup.template.name: "{beatname_lc}" -setup.template.pattern: "{beatname_lc}-*" +setup.template.pattern: "{beat_default_index_prefix}-*" ---------------------------------------------------------------------- *`setup.template.fields`*:: The path to the YAML file describing the fields. The default is +fields.yml+. If a diff --git a/metricbeat/docs/index.asciidoc b/metricbeat/docs/index.asciidoc index 19a8e59092b4..4eab69b50708 100644 --- a/metricbeat/docs/index.asciidoc +++ b/metricbeat/docs/index.asciidoc @@ -10,6 +10,8 @@ include::{asciidoc-dir}/../../shared/attributes.asciidoc[] :beatname_pkg: {beatname_lc} :github_repo_name: beats :discuss_forum: beats/{beatname_lc} +:beat_default_index_prefix: {beatname_lc} +:has_ml_jobs: yes include::../../libbeat/docs/shared-beats-attributes.asciidoc[] diff --git a/packetbeat/docs/index.asciidoc b/packetbeat/docs/index.asciidoc index f49d086042d8..df072e505140 100644 --- a/packetbeat/docs/index.asciidoc +++ b/packetbeat/docs/index.asciidoc @@ -10,6 +10,8 @@ include::{asciidoc-dir}/../../shared/attributes.asciidoc[] :beatname_pkg: {beatname_lc} :github_repo_name: beats :discuss_forum: beats/{beatname_lc} +:beat_default_index_prefix: {beatname_lc} +:has_ml_jobs: yes include::../../libbeat/docs/shared-beats-attributes.asciidoc[] diff --git a/winlogbeat/docs/index.asciidoc b/winlogbeat/docs/index.asciidoc index e6215096ea6e..83a19e70bd28 100644 --- a/winlogbeat/docs/index.asciidoc +++ b/winlogbeat/docs/index.asciidoc @@ -10,6 +10,8 @@ include::{asciidoc-dir}/../../shared/attributes.asciidoc[] :beatname_pkg: {beatname_lc} :github_repo_name: beats :discuss_forum: beats/{beatname_lc} +:beat_default_index_prefix: {beatname_lc} +:has_ml_jobs: yes include::../../libbeat/docs/shared-beats-attributes.asciidoc[]