kibana/docs/setup/configuring-reporting.asciidoc

[role="xpack"]
[[secure-reporting]]
== Configure reporting in {kib}

++++
<titleabbrev>Configure reporting</titleabbrev>
++++

[NOTE]
============
Kibana PNG/PDF Reporting uses a custom binary of headless Chromium, and support comes with special caveats:

* The functionality requires special OS dependencies which may not be available for all distributions and configurations of Linux.
* It is subject to system resource configurations such as the limited number of file descriptors, allowed processes, and types of processes.
* Linux versions that are in end-of-life phase are not supported.
* Linux systems with SELinux or fapolicyd are not supported.

Before upgrading Kibana in a production environment, we encourage you to test your screenshotting use cases in a pre-production environment
to make sure your hosts support our latest build of Chromium. For the most reliable configuration of PDF/PNG {report-features}, consider
installing {kib} using <<docker, Docker>>, or using <<set-up-on-cloud, Elastic Cloud>>.
============

For security, you grant users access to the {report-features} and secure the reporting endpoints
with TLS/SSL encryption. Additionally, you can install graphical packages into the operating system
to enable the {kib} server to have screenshotting capabilities.

* <<grant-user-access>>
* <<reporting-roles-user-api>>
* <<grant-user-access-basic>>
* <<grant-user-access-external-provider>>
* <<securing-reporting>>
* <<install-reporting-packages>>
* <<set-reporting-server-host>>
* <<reporting-elasticsearch-configuration>>

[float]
[[grant-user-access]]
=== Grant users access to reporting
When security is enabled, you grant users access to {report-features} with <<kibana-privileges, {kib} application privileges>>, which allow you to create custom roles that control the spaces and applications where users generate reports.

. Create the reporting role.

.. Go to the *Roles* management page using the navigation menu or the 
<<kibana-navigation-search,global search field>>.

.. Click *Create role*.

. Specify the role settings.

.. Enter the *Role name*. For example, `custom_reporting_user`.

.. Specify the *Indices* and *Privileges*.
+
Access to data is an index-level privilege. For each index that contains the data you want to include in reports, add a line, then give each index `read` and `view_index_metadata` privileges.
+
NOTE: If you use index aliases, you must also grant `read` and `view_index_metadata` privileges to underlying indices to generate CSV reports.
+
For more information, refer to {ref}/security-privileges.html[Security privileges].

. Add the {kib} privileges.

.. Click *Add Kibana privilege*.

.. Select one or more *Spaces*.

.. Click *Customize*, then click *Analytics*.

.. For each application, select *All*, or to customize the privileges, select *Read* and *Customize sub-feature privileges*.
+
NOTE: If you have a Basic license, sub-feature privileges are unavailable. For details, check out <<grant-user-access-basic>>.
[role="screenshot"]
image::user/reporting/images/kibana-privileges-with-reporting.png["Kibana privileges with Reporting options, Gold or higher license"]
+
NOTE: If the *Reporting* options for application features are unavailable, and the cluster license is higher than Basic, contact your administrator.

.. Click *Add {kib} privilege*.

. Click *Create role*.

. Assign the reporting role to a user.

.. Go to the *Users* management page using the navigation menu or the 
<<kibana-navigation-search,global search field>>.

.. Select the user you want to assign the reporting role to.

.. From the *Roles* dropdown, select *custom_reporting_user*.

.. Click *Update user*.

Granting the privilege to generate reports also grants the user the privilege to view their reports in *Stack Management > Reporting*. Users can only access their own reports.

[float]
[[reporting-roles-user-api]]
==== Grant access with the role API
With <<grant-user-access,{kib} application privileges>>, you can use the {api-kibana}/group/endpoint-roles[role APIs] to grant access to the {report-features}, using *All* privileges, or sub-feature privileges.

NOTE: This API request needs to be run against the <<api,Kibana API endpoint>>.

[source, sh]
---------------------------------------------------------------
PUT <kibana host>:<port>/api/security/role/custom_reporting_user
{
	"elasticsearch": {
		"cluster": [],
		"indices": [],
		"run_as": []
	},
	"kibana": [{
		"spaces": ["*"],
		"base": [],
		"feature": {
			"dashboard_v2": ["generate_report",  <1>
      "download_csv_report"], <2>
      "discover_v2": ["generate_report"], <3>
			"canvas": ["generate_report"], <4>
			"visualize_v2": ["generate_report"] <5>
		}
	}]
}
---------------------------------------------------------------
// CONSOLE

<1> Grants access to generate PNG and PDF reports in *Dashboard*.
<2> Grants access to generate CSV reports from saved Discover session panels in *Dashboard*.
<3> Grants access to generate CSV reports from saved Discover sessions in *Discover*.
<4> Grants access to generate PDF reports in *Canvas*.
<5> Grants access to generate PNG and PDF reports in *Visualize Library*.

[float]
[[grant-user-access-basic]]
=== Grant users access with a Basic license

With a Basic license, you can grant users access with custom roles to {report-features} with <<kibana-privileges, {kib} application privileges>>. However, with a Basic license, sub-feature privileges are unavailable. <<grant-user-access,Create a role>>, then select *All* privileges for the applications where users can create reports.

