mirror of
https://github.com/elastic/logstash.git
synced 2025-04-24 14:47:19 -04:00
79 lines
3.7 KiB
Text
79 lines
3.7 KiB
Text
[[upgrading-logstash]]
|
|
== Upgrading Logstash
|
|
|
|
[IMPORTANT]
|
|
===========================================
|
|
Before upgrading Logstash:
|
|
|
|
* Consult the <<breaking-changes,breaking changes>> docs.
|
|
* Test upgrades in a development environment before upgrading your production cluster.
|
|
===========================================
|
|
|
|
=== Upgrading Using Package Managers
|
|
|
|
This procedure uses <<package-repositories,package managers>> to upgrade Logstash.
|
|
|
|
1. Shut down your Logstash pipeline, including any inputs that send events to Logstash.
|
|
2. Using the directions in the _Package Repositories_ section, update your repository links to point to the 2.0 repositories
|
|
instead of the previous version.
|
|
3. Run the `apt-get update logstash` or `yum update logstash` command as appropriate for your operating system.
|
|
4. Test your configuration file with the `logstash --configtest -f <configuration-file>` command. Configuration options for
|
|
some Logstash plugins have changed in the 2.0 release.
|
|
5. Restart your Logstash pipeline after updating your configuration file.
|
|
|
|
=== Upgrading Using a Direct Download
|
|
|
|
This procedure downloads the relevant Logstash binaries directly from Elastic.
|
|
|
|
1. Shut down your Logstash pipeline, including any inputs that send events to Logstash.
|
|
2. Download the https://www.elastic.co/downloads/logstash[Logstash installation file] that matches your host environment.
|
|
3. Unpack the installation file into your Logstash directory.
|
|
4. Test your configuration file with the `logstash --configtest -f <configuration-file>` command. Configuration options for
|
|
some Logstash plugins have changed in the 2.0 release.
|
|
5. Restart your Logstash pipeline after updating your configuration file.
|
|
|
|
=== Upgrading Logstash and Elasticsearch to 2.0
|
|
|
|
If you are using Elasticsearch as an output, and wish to upgrade to Elasticsearch 2.0, please be
|
|
aware of https://www.elastic.co/guide/en/elasticsearch/reference/2.0/breaking-changes-2.0.html[breaking changes]
|
|
before you upgrade. In addition, the following steps needs to be performed after upgrading to Elasticsearch 2.0:
|
|
|
|
**Mapping changes:** Users may have custom template changes, so by default a Logstash upgrade will
|
|
leave the template as is. Even if you don't have a custom template, Logstash will not overwrite an existing
|
|
template by default.
|
|
|
|
There is one known issue (removal of https://www.elastic.co/guide/en/elasticsearch/reference/1.4/mapping-object-type.html#_path_3[path]) with using GeoIP filter that needs a manual update to the template.
|
|
|
|
Note: If you have custom template changes, please make sure to save it and merge any changes. You can
|
|
get the existing template by running:
|
|
|
|
[source,shell]
|
|
curl -XGET localhost:9200/_template/logstash
|
|
|
|
|
|
Add the following option to your Logstash config:
|
|
|
|
[source,json]
|
|
output {
|
|
elasticsearch {
|
|
template_overwrite => true
|
|
}
|
|
}
|
|
|
|
Restart Logstash.
|
|
|
|
**Dots in fields:** Elasticsearch 2.0 does not allow field names to contain the `.` character.
|
|
Further details about this change https://www.elastic.co/guide/en/elasticsearch/reference/2.0/breaking_20_mapping_changes.html#_field_names_may_not_contain_dots[here]. Some plugins already have been updated to compensate
|
|
for this breaking change, including logstash-filter-metrics and logstash-filter-elapsed.
|
|
These plugin updates are available for Logstash 2.0. To upgrade to the latest version of these
|
|
plugins, the command is:
|
|
|
|
[source,shell]
|
|
bin/plugin update <plugin_name>
|
|
|
|
**Multiline Filter:** If you are using the Multiline Filter in your configuration and upgrade to Logstash 2.0,
|
|
you will get an error. Make sure to explicitly set the number of filter workers (`-w`) to `1`. You can set the number
|
|
of workers by passing a command line flag such as:
|
|
|
|
[source,shell]
|
|
bin/logstash `-w 1`
|