[role="xpack"]
[[reporting-settings-kb]]
=== Reporting settings in {kib}
++++
<titleabbrev>Reporting settings</titleabbrev>
++++
:keywords: administrator, reference, setup, reporting
:description: A reference of the reporting settings administrators configure in kibana.yml.

You can configure `xpack.reporting` settings in your `kibana.yml` to:

* <<general-reporting-settings,Enable the {report-features}>>
* <<encryption-keys,Configure the encryption key>>
* <<reporting-kibana-server-settings,Control how the {report-features} communicate with the {kib} server>>
* <<reporting-job-queue-settings,Manage background jobs>>
* <<reporting-capture-settings,Capture screenshots>>
* <<reporting-network-policy,Restrict requests with a Reporting network policy>>
* <<reporting-csv-settings,Increase the byte limit for CSV exports>>

[float]
[[general-reporting-settings]]
==== Enable reporting

[[xpack-enable-reporting]]`xpack.reporting.enabled` {ess-icon}::
When `true`, enables the {report-features}. The {report-features} are automatically enabled in {kib}. The default is `true`.

[float]
[[encryption-keys]]
==== Encryption key setting

By default, an encryption key is generated for the {report-features} each
time you start {kib}. If a static encryption key is not persisted in
the {kib} configuration, any pending reports fail when you restart {kib}.

If you are load balancing across multiple {kib} instances, each instance needs to have
the same reporting encryption key. Otherwise, report generation fails if a
report is queued through one instance, and another instance picks up the job
from the report queue. The instance that picks up the job is unable to decrypt the
reporting job metadata.

[[xpack-reporting-encryptionKey]] `xpack.reporting.encryptionKey` {ess-icon}::
The static encryption key for reporting. Use an alphanumeric text string that is at least 32 characters. By default, {kib} generates a random key when it starts, which causes pending reports to fail after restart. Configure `xpack.reporting.encryptionKey` to preserve the same key across multiple restarts and multiple {kib} instances.

[source,yaml]
--------------------------------------------------------------------------------
xpack.reporting.encryptionKey: "something_secret"
--------------------------------------------------------------------------------

[float]
[[reporting-kibana-server-settings]]
==== {kib} server settings

Reporting opens the {kib} web interface in a server process to generate
screenshots of {kib} visualizations. In most cases, the default settings
work and you don't need to configure the {report-features} to communicate with {kib}.

If your {kib} instance requires a reverse proxy (such as NGINX, Apache, etc.) for
access, because of rewrite rules or special headers being added by the proxy,
you must configure the `xpack.reporting.kibanaServer` settings to make
the headless browser process connect to the proxy.

[NOTE]
============
If a reverse proxy carries encrypted traffic from user
clients back to a {kib} server, the proxy port, protocol, and hostname
in `xpack.reporting.kibanaServer` must be valid for the encryption that the Reporting
browser receives. Encrypted communications fail if there are
mismatches in the host information between the request and the certificate on the server.

Configuring the `xpack.reporting.kibanaServer` settings to point to a
proxy host requires that the {kib} server has network access to the proxy.
============

`xpack.reporting.kibanaServer.port`:: The port for accessing {kib}, if different from the <<server-port, `server.port`>> value.

`xpack.reporting.kibanaServer.protocol`::
The protocol for accessing {kib}, typically `http` or `https`.

[[xpack-kibanaServer-hostname]] `xpack.reporting.kibanaServer.hostname`::
The hostname for accessing {kib}, if different from the <<server-host, `server.host`>> value.

[float]
[[reporting-job-queue-settings]]
==== Background job settings

Reporting generates reports in the background and jobs are coordinated using documents
in {es}. Depending on how often you generate reports and the overall number of
reports, you might need to change the following settings.

`xpack.reporting.queue.indexInterval`::
How often the index that stores reporting jobs rolls over to a new index. Valid values are `year`, `month`, `week`, `day`, and `hour`. Defaults to `week`.

`xpack.reporting.queue.pollEnabled` {ess-icon}::
Set to `true` (default) to enable the {kib} instance to poll the index for pending jobs and claim them for execution. Setting this to `false` allows the {kib} instance to only add new jobs to the reporting queue, list jobs, and provide the downloads to completed report through the UI.

NOTE: Running multiple instances of {kib} in a cluster for load balancing of
reporting requires identical values for <<xpack-reporting-encryptionKey, `xpack.reporting.encryptionKey`>> and, if
security is enabled, <<xpack-security-encryptionKey, `xpack.security.encryptionKey`>>.

`xpack.reporting.queue.pollInterval`:: 
Specifies the {time-units}[time] that the reporting poller waits between polling the index for any pending Reporting jobs. Can be specified as number of milliseconds. Defaults to `3s`.