[role="screenshot"]
image::user/reporting/images/kibana-privileges-with-reporting-basic.png["Kibana privileges with Reporting options, Basic license"]

With a Basic license, sub-feature application privileges are unavailable, but you can use the {ref}/security-api-put-role.html[role API] to grant access to CSV {report-features}:

[source, sh]
---------------------------------------------------------------
PUT localhost:5601/api/security/role/custom_reporting_user
{
  "elasticsearch": { "cluster": [], "indices": [], "run_as": [] },
  "kibana": [
    {
      "base": [],
      "feature": {
        "dashboard_v2": [ "all" ], <1>
        "discover_v2": [ "all" ], <2>
      },
      "spaces": [ "*" ]
    }
  ],
  "metadata": {} // optional
}
---------------------------------------------------------------
// CONSOLE

<1> Grants access to generate CSV reports from saved Discover sessions in *Discover*.
<2> Grants access to generate CSV reports from saved Discover session panels in *Dashboard*.

[float]
[[grant-user-access-external-provider]]
==== Grant access using an external provider

If you are using an external identity provider, such as LDAP or Active Directory, you can assign roles to individual users or groups of users. Role mappings are configured in {ref}/mapping-roles.html[`config/role_mapping.yml`].

For example, assign the `kibana_admin` and `reporting_user` roles to the Bill Murray user:

[source,yaml]
--------------------------------------------------------------------------------
kibana_admin:
  - "cn=Bill Murray,dc=example,dc=com"
reporting_user:
  - "cn=Bill Murray,dc=example,dc=com"
--------------------------------------------------------------------------------

[float]
[[securing-reporting]]
=== Secure the reporting endpoints

To automatically generate reports with {watcher}, you must configure {watcher} to trust the {kib} server certificate.

. Enable {stack-security-features} on your {es} cluster. For more information, see {ref}/security-getting-started.html[Getting started with security].

. Configure TLS/SSL encryption for the {kib} server. For more information, see <<configuring-tls>>.

. Specify the {kib} server CA certificate chain in `elasticsearch.yml`:
+
--
If you are using your own CA to sign the {kib} server certificate, then you need to specify the CA certificate chain in {es} to properly establish trust in TLS connections between {watcher} and {kib}. If your CA certificate chain is contained in a PKCS #12 trust store, specify it like so:

[source,yaml]
--------------------------------------------------------------------------------
xpack.http.ssl.truststore.path: "/path/to/your/truststore.p12"
xpack.http.ssl.truststore.type: "PKCS12"
xpack.http.ssl.truststore.password: "optional decryption password"
--------------------------------------------------------------------------------

Otherwise, if your CA certificate chain is in PEM format, specify it like so:

[source,yaml]
--------------------------------------------------------------------------------
xpack.http.ssl.certificate_authorities: ["/path/to/your/cacert1.pem", "/path/to/your/cacert2.pem"]
--------------------------------------------------------------------------------

For more information, see {ref}/notification-settings.html#ssl-notification-settings[the {watcher} HTTP TLS/SSL Settings].
--

. Add one or more users who have access to the {report-features}.
+
Once you've enabled SSL for {kib}, all requests to the reporting endpoints must include valid credentials.

For more information on sharing reports, direct links, and more, refer to <<reporting-getting-started, Reporting and sharing>>.

[float]
[[install-reporting-packages]]
=== Install the dependencies for the headless browser

If using PNG/PDF {report-features}, make sure the {kib} server operating system has the appropriate packages installed for the distribution.

If you are using RHEL operating systems, install the following packages:

* `xorg-x11-fonts-100dpi`
* `xorg-x11-fonts-75dpi`
* `xorg-x11-utils`
* `xorg-x11-fonts-cyrillic`
* `xorg-x11-fonts-Type1`
* `xorg-x11-fonts-misc`
* `vlgothic-fonts`
* `fontconfig`
* `freetype`

If you are using Ubuntu/Debian systems, install the following packages:

* `fonts-liberation`
* `libfontconfig1`
* `libnss3`

The screenshotting plugin used for {reporting-features} has a built-in utility to check for common issues, such as missing dependencies. See
<<reporting-diagnostics>> for more information.

[float]
[[set-reporting-server-host]]
=== Set the `server.host` for the headless browser

If using PNG/PDF {report-features} in a production environment, it is preferred to use the setting of
`server.host: 0.0.0.0` in the `kibana.yml` configuration file. This allows the headless browser used for
PDF/PNG reporting to reach {kib} over a local interface, while also allowing the {kib} server to listen on
outward-facing network interfaces, as it makes the {kib} server accessible from any network interface on the
machine. Make sure that no firewall rules or other routing rules prevent local services from accessing this
address.

[float]
[[reporting-elasticsearch-configuration]]
=== Ensure {es} allows built-in templates
Reporting relies on {es} to install a mapping template for the data stream that stores reports. Ensure that {es} allows built-in
templates to be installed by keeping the `stack.templates.enabled` setting at the default value of `true`. For more information, see
{ref}/index-management-settings.html#stack-templates-enabled[Index management settings].