Merge pull request elastic#7589 from palecur/master

Alpha4 documentation updates
ycombinator · Jun 30, 2016 · 55bd8c0 · 55bd8c0
2 parents ce9efff + d8953f6
commit 55bd8c0
Show file tree

Hide file tree

Showing 23 changed files with 1,276 additions and 24 deletions.
diff --git a/docs/advanced-settings.asciidoc b/docs/advanced-settings.asciidoc
@@ -14,9 +14,9 @@ compatible with other configuration settings. Deleting a custom setting removes
 `dateFormat:dow`:: This property defines what day weeks should start on.
 adapt to the interval between measurements. Keys are http://en.wikipedia.org/wiki/ISO_8601#Time_intervals[ISO8601 intervals].
 `defaultIndex`:: Default is `null`. This property specifies the default index.
+`defaultColumns`:: Default is `_source`. Defines the columns that appear by default on the Discover page.
 `metaFields`:: An array of fields outside of `_source`. Kibana merges these fields into the document when displaying the
 document.
-`defaultColumns`:: Default is `_source`. Defines the columns that appear by default on the Discover page.
 `discover:sampleSize`:: The number of rows to show in the Discover table.
 `doc_table:highlight`:: Highlight results in Discover and Saved Searches Dashboard. Highlighing makes request slow when
 working on big documents. Set this property to `false` to disable highlighting.
@@ -52,3 +52,10 @@ mentioned use "_default_".
 `timepicker:timeDefaults`:: The default time filter selection.
 `timepicker:refreshIntervalDefaults`:: The time filter's default refresh interval.
 `dashboard:defaultDarkTheme`:: Set this property to `true` to make new dashboards use the dark theme by default.
+`filters:pinnedByDefault`:: Set this property to `true` to make filters have a global state by default.
+`notifications:banner`:: You can specify a custom banner to display temporary notices to all users. This field supports 
+Markdown.
+`notifications:lifetime:banner`:: Specifies the duration in milliseconds for banner notification displays. The default value is 3000000. Set this field to `Infinity` to disable banner notifications.
+`notifications:lifetime:error`:: Specifies the duration in milliseconds for error notification displays. The default value is 300000. Set this field to `Infinity` to disable error notifications.
+`notifications:lifetime:warning`:: Specifies the duration in milliseconds for warning notification displays. The default value is 10000. Set this field to `Infinity` to disable warning notifications.
+`notifications:lifetime:info`:: Specifies the duration in milliseconds for information notification displays. The default value is 5000. Set this field to `Infinity` to disable information notifications.
diff --git a/docs/area.asciidoc b/docs/area.asciidoc
@@ -67,7 +67,6 @@ values.
 *Scale Y-Axis to Data Bounds*:: The default Y axis bounds are zero and the maximum value returned in the data. Check 
 this box to change both upper and lower bounds to match the values returned in the data.
 *Show Tooltip*:: Check this box to enable the display of tooltips.
-*Show Legend*:: Check this box to enable the display of a legend next to the chart.
 
 [float]
 [[area-viewing-detailed-information]]

diff --git a/docs/getting-started.asciidoc b/docs/getting-started.asciidoc
@@ -27,15 +27,14 @@ The tutorials in this section rely on the following data sets:
 
 * The complete works of William Shakespeare, suitably parsed into fields. Download this data set by clicking here: 
   https://www.elastic.co/guide/en/kibana/3.0/snippets/shakespeare.json[shakespeare.json].
-* A set of fictitious accounts with randomly generated data. Download this data set by clicking here: 
-  https://github.com/bly2k/files/blob/master/accounts.zip?raw=true[accounts.zip]
+* A set of fictitious accounts with randomly generated data, in CSV format. Download this data set by clicking here: 
+  https://www.github.com/elastic/kibana/docs/tutorial/accounts.csv[accounts.csv]
 * A set of randomly generated log files. Download this data set by clicking here: 
   https://download.elastic.co/demos/kibana/gettingstarted/logs.jsonl.gz[logs.jsonl.gz]
 
