[[marvel]]
=== Using Marvel with Shield

https://www.elastic.co/guide/en/marvel/current/introduction.html[Marvel] consists of two 
components: a Marvel agent that you install on on each node in your cluster, and a Marvel application you install in https://www.elastic.co/guide/en/kibana/current/introduction.html[Kibana]. The Marvel agent collects and indexes metrics from Elasticsearch and you visualize the data through the Marvel dashboards in Kibana. The agent can index data on the same cluster, or send it to an external monitoring cluster.

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

[float]
[[marvel-app-users]]
==== Setting Up Marvel App Users

When Shield is enabled, Kibana users are prompted to log in when they access the UI. To use
the Marvel app, a user must have access to the Kibana indices and permission to read from the 
Marvel indices. 

You set up Marvel app users on the cluster where the monitoring data is being stored. To grant 
all of the necessary permissions, assign user the `kibana_user` and `marvel_user` roles defined 
in `roles.yml`:

* If you're using the default `esusers` realm, you can assign roles when you <<esusers-add, add a 
user>>, or modify the role assignments with the <<esusers-roles, `roles`>> command. For example, 
the following command creates a user named `jacknich` and assigns the `marvel_user` role:
+
[source,console]
--------------------------------------------------------------------------------
esusers useradd jacknich -r kibana_user,marvel_user -p password
--------------------------------------------------------------------------------    

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

[float]
[[configuring-marvel-agent-shield]]
==== Configuring Marvel Agent to Communicate with a Shield-Enabled Monitoring Cluster

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

. Configure a user on the monitoring cluster who has the `marvel_agent` role, which is defined in
`roles.yml`. For example:
+
[source,console]
--------------------------------------------------------------------------------
esusers useradd agent-user -r marvel_agent -p password
--------------------------------------------------------------------------------   
+
.Marvel Agent Role
[source,yaml]
--------------------------------------------------
marvel_agent:
  cluster: indices:admin/template/get, indices:admin/template/put
  indices:
    '.marvel-*': indices:data/write/bulk, create_index
--------------------------------------------------

. On each node in the cluster being monitored, configure a Marvel HTTP exporter 
in `elasticsearch.yml` and resart 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]
--------------------------------------------------
marvel.agent.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.
.. Specify a truststore that contains the CA certificate to use to verify the identities of the 
nodes in the monitoring cluster. You need to set the `truststore.path` and 
`truststore.password`.

For example:

[source,yaml]
--------------------------------------------------
marvel.agent.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
--------------------------------------------------
--