[[xpack-reporting-q-timeout]] `xpack.reporting.queue.timeout` {ess-icon}:: 
{time-units}[How long] each worker has to produce a report. If your machine is slow or under heavy load, you might need to increase this timeout. If a Reporting job execution goes over this time limit, the job is marked as a failure and no download will be available. Can be specified as number of milliseconds. Defaults to `2m`.

[float]
[[reporting-capture-settings]]
==== Capture settings

Reporting works by capturing screenshots from {kib}. The following settings control the capturing process.

`xpack.reporting.capture.timeouts.openUrl` {ess-icon}:: 
Specify the {time-units}[time] to allow the Reporting browser to wait for the "Loading..." screen to dismiss and find the initial data for the page. If the time is exceeded, a screenshot is captured showing the current page, and the download link shows a warning message. Can be specified as number of milliseconds. Defaults to `1m`.

`xpack.reporting.capture.timeouts.waitForElements` {ess-icon}::
 Specify the {time-units}[time] to allow the Reporting browser to wait for all visualization panels to load on the page. If the time is exceeded, a screenshot is captured showing the current page, and the download link shows a warning message. Can be specified as number of milliseconds. Defaults to `30s`.

`xpack.reporting.capture.timeouts.renderComplete` {ess-icon}::
 Specify the {time-units}[time] to allow the Reporting browser to wait for all visualizations to fetch and render the data. If the time is exceeded, a screenshot is captured showing the current page, and the download link shows a warning message. Can be specified as number of milliseconds. Defaults to `30s`.

NOTE: If any timeouts from `xpack.reporting.capture.timeouts.*` settings occur when
running a report job, Reporting will log the error and try to continue
capturing the page with a screenshot. As a result, a download will be
available, but there will likely be errors in the visualizations in the report.

`xpack.reporting.capture.maxAttempts` {ess-icon}:: 
If capturing a report fails for any reason, {kib} will re-attempt other reporting job, as many times as this setting. Defaults to `3`.

`xpack.reporting.capture.loadDelay`::
Specify the {time-units}[amount of time] before taking a screenshot when visualizations are not evented. All visualizations that ship with {kib} are evented, so this setting should not have much effect. If you are seeing empty images instead of visualizations, try increasing this value. Defaults to `3s`.

[[xpack-reporting-browser]] `xpack.reporting.capture.browser.type` {ess-icon}::
Specifies the browser to use to capture screenshots. This setting exists for backward compatibility. The only valid option is `chromium`.

[float]
[[reporting-chromium-settings]]
==== Chromium settings

When <<xpack-reporting-browser, `xpack.reporting.capture.browser.type`>> is set to `chromium` (default) you can also specify the following settings.

`xpack.reporting.capture.browser.chromium.disableSandbox`::
It is recommended that you research the feasibility of enabling unprivileged user namespaces. An exception is if you are running {kib} in Docker because the container runs in a user namespace with the built-in seccomp/bpf filters. For more information, refer to <<reporting-chromium-sandbox>>. Defaults to `false` for all operating systems except Debian, Red Hat Linux, and CentOS, which use `true`.

`xpack.reporting.capture.browser.chromium.proxy.enabled`::
Enables the proxy for Chromium to use. When set to `true`, you must also specify the `xpack.reporting.capture.browser.chromium.proxy.server` setting. Defaults to `false`.

`xpack.reporting.capture.browser.chromium.proxy.server`::
The uri for the proxy server. Providing the username and password for the proxy server via the uri is not supported.

`xpack.reporting.capture.browser.chromium.proxy.bypass`::
An array of hosts that should not go through the proxy server and should use a direct connection instead. Examples of valid entries are "elastic.co", "*.elastic.co", ".elastic.co", ".elastic.co:5601".

[float]
[[reporting-network-policy]]
=== Network policy settings

To generate PDF reports, *Reporting* uses the Chromium browser to fully load the {kib} page on the server. This potentially involves sending requests to external hosts. For example, a request might go to an external image server to show a field formatted as an image, or to show an image in a Markdown visualization.

If the Chromium browser is asked to send a request that violates the network policy, *Reporting* stops processing the page before the request goes out, and the report is marked as a failure. Additional information about the event is in the {kib} server logs.

NOTE: {kib} installations are not designed to be publicly accessible over the internet. The Reporting network policy and other capabilities of the Elastic Stack security features do not change this condition.

`xpack.reporting.capture.networkPolicy`::
Capturing a screenshot from a {kib} page involves sending out requests for all the linked web assets. For example, a Markdown visualization can show an image from a remote server.

`xpack.reporting.capture.networkPolicy.enabled`::
When `false`, disables the *Reporting* network policy. Defaults to `true`.

