github-mirrors/kibana
1
0
Fork 0
mirror of https://github.com/elastic/kibana.git synced 2025-04-23 09:19:04 -04:00
Code Issues Projects Releases Packages Wiki Activity

Sync docs with master

Browse source 
The 5.x docs have fallen out of date with master, so this gets them
synced up.
This commit is contained in:
Court Ewing 2016-10-23 15:44:32 -04:00
parent 4088887fb7
commit 3f33c37c7f
4 changed files with 35 additions and 222 deletions
Download patch file Download diff file Expand all files Collapse all files

15
docs/console.asciidoc
View file

@ -158,16 +158,25 @@ Console is meant to be used as a local development tool. As such, it will send r
just as a local curl command would. To overcome the CORS limitations enforced by browsers, Console's Node.js backend
serves as a proxy to send requests on behalf of the browser. However, if put on a server and exposed to the internet
this can become a security risk. In those cases, we highly recommend you lock down the proxy by setting the
`console.proxyFilter` setting. The setting accepts a list of regular expressions that are evaluated against each URL
the proxy is requested to retrieve. If none of the regular expressions match the proxy will reject the request.
`console.proxyFilter` Kibana server setting. The setting accepts a list of regular expressions that are evaluated
against each URL the proxy is requested to retrieve. If none of the regular expressions match the proxy will reject
the request.
Here is an example configuration the only allows Console to connect to localhost:
[source,yaml]
--------
sense.proxyFilter:
console.proxyFilter:
- ^https?://(localhost|127\.0\.0\.1|\[::0\]).*
--------
Restart Kibana for these changes to take effect.
Alternatively if the users of Kibana have no requirements or need to access any of the Console functionality, it can
be disabled completely and not even show up as an available app by setting the `console.enabled` Kibana server setting to `false`:
[source,yaml]
--------
console.enabled:
- false
--------

10
docs/kibana-repositories.asciidoc
View file

@ -19,14 +19,14 @@ has the following fingerprint:
+
[source,sh]
--------------------------------------------------
wget -qO - https://packages.elastic.co/GPG-KEY-elasticsearch | sudo apt-key add -
wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch | sudo apt-key add -
--------------------------------------------------
+
. Add the repository definition to your `/etc/apt/sources.list.d/kibana.list` file:
+
["source","sh",subs="attributes"]
--------------------------------------------------
echo "deb https://packages.elastic.co/kibana/{packageversion}/debian stable main" | sudo tee -a /etc/apt/sources.list.d/kibana.list
echo "deb https://artifacts.elastic.co/packages/5.x-prerelease/apt stable main" | sudo tee -a /etc/apt/sources.list.d/kibana.list
--------------------------------------------------
+
[WARNING]
@ -75,7 +75,7 @@ as CentOS version 5.
+
[source,sh]
--------------------------------------------------
rpm --import https://packages.elastic.co/GPG-KEY-elasticsearch
rpm --import https://artifacts.elastic.co/GPG-KEY-elasticsearch
--------------------------------------------------
+
. Create a file named `kibana.repo` in the `/etc/yum.repos.d/` directory with the following contents:
@ -84,9 +84,9 @@ rpm --import https://packages.elastic.co/GPG-KEY-elasticsearch
--------------------------------------------------
[kibana-{packageversion}]
name=Kibana repository for {packageversion} packages
baseurl=https://packages.elastic.co/kibana/{packageversion}/centos
baseurl=https://artifacts.elastic.co/packages/5.x-prerelease/yum
gpgcheck=1
gpgkey=https://packages.elastic.co/GPG-KEY-elasticsearch
gpgkey=https://artifacts.elastic.co/GPG-KEY-elasticsearch
enabled=1
--------------------------------------------------
+

228
docs/production.asciidoc
View file

@ -19,222 +19,19 @@ and an Elasticsearch client node on the same machine. For more information, see
[float]
[[configuring-kibana-shield]]
=== Configuring Kibana to Work with {scyld}
=== Using Kibana with X-Pack
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.
When you install X-Pack, Kibana users have to log in. They need to
have the `kibana_user` role as well as access to the indices they
will be working with in Kibana.
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
If a user loads a Kibana dashboard that accesses data in an index that they
are not authorized to view, they 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
{xpack}/security-api-users.html[{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 {xpack}/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`.
|======
For information about setting up Kibana users and how to configure Kibana
to work with X-Pack, see {xpack-ref}kibana.html.
[float]
[[enabling-ssl]]
@ -322,3 +119,10 @@ cluster.name: "my_cluster"
# The Elasticsearch instance to use for all your queries.
elasticsearch.url: "http://localhost:9200"
--------
[float]
[[kibana-tribe]]
=== Kibana and Tribe Nodes
Kibana 5.0 does not support tribe nodes. We are working on a solution that
addresses this limitation.

4
docs/x-axis-aggs.asciidoc
View file

@ -20,9 +20,9 @@ a range.
*Date Range*:: A {ref}search-aggregations-bucket-daterange-aggregation.html[_date range_] aggregation reports values
that are within a range of dates that you specify. You can specify the ranges for the dates using
{ref}common-options.html#date-math[_date math_] expressions. Click *Add Range* to add a set of range endpoints.
Click the red *(/)* symbol to remove a range.
Click the red *(x)* symbol to remove a range.
*IPv4 Range*:: The {ref}search-aggregations-bucket-iprange-aggregation.html[_IPv4 range_] aggregation enables you to
specify ranges of IPv4 addresses. Click *Add Range* to add a set of range endpoints. Click the red *(/)* symbol to
specify ranges of IPv4 addresses. Click *Add Range* to add a set of range endpoints. Click the red *(x)* symbol to
remove a range.
*Terms*:: A {ref}search-aggregations-bucket-terms-aggregation.html[_terms_] aggregation enables you to specify the top
or bottom _n_ elements of a given field to display, ordered by count or a custom metric.