263 lines
16 KiB
Plaintext
263 lines
16 KiB
Plaintext
[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" ]`.
|