[[upgrading-logstash]] == Upgrading Logstash [IMPORTANT] =========================================== Before upgrading Logstash: * Consult the <> docs. * Test upgrades in a development environment before upgrading your production cluster. While upgrading Logstash: * If you use {monitoring}, you must 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're upgrading other products in the stack, also read the {stack-ref}/index.html[Elastic Stack Installation and Upgrade Guide]. Want an upgrade list that's tailored to your stack? Try out our {upgrade_guide}[Interactive Upgrade Guide]. See the following topics for information about upgrading Logstash: * <> * <> * <> * <> [[upgrading-using-package-managers]] === Upgrading Using Package Managers This procedure uses <> 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 5.x repositories instead of the previous version. 3. Run the `apt-get upgrade logstash` or `yum update logstash` command as appropriate for your operating system. 4. Test your configuration file with the `logstash --config.test_and_exit -f ` command. Configuration options for some Logstash plugins have changed in the 5.x release. 5. Restart your Logstash pipeline after updating your configuration file. [[upgrading-using-direct-download]] === 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 --config.test_and_exit -f ` command. Configuration options for some Logstash plugins have changed in the 5.x release. 5. Restart your Logstash pipeline after updating your configuration file. [[upgrading-logstash-pqs]] === Upgrading with Persistent Queues Enabled Upgrading Logstash with persistent queues enabled is supported. The persistent queue directory is self-contained and can be read by a new Logstash instance running the same pipeline. You can safely shut down the original Logstash instance, spin up a new instance, and set `path.queue` in the `logstash.yml` <> to point to the original queue directory. You can also use a mounted drive to make this workflow easier. Keep in mind that only one Logstash instance can write to `path.queue`. You cannot have the original instance and the new instance writing to the queue at the same time. [[upgrading-logstash-5.0]] === Upgrading Logstash to 5.0 Before upgrading Logstash, remember to read the <>. If you are installing Logstash with other components in the Elastic Stack, also see the {stack-ref}/index.html[Elastic Stack installation and upgrade documentation]. ==== When to Upgrade Fresh installations can and should start with the same version across the Elastic Stack. Elasticsearch 5.0 does not require Logstash 5.0. An Elasticsearch 5.0 cluster will happily receive data from a Logstash 2.x instance via the default HTTP communication layer. This provides some flexibility to decide when to upgrade Logstash relative to an Elasticsearch upgrade. It may or may not be convenient for you to upgrade them together, and it is not required to be done at the same time as long as Elasticsearch is upgraded first. You should upgrade in a timely manner to get the performance improvements that come with Logstash 5.0, but do so in the way that makes the most sense for your environment. ==== When Not to Upgrade If any Logstash plugin that you require is not compatible with Logstash 5.0, then you should wait until it is ready before upgrading. Although we make great efforts to ensure compatibility, Logstash 5.0 is not completely backwards compatible. As noted in the Elastic Stack upgrade guide, Logstash 5.0 should not be upgraded before Elasticsearch 5.0. This is both practical and because some Logstash 5.0 plugins may attempt to use features of Elasticsearch 5.0 that did not exist in earlier versions. For example, if you attempt to send the 5.x template to a cluster before Elasticsearch 5.0, then it will not be able to use it and all indexing will fail likely fail. If you use your own, custom template with Logstash, then this issue can be ignored. Note the Elasticsearch Output Index Template change in the <> documentation for further insight into this change and how it impacts operations.