From a066c69fd509ae7561cd61d47907ce41173c3c99 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Wed, 23 Apr 2025 15:19:16 -0500 Subject: [PATCH] [docs] Fix various syntax and rendering errors (#17580) * fix various syntax and rendering issues * more fixes (cherry picked from commit 54472f2e9b42f36e3ec946a5f959c318ae290854) --- docs/docset.yml | 3 ++ docs/reference/advanced-pipeline.md | 2 +- docs/reference/connecting-to-cloud.md | 2 +- ...dashboard-monitoring-with-elastic-agent.md | 2 +- docs/reference/dir-layout.md | 38 ++++++++--------- docs/reference/first-event.md | 8 ++-- docs/reference/index.md | 2 +- docs/reference/logstash-settings-file.md | 2 +- .../running-logstash-command-line.md | 20 ++++++--- docs/reference/running-logstash.md | 11 +++-- docs/reference/secure-connection.md | 11 +++-- ...erverless-monitoring-with-elastic-agent.md | 2 +- docs/reference/upgrading-logstash.md | 2 +- docs/reference/use-filebeat-modules-kafka.md | 2 +- docs/reference/working-with-plugins.md | 8 ++-- docs/release-notes/breaking-changes.md | 42 +++++++++---------- 16 files changed, 85 insertions(+), 72 deletions(-) diff --git a/docs/docset.yml b/docs/docset.yml index b234d98491c..98dc7dcf19f 100644 --- a/docs/docset.yml +++ b/docs/docset.yml @@ -12,6 +12,7 @@ toc: - toc: release-notes - toc: extend subs: + version: "9.0.0" logstash-ref: "https://www.elastic.co/guide/en/logstash/current" ecloud: "Elastic Cloud" esf: "Elastic Serverless Forwarder" @@ -44,3 +45,5 @@ subs: stack-version: "9.0.0" major-version: "9.x" docker-repo: "docker.elastic.co/logstash/logstash" + ess-leadin-short: "Our hosted Elasticsearch Service is available on AWS, GCP, and Azure, and you can try it for free at https://cloud.elastic.co/registration" + ess-leadin: "You can run Elasticsearch on your own hardware or use our hosted Elasticsearch Service that is available on AWS, GCP, and Azure. Try the Elasticsearch Service for free: https://cloud.elastic.co/registration." diff --git a/docs/reference/advanced-pipeline.md b/docs/reference/advanced-pipeline.md index ab052976529..c14f778894d 100644 --- a/docs/reference/advanced-pipeline.md +++ b/docs/reference/advanced-pipeline.md @@ -379,7 +379,7 @@ Notice that the event now contains geographic location information: Now that the web logs are broken down into specific fields, you’re ready to get your data into Elasticsearch. ::::{tip} -{ess-leadin} +{{ess-leadin}} :::: diff --git a/docs/reference/connecting-to-cloud.md b/docs/reference/connecting-to-cloud.md index 34397c27f50..67a4a2aa53d 100644 --- a/docs/reference/connecting-to-cloud.md +++ b/docs/reference/connecting-to-cloud.md @@ -12,7 +12,7 @@ Examples: * `output {elasticsearch { cloud_id => "" cloud_auth => "" } }` * `output {elasticsearch { cloud_id => "" api_key => "" } }` -{ess-leadin-short} +{{ess-leadin-short}} ## Cloud ID [cloud-id] diff --git a/docs/reference/dashboard-monitoring-with-elastic-agent.md b/docs/reference/dashboard-monitoring-with-elastic-agent.md index 9b3743cdc84..25751f88543 100644 --- a/docs/reference/dashboard-monitoring-with-elastic-agent.md +++ b/docs/reference/dashboard-monitoring-with-elastic-agent.md @@ -144,6 +144,6 @@ A number of dashboards are included to view {{ls}} as a whole, and dashboards th From the list of assets, open the **[Metrics {{ls}}] {{ls}} overview** dashboard to view overall performance. Then follow the navigation panel to further drill down into {{ls}} performance. % TO DO: Use `:class: screenshot` -![The {{ls}} Overview dashboard in {{kib}} with various metrics from your monitored {ls}](images/integration-dashboard-overview.png) +![The {{ls}} Overview dashboard in {{kib}} with various metrics from your monitored {{ls}}](images/integration-dashboard-overview.png) You can hover over any visualization to adjust its settings, or click the **Edit** button to make changes to the dashboard. To learn more, refer to [Dashboard and visualizations](docs-content://explore-analyze/dashboards.md). diff --git a/docs/reference/dir-layout.md b/docs/reference/dir-layout.md index be4c4eb857a..56c62fa1dbd 100644 --- a/docs/reference/dir-layout.md +++ b/docs/reference/dir-layout.md @@ -15,12 +15,12 @@ This is very convenient because you don’t have to create any directories to st | Type | Description | Default Location | Setting | | --- | --- | --- | --- | -| home | Home directory of the Logstash installation. | ``{extract.path}`- Directory created by unpacking the archive` | | -| bin | Binary scripts, including `logstash` to start Logstash and `logstash-plugin` to install plugins | ``{extract.path}/bin`` | | -| settings | Configuration files, including `logstash.yml` and `jvm.options` | ``{extract.path}/config`` | ``path.settings`` | -| logs | Log files | ``{extract.path}/logs`` | ``path.logs`` | -| plugins | Local, non Ruby-Gem plugin files. Each plugin is contained in a subdirectory. Recommended for development only. | ``{extract.path}/plugins`` | ``path.plugins`` | -| data | Data files used by logstash and its plugins for any persistence needs. | ``{extract.path}/data`` | ``path.data`` | +| home | Home directory of the Logstash installation. | `{extract.path}`- Directory created by unpacking the archive | | +| bin | Binary scripts, including `logstash` to start Logstash and `logstash-plugin` to install plugins | `{extract.path}/bin` | | +| settings | Configuration files, including `logstash.yml` and `jvm.options` | `{extract.path}/config` | `path.settings` | +| logs | Log files | `{extract.path}/logs` | `path.logs` | +| plugins | Local, non Ruby-Gem plugin files. Each plugin is contained in a subdirectory. Recommended for development only. | `{extract.path}/plugins` | `path.plugins` | +| data | Data files used by logstash and its plugins for any persistence needs. | `{extract.path}/data` | `path.data` | ## Directory Layout of Debian and RPM Packages [deb-layout] @@ -29,13 +29,13 @@ The Debian package and the RPM package each place config files, logs, and the se | Type | Description | Default Location | Setting | | --- | --- | --- | --- | -| home | Home directory of the Logstash installation. | ``/usr/share/logstash`` | | -| bin | Binary scripts including `logstash` to start Logstash and `logstash-plugin` to install plugins | ``/usr/share/logstash/bin`` | | -| settings | Configuration files, including `logstash.yml` and `jvm.options` | ``/etc/logstash`` | ``path.settings`` | -| conf | Logstash pipeline configuration files | ``/etc/logstash/conf.d/*.conf`` | `See `/etc/logstash/pipelines.yml`` | -| logs | Log files | ``/var/log/logstash`` | ``path.logs`` | -| plugins | Local, non Ruby-Gem plugin files. Each plugin is contained in a subdirectory. Recommended for development only. | ``/usr/share/logstash/plugins`` | ``path.plugins`` | -| data | Data files used by logstash and its plugins for any persistence needs. | ``/var/lib/logstash`` | ``path.data`` | +| home | Home directory of the Logstash installation. | `/usr/share/logstash` | | +| bin | Binary scripts including `logstash` to start Logstash and `logstash-plugin` to install plugins | `/usr/share/logstash/bin` | | +| settings | Configuration files, including `logstash.yml` and `jvm.options` | `/etc/logstash` | `path.settings` | +| conf | Logstash pipeline configuration files | `/etc/logstash/conf.d/*.conf` | See `/etc/logstash/pipelines.yml` | +| logs | Log files | `/var/log/logstash` | `path.logs` | +| plugins | Local, non Ruby-Gem plugin files. Each plugin is contained in a subdirectory. Recommended for development only. | `/usr/share/logstash/plugins` | `path.plugins` | +| data | Data files used by logstash and its plugins for any persistence needs. | `/var/lib/logstash` | `path.data` | ## Directory Layout of Docker Images [docker-layout] @@ -44,12 +44,12 @@ The Docker images are created from the `.tar.gz` packages, and follow a similar | Type | Description | Default Location | Setting | | --- | --- | --- | --- | -| home | Home directory of the Logstash installation. | ``/usr/share/logstash`` | | -| bin | Binary scripts, including `logstash` to start Logstash and `logstash-plugin` to install plugins | ``/usr/share/logstash/bin`` | | -| settings | Configuration files, including `logstash.yml` and `jvm.options` | ``/usr/share/logstash/config`` | ``path.settings`` | -| conf | Logstash pipeline configuration files | ``/usr/share/logstash/pipeline`` | ``path.config`` | -| plugins | Local, non Ruby-Gem plugin files. Each plugin is contained in a subdirectory. Recommended for development only. | ``/usr/share/logstash/plugins`` | ``path.plugins`` | -| data | Data files used by logstash and its plugins for any persistence needs. | ``/usr/share/logstash/data`` | ``path.data`` | +| home | Home directory of the Logstash installation. | `/usr/share/logstash` | | +| bin | Binary scripts, including `logstash` to start Logstash and `logstash-plugin` to install plugins | `/usr/share/logstash/bin` | | +| settings | Configuration files, including `logstash.yml` and `jvm.options` | `/usr/share/logstash/config` | `path.settings` | +| conf | Logstash pipeline configuration files | `/usr/share/logstash/pipeline` | `path.config` | +| plugins | Local, non Ruby-Gem plugin files. Each plugin is contained in a subdirectory. Recommended for development only. | `/usr/share/logstash/plugins` | `path.plugins` | +| data | Data files used by logstash and its plugins for any persistence needs. | `/usr/share/logstash/data` | `path.data` | ::::{note} Logstash Docker containers do not create log files by default. They log to standard output. diff --git a/docs/reference/first-event.md b/docs/reference/first-event.md index 45c73d1addf..f465aee5d48 100644 --- a/docs/reference/first-event.md +++ b/docs/reference/first-event.md @@ -37,16 +37,16 @@ The location of the `bin` directory varies by platform. See [Directory layout](/ ::::{admonition} macOS Gatekeeper warnings :class: important -Apple’s rollout of stricter notarization requirements affected the notarization of the 9.0.0-beta1 {{ls}} artifacts. If macOS Catalina displays a dialog when you first run {{ls}} that interrupts it, you will need to take an action to allow it to run. To prevent Gatekeeper checks on the {{ls}} files, run the following command on the downloaded `.tar.gz` archive or the directory to which was extracted: +Apple’s rollout of stricter notarization requirements affected the notarization of {{version}} {{ls}} artifacts. If macOS Catalina displays a dialog when you first run {{ls}} that interrupts it, you will need to take an action to allow it to run. To prevent Gatekeeper checks on the {{ls}} files, run the following command on the downloaded `.tar.gz` archive or the directory to which was extracted: ```sh xattr -d -r com.apple.quarantine ``` -For example, if the `.tar.gz` file was extracted to the default logstash-9.0.0-beta1 directory, the command is: +For example, if the `.tar.gz` file was extracted to the default logstash-{{version}} directory, the command is: -```sh -xattr -d -r com.apple.quarantine logstash-9.0.0-beta1 +```sh subs=true +xattr -d -r com.apple.quarantine logstash-{{version}} ``` Alternatively, you can add a security override if a Gatekeeper popup appears by following the instructions in the *How to open an app that hasn’t been notarized or is from an unidentified developer* section of [Safely open apps on your Mac](https://support.apple.com/en-us/HT202491). diff --git a/docs/reference/index.md b/docs/reference/index.md index e5c9c6b4530..113bf323286 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -5,7 +5,7 @@ mapped_pages: - https://www.elastic.co/guide/en/serverless/current/elasticsearch-ingest-data-through-logstash.html --- -# Logstash introduction [introduction] +# Logstash [introduction] Logstash is an open source data collection engine with real-time pipelining capabilities. Logstash can dynamically unify data from disparate sources and normalize the data into destinations of your choice. diff --git a/docs/reference/logstash-settings-file.md b/docs/reference/logstash-settings-file.md index 31050d549c2..7bcce3c853a 100644 --- a/docs/reference/logstash-settings-file.md +++ b/docs/reference/logstash-settings-file.md @@ -59,7 +59,7 @@ The `logstash.yml` file includes these settings. | `config.reload.interval` | How often in seconds Logstash checks the config files for changes. Note that the unit qualifier (`s`) is required. | `3s` | | `config.debug` | When set to `true`, shows the fully compiled configuration as a debug log message. You must also set `log.level: debug`. WARNING: The log message will include any *password* options passed to plugin configs as plaintext, and may result in plaintext passwords appearing in your logs! | `false` | | `config.support_escapes` | When set to `true`, quoted strings will process the following escape sequences: `\n` becomes a literal newline (ASCII 10). `\r` becomes a literal carriage return (ASCII 13). `\t` becomes a literal tab (ASCII 9). `\\` becomes a literal backslash `\`. `\"` becomes a literal double quotation mark. `\'` becomes a literal quotation mark. | `false` | -| `config.field_reference.escape_style` | Provides a way to reference fields that contain [field reference special characters](https://www.elastic.co/guide/en/logstash/current/field-references-deepdive.html#formal-grammar-escape-sequences) `[` and `]`.

::::{note}
This feature is in **technical preview** and may change in the future.
::::


Current options are:

* `percent`: URI-style `%`+`HH` hexadecimal encoding of UTF-8 bytes (`[` → `%5B`; `]` → `%5D`)
* `ampersand`: HTML-style `&#`+`DD`+`;` encoding of decimal Unicode code-points (`[` → `[`; `]` → `]`)
* `none`: field names containing special characters *cannot* be referenced.
| `none` | +| `config.field_reference.escape_style` | Provides a way to reference fields that contain [field reference special characters](https://www.elastic.co/guide/en/logstash/current/field-references-deepdive.html#formal-grammar-escape-sequences) `[` and `]`.

Note: This feature is in **technical preview** and may change in the future.

Current options are:

* `percent`: URI-style `%`+`HH` hexadecimal encoding of UTF-8 bytes (`[` → `%5B`; `]` → `%5D`)
* `ampersand`: HTML-style `&#`+`DD`+`;` encoding of decimal Unicode code-points (`[` → `[`; `]` → `]`)
* `none`: field names containing special characters *cannot* be referenced.
| `none` | | `queue.type` | The internal queuing model to use for event buffering. Specify `memory` for legacy in-memory based queuing, or `persisted` for disk-based ACKed queueing ([persistent queues](/reference/persistent-queues.md)). | `memory` | | `path.queue` | The directory path where the data files will be stored when persistent queues are enabled (`queue.type: persisted`). | `path.data/queue` | | `queue.page_capacity` | The size of the page data files used when persistent queues are enabled (`queue.type: persisted`). The queue data consists of append-only data files separated into pages. | 64mb | diff --git a/docs/reference/running-logstash-command-line.md b/docs/reference/running-logstash-command-line.md index 591d52e2102..d3559f6331c 100644 --- a/docs/reference/running-logstash-command-line.md +++ b/docs/reference/running-logstash-command-line.md @@ -8,16 +8,16 @@ mapped_pages: ::::{admonition} macOS Gatekeeper warnings :class: important -Apple’s rollout of stricter notarization requirements affected the notarization of the 9.0.0-beta1 {{ls}} artifacts. If macOS Catalina displays a dialog when you first run {{ls}} that interrupts it, you will need to take an action to allow it to run. To prevent Gatekeeper checks on the {{ls}} files, run the following command on the downloaded `.tar.gz` archive or the directory to which was extracted: +Apple’s rollout of stricter notarization requirements affected the notarization of the {{version}} {{ls}} artifacts. If macOS Catalina displays a dialog when you first run {{ls}} that interrupts it, you will need to take an action to allow it to run. To prevent Gatekeeper checks on the {{ls}} files, run the following command on the downloaded `.tar.gz` archive or the directory to which was extracted: ```sh xattr -d -r com.apple.quarantine ``` -For example, if the `.tar.gz` file was extracted to the default logstash-9.0.0-beta1 directory, the command is: +For example, if the `.tar.gz` file was extracted to the default logstash-{{version}} directory, the command is: -```sh -xattr -d -r com.apple.quarantine logstash-9.0.0-beta1 +```sh subs=true +xattr -d -r com.apple.quarantine logstash-{{version}} ``` Alternatively, you can add a security override if a Gatekeeper popup appears by following the instructions in the *How to open an app that hasn’t been notarized or is from an unidentified developer* section of [Safely open apps on your Mac](https://support.apple.com/en-us/HT202491). @@ -116,7 +116,11 @@ Logstash has the following flags. You can use the `--help` flag to display this **`--config.debug`** -: Show the fully compiled configuration as a debug log message (you must also have `--log.level=debug` enabled). WARNING: The log message will include any *password* options passed to plugin configs as plaintext, and may result in plaintext passwords appearing in your logs! +: Show the fully compiled configuration as a debug log message (you must also have `--log.level=debug` enabled). + + :::{warning} + The log message will include any *password* options passed to plugin configs as plaintext, and may result in plaintext passwords appearing in your logs! + ::: **`-i, --interactive SHELL`** : Drop to shell instead of running as normal. Valid shells are "irb" and "pry". @@ -128,7 +132,11 @@ Logstash has the following flags. You can use the `--help` flag to display this : Check configuration for valid syntax and then exit. Note that grok patterns are not checked for correctness with this flag. Logstash can read multiple config files from a directory. If you combine this flag with `--log.level=debug`, Logstash will log the combined config file, annotating each config block with the source file it came from. **`-r, --config.reload.automatic`** -: Monitor configuration changes and reload whenever the configuration is changed. NOTE: Use SIGHUP to manually reload the config. The default is false. +: Monitor configuration changes and reload whenever the configuration is changed. + + :::{note} + Use SIGHUP to manually reload the config. The default is false. + ::: **`--config.reload.interval RELOAD_INTERVAL`** : How frequently to poll the configuration location for changes. The default value is "3s". Note that the unit qualifier (`s`) is required. diff --git a/docs/reference/running-logstash.md b/docs/reference/running-logstash.md index 4283b2d20e7..0febbbe563d 100644 --- a/docs/reference/running-logstash.md +++ b/docs/reference/running-logstash.md @@ -9,12 +9,11 @@ Logstash is not started automatically after installation. Starting and stopping As systemd is now the de-facto init system, here are some common operating systems and versions that use it. This list is intended to be informative, not exhaustive. -| | | | -| --- | --- | --- | -| Distribution | Service System | | -| Ubuntu 16.04 and newer | [systemd](#running-logstash-systemd) | | -| Debian 8 "jessie" and newer | [systemd](#running-logstash-systemd) | | -| CentOS (and RHEL) 7 and newer | [systemd](#running-logstash-systemd) | | +| Distribution | Service System | +| --- | --- | +| Ubuntu 16.04 and newer | [systemd](#running-logstash-systemd) | +| Debian 8 "jessie" and newer | [systemd](#running-logstash-systemd) | +| CentOS (and RHEL) 7 and newer | [systemd](#running-logstash-systemd) | ## Running Logstash by Using Systemd [running-logstash-systemd] diff --git a/docs/reference/secure-connection.md b/docs/reference/secure-connection.md index 0a35075b14b..ddeae0ffef5 100644 --- a/docs/reference/secure-connection.md +++ b/docs/reference/secure-connection.md @@ -24,7 +24,9 @@ Security is enabled by default on the {{es}} cluster (starting in 8.0). You must {{ess}} uses certificates signed by standard publicly trusted certificate authorities, and therefore setting a cacert is not necessary. -::::{admonition} Security to {{serverless-full}} $$$serverless$$$ +$$$serverless$$$ + +::::{admonition} Security to {{serverless-full}} :class: note {{es-serverless}} simplifies safe, secure communication between {{ls}} and {{es}}. @@ -39,11 +41,12 @@ For more details, check out [Grant access using API keys](#ls-api-keys). :::: +$$$hosted-ess$$$ -::::{admonition} Security to hosted {{ess}} $$$hosted-ess$$$ +::::{admonition} Security to hosted {{ess}} :class: note -Our hosted {{ess}} on Elastic Cloud simplifies safe, secure communication between {{ls}} and {{es}}. When you configure the [{{ls}} {{es}} output plugin](logstash-docs-md://lsr/plugins-outputs-elasticsearch.md) to use [`cloud_id`](logstash-docs-md://lsr/plugins-outputs-elasticsearch.md#plugins-outputs-elasticsearch-cloud_id) with either the [`cloud_auth` option](logstash-docs-md://lsr/plugins-outputs-elasticsearch.md#plugins-outputs-elasticsearch-cloud_auth) or the [`api_key` option](logstash-docs-md://lsr/plugins-outputs-elasticsearch.md#plugins-outputs-elasticsearch-api_key), no additional SSL configuration steps are needed. {ess-leadin-short} +Our hosted {{ess}} on Elastic Cloud simplifies safe, secure communication between {{ls}} and {{es}}. When you configure the [{{ls}} {{es}} output plugin](logstash-docs-md://lsr/plugins-outputs-elasticsearch.md) to use [`cloud_id`](logstash-docs-md://lsr/plugins-outputs-elasticsearch.md#plugins-outputs-elasticsearch-cloud_id) with either the [`cloud_auth` option](logstash-docs-md://lsr/plugins-outputs-elasticsearch.md#plugins-outputs-elasticsearch-cloud_auth) or the [`api_key` option](logstash-docs-md://lsr/plugins-outputs-elasticsearch.md#plugins-outputs-elasticsearch-api_key), no additional SSL configuration steps are needed. {{ess-leadin-short}} Configuration example: @@ -217,7 +220,7 @@ output { ::::{note} -Hosted {{ess}} simplifies security. This configuration step is not necessary for hosted Elasticsearch Service on Elastic Cloud. {ess-leadin-short} +Hosted {{ess}} simplifies security. This configuration step is not necessary for hosted Elasticsearch Service on Elastic Cloud. {{ess-leadin-short}} :::: diff --git a/docs/reference/serverless-monitoring-with-elastic-agent.md b/docs/reference/serverless-monitoring-with-elastic-agent.md index 0b0346b6eb5..1ef5b65ce31 100644 --- a/docs/reference/serverless-monitoring-with-elastic-agent.md +++ b/docs/reference/serverless-monitoring-with-elastic-agent.md @@ -65,6 +65,6 @@ For the best experience with the Logstash dashboards, we recommend collecting al From the list of assets, open the **[Metrics {{ls}}] {{ls}} overview** dashboard to view overall performance. Then follow the navigation panel to further drill down into {{ls}} performance. % TO DO: Use `:class: screenshot` -![The {{ls}} Overview dashboard in {{kib}} with various metrics from your monitored {ls}](images/integration-dashboard-overview.png) +![The {{ls}} Overview dashboard in {{kib}} with various metrics from your monitored {{ls}}](images/integration-dashboard-overview.png) You can hover over any visualization to adjust its settings, or click the **Edit** button to make changes to the dashboard. To learn more, refer to [Dashboard and visualizations](docs-content://explore-analyze/dashboards.md). diff --git a/docs/reference/upgrading-logstash.md b/docs/reference/upgrading-logstash.md index dc33cb536a9..5b59a9f9c67 100644 --- a/docs/reference/upgrading-logstash.md +++ b/docs/reference/upgrading-logstash.md @@ -27,7 +27,7 @@ This step helps reduce risk and makes roll backs easier if you hit a snag. * If you use monitoring, re-use the data directory when you upgrade Logstash. Otherwise, the Logstash node is assigned a new persistent UUID and becomes a new node in the monitoring data. * If you use the [elastic_integration filter](logstash-docs-md://lsr/plugins-filters-elastic_integration.md) plugin in Logstash pipelines: * Logstash and Elasticsearch must be on the same version. - * The recommended order for upgrading {{stack}} is ({es})-({ls})-({kib}) to ensure the best experience with {agent}-managed pipelines. + * The recommended order for upgrading {{stack}} is {{es}}-{{ls}}-{{kib}} to ensure the best experience with {{agent}}-managed pipelines. Note that this is different from the typical {{stack}} upgrade order. See [when `elastic_integration` is in {{ls}} pipeline](#upgrading-when-elastic_integration-in-pipeline) section for details. diff --git a/docs/reference/use-filebeat-modules-kafka.md b/docs/reference/use-filebeat-modules-kafka.md index 04313050c90..8d242187a51 100644 --- a/docs/reference/use-filebeat-modules-kafka.md +++ b/docs/reference/use-filebeat-modules-kafka.md @@ -21,7 +21,7 @@ The examples in this section show simple configurations with topic names hard co A connection to {{es}} and {{kib}} is required for this one-time setup step because {{filebeat}} needs to create the index template in {{es}} and load the sample dashboards into {{kib}}. For more information about configuring the connection to {{es}}, see the Filebeat [quick start](beats://reference/filebeat/filebeat-installation-configuration.md). - After the template and dashboards are loaded, you’ll see the message `INFO {{kib}} dashboards successfully loaded. Loaded dashboards`. + After the template and dashboards are loaded, you’ll see the message _INFO {{kib}} dashboards successfully loaded. Loaded dashboards_. 2. Run the `modules enable` command to enable the modules that you want to run. For example: diff --git a/docs/reference/working-with-plugins.md b/docs/reference/working-with-plugins.md index 863d72cd2ee..1956ab439de 100644 --- a/docs/reference/working-with-plugins.md +++ b/docs/reference/working-with-plugins.md @@ -8,16 +8,16 @@ mapped_pages: ::::{admonition} macOS Gatekeeper warnings :class: important -Apple’s rollout of stricter notarization requirements affected the notarization of the 9.0.0-beta1 {{ls}} artifacts. If macOS Catalina displays a dialog when you first run {{ls}}, you need to take an action to allow it to run. To prevent Gatekeeper checks on the {{ls}} files, run the following command on the downloaded `.tar.gz` archive or the directory to which was extracted: +Apple’s rollout of stricter notarization requirements affected the notarization of the {{version}} {{ls}} artifacts. If macOS Catalina displays a dialog when you first run {{ls}}, you need to take an action to allow it to run. To prevent Gatekeeper checks on the {{ls}} files, run the following command on the downloaded `.tar.gz` archive or the directory to which was extracted: ```sh xattr -d -r com.apple.quarantine ``` -For example, if the `.tar.gz` file was extracted to the default logstash-9.0.0-beta1 directory, the command is: +For example, if the `.tar.gz` file was extracted to the default logstash-{{version}} directory, the command is: -```sh -xattr -d -r com.apple.quarantine logstash-9.0.0-beta1 +```sh subs=true +xattr -d -r com.apple.quarantine logstash-{{version}} ``` Alternatively, you can add a security override if a Gatekeeper popup appears by following the instructions in the *How to open an app that hasn’t been notarized or is from an unidentified developer* section of [Safely open apps on your Mac](https://support.apple.com/en-us/HT202491). diff --git a/docs/release-notes/breaking-changes.md b/docs/release-notes/breaking-changes.md index 31a2f73c116..6e53ee67edf 100644 --- a/docs/release-notes/breaking-changes.md +++ b/docs/release-notes/breaking-changes.md @@ -3,8 +3,8 @@ navigation_title: "Breaking changes" --- # Logstash breaking changes [logstash-breaking-changes] -Breaking changes can impact your Elastic applications, potentially disrupting normal operations. -Before you upgrade, carefully review the Logstash breaking changes and take the necessary steps to mitigate any issues. +Breaking changes can impact your Elastic applications, potentially disrupting normal operations. +Before you upgrade, carefully review the Logstash breaking changes and take the necessary steps to mitigate any issues. % ## Next version [logstash-nextversion-breaking-changes] @@ -23,7 +23,7 @@ Before you upgrade, carefully review the Logstash breaking changes and take the We’ve removed deprecated SSL settings in some {{ls}} plugins, and have replaced them with updated settings. If your plugin configuration contains any of these obsolete options, the plugin may fail to start. -::::{dropdown} `logstash-input-beats` +::::{dropdown} logstash-input-beats :name: input-beats-ssl-9.0 | Setting | Replaced by | @@ -37,7 +37,7 @@ We’ve removed deprecated SSL settings in some {{ls}} plugins, and have replace :::: -::::{dropdown} `logstash-input-elastic_agent` +::::{dropdown} logstash-input-elastic_agent :name: input-elastic_agent-ssl-9.0 | Setting | Replaced by | @@ -52,7 +52,7 @@ We’ve removed deprecated SSL settings in some {{ls}} plugins, and have replace :::: -::::{dropdown} `logstash-input-elasticsearch` +::::{dropdown} logstash-input-elasticsearch :name: input-elasticsearch-ssl-9.0 | Setting | Replaced by | @@ -64,7 +64,7 @@ We’ve removed deprecated SSL settings in some {{ls}} plugins, and have replace :::: -::::{dropdown} `logstash-input-elastic_serverless_forwarder` +::::{dropdown} logstash-input-elastic_serverless_forwarder :name: input-elastic_serverless_forwarder-ssl-9.0 | Setting | Replaced by | @@ -74,7 +74,7 @@ We’ve removed deprecated SSL settings in some {{ls}} plugins, and have replace :::: -::::{dropdown} `logstash-input-http` +::::{dropdown} logstash-input-http :name: input-http-ssl-9.0 | Setting | Replaced by | @@ -91,7 +91,7 @@ We’ve removed deprecated SSL settings in some {{ls}} plugins, and have replace :::: -::::{dropdown} `logstash-input-http_poller` +::::{dropdown} logstash-input-http_poller :name: input-http_poller-ssl-9.0 | Setting | Replaced by | @@ -109,7 +109,7 @@ We’ve removed deprecated SSL settings in some {{ls}} plugins, and have replace :::: -::::{dropdown} `logstash-input-tcp` +::::{dropdown} logstash-input-tcp :name: input-tcp-ssl-9.0 | Setting | Replaced by | @@ -121,7 +121,7 @@ We’ve removed deprecated SSL settings in some {{ls}} plugins, and have replace :::: -::::{dropdown} `logstash-filter-elasticsearch` +::::{dropdown} logstash-filter-elasticsearch :name: filter-elasticsearch-ssl-9.0 | Setting | Replaced by | @@ -134,7 +134,7 @@ We’ve removed deprecated SSL settings in some {{ls}} plugins, and have replace :::: -::::{dropdown} `logstash-filter-http` +::::{dropdown} logstash-filter-http :name: filter-http-ssl-9.0 | Setting | Replaced by | @@ -152,7 +152,7 @@ We’ve removed deprecated SSL settings in some {{ls}} plugins, and have replace :::: -::::{dropdown} `logstash-output-elasticsearch` +::::{dropdown} logstash-output-elasticsearch :name: output-elasticsearch-ssl-9.0 | Setting | Replaced by | @@ -168,7 +168,7 @@ We’ve removed deprecated SSL settings in some {{ls}} plugins, and have replace :::: -::::{dropdown} `logstash-output-http` +::::{dropdown} logstash-output-http :name: output-http-ssl-9.0 | Setting | Replaced by | @@ -186,7 +186,7 @@ We’ve removed deprecated SSL settings in some {{ls}} plugins, and have replace :::: -::::{dropdown} `logstash-output-tcp` +::::{dropdown} logstash-output-tcp :name: output-tcp-ssl-9.0 | Setting | Replaced by | @@ -208,7 +208,7 @@ If you need to re-enable the previous behavior, change the `pipeline.buffer.type Check out [off-heap-buffers-allocation](/reference/jvm-settings.md#off-heap-buffers-allocation) for details. [#16500](https://github.com/elastic/logstash/pull/16500) :::: -::::{dropdown} {{ls}} modules removed +::::{dropdown} {{ls}} modules removed :name: removed-modules We have removed the {{ls}} modules framework, and encourage users to try Elastic Integrations @@ -216,7 +216,7 @@ This includes the netflow, azure and arcsight modules, and the modules framework :::: -::::{dropdown} Deprecated configuration settings removed +::::{dropdown} Deprecated configuration settings removed :name:removed-params We have removed support for previously deprecated configuration settings: @@ -225,11 +225,11 @@ We have removed support for previously deprecated configuration settings: - **`event_api.tags.illegal`** Any events that include field named tags automatically rename the field _tags to avoid any clash -with the reserved {{ls}} tags field. +with the reserved {{ls}} tags field. Instead, {{ls}} generates `_tagsparsefailure` in the event `tags` and the illegal value is written to the `_tags` field. [#16461](https://github.com/elastic/logstash/pull/16461) :::: -::::{dropdown} Ingest converter removed +::::{dropdown} Ingest converter removed :name: removed-ingest-converter The ingest converter, which was used to convert ingest pipelines to {{ls}} pipelines, has been removed. [#16453](https://github.com/elastic/logstash/pull/16453) @@ -241,7 +241,7 @@ The `logstash-filter-elastic_integration` plugin offers similar functionality, a :name: jdk-11-support-drop JDK17 is the minimum version of the JDK required to run Logstash. -For the best experience, we still recommend running {{ls}} using the bundled-jdk. +For the best experience, we still recommend running {{ls}} using the bundled-jdk. See [Logstash JVM requirements](/reference/getting-started-with-logstash.md#ls-jvm) for details. [#16443](https://github.com/elastic/logstash/pull/16443) :::: @@ -250,7 +250,7 @@ for details. [#16443](https://github.com/elastic/logstash/pull/16443) :name: docker-base-image-change The base image for {{ls}} on Docker has been changed from Ubuntu to UBI9. -If you create a Docker image based on the {{ls}} image and rely on it being Ubuntu based, you need to change your derived image to take account of this change. +If you create a Docker image based on the {{ls}} image and rely on it being Ubuntu based, you need to change your derived image to take account of this change. For example, if your derived docker image installs additional packages using a package manager, UBI9 uses `microdnf`, rather than `apt`. [#16599](https://github.com/elastic/logstash/pull/16599) :::: @@ -287,7 +287,7 @@ Check out [Logging in json format can write duplicate message fields](docs-conte ::::{dropdown} Enterprise_search integration plugin is removed from default Logstash install :name: enterprise_search-deprecated-9.0 -We’ve removed the {{ls}} Enterprise_search integration plugin, and its component App Search and Workplace Search plugins from the default {{ls}} install. +We’ve removed the {{ls}} Enterprise_search integration plugin, and its component App Search and Workplace Search plugins from the default {{ls}} install. These plugins will receive only security updates and critical fixes moving forward. We recommend using our native {{es}} tools for your Search use cases. For more details, please visit the [Search solution and use case documentation](docs-content://solutions/search.md).