-Two of the data sets are compressed. Use the following commands to extract the files:
+Extract the logs with the following command:
 
 [source,shell]
-unzip accounts.zip
 gunzip logs.jsonl.gz
 
 The Shakespeare data set is organized in the following schema:
@@ -82,6 +81,8 @@ field's searchability or whether or not it's _tokenized_, or broken up into sepa
 
 Use the following command to set up a mapping for the Shakespeare data set:
 
+=============
+
 [source,shell]
 curl -XPUT http://localhost:9200/shakespeare -d '
 {
@@ -98,6 +99,8 @@ curl -XPUT http://localhost:9200/shakespeare -d '
 }
 ';
 
+=============
+
 This mapping specifies the following qualities for the data set:
 
 * The _speaker_ field is a string that isn't analyzed. The string in this field is treated as a single unit, even if
@@ -167,16 +170,29 @@ curl -XPUT http://localhost:9200/logstash-2015.05.20 -d '
 }
 ';
 
-The accounts data set doesn't require any mappings, so at this point we're ready to use the Elasticsearch 
-{ref}/docs-bulk.html[`bulk`] API to load the data sets with the following commands:
+At this point we're ready to use the Elasticsearch {ref}/docs-bulk.html[`bulk`] API to load the data sets with the 
+following commands:
 
 [source,shell]
-curl -XPOST 'localhost:9200/bank/account/_bulk?pretty' --data-binary @accounts.json
 curl -XPOST 'localhost:9200/shakespeare/_bulk?pretty' --data-binary @shakespeare.json
 curl -XPOST 'localhost:9200/_bulk?pretty' --data-binary @logs.jsonl
 
 These commands may take some time to execute, depending on the computing resources available.
 
+To load the Accounts data set, click the *Management* image:images/SettingsButton.jpg[gear icon] tab, the 
+select *Upload CSV*.
+
+image::images/management-panel.png[kibana management panel]
+
+Click *Select File*, then navigate to the `accounts.csv` file. Review the sample, then click *Next*.
+
+image::images/csv-sample.png[sample csv import]
+
+Review the index pattern built by the CSV import function. You can change any field types from the drop-downs, but for 
+this tutorial, accept the defaults. Enter `bank` as the name for the index pattern, then click *Save*.
+
+image::images/sample-index.png[sample index pattern]
+
 Verify successful loading with the following command:
 
 [source,shell]

diff --git a/docs/images/NewViz01.jpg b/docs/images/NewViz01.jpg
diff --git a/docs/images/csv-sample.png b/docs/images/csv-sample.png
diff --git a/docs/images/dashboard-icon.png b/docs/images/dashboard-icon.png
diff --git a/docs/images/discover-compass.png b/docs/images/discover-compass.png
diff --git a/docs/images/history.png b/docs/images/history.png
diff --git a/docs/images/kibana-status-page.png b/docs/images/kibana-status-page.png
diff --git a/docs/images/management-panel.png b/docs/images/management-panel.png
diff --git a/docs/images/sample-index.png b/docs/images/sample-index.png
diff --git a/docs/images/settings.png b/docs/images/settings.png
diff --git a/docs/images/tutorial-discover-2.png b/docs/images/tutorial-discover-2.png
diff --git a/docs/images/tutorial-discover-3.png b/docs/images/tutorial-discover-3.png
diff --git a/docs/images/tutorial-discover.png b/docs/images/tutorial-discover.png
diff --git a/docs/images/tutorial-visualize.png b/docs/images/tutorial-visualize.png
diff --git a/docs/images/visualize-icon.png b/docs/images/visualize-icon.png
diff --git a/docs/line.asciidoc b/docs/line.asciidoc
@@ -46,7 +46,6 @@ affect the representation of your data and create a potential for ambiguity.
 *Set Y-Axis Extents*:: Check this box and enter values in the *y-max* and *y-min* fields to set the Y axis to specific 
 values. 
 *Show Tooltip*:: Check this box to enable the display of tooltips.
