From 03f281f96924f7d044a4b5862d49ec2869d2b9d3 Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Thu, 28 May 2020 08:17:36 -0700 Subject: [PATCH] docs: Update security documentation (#3799) # Conflicts: # docs/copied-from-beats/docs/https.asciidoc # docs/copied-from-beats/docs/security/basic-auth.asciidoc # docs/copied-from-beats/docs/security/users.asciidoc --- docs/configure-kibana-endpoint.asciidoc | 12 +- docs/copied-from-beats/docs/https.asciidoc | 152 ++++-- .../docs/security/api-keys.asciidoc | 23 +- .../docs/security/securing-beats.asciidoc | 41 -- .../docs/security/tls.asciidoc | 24 - .../docs/shared-securing-beat.asciidoc | 51 +- .../docs/shared-ssl-logstash-config.asciidoc | 6 +- docs/feature-roles.asciidoc | 445 ++++++++++++++++++ docs/index.asciidoc | 1 + 9 files changed, 627 insertions(+), 128 deletions(-) delete mode 100644 docs/copied-from-beats/docs/security/securing-beats.asciidoc delete mode 100644 docs/copied-from-beats/docs/security/tls.asciidoc create mode 100644 docs/feature-roles.asciidoc diff --git a/docs/configure-kibana-endpoint.asciidoc b/docs/configure-kibana-endpoint.asciidoc index 8ff392f7b28..efa5e5dc5cb 100644 --- a/docs/configure-kibana-endpoint.asciidoc +++ b/docs/configure-kibana-endpoint.asciidoc @@ -1,7 +1,7 @@ [[setup-kibana-endpoint]] == Configure the Kibana endpoint -Configuring the Kibana endpoint is required for +Configuring the Kibana endpoint is required for {kibana-ref}/agent-configuration.html[APM Agent configuration in Kibana]. You configure the endpoint in the `apm-server.kibana` section of the +{beatname_lc}.yml+ config file. @@ -21,7 +21,7 @@ apm-server.kibana.host: "http://localhost:5601" the same token is used to secure this endpoint. * It's important to still set relevant defaults locally in each Agent's configuration. If APM Server is unreachable, slow to respond, returns an error, etc., -defaults set in the agent will apply according to their precedence. +defaults set in the agent will apply according to their precedence. [float] === Kibana endpoint configuration options @@ -71,16 +71,12 @@ apm-server.kibana.path: /kibana [float] ==== `apm-server.kibana.username` -The basic authentication username for connecting to Kibana. If you don't -specify a value for this setting, {beatname_uc} uses the `username` specified -for the Elasticsearch output. +The basic authentication username for connecting to Kibana. [float] ==== `apm-server.kibana.password` -The basic authentication password for connecting to Kibana. If you don't -specify a value for this setting, {beatname_uc} uses the `password` specified -for the Elasticsearch output. +The basic authentication password for connecting to Kibana. [float] [[kibana-path-option]] diff --git a/docs/copied-from-beats/docs/https.asciidoc b/docs/copied-from-beats/docs/https.asciidoc index 33a08c5beb2..9d9399e8374 100644 --- a/docs/copied-from-beats/docs/https.asciidoc +++ b/docs/copied-from-beats/docs/https.asciidoc @@ -10,62 +10,111 @@ //// This content is structured to be included as a whole file. ////////////////////////////////////////////////////////////////////////// +[role="xpack"] +[[securing-communication-elasticsearch]] +== Secure communication with Elasticsearch + To secure the communication between {beatname_uc} and Elasticsearch, you can use HTTPS and basic authentication. Basic authentication for Elasticsearch is available when you enable {security} (see {stack-ov}/elasticsearch-security.html[Securing the {stack}] and <>). If you aren't using {security}, you can use a web proxy instead. -Here is a sample configuration: +When sending data to a secured cluster through the `elasticsearch` +output, {beatname_uc} can use any of the following authentication methods: + +* Basic authentication credentials (username and password). +* Token-based API authentication. +* A client certificate. +Authentication is specified in the {beatname_uc} configuration file: + +* To use *basic authentication*, specify the `username` and `password` settings under `output.elasticsearch`. +For example: ++ +-- ["source","yaml",subs="attributes,callouts"] ---------------------------------------------------------------------- output.elasticsearch: - username: {beatname_lc} <1> - password: verysecret <2> - protocol: https <3> - hosts: ["elasticsearch.example.com:9200"] <4> + hosts: ["https://myEShost:9200"] + username: "{beat_default_index_prefix}_writer" <1> + password: "{pwd}" <2> ---------------------------------------------------------------------- -<1> The username to use for authenticating to Elasticsearch. -<2> The password to use for authenticating to Elasticsearch. -<3> This setting enables the HTTPS protocol. -<4> The IP and port of the Elasticsearch nodes. - -TIP: To obfuscate passwords and other sensitive settings, +<1> This user needs the privileges required to publish events to {es}. +To create a user like this, see <>. +<2> This example shows a hard-coded password, but you should store sensitive +values ifndef::serverless[] -use the <>. +in the <>. endif::[] ifdef::serverless[] -use environment variables. +in environment variables. endif::[] +-- -{beatname_uc} verifies the validity of the server certificates and only accepts trusted -certificates. Creating a correct SSL/TLS infrastructure is outside the scope of -this document. - -By default {beatname_uc} uses the list of trusted certificate authorities from the -operating system where {beatname_uc} is running. You can configure {beatname_uc} to use a specific list of -CA certificates instead of the list from the OS. You can also configure it to use client authentication -by specifying the certificate and key to use when the server requires the {beatname_uc} to authenticate. Here is an example -configuration: +* To use token-based *API key authentication*, specify the `api_key` under `output.elasticsearch`. +For example: ++ +-- +["source","yaml",subs="attributes,callouts"] +---------------------------------------------------------------------- +output.elasticsearch: + hosts: ["https://myEShost:9200"] + api_key: "KnR6yE41RrSowb0kQ0HWoA" <1> +---------------------------------------------------------------------- +<1> This API key must have the privileges required to publish events to {es}. +To create an API key like this, see <>. +-- +[[beats-tls]] +* To use *Public Key Infrastructure (PKI) certificates* to authenticate users, +specify the `certificate` and `key` settings under `output.elasticsearch`. +For example: ++ +-- +["source","yaml",subs="attributes,callouts"] +---------------------------------------------------------------------- +output.elasticsearch: + hosts: ["https://myEShost:9200"] + ssl.certificate: "/etc/pki/client/cert.pem" <1> + ssl.key: "/etc/pki/client/cert.key" <2> +---------------------------------------------------------------------- +<1> The path to the certificate for SSL client authentication +<2> The client certificate key +-- ++ +These settings assume that the +distinguished name (DN) in the certificate is mapped to the appropriate roles in +the `role_mapping.yml` file on each node in the {es} cluster. For more +information, see {ref}/mapping-roles.html#mapping-roles-file[Using role +mapping files]. ++ +By default, {beatname_uc} uses the list of trusted certificate authorities (CA) from the +operating system where {beatname_uc} is running. If the certificate authority that signed your node certificates +is not in the host system's trusted certificate authorities list, you need +to add the path to the `.pem` file that contains your CA's certificate to the +{beatname_uc} configuration. This will configure {beatname_uc} to use a specific list of +CA certificates instead of the default list from the OS. ++ +Here is an example configuration: ++ +-- ["source","yaml",subs="attributes,callouts"] ---------------------------------------------------------------------- output.elasticsearch: - username: {beatname_lc} - password: verysecret - protocol: https - hosts: ["elasticsearch.example.com:9200"] + hosts: ["https://myEShost:9200"] ssl.certificate_authorities: <1> - /etc/pki/my_root_ca.pem - /etc/pki/my_other_ca.pem ssl.certificate: "/etc/pki/client.pem" <2> ssl.key: "/etc/pki/key.pem" <3> ---------------------------------------------------------------------- -<1> The list of CA certificates to trust +<1> Specify the path to the local `.pem` file that contains your Certificate +Authority's certificate. This is needed if you use your own CA to sign your node certificates. <2> The path to the certificate for SSL client authentication <3> The client certificate key - +-- ++ NOTE: For any given connection, the SSL/TLS certificates must have a subject that matches the value specified for `hosts`, or the SSL handshake fails. For example, if you specify `hosts: ["foobar:9200"]`, the certificate MUST @@ -73,3 +122,50 @@ include `foobar` in the subject (`CN=foobar`) or as a subject alternative name (SAN). Make sure the hostname resolves to the correct IP address. If no DNS is available, then you can associate the IP address with your hostname in `/etc/hosts` (on Unix) or `C:\Windows\System32\drivers\etc\hosts` (on Windows). + +ifndef::no_dashboards[] +[role="xpack"] +[float] +[[securing-communication-kibana]] +=== Secure communication with the Kibana endpoint + +If you've configured the <>, +you can also specify credentials for authenticating with {kib} under `kibana.setup`. +If no credentials are specified, Kibana will use the configured authentication method +in the Elasticsearch output. + +For example, specify a unique username and password to connect to Kibana like this: + +-- +["source","yaml",subs="attributes,callouts"] +---- +setup.kibana: + host: "mykibanahost:5601" + username: "{beat_default_index_prefix}_kib_setup" <1> + password: "{pwd}" <2> +---- +<1> This user needs privileges required to set up dashboards. To create a user like this, +see <>. +<2> This example shows a hard-coded password, but you should store sensitive +values +ifndef::serverless[] +in the <>. +endif::[] +ifdef::serverless[] +in environment variables. +endif::[] +endif::no_dashboards[] +-- + +[role="xpack"] +[float] +[[securing-communication-learn-more]] +=== Learn more about secure communication + +More information on sending data to a secured cluster is available in the configuration reference: + +* <> +* <> +ifndef::no_dashboards[] +* <> +endif::no_dashboards[] diff --git a/docs/copied-from-beats/docs/security/api-keys.asciidoc b/docs/copied-from-beats/docs/security/api-keys.asciidoc index aef276417a4..403fd011122 100644 --- a/docs/copied-from-beats/docs/security/api-keys.asciidoc +++ b/docs/copied-from-beats/docs/security/api-keys.asciidoc @@ -1,18 +1,12 @@ [role="xpack"] [[beats-api-keys]] -=== Grant access using API keys +== Grant access using API keys Instead of using usernames and passwords, you can use API keys to grant access to {es} resources. You can set API keys to expire at a certain time, and you can explicitly invalidate them. Any user with the `manage_api_key` or `manage_own_api_key` cluster privilege can create API keys. -See the {es} API key documentation for more information: - -* {ref}/security-api-create-api-key.html[Create API key] -* {ref}/security-api-get-api-key.html[Get API key information] -* {ref}/security-api-invalidate-api-key.html[Invalidate API key] - {beatname_uc} instances typically send both collected data and monitoring information to {es}. If you are sending both to the same cluster, you can use the same API key. For different clusters, you need to use an API key per cluster. @@ -20,8 +14,9 @@ API key. For different clusters, you need to use an API key per cluster. NOTE: For security reasons, we recommend using a unique API key per {beatname_uc} instance. You can create as many API keys per user as necessary. +[float] [[beats-api-key-publish]] -==== Create an API key for publishing +=== Create an API key for publishing To create an API key to use for writing data to {es}, use the {ref}/security-api-create-api-key.html[Create API key API], for example: @@ -67,8 +62,9 @@ output.elasticsearch: -------------------- <1> Format is `id:api_key` (as returned by {ref}/security-api-create-api-key.html[Create API key]) +[float] [[beats-api-key-monitor]] -==== Create an API key for monitoring +=== Create an API key for monitoring To create an API key to use for sending monitoring data to {es}, use the {ref}/security-api-create-api-key.html[Create API key API], for example: @@ -114,3 +110,12 @@ monitoring.elasticsearch: -------------------- <1> Format is `id:api_key` (as returned by {ref}/security-api-create-api-key.html[Create API key]) +[[learn-more-api-keys]] +[float] +=== Learn more about API keys + +See the {es} API key documentation for more information: + +* {ref}/security-api-create-api-key.html[Create API key] +* {ref}/security-api-get-api-key.html[Get API key information] +* {ref}/security-api-invalidate-api-key.html[Invalidate API key] diff --git a/docs/copied-from-beats/docs/security/securing-beats.asciidoc b/docs/copied-from-beats/docs/security/securing-beats.asciidoc deleted file mode 100644 index f103efbf2f0..00000000000 --- a/docs/copied-from-beats/docs/security/securing-beats.asciidoc +++ /dev/null @@ -1,41 +0,0 @@ -[role="xpack"] -[[securing-beats]] -== Configure {beatname_uc} to use {security-features} - -[subs="attributes"] -++++ -Use {security-features} -++++ - -If you want {beatname_uc} to connect to a cluster that has -{security-features} enabled, there are extra configuration steps: - -. <>. -+ -You can use role-based access control to grant {beatname_uc} users access to -secured resources. - -. <>. -+ -You can use API keys to grant access to {es} more securely. - -. <>. -+ -To interact with a secured cluster, {beatname_uc} must either provide basic -authentication credentials or present a client certificate. - -. <>. -+ -If encryption is enabled on the cluster, you need to enable HTTPS in the -{beatname_uc} configuration. - -For more information about {security-features}, see -{ref}/secure-cluster.html[Secure a cluster]. - -include::users.asciidoc[] - -include::api-keys.asciidoc[] - -include::basic-auth.asciidoc[] - -include::tls.asciidoc[] diff --git a/docs/copied-from-beats/docs/security/tls.asciidoc b/docs/copied-from-beats/docs/security/tls.asciidoc deleted file mode 100644 index 10f7a60653e..00000000000 --- a/docs/copied-from-beats/docs/security/tls.asciidoc +++ /dev/null @@ -1,24 +0,0 @@ -[role="xpack"] -[[beats-tls]] -=== Configure {beatname_uc} to use encrypted connections - -If encryption is enabled on the {es} cluster, you need to connect to {es} via -HTTPS. If the certificate authority (CA) that signed your node certificates -is not in the host system's trusted certificate authorities list, you also need -to add the path to the `.pem` file that contains your CA's certificate to the -{beatname_uc} configuration. - -To configure a {beatname_uc} to connect to {es} via HTTPS, add the `https` -protocol to all host URLs: - -["source","js",subs="attributes,callouts"] --------------------------------------------------- -output.elasticsearch: - hosts: ["https://localhost:9200"] <1> - index: "{beatname_lc}" - ssl.certificate_authorities: ["/etc/pki/root/ca.pem"] <2> --------------------------------------------------- -<1> Specify the `https` protocol to connect the {es} cluster. -<2> Specify the path to the local `.pem` file that contains your Certificate -Authority's certificate. This is generally only needed if you use your -own CA to sign your node certificates. diff --git a/docs/copied-from-beats/docs/shared-securing-beat.asciidoc b/docs/copied-from-beats/docs/shared-securing-beat.asciidoc index 67f38aeb50b..b8dcc3b1957 100644 --- a/docs/copied-from-beats/docs/shared-securing-beat.asciidoc +++ b/docs/copied-from-beats/docs/shared-securing-beat.asciidoc @@ -9,49 +9,66 @@ ++++ The following topics provide information about securing the {beatname_uc} -process and securing communication between {beatname_uc} and other products in -the Elastic stack: +process and connecting to a cluster that has {security-features} enabled. + +You can use role-based access control and optionally, API keys to grant {beatname_uc} users access to +secured resources. + +* <> +* <>. + +After privileged users have been created, use authentication to connect to a secured Elastic cluster. -ifdef::apm-server[] -* <> -endif::[] * <> ifndef::no-output-logstash[] * <> endif::[] -* <> + +ifdef::apm-server[] +For secure communication between APM Server and APM Agents, see <>. +endif::[] + ifndef::serverless[] +On Linux, {beatname_uc} can take advantage of secure computing mode to restrict the +system calls that a process can issue. + * <> endif::[] +// APM HTTPS information ifdef::beat-specific-security[] include::{beat-specific-security}[] endif::[] -- +// APM privileges ifdef::apm-server[] -include::{docdir}/secure-communication-agents.asciidoc[] +include::{docdir}/feature-roles.asciidoc[] endif::[] -//sets block macro for https.asciidoc included in next section +// Beat privileges +ifndef::apm-server[] +include::./security/users.asciidoc[] +endif::[] -[[securing-communication-elasticsearch]] -== Secure communication with Elasticsearch +// API Keys +include::./security/api-keys.asciidoc[] -include::./https.asciidoc[] +// APM Agent security +ifdef::apm-server[] +include::{docdir}/secure-communication-agents.asciidoc[] +endif::[] -//sets block macro for shared-ssl-logstash-config.asciidoc included in next section +// Elasticsearch security +include::./https.asciidoc[] +// Logstash security ifndef::no-output-logstash[] -[[configuring-ssl-logstash]] -== Secure communication with Logstash - include::./shared-ssl-logstash-config.asciidoc[] endif::[] -include::./security/securing-beats.asciidoc[] - +// Linux Seccomp ifndef::serverless[] include::./security/linux-seccomp.asciidoc[] endif::[] diff --git a/docs/copied-from-beats/docs/shared-ssl-logstash-config.asciidoc b/docs/copied-from-beats/docs/shared-ssl-logstash-config.asciidoc index 090b34cfc33..31cbf73fc62 100644 --- a/docs/copied-from-beats/docs/shared-ssl-logstash-config.asciidoc +++ b/docs/copied-from-beats/docs/shared-ssl-logstash-config.asciidoc @@ -9,6 +9,10 @@ //// include::../../libbeat/docs/shared-ssl-logstash-config.asciidoc[] ////////////////////////////////////////////////////////////////////////// +[role="xpack"] +[[configuring-ssl-logstash]] +== Secure communication with Logstash + You can use SSL mutual authentication to secure connections between {beatname_uc} and Logstash. This ensures that {beatname_uc} sends encrypted data to trusted Logstash servers only, and that the Logstash server receives data from trusted {beatname_uc} clients only. @@ -19,7 +23,7 @@ To use SSL mutual authentication: {beatname_uc} and Logstash. Creating a correct SSL/TLS infrastructure is outside the scope of this document. There are many online resources available that describe how to create certificates. + -TIP: If you are using {security}, you can use the +TIP: If you are using {security-features}, you can use the {ref}/certutil.html[elasticsearch-certutil tool] to generate certificates. . Configure {beatname_uc} to use SSL. In the +{beatname_lc}.yml+ config file, specify the following settings under diff --git a/docs/feature-roles.asciidoc b/docs/feature-roles.asciidoc new file mode 100644 index 00000000000..93355894e4f --- /dev/null +++ b/docs/feature-roles.asciidoc @@ -0,0 +1,445 @@ +[role="xpack"] +[[feature-roles]] +== Grant users access to secured resources + +You can use role-based access control to grant users access to secured +resources. The roles that you set up depend on your organization's security +requirements and the minimum privileges required to use specific features. + +Typically, you need to create the following separate roles: + +* <>: To set up index templates and +other dependencies +* <>: One for sending monitoring +information, and another for viewing it +* <>: To publish events collected by {beatname_uc}. +* <>: To view +APM Agent central configurations. + +{es-security-features} provides {ref}/built-in-roles.html[built-in roles] that grant a +subset of the privileges needed by APM users. +When possible, assign users the built-in roles to minimize the affect of future changes on your security strategy. +If no built-in role is available, you can assign users the privileges needed to accomplish a specific task. +In general, there are three types of privileges you'll work with: + +* **Elasticsearch cluster privileges**: Manage the actions a user can perform against your cluster. +* **Elasticsearch index privileges**: Control access to the data in specific indices your cluster. +* **Kibana space privileges**: Grant users write or read access to features and apps within Kibana. + +//// +*********************************** *********************************** +*********************************** *********************************** +//// + +[[privileges-to-setup-beats]] +=== Grant privileges and roles needed for setup + +++++ +Create a _setup_ user +++++ + +IMPORTANT: Setting up {beatname_uc} is an admin-level task that requires extra +privileges. As a best practice, grant the setup role to administrators only, and +use a more restrictive role for event publishing. + +Administrators who set up {beatname_uc} typically need to load the index template, +set up ILM aliases, templates, and policies, and register ingest pipelines. + +To grant users the required privileges for setup: + +. Create a *setup role*, called something like +{beat_default_index_prefix}_setup+, that has +the following privileges: ++ +[options="header"] +|==== +|Type | Privilege | Purpose + +|Cluster +|`manage_ilm` +|All index lifecycle management operations related to managing policies + +|Index +|`manage` on +{beat_default_index_prefix}-*+ indices +|All index administration privileges +|==== + +. Assign the *setup role*, along with the following built-in roles, to users who +need to set up {beatname_uc}: ++ +[options="header"] +|==== +|Role | Purpose + +|`ingest_admin` +|Set up index templates and ingest pipelines +|==== + +NOTE: These instructions assume that you are using the default name for +{beatname_uc} indices (+{beat_default_index_prefix}-*+). +If you are using a custom index name, modify the privileges to +match your index naming pattern. + +[float] +==== Partial setup + +In some instances, you may want to create a less-privileged user for a specific setup task. + +[float] +===== Set up index templates + +APM Server loads an index template to Elasticsearch at setup time. +The following privileges are required for this task: + +[options="header"] +|==== +|Type | Privilege | Purpose + +|Cluster +|`manage_index_template` +|All operations on index templates +|==== + +See <> for more information. + +[float] +===== Set up ILM + +Index lifecycle management (ILM) allows you to automate the lifecycle of your APM Server indices as they grow and age. +To set up and configure ILM, the following privileges are required: + +[options="header"] +|==== +|Type | Privilege | Purpose + +|Cluster +|`manage_index_template` +|All operations on index templates + +|Cluster +|`manage_ilm` +|All index lifecycle management operations related to managing policies. + +|Index +|`manage` on +{beat_default_index_prefix}-*+ indices +|All index administration privileges +|==== + +See <> for more information. + +[float] +===== Set up ingest pipelines + +Ingest pipelines allow you to pre-process documents in Elasticsearch before indexing them. +The following privileges are required to manage pipelines: + +[options="header"] +|==== +|Type | Privilege | Purpose + +|Cluster +|`manage_pipeline` +|All operations on ingest pipelines +|==== + +See <> for more information. + +//// +*********************************** *********************************** +*********************************** *********************************** +//// + +[[privileges-to-publish-events]] +=== Grant privileges and roles needed for writing events + +++++ +Create a _writer_ user +++++ + +IMPORTANT: To minimize the privileges required by the writer role, +use the <> to pre-load dependencies. +This section assumes that you've done that. + +{beatname_uc} users that publish events to {es} need to create and write to +{beat_default_index_prefix}-*+ +indices, upload and read sourcemaps, read API keys from Elasticsearch, and perform self-instrumentation. + +[float] +==== General writer role + +To grant an APM Server user the required privileges for writing events to {es}: + +. Create a *general writer role*, called something like +{beat_default_index_prefix}_writer+, +that has the following privileges: ++ +[options="header"] +|==== +|Type | Privilege | Purpose + +|Index +|`create_doc` on +{beat_default_index_prefix}-*+ indices +|Write events into {es} + +|Index +|`create_index` on +{beat_default_index_prefix}-*+ indices +|Create APM indices in {es} +|==== + +. If <> and <> are enabled, +assign the following additional privileges to the *general writer role*: ++ +[options="header"] +|==== +|Type | Privilege | Purpose + +|Index +|`read` on +{beat_default_index_prefix}-*sourcemap+ indices +|Read sourcemaps from {es} +|==== + +. Assign the *general writer role* to users who need to publish {beatname_uc} data. + +[float] +==== Specific writer roles + +Instead of creating a *general writer role*, +individual publishing tasks, like writing events or uploading sourcemaps, +can be performed by dedicated users with stricter privileges. + +[float] +===== Sourcemap writer role + +To create an {beatname_uc} user that can write sourcemaps to {es}: + +. Create a *sourcemap writer role*, called something like +{beat_default_index_prefix}_sourcemap+, +that has the following privileges: ++ +[options="header"] +|==== +|Type | Privilege | Purpose + +|Index +|`create_doc` on +{beat_default_index_prefix}-*+ indices +|Write APM events into {es} + +|Index +|`create_index` on +{beat_default_index_prefix}-*+ indices +|Create APM indices in {es} +|==== + +. Assign the *sourcemap writer role* to users who need to publish sourcemaps. + +//// +*********************************** *********************************** +*********************************** *********************************** +//// + +[[privileges-to-publish-monitoring]] +=== Grant privileges and roles needed for monitoring + +++++ +Create a _monitoring_ user +++++ + +{es-security-features} provides built-in users and roles for publishing and viewing monitoring data. +The privileges and roles needed to publish monitoring data +depend on the method used to collect that data. + +* <> +** <> +** <> +* <> + +[float] +[[privileges-to-publish-monitoring-write]] +==== Publish monitoring data + +[IMPORTANT] +==== +**{ecloud} users:** This section does not apply to our +https://www.elastic.co/cloud/elasticsearch-service[hosted {ess}]. +Monitoring on {ecloud} is enabled by clicking the *Enable* button in the *Monitoring* panel. +==== + +[float] +[[privileges-to-publish-monitoring-internal]] +===== Internal collection + +If you're using <> to +collect metrics about {beatname_uc}, {security-features} provides +the +{beat_monitoring_user}+ {ref}/built-in-users.html[built-in user] and ++{beat_monitoring_user}+ {ref}/built-in-roles.html[built-in role] to send +monitoring information. You can use the built-in user, if it's available in your +environment, or create a user who has the the built-in role assigned, +or create a user and manually assign the privileges needed to send monitoring +information. + +If you use the built-in +{beat_monitoring_user}+ user, +make sure you set the password before using it. + +If you don't use the +{beat_monitoring_user}+ user: + +-- +. Create a *monitoring role*, called something like ++{beat_default_index_prefix}_monitoring_writer+, that has the following privileges: ++ +[options="header"] +|==== +|Type | Privilege | Purpose + +|Index +|`create_index` on `.monitoring-beats-*` indices +|Create monitoring indices in {es} + +|Index +|`create_doc` on `.monitoring-beats-*` indices +|Write monitoring events into {es} +|==== ++ +. Assign the *monitoring role* to users who need to write monitoring data to {es}. +-- + +[float] +[[privileges-to-publish-monitoring-metricbeat]] +===== Metricbeat collection + +NOTE: When using Metricbeat to collect metrics, +no roles or users need to be created with APM Server. +See <> +for complete details on setting up Metricbeat collection. + +If you're <> to collect +metrics about {beatname_uc}, {security-features} provides the `remote_monitoring_user` +{ref}/built-in-users.html[built-in user], and the `remote_monitoring_collector` +and `remote_monitoring_agent` {ref}/built-in-roles.html[built-in roles] for +collecting and sending monitoring information. You can use the built-in user, if +it's available in your environment, or create a user who has the privileges +needed to collect and send monitoring information. + +If you use the built-in `remote_monitoring_user` user, +make sure you set the password before using it. + +If you don't use the `remote_monitoring_user` user: + +-- +. Create a *monitoring user* on the production cluster who will collect and send monitoring +information. Assign the following roles to the *monitoring user*: ++ +[options="header"] +|==== +|Role | Purpose + +|`remote_monitoring_collector` +|Collect monitoring metrics from {beatname_uc} + +|`remote_monitoring_agent` +|Send monitoring data to the monitoring cluster +|==== +-- + +[float] +[[privileges-to-publish-monitoring-view]] +==== View monitoring data + +To grant users the required privileges for viewing monitoring data: + +. Create a *monitoring role*, called something like ++{beat_default_index_prefix}_monitoring_viewer+, that has the following privileges: ++ +[options="header"] +|==== +|Type | Privilege | Purpose + +| Spaces +|`Read` on Stack monitoring +|Read-only access to the Stack Monitoring feature in {kib}. + +| Spaces +|`Read` on Dashboards +|Read-only access to the Dashboards feature in {kib}. +|==== ++ +. Assign the *monitoring role*, along with the following built-in roles, to users who +need to view monitoring data for {beatname_uc}: ++ +[options="header"] +|==== +|Role | Purpose + +|`monitoring_user` +|Grants access to monitoring indices for {beatname_uc} +|==== + +//// +*********************************** *********************************** +*********************************** *********************************** +//// + +[[privileges-agent-central-config]] +=== Grant privileges and roles needed for APM Agent central configuration + +++++ +Create a _central config_ user +++++ + +[[privileges-agent-central-config-server]] +==== APM Server central configuration management + +APM Server acts as a proxy between your APM agents and the APM app. +The APM app communicates any changed settings to APM Server so that your agents only need to poll the Server +to determine which central configuration settings have changed. + +To grant an APM Server user with the required privileges for managing central configuration, +assign the user the following privileges: + +[options="header"] +|==== +|Type | Privilege | Purpose + +| Spaces +|`Read` on {beat_kib_app} +|Allow {beatname_uc} to manage central configurations via the {beat_kib_app} +|==== + +TIP: Looking for privileges and roles needed use central configuration from the APM app or APM app API? +See {kibana-ref}/apm-app-central-config-user.html[APM app central configuration user]. + +//// +*********************************** *********************************** +*********************************** *********************************** +//// + +// [[privileges-create-api-keys]] +// === Grant privileges and roles needed to create APM Server API keys + +// ++++ +// Create an _APM API key_ user +// ++++ + +// CONTENT + +//// +*********************************** *********************************** +*********************************** *********************************** +//// + +[[more-security-roles]] +=== Additional APM users and roles + +In addition to the {beatname_uc} users described in this documentation, +you'll likely need to create users for other APM tasks: + +* An {kibana-ref}/apm-app-reader.html[APM reader], for {kib} users who need to view the APM app, +or create and edit visualizations that access +{beat_default_index_prefix}-*+ data. +* Various {kibana-ref}/apm-app-api-user.html[APM app API users], +for interacting with the APIs exposed by the APM app. + +[float] +[[learn-more-security]] +=== Learn more about users and roles + +Want to learn more about creating users and roles? See +{ref}/secure-cluster.html[Secure a cluster]. Also see: + +* {ref}/security-privileges.html[Security privileges] for a description of +available privileges +* {ref}/built-in-roles.html[Built-in roles] for a description of roles that +you can assign to users diff --git a/docs/index.asciidoc b/docs/index.asciidoc index 382df099c7b..5b07996d4b2 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -7,6 +7,7 @@ include::{asciidoc-dir}/../../shared/attributes.asciidoc[] :beatname_lc: apm-server :beatname_uc: APM Server :beatname_pkg: {beatname_lc} +:beat_kib_app: APM app :beat_monitoring_user: apm_system :beat_monitoring_user_version: 6.5.0 :beat_monitoring_version: 6.5