From 32ed1ceb4daa4e82e70be738969360cfb95c61be Mon Sep 17 00:00:00 2001
From: LeeDr <lee.drengenberg@elastic.co>
Date: Fri, 22 Jul 2016 13:25:11 -0500
Subject: [PATCH] Added 'Upgrading Kibana' section

---
 docs/setup.asciidoc | 35 +++++++++++++++++++++++++++++------
 1 file changed, 29 insertions(+), 6 deletions(-)

diff --git a/docs/setup.asciidoc b/docs/setup.asciidoc
index 9504aee0ba058..b06f8ece6cbeb 100644
--- a/docs/setup.asciidoc
+++ b/docs/setup.asciidoc
@@ -1,10 +1,10 @@
 [[setup]]
-== Getting Kibana Up and Running
+== Installing Kibana
 You can set up Kibana and start exploring your Elasticsearch indices in minutes.
 All you need is:
 
 * Elasticsearch {esversion}
-* A modern web browser - http://www.elastic.co/subscriptions/matrix#matrix_browsers[Supported Browsers].
+* A modern web browser - https://www.elastic.co/support/matrix#show_browsers[Supported Browsers].
 * Information about your Elasticsearch installation:
 ** URL of the Elasticsearch instance you want to connect to.
 ** Which Elasticsearch indices you want to search.
@@ -12,22 +12,45 @@ All you need is:
 NOTE: If your Elasticsearch installation is protected by http://www.elastic.co/overview/shield/[{scyld}], see
 {shield}/kibana.html#using-kibana4-with-shield[{scyld} with Kibana] for additional setup instructions.
 
+=== Upgrading Kibana
+
+Your existing Kibana version is generally compatible with the next minor version release of Elasticsearch.
+This means you should upgrade your Elasticsearch cluster(s) before or at the same time as Kibana.
+We cannot guarantee compatibility between major version releases so in those cases both Elasticsearch and Kibana must be upgraded together.
+
+. https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-snapshots.html[snapshot] existing `.kibana` index in Elasticsearch
+. save a backup copy of the existing `config/kibana.yml`
+. take note of the Kibana plugins that are installed;
+.. `/opt/kibana/bin/kibana plugin --list` on 4.x versions of Kibana.
+.. `/usr/share/kibana/bin/kibana-plugin --list` on 5.x versions of Kibana.
+. For Kibana installations using an extracted **archive file**;
+.. extract the new version of Kibana into a different directory.  See steps below.
+.. migrate any custom configuration from your old kibana.yml to your new one
+.. follow other steps below to complete the new installation
+.. once the new version is fully configured and working with required plugins, remove the previous version of Kibana
+. For Kibana installations using a Linux **package manager**;
+.. uninstall the existing Kibana package `apt-get remove kibana` or `yum remove kibana`
+.. install the new Kibana package.  See steps below.   (There have been some installer issues between various version of Kibana so the uninstall and install process is safer than an upgrade.)
+
+
 [float]
 [[install]]
-=== Install and Start Kibana
+=== Install and Start Kibana from archive file
 
 To get Kibana up and running:
 
 . Download the https://www.elastic.co/downloads/kibana[Kibana {version} binary package] for your platform.
 . Extract the `.zip` or `tar.gz` archive file.
-. After installing, run Kibana from the install directory: `bin/kibana` (Linux/MacOSX) or `bin\kibana.bat` (Windows).
+. If upgrading, copy configuration changes from the previous kibana.yml to the new version.
+. Optionally install Kibana plugins.
+. Run Kibana from the install directory: `bin/kibana` (Linux/MacOSX) or `bin\kibana.bat` (Windows).
 
 On Unix, you can instead run the package manager suited for your distribution.
 
-////
+
 [float]
 include::kibana-repositories.asciidoc[]
-////
+
 
 That's it! Kibana is now running on port 5601.