[[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`