mirror of
https://github.com/elastic/kibana.git
synced 2025-06-27 18:51:07 -04:00
9da44e3571
## Summary Docs request to tighten the language around csv.maxSizeBytes on this [page](https://www.elastic.co/guide/en/kibana/8.8/reporting-settings-kb.html#reporting-csv-settings). - [x] test the links Closes: https://github.com/elastic/kibana/issues/159112 Replaces: https://github.com/elastic/kibana/pull/161189 --------- Co-authored-by: Amy Jonsson <amy.jonsson@elastic.co> Co-authored-by: amyjtechwriter <61687663+amyjtechwriter@users.noreply.github.com>
295 lines
17 KiB
Text
295 lines
17 KiB
Text
[role="xpack"]
|
|
[[reporting-settings-kb]]
|
|
=== Reporting settings in {kib}
|
|
++++
|
|
<titleabbrev>Reporting settings</titleabbrev>
|
|
++++
|
|
|
|
:frontmatter-description: A reference of the reporting settings administrators configure in kibana.yml.
|
|
:frontmatter-tags-products: [kibana]
|
|
:frontmatter-tags-content-type: [reference]
|
|
:frontmatter-tags-user-goals: [configure]
|
|
|
|
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-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>>
|
|
* <<reporting-kibana-server-settings,Control how the {report-features} communicate with the {kib} server>>
|
|
|
|
[float]
|
|
[[general-reporting-settings]]
|
|
==== Enable reporting
|
|
|
|
[[xpack-enable-reporting]]`xpack.reporting.enabled` {ess-icon}::
|
|
When `true`, enables the {report-features}. Set this to `false` to disable {report-features} entirely. The default is `true`.
|
|
|
|
[NOTE]
|
|
============
|
|
Disabling the {report-features} is discouraged. If you need to turn off the ability to generate reports,
|
|
configure the roles and spaces in the <<grant-user-access, {kib} application privileges>>.
|
|
|
|
If needed, you can also prevent a {kib} instance from claiming reporting work by setting
|
|
<<xpack-reportingQueue-pollEnabled, `xpack.reporting.queue.pollEnabled: false`>>.
|
|
============
|
|
|
|
[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-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.capture.maxAttempts` {ess-icon}::
|
|
If capturing a report fails for any reason, {kib} will re-queue the report job for retry, as many times as this setting. Defaults to `3`.
|
|
|
|
`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-reportingQueue-pollEnabled]] `xpack.reporting.queue.pollEnabled` ::
|
|
When `true`, enables the {kib} instance to poll {es} for pending jobs and claim them for
|
|
execution. When `false`, allows the {kib} instance to only add new jobs to the reporting queue, list
|
|
jobs, and provide the downloads to completed reports through the UI. This requires a deployment where at least
|
|
one other {kib} instance in the Elastic cluster has this setting to `true`. The default is `true`.
|
|
|
|
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 `4m`.
|
|
|
|
[float]
|
|
[[reporting-capture-settings]]
|
|
==== Capture settings
|
|
|
|
Reporting uses an internal "screenshotting" plugin to capture screenshots from {kib}. The following settings control the capturing process.
|
|
|
|
`xpack.screenshotting.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.screenshotting.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 `1m`.
|
|
|
|
`xpack.screenshotting.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 `2m`.
|
|
|
|
NOTE: If any timeouts from `xpack.screenshotting.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.screenshotting.capture.loadDelay`::
|
|
deprecated:[8.0.0,This setting has no effect.] 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. *NOTE*: This setting exists for backwards compatibility, but is unused and therefore does not have an affect on reporting performance.
|
|
|
|
[float]
|
|
[[reporting-chromium-settings]]
|
|
==== Chromium settings
|
|
|
|
For PDF and PNG reports, Reporting spawns a headless Chromium browser process on the server to load and capture a screenshot of the {kib} app. When installing {kib} on Linux and Windows platforms, the Chromium binary comes bundled with the {kib} download. For Mac platforms, the Chromium binary is downloaded the first time {kib} is started.
|
|
|
|
`xpack.screenshotting.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 CentOS, Debian, and Red Hat Linux, which use `true`.
|
|
|
|
`xpack.screenshotting.browser.chromium.proxy.enabled`::
|
|
Enables the proxy for Chromium to use. When set to `true`, you must also specify the `xpack.screenshotting.browser.chromium.proxy.server` setting. Defaults to `false`.
|
|
|
|
`xpack.screenshotting.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.screenshotting.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.screenshotting.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.screenshotting.networkPolicy.enabled`::
|
|
When `false`, disables the *Reporting* network policy. Defaults to `true`.
|
|
|
|
`xpack.screenshotting.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.screenshotting.networkPolicy:
|
|
rules: [ { allow: true, host: "placeholder.com" } ]
|
|
-------------------------------------------------------
|
|
|
|
[source,yaml]
|
|
-------------------------------------------------------
|
|
# Only allow requests to https://placeholder.com
|
|
xpack.screenshotting.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.screenshotting.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.screenshotting.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 `250mb`.
|
|
|
|
[NOTE]
|
|
============
|
|
We recommend using CSV reports to export moderate amounts of data only. The feature enables analysis of data in
|
|
external tools, but it's not intended for bulk export or to backup {es} data. If you need to export more than
|
|
250 MB of CSV, rather than increasing `xpack.reporting.csv.maxSizeBytes`, please use filters to create multiple
|
|
smaller reports, or extract the data you need directly from {es}.
|
|
|
|
The following deployment configurations may lead to failed report jobs or incomplete reports:
|
|
|
|
* Any shard needed for search is unavailable.
|
|
* Data is stored on slow storage tiers.
|
|
* Network latency between nodes is high.
|
|
* {ccs-cap} is used.
|
|
|
|
To export large amounts of data we recommend using {es} APIs directly. See {ref}/point-in-time-api.html[Point
|
|
in time API], or {ref}/sql-rest-format.html#_csv[SQL with CSV response data format].
|
|
============
|
|
|
|
`xpack.reporting.csv.scroll.size`::
|
|
Number of documents retrieved from {es} for each scroll iteration during a CSV export. Defaults to `500`.
|
|
[NOTE]
|
|
============
|
|
You may need to lower this setting if the default number of documents creates a strain on network resources.
|
|
============
|
|
|
|
`xpack.reporting.csv.scroll.duration`::
|
|
Amount of {time-units}[time] allowed before {kib} cleans the scroll context during a CSV export. Defaults to `30s`.
|
|
[NOTE]
|
|
============
|
|
If search latency in {es} is sufficiently high, such as if you are using {ccs}, you may need to increase the setting.
|
|
============
|
|
|
|
`xpack.reporting.csv.checkForFormulas`::
|
|
Enables a check that warns you when there's a potential formula included in the output (=, -, +, and @ chars). See OWASP: https://www.owasp.org/index.php/CSV_Injection. Defaults to `true`.
|
|
|
|
`xpack.reporting.csv.escapeFormulaValues`::
|
|
Escape formula values in cells with a `'`. See OWASP: https://www.owasp.org/index.php/CSV_Injection. Defaults to `true`.
|
|
|
|
`xpack.reporting.csv.enablePanelActionDownload`::
|
|
deprecated:[7.9.0,This setting has no effect.] 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, and is hardcoded to `true`. CSV export from a saved search on a dashboard is enabled when Reporting is enabled.
|
|
============
|
|
|
|
`xpack.reporting.csv.useByteOrderMarkEncoding`::
|
|
Adds a byte order mark (`\ufeff`) at the beginning of the CSV file. Defaults to `false`.
|
|
|
|
[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. Turning off this feature allows API Keys to generate reports, and allows reporting access through {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" ]`.
|
|
|
|
[float]
|
|
[[reporting-kibana-server-settings]]
|
|
==== {kib} server settings
|
|
|
|
To generate screenshots for PNG and PDF reports, Reporting opens the {kib} web interface using a local
|
|
connection on the server. In most cases, using a local connection to the {kib} server presents no issue. If
|
|
you prefer the headless browser to connect to {kib} using a specific hostname, there are a number of
|
|
settings that allow the headless browser to connect to {kib} through a proxy, rather than directly.
|
|
|
|
[NOTE]
|
|
============
|
|
The `xpack.reporting.kibanaServer` settings are optional. Take caution when editing these settings. Adding
|
|
these settings can cause the {report-features} to fail. If report fail,
|
|
inspect the server logs. The full {kib} URL that Reporting is attempting to
|
|
open is logged during report execution.
|
|
============
|
|
|
|
`xpack.reporting.kibanaServer.port`:: The port for accessing {kib}.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}.
|