2015-02-13 19:22:02 +01:00
|
|
|
[[production]]
|
|
|
|
== Using Kibana in a Production Environment
|
2016-04-05 01:38:09 +02:00
|
|
|
* <<configuring-kibana-shield, Configuring Kibana to Work with {scyld}>>
|
2015-03-03 23:16:13 +01:00
|
|
|
* <<enabling-ssl, Enabling SSL>>
|
|
|
|
* <<controlling-access, Controlling Access>>
|
|
|
|
* <<load-balancing, Load Balancing Across Multiple Elasticsearch Nodes>>
|
2015-02-13 19:22:02 +01:00
|
|
|
|
|
|
|
How you deploy Kibana largely depends on your use case. If you are the only user,
|
2015-07-15 10:48:49 +02:00
|
|
|
you can run Kibana on your local machine and configure it to point to whatever
|
|
|
|
Elasticsearch instance you want to interact with. Conversely, if you have a large
|
2015-02-13 19:22:02 +01:00
|
|
|
number of heavy Kibana users, you might need to load balance across multiple
|
|
|
|
Kibana instances that are all connected to the same Elasticsearch instance.
|
|
|
|
|
2015-07-15 10:48:49 +02:00
|
|
|
While Kibana isn't terribly resource intensive, we still recommend running Kibana
|
2015-03-03 23:16:13 +01:00
|
|
|
separate from your Elasticsearch data or master nodes. To distribute Kibana
|
|
|
|
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>>.
|
2015-02-13 19:22:02 +01:00
|
|
|
|
2016-05-17 03:19:18 +02:00
|
|
|
[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
|
2016-06-30 23:32:21 +02:00
|
|
|
so those requests can be authenticated.
|
2016-05-17 03:19:18 +02:00
|
|
|
|
2016-06-30 23:32:21 +02:00
|
|
|
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
|
2016-05-17 03:19:18 +02:00
|
|
|
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`.
|
|
|
|
|======
|
|
|
|
|
2015-05-28 20:26:02 +02:00
|
|
|
|
2015-03-03 23:16:13 +01:00
|
|
|
[float]
|
|
|
|
[[enabling-ssl]]
|
2015-02-13 19:22:02 +01:00
|
|
|
=== Enabling SSL
|
2015-07-15 10:48:49 +02:00
|
|
|
Kibana supports SSL encryption for both client requests and the requests the Kibana server
|
2015-02-13 19:22:02 +01:00
|
|
|
sends to Elasticsearch.
|
|
|
|
|
2015-11-24 17:25:14 +01:00
|
|
|
To encrypt communications between the browser and the Kibana server, you configure the `ssl_key_file` and
|
2015-05-18 04:31:43 +02:00
|
|
|
`ssl_cert_file` properties in `kibana.yml`:
|
2015-02-13 19:22:02 +01:00
|
|
|
|
2015-05-01 19:59:15 +02:00
|
|
|
[source,text]
|
2015-02-13 19:22:02 +01:00
|
|
|
----
|
|
|
|
# SSL for outgoing requests from the Kibana Server (PEM formatted)
|
2015-11-24 17:25:14 +01:00
|
|
|
server.ssl.key: /path/to/your/server.key
|
|
|
|
server.ssl.cert: /path/to/your/server.crt
|
2015-02-13 19:22:02 +01:00
|
|
|
----
|
|
|
|
|
2016-04-05 01:38:09 +02:00
|
|
|
If you are using {scyld} or a proxy that provides an HTTPS endpoint for Elasticsearch,
|
2015-02-13 19:22:02 +01:00
|
|
|
you can configure Kibana to access Elasticsearch via HTTPS so communications between
|
2015-07-15 10:48:49 +02:00
|
|
|
the Kibana server and Elasticsearch are encrypted.
|
2015-02-13 19:22:02 +01:00
|
|
|
|
|
|
|
To do this, you specify the HTTPS
|
|
|
|
protocol when you configure the Elasticsearch URL in `kibana.yml`:
|
|
|
|
|
2015-05-01 19:59:15 +02:00
|
|
|
[source,text]
|
2015-02-13 19:22:02 +01:00
|
|
|
----
|
|
|
|
elasticsearch: "https://<your_elasticsearch_host>.com:9200"
|
|
|
|
----
|
|
|
|
|
|
|
|
If you are using a self-signed certificate for Elasticsearch, set the `ca` property in
|
|
|
|
`kibana.yml` to specify the location of the PEM file. Setting the `ca` property lets you leave the `verify_ssl` option enabled.
|
2015-05-01 19:59:15 +02:00
|
|
|
|
|
|
|
[source,text]
|
2015-02-13 19:22:02 +01:00
|
|
|
----
|
2015-08-19 15:24:35 +02:00
|
|
|
# If you need to provide a CA certificate for your Elasticsearch instance, put
|
2015-02-13 19:22:02 +01:00
|
|
|
# the path of the pem file here.
|
|
|
|
ca: /path/to/your/ca/cacert.pem
|
|
|
|
----
|
|
|
|
|
2015-03-03 23:16:13 +01:00
|
|
|
[float]
|
|
|
|
[[controlling-access]]
|
2015-02-13 19:22:02 +01:00
|
|
|
=== Controlling access
|
2016-04-05 01:38:09 +02:00
|
|
|
You can use http://www.elastic.co/overview/shield/[{scyld}] to control what Elasticsearch data users can access through Kibana.
|
|
|
|
{scyld} provides index-level access control. If a user isn't authorized to run
|
2015-07-15 10:48:49 +02:00
|
|
|
the query that populates a Kibana visualization, the user just sees an empty
|
|
|
|
visualization.
|
|
|
|
|
2016-04-05 01:38:09 +02:00
|
|
|
To configure access to Kibana using {scyld}, you create roles
|
2016-09-08 15:53:09 +02:00
|
|
|
for Kibana using the `my_kibana_user` default role as a starting point. For more
|
|
|
|
information, see {shield}/kibana.html#using-kibana4-with-shield[Using Kibana with {scyld}].
|
2015-03-03 23:16:13 +01:00
|
|
|
|
|
|
|
[float]
|
|
|
|
[[load-balancing]]
|
|
|
|
=== Load Balancing Across Multiple Elasticsearch Nodes
|
|
|
|
If you have multiple nodes in your Elasticsearch cluster, the easiest way to distribute Kibana requests
|
2015-07-15 10:48:49 +02:00
|
|
|
across the nodes is to run an Elasticsearch _client_ node on the same machine as Kibana.
|
2015-03-03 23:16:13 +01:00
|
|
|
Elasticsearch client nodes are essentially smart load balancers that are part of the cluster. They
|
2015-07-15 10:48:49 +02:00
|
|
|
process incoming HTTP requests, redirect operations to the other nodes in the cluster as needed, and
|
|
|
|
gather and return the results. For more information, see
|
2015-05-18 04:31:43 +02:00
|
|
|
http://www.elastic.co/guide/en/elasticsearch/reference/current/modules-node.html[Node] in the Elasticsearch reference.
|
2015-03-03 23:16:13 +01:00
|
|
|
|
|
|
|
To use a local client node to load balance Kibana requests:
|
|
|
|
|
2015-07-15 10:48:49 +02:00
|
|
|
. Install Elasticsearch on the same machine as Kibana.
|
2015-03-03 23:16:13 +01:00
|
|
|
. Configure the node as a client node. In `elasticsearch.yml`, set both `node.data` and `node.master` to `false`:
|
|
|
|
+
|
|
|
|
--------
|
|
|
|
# 3. You want this node to be neither master nor data node, but
|
|
|
|
# to act as a "search load balancer" (fetching data from nodes,
|
|
|
|
# aggregating results, etc.)
|
|
|
|
#
|
|
|
|
node.master: false
|
|
|
|
node.data: false
|
|
|
|
--------
|
2015-07-15 10:48:49 +02:00
|
|
|
. Configure the client node to join your Elasticsearch cluster. In `elasticsearch.yml`, set the `cluster.name` to the
|
2015-03-03 23:16:13 +01:00
|
|
|
name of your cluster.
|
|
|
|
+
|
|
|
|
--------
|
|
|
|
cluster.name: "my_cluster"
|
|
|
|
--------
|
2016-08-15 14:14:33 +02:00
|
|
|
. Make sure Kibana is configured to point to your local client node. In `kibana.yml`, the `elasticsearch.url` should be set to
|
2015-03-03 23:16:13 +01:00
|
|
|
`localhost:9200`.
|
|
|
|
+
|
|
|
|
--------
|
|
|
|
# The Elasticsearch instance to use for all your queries.
|
2016-08-15 14:14:33 +02:00
|
|
|
elasticsearch.url: "http://localhost:9200"
|
2015-05-18 04:31:43 +02:00
|
|
|
--------
|