-*Show Legend*:: Check this box to enable the display of a legend next to the chart.
 *Scale Y-Axis to Data Bounds*:: The default Y-axis bounds are zero and the maximum value returned in the data. Check 
 this box to change both upper and lower bounds to match the values returned in the data.
 

diff --git a/docs/pie.asciidoc b/docs/pie.asciidoc
@@ -80,7 +80,6 @@ Select the *Options* tab to change the following aspects of the table:
 
 *Donut*:: Display the chart as a sliced ring instead of a sliced pie.
 *Show Tooltip*:: Check this box to enable the display of tooltips.
-*Show Legend*:: Check this box to enable the display of a legend next to the chart.
 
 After changing options, click the *Apply changes* button to update your visualization, or the grey *Discard 
 changes* button to keep your visualization in its current state.

diff --git a/docs/production.asciidoc b/docs/production.asciidoc
@@ -17,11 +17,231 @@ traffic across the nodes in your Elasticsearch cluster, you can run Kibana
 and an Elasticsearch client node on the same machine. For more information, see
 <<load-balancing, Load Balancing Across Multiple Elasticsearch Nodes>>.
 
+[float]
+[[configuring-kibana-shield]]
+=== Configuring Kibana to Work with {scyld}
+
+Kibana users have to authenticate when your cluster has {scyld} enabled. You
+configure {scyld} roles for your Kibana users to control what data those users
+can access. Kibana runs a webserver that makes requests to Elasticsearch on the
+client's behalf, so you also need to configure credentials for the Kibana server
+so those requests can be authenticated. 
+
+You must configure Kibana to encrypt communications between the browser and the 
+Kibana server to prevent user passwords from being sent in the clear. If are 
+using SSL/TLS to encrypt traffic to and from the nodes in your Elasticsearch 
+cluster, you must also configure Kibana to connect to Elasticsearch via HTTPS.
+
+With {scyld} enabled, if you load a Kibana dashboard that accesses data in an
+index that you are not authorized to view, you get an error that indicates the
+index does not exist. {scyld} does not currently provide a way to control which
+users can load which dashboards.
+
+To use Kibana with {scyld}:
+
+. Configure the password for the built-in `kibana` user. The Kibana server uses
+this user to gain access to the cluster monitoring APIs and the `.kibana` index.
+The server does _not_ need access to user indexes.
++
+By default, the `kibana` user password is set to `changeme`. Change this password
+through the reset password API:
++
+[source,shell]
+--------------------------------------------------------------------------------
+curl -XPUT 'localhost:9200/_security/user/kibana/_password' -d '{
+  "password" : "s0m3th1ngs3cr3t"
+}'
+--------------------------------------------------------------------------------
++
+Once reset, you need to add the following property to `kibana.yml`:
++
+[source,yaml]
+--------------------------------------------------------------------------------
+elasticsearch.password: "s0m3th1ngs3cr3t"
+--------------------------------------------------------------------------------
+
+[[kibana-roles]]
+. Derive Kibana user roles from the example <<kibana-user-role, `my_kibana_user`>>
+user role. Assign the roles to the Kibana users to control which indices they can
+access. Kibana users need access to the indices that they will be working with
+and the `.kibana` index where their saved searches, visualizations, and dashboards
+are stored. Users also need access to the `.kibana-devnull` index. The example
+`my_kibana_user` role grants read access to the indices that match the
+`logstash-*` pattern and full access to the `.kibana` index, which is required.
++
+TIP: You can define as many different roles for your Kibana users as you need.
++
+[[kibana-user-role]]
+For example, the following `my_kibana_user` role only allows users to discover
+and visualize data in the `logstash-*` indices.
++
+[source,js]
+--------------------------------------------------------------------------------
+{
+  "cluster" : [ "monitor" ],
+  "indices" : [
+    {
+      "names" : [ "logstash-*" ],
+      "privileges" : [ "view_index_metadata", "read" ]
+    },
+    {
+      "names" : [ ".kibana*" ], <1>
+      "privileges" : [ "manage", "read", "index" ]
+    }
+  ]
+}
+--------------------------------------------------------------------------------
+<1> All Kibana users need access to the `.kibana` and `.kibana-devnull` indices.
+
+. Assign the appropriate roles to your Kibana users or groups of users:
+
+** If you're using the `native` realm, you can assign roles using the
+{shield}/shield-rest.html#shield-users-rest[{scyld} User Management API]. For example, the following
+creates a user named `jacknich` and assigns it the `kibana_monitoring` role:
++
+[source,js]
+--------------------------------------------------------------------------------
+POST /_xpack/security/user/jacknich
+{
+  "password" : "t0pS3cr3t",
+  "roles" : [ "kibana_monitoring" ]
+}
+--------------------------------------------------------------------------------
+
+** If you are using an LDAP or Active Directory realm, you can either assign
+roles on a per user basis, or assign roles to groups of users. By default, role
+mappings are stored in {shield}/mapping-roles.html[`CONFIGDIR/x-pack/role_mapping.yml`].
+For example, the following snippet assigns the `kibana_monitoring` role to the
+group named `admins` and the user named Jack Nicholson:
++
+[source,yaml]
+--------------------------------------------------------------------------------
+kibana_monitoring:
+  - "cn=admins,dc=example,dc=com"
+  - "cn=Jack Nicholson,dc=example,dc=com"
+--------------------------------------------------------------------------------
+
+. If you have enabled SSL encryption in {scyld}, configure Kibana to connect
+to Elasticsearch via HTTPS. To do this:
+
+.. Specify the HTTPS protocol in the `elasticsearch.url` setting in the Kibana
+configuration file, `kibana.yml`:
++
+[source,yaml]
+--------------------------------------------------------------------------------
+elasticsearch.url: "https://<your_elasticsearch_host>.com:9200"
+--------------------------------------------------------------------------------
+
+.. If you are using your own CA to sign certificates for Elasticsearch, set the
+`elasticsearch.ssl.ca` setting in `kibana.yml` to specify the location of the PEM
+file.
++
+[source,yaml]
+--------------------------------------------------------------------------------
+elasticsearch.ssl.ca: /path/to/your/cacert.pem
+--------------------------------------------------------------------------------
+
+. Configure Kibana to encrypt communications between the browser and the Kibana
+server. To do this, configure the `server.ssl.key` and `server.ssl.cert` properties
+in `kibana.yml`:
++
+[source,yaml]
+--------------------------------------------------------------------------------
+server.ssl.key: /path/to/your/server.key
+server.ssl.cert: /path/to/your/server.crt
+--------------------------------------------------------------------------------
++
+Once you enable SSL encryption between the browser and the Kibana server, access
+Kibana via HTTPS. For example, `https://localhost:5601`.
++
+NOTE: Enabling browser encryption is required to prevent passing user credentials
+      in the clear.
+
+. Install X-Pack into Kibana. {scyld} secures user sessions and enables users
+to log in and out of Kibana. To install the X-Pack on Kibana:
+
+.. Run the following command in your Kibana installation directory.
++
+[source,console]
+--------------------------------------------------------------------------------
+bin/kibana-plugin install x-pack
+--------------------------------------------------------------------------------
++
+[NOTE]
+=============================================================================
+To perform an offline install, download X-Pack from
++http://download.elasticsearch.org/kibana/x-pack/xpack-{version}.zip+
+(http://download.elasticsearch.org/kibana/x-pack/xpack-{version}.zip.sha1.txt[sha1])
+and run:
+
+[source,shell]
+---------------------------------------------------------
+bin/kibana-plugin install file:///path/to/file/xpack-{version}.tar.gz.
+---------------------------------------------------------
+=============================================================================
+
+.. Set the `xpack.security.encryptionKey` property in the `kibana.yml` configuration file.
+You can use any text string as the encryption key.
++
+[source,yaml]
+--------------------------------------------------------------------------------
+xpack.security.encryptionKey: "something_secret"
+--------------------------------------------------------------------------------
+
+.. To change the default session duration, set the `xpack.security.sessionTimeout` property
+in the `kibana.yml` configuration file. By default, sessions expire after 30 minutes.
+The timeout is specified in milliseconds. For example, set the timeout to 600000
+to expire sessions after 10 minutes:
++
+[source,yaml]
+--------------------------------------------------------------------------------
+xpack.security.sessionTimeout: 600000
+--------------------------------------------------------------------------------
+
+. Restart Kibana and verify that you can sign in as a user. If you are running
+Kibana locally, go to `https://localhost:5601` and enter the credentials for a
+user you've assigned a Kibana user role. For example, you could log in as the
+`jacknich` user created above.
++
+kibana-login.jpg["Kibana Login",link="images/kibana-login.jpg"]
++
+NOTE: This must be a user who has been assigned a role derived from the example
+      <<kibana-user-role, `my_kibana_user` user role>>. Kibana server credentials
+      should only be used internally by the Kibana server. The Kibana server role
+      doesn't grant permission to access user indices.
+
+[float]
+[[security-ui-settings]]
+===== Kibana {scyld} UI Settings
+[options="header"]
+|======
+| Name                               | Default                  | Description
+| `xpack.security.encryptionKey`     | -                        | An arbitrary string used to encrypt credentials in a
+                                                                  cookie. It is crucial that this key is not exposed to
+                                                                  users of Kibana. Required.
+| `xpack.security.sessionTimeout`    | `1800000` (30 minutes)   | Sets the session duration (in milliseconds).
+| `xpack.security.cookieName`        | `"sid"`                  | Sets the name of the cookie used for the session.
+| `xpack.security.skipSslCheck`      | `false`                  | Advanced setting. Set to `true` to enable Kibana to
+                                                                  start if `server.ssl.cert` and `server.ssl.key` are
+                                                                  not specified in `kibana.yml`. This should only be
+                                                                  used if either SSL is configured outside of Kibana
+                                                                  (for example, you are routing requests through a load
+                                                                  balancer or proxy) or
+                                                                  `xpack.security.useUnsafeSessions` is also set to
+                                                                  `true`.
+| `xpack.security.useUnsafeSessions` | `false`                  | Advanced setting. Set to `true` to use insecure
+                                                                  cookies for sessions in Kibana. Requires
+                                                                  `xpack.security.skipSslCheck` to also be set to
+                                                                  `true`.
+|======
+
+////
+
 [float]
 [[configuring-kibana-shield]]
 === Configuring Kibana to Work with {scyld}
 If you are using {scyld} to authenticate Elasticsearch users, you need to provide
-the Kibana server with credentials so it can access the `.kibana` index and monitor
+the Kibana server with credentials to enable access to the `.kibana` index and monitor
 the cluster.
 
 To configure credentials for the Kibana server:
@@ -45,6 +265,7 @@ dashboards. For more information, see {shield}/kibana.html[Using Kibana with {sc
 
 TIP: See <<kibana-dynamic-mapping, Kibana and Elasticsearch Dynamic Mapping>> for important information on Kibana and
 the dynamic mapping feature in Elasticsearch.
+////
 
 [float]
 [[enabling-ssl]]
@@ -93,8 +314,7 @@ the query that populates a Kibana visualization, the user just sees an empty
 visualization.
 
 To configure access to Kibana using {scyld}, you create roles
-for Kibana using the `kibana4` default role as a starting point. For more
-information, see {shield}/kibana.html#using-kibana4-with-shield[Using Kibana with {scyld}].
+for Kibana using the `my_kibana_user` default role as a starting point.
 
 [float]
 [[load-balancing]]