`xpack.reporting.capture.networkPolicy.rules`::
A policy is specified as an array of objects that describe what to allow or deny based on a host or protocol. If a host or protocol is not specified, the rule matches any host or protocol.

The rule objects are evaluated sequentially from the beginning to the end of the array, and continue until there is a matching rule. If no rules allow a request, the request is denied.

[source,yaml]
-------------------------------------------------------
# Only allow requests to placeholder.com
xpack.reporting.capture.networkPolicy:
  rules: [ { allow: true, host: "placeholder.com" } ] 
-------------------------------------------------------

[source,yaml]
-------------------------------------------------------
# Only allow requests to https://placeholder.com 
xpack.reporting.capture.networkPolicy:
  rules: [ { allow: true, host: "placeholder.com", protocol: "https:" } ] 
-------------------------------------------------------

A final `allow` rule with no host or protocol allows all requests that are not explicitly denied:

[source,yaml]
-------------------------------------------------------
# Denies requests from http://placeholder.com, but anything else is allowed.
xpack.reporting.capture.networkPolicy:
  rules: [{ allow: false, host: "placeholder.com", protocol: "http:" }, { allow: true }];
-------------------------------------------------------

A network policy can be composed of multiple rules:

[source,yaml]
-------------------------------------------------------
# Allow any request to http://placeholder.com but for any other host, https is required
xpack.reporting.capture.networkPolicy
  rules: [
    { allow: true, host: "placeholder.com", protocol: "http:" },
    { allow: true, protocol: "https:" },
  ]
-------------------------------------------------------

[NOTE]
============
The `file:` protocol is always denied, even if no network policy is configured.
============

[float]
[[reporting-csv-settings]]
==== CSV settings

[[xpack-reporting-csv]] `xpack.reporting.csv.maxSizeBytes` {ess-icon}::
The maximum {byte-units}[byte size] of a CSV file before being truncated. This setting exists to prevent large exports from causing performance and storage issues. Can be specified as number of bytes. Defaults to `10mb`.

[NOTE]
============
Setting `xpack.reporting.csv.maxSizeBytes` much larger than the default 10 MB limit has the potential to negatively affect the
performance of {kib} and your {es} cluster. There is no enforced maximum for this setting, but a reasonable maximum value depends
on multiple factors:

* The `http.max_content_length` setting in {es}.
* Network proxies, which are often configured by default to block large requests with a 413 error.
* The amount of memory available to the {kib} server, which limits the size of CSV data that must be held temporarily.

For information about {kib} memory limits, see <<production, using {kib} in a production environment>>.
============

`xpack.reporting.csv.scroll.size`::
Number of documents retrieved from {es} for each scroll iteration during a CSV export. Defaults to `500`.

`xpack.reporting.csv.scroll.duration`::
 Amount of {time-units}[time] allowed before {kib} cleans the scroll context during a CSV export. Defaults to `30s`.

`xpack.reporting.csv.checkForFormulas`::
Enables a check that warns you when there's a potential formula involved in the output (=, -, +, and @ chars). See OWASP: https://www.owasp.org/index.php/CSV_Injection. Defaults to `true`.

`xpack.reporting.csv` `.enablePanelActionDownload`::
Enables CSV export from a saved search on a dashboard. This action is available in the dashboard panel menu for the saved search.
NOTE: This setting exists for backwards compatibility, but is unused and hardcoded to `true`. CSV export from a saved search on a dashboard is enabled when Reporting is enabled.

[float]
[[reporting-advanced-settings]]
==== Security settings

With Security enabled, Reporting has two forms of access control: each user can only access their own reports, and custom roles determine who has privilege to generate reports. When Reporting is configured with <<kibana-privileges, {kib} application privileges>>, you can control the spaces and applications where users are allowed to generate reports.

[NOTE]
============================================================================
The `xpack.reporting.roles` settings are for a deprecated system of access control in Reporting. It does not allow API Keys to generate reports, and it doesn't allow {kib} application privileges. We recommend you explicitly turn off reporting's deprecated access control feature by adding `xpack.reporting.roles.enabled: false` in kibana.yml. This will enable you to create custom roles that provide application privileges for reporting, as described in <<grant-user-access, granting users access to reporting>>.
============================================================================

[[xpack-reporting-roles-enabled]] `xpack.reporting.roles.enabled`::
deprecated:[7.14.0,The default for this setting will be `false` in an upcoming version of {kib}.] Sets access control to a set of assigned reporting roles, specified by `xpack.reporting.roles.allow`. Defaults to `true`.

`xpack.reporting.roles.allow`::
deprecated:[7.14.0] In addition to superusers, specifies the roles that can generate reports using the {ref}/security-api.html#security-role-apis[{es} role management APIs]. Requires `xpack.reporting.roles.enabled` to be `true`. Defaults to `[ "reporting_user" ]`.
