diff --git a/docs/kibana-repositories.asciidoc b/docs/kibana-repositories.asciidoc index 0587adb69ee172..ca6a7cd71ad53d 100644 --- a/docs/kibana-repositories.asciidoc +++ b/docs/kibana-repositories.asciidoc @@ -1,8 +1,8 @@ [[setup-repositories]] -=== Install Kibana using a Linux Package Manager +=== Installing Kibana with apt and yum -Binary packages for Kibana are available for Unix distributions that support the `apt` and `yum` tools. We also have -repositories available for APT and YUM based distributions. +Binary packages for Kibana are available for Unix distributions that support the `apt` and `yum` tools. +We also have repositories available for APT and YUM based distributions. NOTE: Since the packages are created as part of the Kibana build, source packages are not available. diff --git a/docs/setup.asciidoc b/docs/setup.asciidoc index 547f5b8729b318..91940320ffaa46 100644 --- a/docs/setup.asciidoc +++ b/docs/setup.asciidoc @@ -1,6 +1,6 @@ [[setup]] -== Installing Kibana -You can set up Kibana and start exploring your Elasticsearch indices in minutes. +== Setting Up Kibana +You can install Kibana and start exploring your Elasticsearch indices in minutes. All you need is: * Elasticsearch {esversion} @@ -9,114 +9,70 @@ All you need is: ** URL of the Elasticsearch instance you want to connect to. ** Which Elasticsearch indices you want to search. -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. - -To upgrade Kibana: - -. Create a https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-snapshots.html[snapshot] of the existing `.kibana` index. -. Back up the `kibana.yml` configuration file. -. Take note of the Kibana plugins that are installed: - * `bin/kibana plugin --list` on 4.x versions of Kibana. - * `bin/kibana-plugin list` on 5.x versions of Kibana. -. To upgrade from an 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 -. To upgrade using a Linux Package Manager: -.. Uninstall the existing Kibana package: `apt-get remove kibana` or `yum remove kibana` -.. Install the new Kibana package. 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 from an Archive File - -To get Kibana up and running: +=== Install Kibana +To install and start Kibana: -. Download the https://www.elastic.co/downloads/kibana[Kibana {version} binary package] for your platform. +. Download the https://www.elastic.co/downloads/kibana[Kibana 4 binary package] for your platform. . Extract the `.zip` or `tar.gz` archive file. . If you're upgrading, migrate any configuration changes from the previous `kibana.yml` to the new version. . Install Kibana plugins (optional). . 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. -[float] -[[kibana-dynamic-mapping]] -==== Kibana and Elasticsearch Dynamic Mapping -By default, Elasticsearch enables {ref}dynamic-mapping.html[dynamic mapping] for fields. Kibana needs dynamic mapping -to use fields in visualizations correctly, as well as to manage the `.kibana` index where saved searches, -visualizations, and dashboards are stored. - -If your Elasticsearch use case requires you to disable dynamic mapping, you need to manually provide mappings for -fields that Kibana uses to create visualizations. You also need to manually enable dynamic mapping for the `.kibana` -index. +On Unix, you can also install Kibana using the package manager suited for your distribution. For more +information, see <>. -The following procedure assumes that the `.kibana` index does not already exist in Elasticsearch and that the -`index.mapper.dynamic` setting in `elasticsearch.yml` is set to `false`: - -. Start Elasticsearch. -. Create the `.kibana` index with dynamic mapping enabled just for that index: -+ -[source,shell] -PUT .kibana -{ - "index.mapper.dynamic": true -} -+ -. Start Kibana and navigate to the web UI and verify that there are no error messages related to dynamic mapping. +IMPORTANT: If your Elasticsearch installation is protected by http://www.elastic.co/overview/shield/[Shield] +see {shield}/kibana.html#using-kibana4-with-shield[Using Kibana with Shield] for additional setup +instructions. [float] [[connect]] === Connect Kibana with Elasticsearch -Before you can start using Kibana, you need to tell it which Elasticsearch indices you want to explore. The first time -you access Kibana, you are prompted to define an _index pattern_ that matches the name of one or more of your indices. -That's it. That's all you need to configure to start using Kibana. You can add index patterns at any time from the -<>. +Before you can start using Kibana, you need to tell it which Elasticsearch indices you want to explore. +The first time you access Kibana, you are prompted to define an _index pattern_ that matches the name of +one or more of your indices. That's it. That's all you need to configure to start using Kibana. You can +add index patterns at any time from the <>. -TIP: By default, Kibana connects to the Elasticsearch instance running on `localhost`. To connect to a different -Elasticsearch instance, modify the Elasticsearch URL in the `kibana.yml` configuration file and restart Kibana. For -information about using Kibana with your production nodes, see <>. +TIP: By default, Kibana connects to the Elasticsearch instance running on `localhost`. To connect to a +different Elasticsearch instance, modify the Elasticsearch URL in the `kibana.yml` configuration file and +restart Kibana. Forninformation about using Kibana with your production nodes, see <>. To configure the Elasticsearch indices you want to access with Kibana: -. Point your browser at port 5601 to access the Kibana UI. For example, `localhost:5601` or `http://YOURDOMAIN.com:5601`. +. Point your browser at port 5601 to access the Kibana UI. For example, `localhost:5601` or +`http://YOURDOMAIN.com:5601`. + image:images/Start-Page.png[Kibana start page] + -. Specify an index pattern that matches the name of one or more of your Elasticsearch indices. By default, Kibana -guesses that you're working with data being fed into Elasticsearch by Logstash. If that's the case, you can use the -default `logstash-*` as your index pattern. The asterisk (*) matches zero or more characters in an index's name. If -your Elasticsearch indices follow some other naming convention, enter an appropriate pattern. The "pattern" can also -simply be the name of a single index. -. Select the index field that contains the timestamp that you want to use to perform time-based comparisons. Kibana -reads the index mapping to list all of the fields that contain a timestamp. If your index doesn't have time-based data, -disable the *Index contains time-based events* option. +. Specify an index pattern that matches the name of one or more of your Elasticsearch indices. By default, +Kibana guesses that you're working with data being fed into Elasticsearch by Logstash. If that's the case, +you can use the default `logstash-*` as your index pattern. The asterisk (*) matches zero or more +characters in an index's name. If your Elasticsearch indices follow some other naming convention, enter +an appropriate pattern. The "pattern" can also simply be the name of a single index. +. Select the index field that contains the timestamp that you want to use to perform time-based +comparisons. Kibana reads the index mapping to list all of the fields that contain a timestamp. If your +index doesn't have time-based data, disable the *Index contains time-based events* option. + -WARNING: Using event times to create index names is *deprecated* in this release of Kibana. Starting in the 2.1 -release, Elasticsearch includes sophisticated date parsing APIs that Kibana uses to determine date information, -removing the need to specify dates in the index pattern name. +WARNING: Using event times to create index names is *deprecated* in this release of Kibana. Support for +this functionality will be removed entirely in the next major Kibana release. Elasticsearch 2.1 includes +sophisticated date parsing APIs that Kibana uses to determine date information, removing the need to +specify dates in the index pattern name. + . Click *Create* to add the index pattern. This first pattern is automatically configured as the default. -When you have more than one index pattern, you can designate which one to use as the default from *Settings > Indices*. +When you have more than one index pattern, you can designate which one to use as the default from +*Settings > Indices*. + +All done! Kibana is now connected to your Elasticsearch data. Kibana displays a read-only list of fields +configured for the matching index. -All done! Kibana is now connected to your Elasticsearch data. Kibana displays a read-only list of fields configured for -the matching index. +NOTE: Kibana relies on dynamic mapping to use fields in visualizations and manage the +`.kibana` index. If you have disabled dynamic mapping, you need to manually provide +mappings for the fields that Kibana uses to create visualizations. For more information, see +<>. [float] [[explore]] @@ -127,5 +83,60 @@ You're ready to dive in to your data: * Chart and map your data from the <> page. * Create and view custom dashboards from the <> page. -For a tutorial that explores these core Kibana concepts, take a look at the <> page. +For a step-by-step introduction to these core Kibana concepts, see the <> tutorial. + +[float] +[[kibana-dynamic-mapping]] +=== Kibana and Elasticsearch Dynamic Mapping +By default, Elasticsearch enables {ref}dynamic-mapping.html[dynamic mapping] for fields. Kibana needs +dynamic mapping to use fields in visualizations correctly, as well as to manage the `.kibana` index +where saved searches, visualizations, and dashboards are stored. + +If your Elasticsearch use case requires you to disable dynamic mapping, you need to manually provide +mappings for fields that Kibana uses to create visualizations. You also need to manually enable dynamic +mapping for the `.kibana` index. + +The following procedure assumes that the `.kibana` index does not already exist in Elasticsearch and +that the `index.mapper.dynamic` setting in `elasticsearch.yml` is set to `false`: + +. Start Elasticsearch. +. Create the `.kibana` index with dynamic mapping enabled just for that index: ++ +[source,shell] +PUT .kibana +{ + "index.mapper.dynamic": true +} ++ +. Start Kibana and navigate to the web UI and verify that there are no error messages related to dynamic +mapping. + +include::kibana-repositories.asciidoc[] + +[[upgrading-kibana]] +=== 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. + +To upgrade Kibana: + +. Create a https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-snapshots.html[snapshot] +of the existing `.kibana` index. +. Back up the `kibana.yml` configuration file. +. Take note of the Kibana plugins that are installed: + * `bin/kibana plugin --list` on 4.x versions of Kibana. + * `bin/kibana-plugin list` on 5.x versions of Kibana. +. To upgrade from an 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 +. To upgrade using a Linux Package Manager: +.. Uninstall the existing Kibana package: `apt-get remove kibana` or `yum remove kibana` +.. Install the new Kibana package. There have been some installer issues between various version of +Kibana so the uninstall and install process is safer than an upgrade. \ No newline at end of file