[[secure-monitoring]]
=== Monitoring and Security

<<xpack-monitoring, {monitoring}>> consists of two components: an agent
that you install on on each Elasticsearch and Logstash node, and a Monitoring UI
in Kibana. The monitoring agent collects and indexes metrics from the nodes
and you visualize the data through the Monitoring dashboards in Kibana. The agent
can index data on the same Elasticsearch cluster, or send it to an external
monitoring cluster.

To use {monitoring} with {security} enabled, you need to
<<kibana, set up Kibana to work with {security}>> and create at least one user
for the Monitoring UI. If you are using an external monitoring cluster, you also
need to configure a user for the monitoring agent and configure the agent to use
the appropriate credentials when communicating with the monitoring cluster.

[float]
[[monitoring-ui-users]]
==== Setting Up Monitoring UI Users

When {security} is enabled, Kibana users are prompted to log in when they access
the UI. To use the Monitoring UI, a user must have access to the Kibana indices
and permission to read from the monitoring indices.

You set up Monitoring UI users on the cluster where the monitoring data is being
stored. To grant all of the necessary permissions, assign the user the
`monitoring_user` and `kibana_user` roles:

* If you're using the `native` realm, you can assign roles through Kibana or
with the <<managing-native-users, User Management API>>. For example, the following
command creates a user named `jacknich` and assigns him the `kibana_user` and
`monitoring_user` roles:
+
[source,js]
--------------------------------------------------------------------------------
POST /_xpack/security/user/jacknich
{
  "password" : "t0pS3cr3t",
  "roles" : [ "kibana_user", "monitoring_user" ]
}

--------------------------------------------------------------------------------

* 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 configured in <<mapping-roles, `config/x-pack/role_mapping.yml`>>. For example,
the following snippet assigns the user named Jack Nicholson to the `kibana_user`
and `monitoring_user` roles:
+
[source,yaml]
--------------------------------------------------------------------------------
kibana_user:
  - "cn=Jack Nicholson,dc=example,dc=com"
monitoring_user:
  - "cn=Jack Nicholson,dc=example,dc=com"
--------------------------------------------------------------------------------

[float]
[[configuring-monitoring-agent-security]]
==== Configuring Monitoring Agent to Communicate with a {security}-Enabled Monitoring Cluster

To configure the monitoring agent to communicate with a secured monitoring cluster:

. Configure a user on the monitoring cluster who has the `remote_monitoring_agent` 
role, which is <<[[built-in-roles-remote-monitoring-agent]], built-in to {xpack}>>.
For example:
+
[source,js]
--------------------------------------------------------------------------------
POST /_xpack/security/user/agent-user
{
  "password" : "t0pS3cr3t",
  "roles" : [ "remote_monitoring_agent" ]
}
--------------------------------------------------------------------------------
+

. On each node in the cluster being monitored, configure a Monitoring HTTP exporter
in `elasticsearch.yml` and restart Elasticsearch. In the exporter configuration,
you need to:
+
--
.. Set the `type` to `http`.
.. Specify the location of the monitoring cluster in the `host` setting.
.. Provide the agent user credentials with the `username` and `password` settings.

For example:

[source,yaml]
--------------------------------------------------
xpack.monitoring.exporters:
  id1:
    type: http
    host: ["http://es-mon1:9200", "http://es-mon2:9200"]
    auth:
      username: agent-user
      password: password
--------------------------------------------------

If SSL/TLS is enabled on the monitoring cluster:

.. Specify the HTTPS protocol when setting the monitoring server host.
.. Include the CA certificate in each node's trusted certificates in order to verify
   the identities of the nodes in the monitoring cluster.

To add a CA certificate to an Elasticsearch node's trusted certificates, you
can specify the location of the PEM encoded certificate with the
`certificate_authorities` setting:

[source,yaml]
--------------------------------------------------
xpack.monitoring.exporters:
  id1:
    type: http
    host: ["https://es-mon1:9200", "https://es-mon2:9200"]
    auth:
      username: agent-user
      password: password
    ssl:
      certificate_authorities: [ "/path/to/ca.crt" ]
  id2:
    type: local
--------------------------------------------------

Alternatively, you can configure trusted certificates using a truststore
(a Java Keystore file that contains the certificates):

[source,yaml]
--------------------------------------------------
xpack.monitoring.exporters:
  id1:
    type: http
    host: ["https://es-mon1:9200", "https://es-mon2:9200"]
    auth:
      username: agent-user
      password: password
    ssl:
      truststore.path: /path/to/file
      truststore.password: password
  id2:
    type: local
--------------------------------------------------
--

. On each Logstash node being monitored, update `logstash.yml` to:
+
--
.. Specify the location of the monitoring cluster and provide credentials
for the agent user:

[source,yaml]
--------------------------------------------------
xpack.monitoring.elasticsearch.url: ["http://es-mon-1:9200", "http://es-mon2:9200"]
xpack.monitoring.elasticsearch.username: "remote_monitor"
xpack.monitoring.elasticsearch.password: "changeme"
--------------------------------------------------

.. If SSL/TLS is enabled on the monitoring cluster:

* Specify the HTTPS protocol when setting the `elasticsearch.url`.
* Include the CA certificate in each node's trusted certificates in order to verify
   the identities of the nodes in the monitoring cluster.

To add a CA certificate to an node's trusted certificates, you
can specify the location of the PEM encoded certificate with the
`xpack.monitoring.elasticsearch.ssl.ca` setting:

[source,yaml]
--------------------------------------------------
xpack.monitoring.elasticsearch.ssl.ca: [ "/path/to/ca.crt" ]
--------------------------------------------------

Alternatively, you can configure trusted certificates using a truststore
(a Java Keystore file that contains the certificates):

[source,yaml]
--------------------------------------------------
xpack.monitoring.elasticsearch.ssl.truststore.path: /path/to/file
xpack.monitoring.elasticsearch.ssl.truststore.password: changeme
--------------------------------------------------
--