Improve breaking changes documentation

docs/index.asciidoc

@@ -16,7 +16,7 @@ include::setup.asciidoc[]
 
 include::getting-started.asciidoc[]
 
-include::breaking-changes.asciidoc[]
+include::migration/index.asciidoc[]
 
 include::plugins.asciidoc[]
 

docs/migration/index.asciidoc

@@ -0,0 +1,8 @@
+[[breaking-changes]]
+== Breaking Changes
+
+This section discusses the changes that you need to be aware of when migrating
+your application from one version of Kibana to another.
+
+include::migrate_5_0.asciidoc[]
+

docs/migration/migrate_5_0.asciidoc

@@ -0,0 +1,45 @@
+[[breaking-changes-5.0]]
+=== Breaking changes in 5.0
+
+==== Kibana binds to localhost by default
+{k4pull}8013[Pull Request 8013]
+
+*Details:* Kibana (like Elasticsearch) now binds to localhost for security purposes instead of 0.0.0.0 (all addresses). Previous binding to 0.0.0.0 also caused issues for Windows users.
+
+*Impact:* If you are running Kibana inside a container/environment that does not allow localhost binding, this will cause Kibana not to start up unless server.host is configured in the kibana.yml to a valid IP address/host, etc..
+
+==== Markdown headers
+
+{k4pull}7855[Pull Request 7855]
+
+*Details:* As part of addressing the security issue https://www.elastic.co/community/security[ESA-2016-03] (CVE-2016-1000220) in the Kibana product, the markdown version has been bumped.
+
+*Impact:* As a result of the fix to ESA-2016-03, there is a slight change in the markdown format for headers.
+
+Previously, headers are defined using `###` followed by the title:
+
+ ###Packetbeat:
+    [Dashboard](/#/dashboard/Packetbeat-Dashboard)
+    [Web transactions](/#/dashboard/HTTP)
+
+It should now be defined as follows (with a space between ### and the title):
+
+ ### Packetbeat:
+     [Dashboard](/#/dashboard/Packetbeat-Dashboard)
+     [Web transactions](/#/dashboard/HTTP)
+
+==== Linux package install directories
+
+{k4pull}7308[Pull Request 7308]
+
+*Details:* To align with the Elasticsearch packages, Kibana now installs binaries under `/usr/share/kibana` and configuration files under `/etc/kibana`. Previously they were both located under `/opt/kibana`.
+
+*Impact:* Apart from learning the new location of Kibana binaries and configuration files, you may have to update your automation scripts as needed.
+
+==== The plugin installer now has its own executable
+
+{k4pull}6402[Pull Request 6402]
+
+*Details:* The new installer can be found at `/bin/kibana-plugin`. When installing/removing Kibana plugins, you will now call `kibana-plugin` instead of the main kibana script.
+
+*Impact:* You may have to update your automation scripts.