We've been maintaining the 5.0 docs separately for awhile, but now it is time to get the changes synced up with the repo itself.
324 lines
15 KiB
Text
324 lines
15 KiB
Text
[[production]]
|
|
== Using Kibana in a Production Environment
|
|
* <<configuring-kibana-shield, Configuring Kibana to Work with {scyld}>>
|
|
* <<enabling-ssl, Enabling SSL>>
|
|
* <<controlling-access, Controlling Access>>
|
|
* <<load-balancing, Load Balancing Across Multiple Elasticsearch Nodes>>
|
|
|
|
How you deploy Kibana largely depends on your use case. If you are the only user,
|
|
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
|
|
number of heavy Kibana users, you might need to load balance across multiple
|
|
Kibana instances that are all connected to the same Elasticsearch instance.
|
|
|
|
While Kibana isn't terribly resource intensive, we still recommend running Kibana
|
|
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>>.
|
|
|
|
[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]
|
|
[[enabling-ssl]]
|
|
=== Enabling SSL
|
|
Kibana supports SSL encryption for both client requests and the requests the Kibana server
|
|
sends to Elasticsearch.
|
|
|
|
To encrypt communications between the browser and the Kibana server, you configure the `ssl_key_file` and
|
|
`ssl_cert_file` properties in `kibana.yml`:
|
|
|
|
[source,text]
|
|
----
|
|
# SSL for outgoing requests from the Kibana Server (PEM formatted)
|
|
server.ssl.key: /path/to/your/server.key
|
|
server.ssl.cert: /path/to/your/server.crt
|
|
----
|
|
|
|
If you are using {scyld} or a proxy that provides an HTTPS endpoint for Elasticsearch,
|
|
you can configure Kibana to access Elasticsearch via HTTPS so communications between
|
|
the Kibana server and Elasticsearch are encrypted.
|
|
|
|
To do this, you specify the HTTPS
|
|
protocol when you configure the Elasticsearch URL in `kibana.yml`:
|
|
|
|
[source,text]
|
|
----
|
|
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.
|
|
|
|
[source,text]
|
|
----
|
|
# If you need to provide a CA certificate for your Elasticsearch instance, put
|
|
# the path of the pem file here.
|
|
ca: /path/to/your/ca/cacert.pem
|
|
----
|
|
|
|
[float]
|
|
[[controlling-access]]
|
|
=== Controlling access
|
|
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
|
|
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 `my_kibana_user` default role as a starting point. For more
|
|
information, see {shield}/kibana.html#using-kibana4-with-shield[Using Kibana with {scyld}].
|
|
|
|
[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
|
|
across the nodes is to run an Elasticsearch _client_ node on the same machine as Kibana.
|
|
Elasticsearch client nodes are essentially smart load balancers that are part of the cluster. They
|
|
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
|
|
http://www.elastic.co/guide/en/elasticsearch/reference/current/modules-node.html[Node] in the Elasticsearch reference.
|
|
|
|
To use a local client node to load balance Kibana requests:
|
|
|
|
. Install Elasticsearch on the same machine as Kibana.
|
|
. 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
|
|
--------
|
|
. Configure the client node to join your Elasticsearch cluster. In `elasticsearch.yml`, set the `cluster.name` to the
|
|
name of your cluster.
|
|
+
|
|
--------
|
|
cluster.name: "my_cluster"
|
|
--------
|
|
. Make sure Kibana is configured to point to your local client node. In `kibana.yml`, the `elasticsearch.url` should be set to
|
|
`localhost:9200`.
|
|
+
|
|
--------
|
|
# The Elasticsearch instance to use for all your queries.
|
|
elasticsearch.url: "http://localhost:9200"
|
|
--------
|