github-mirrors/kibana
1
0
Fork 0
mirror of https://github.com/elastic/kibana.git synced 2025-04-23 17:28:26 -04:00
Code Issues Projects Releases Packages Wiki Activity

[DOCS] Updates to the Reporting docs (#101326) (#103947)

Browse source 
* [DOCS] Updates to thee Reporting docs

* Adds the main sharing page

* Final changes

* Changed configuring-reporting link to secure-reporting

* Updates from meeting with Tim and Larry

* Moves reporting and sharing content above ML

* Update docs/setup/configuring-reporting.asciidoc

Co-authored-by: Larry Gregory <lgregorydev@gmail.com>

* Review comments from Tim and Larry

* Fixes broken links

* Fixes redirect

* Fixes broken link from ES docs

* Adds metadata to changed pages

* Review comments

Co-authored-by: Larry Gregory <lgregorydev@gmail.com>

Co-authored-by: Larry Gregory <lgregorydev@gmail.com>
This commit is contained in:
Kaarina Tungseth 2021-06-30 12:24:39 -05:00 • committed by GitHub
parent 13028ea677
commit 3206e8fc4f
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
30 changed files with 711 additions and 876 deletions
Download patch file Download diff file Expand all files Collapse all files

42
docs/canvas/canvas-share-workpad.asciidoc
View file

@ -1,42 +0,0 @@
[role="xpack"]
[[workpad-share-options]]
== Share your workpad
When you've finished your workpad, you can share it outside of {kib}.
For information on how to create PDFs and POST URLs, refer to <<reporting-getting-started, Reporting from {kib}>>.
[float]
[[export-single-workpad]]
=== Export workpads
Create a JSON file of your workpad that you can export outside of {kib}.
To begin, click *Share > Download as JSON*.
[role="screenshot"]
image::images/canvas-export-workpad.png[Export single workpad through JSON, from Share dropdown]
Want to export multiple workpads? Go to the *Canvas* home page, select the workpads you want to export, then click *Export*.
[float]
[[add-workpad-website]]
=== Share the workpad on a website
beta[] *Canvas* allows you to create _shareables_, which are workpads that you download and securely share on any website.
To customize the behavior of the workpad on your website, you can choose to autoplay the pages or hide the workpad toolbar.
. Click *Share > Share on a website*.
. Follow the *Share on a website* instructions.
. To customize the workpad behavior to autoplay the pages or hide the toolbar, use the inline parameters.
+
To make sure that your data remains secure, the data in the JSON file is not connected to {kib}. *Canvas* does not display elements that manipulate the data on the workpad.
+
[role="screenshot"]
image::canvas/images/canvas-embed_workpad.gif[Image showing how to share the workpad on a website]
+
NOTE: Shareable workpads encode the current state of the workpad in a JSON file. When you make changes to the workpad, the changes do not appear in the shareable workpad on your website.
. To change the settings, click the settings icon, then choose the settings you want to use.

0
docs/user/reporting/development/csv-integration.asciidoc → docs/developer/architecture/development/csv-integration.asciidoc
View file

0
docs/user/reporting/development/index.asciidoc → docs/developer/architecture/development/index.asciidoc
View file

0
docs/user/reporting/development/pdf-integration.asciidoc → docs/developer/architecture/development/pdf-integration.asciidoc
View file

3
docs/developer/architecture/index.asciidoc
View file

@ -24,6 +24,7 @@ A few notable services are called out below.
* <<development-security>>
* <<add-data-tutorials>>
* <<development-visualize-index>>
* <<reporting-integration>>
include::kibana-platform-plugin-api.asciidoc[leveloffset=+1]
@ -53,3 +54,5 @@ include::security/index.asciidoc[leveloffset=+1]
include::add-data-tutorials.asciidoc[leveloffset=+1]
include::development-visualize-index.asciidoc[leveloffset=+1]
include::development/index.asciidoc[leveloffset=+1]

9
docs/redirects.asciidoc
View file

@ -329,3 +329,12 @@ This content has moved. Refer to <<discover-view-surrounding-documents>>.
This content has moved. Refer to <<string-field-formatters>>.
[role="exclude",id="embedding"]
== Embed {kib} content in a web page
This content has moved. Refer to <<embedded-content-authentication>> and <<embed-code>>.
[role="exclude",id="reporting-troubleshooting-system-dependencies"]
== System dependencies
This content has moved. Refer to <<install-reporting-packages>>.

384
docs/settings/reporting-settings.asciidoc
View file

@ -4,29 +4,75 @@
++++
<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>>
* <<report-indices,Configure the reporting index>>
* <<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]]
==== General reporting settings
==== Enable reporting
[cols="2*<"]
|===
| [[xpack-enable-reporting]]`xpack.reporting.enabled` {ess-icon}
| Set to `false` to disable the {report-features}.
[[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`.
|[[xpack-reporting-encryptionKey]] `xpack.reporting.encryptionKey` {ess-icon}
| Set to an alphanumeric, at least 32 characters long text string. By default, {kib} will generate a random key when it
starts, which will cause pending reports to fail after restart. Configure this
setting to preserve the same key across multiple restarts and multiple instances of {kib}.
[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]
[[report-indices]]
==== Reporting index setting
`xpack.reporting.index`::
deprecated:[7.11.0,This setting will be removed in 8.0.0.] Multitenancy by changing `kibana.index` is unsupported starting in 8.0.0. For more details, refer to https://ela.st/kbn-remove-legacy-multitenancy[8.0 Breaking Changes]. When you divide workspaces in an Elastic cluster using multiple {kib} instances with a different `kibana.index` setting per instance, you must set a unique `xpack.reporting.index` setting per `kibana.index`. Otherwise, report generation periodically fails if a report is queued through an instance with one `kibana.index` setting, and an instance with a different `kibana.index` attempts to claim the job. Reporting uses a weekly index in {es} to store the reporting job and the report content. The index is automatically created if it does not already exist. Configure a unique value for `xpack.reporting.index`, beginning with `.reporting-`, for every {kib} instance that has a unique <<kibana-index, `kibana.index`>> setting. Defaults to `.reporting`.
{kib} instance A:
[source,yaml]
--------------------------------------------------------------------------------
kibana.index: ".kibana-a"
xpack.reporting.index: ".reporting-a"
xpack.reporting.encryptionKey: "something_secret"
--------------------------------------------------------------------------------
{kib} instance B:
[source,yaml]
--------------------------------------------------------------------------------
kibana.index: ".kibana-b"
xpack.reporting.index: ".reporting-b"
xpack.reporting.encryptionKey: "something_secret"
--------------------------------------------------------------------------------
NOTE: If security is enabled, the `xpack.reporting.index` setting should begin with `.reporting-` for the `kibana_system` role to have the necessary privileges over the index.
[float]
[[reporting-kibana-server-settings]]
@ -34,44 +80,37 @@ You can configure `xpack.reporting` settings in your `kibana.yml` to:
Reporting opens the {kib} web interface in a server process to generate
screenshots of {kib} visualizations. In most cases, the default settings
will work and you don't need to configure Reporting to communicate with {kib}.
However, if your client connections must go through a reverse-proxy
to access {kib}, Reporting configuration must have the proxy port, protocol,
and hostname set in the `xpack.reporting.kibanaServer.*` 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 end-user
============
If a reverse proxy carries encrypted traffic from user
clients back to a {kib} server, the proxy port, protocol, and hostname
in Reporting settings must be valid for the encryption that the Reporting
browser will receive. Encrypted communications will fail if there are
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.
====
[cols="2*<"]
|===
| `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.
|===
[NOTE]
============
Reporting authenticates requests on the {kib} page only when the hostname matches the
<<xpack-kibanaServer-hostname, `xpack.reporting.kibanaServer.hostname`>> setting. Therefore Reporting would fail if the
`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.
NOTE: Reporting authenticates requests on the {kib} page only when the hostname matches the
<<xpack-kibanaServer-hostname, `xpack.reporting.kibanaServer.hostname`>> setting. Therefore Reporting fails if the
set value redirects to another server. For that reason, `"0"` is an invalid setting
because, in the Reporting browser, it becomes an automatic redirect to `"0.0.0.0"`.
============
[float]
[[reporting-job-queue-settings]]
@ -81,98 +120,50 @@ Reporting generates reports in the background and jobs are coordinated using doc
in {es}. Depending on how often you generate reports and the overall number of
reports, you might need to change the following settings.
[cols="2*<"]
|===
| `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.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.
`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
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`>>.
============
[cols="2*<"]
|===
| `xpack.reporting.queue.pollInterval`
| Specify the {ref}/common-options.html#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.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}
| {ref}/common-options.html#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`.
|===
[[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.
Reporting works by capturing screenshots from {kib}. The following settings control the capturing process.
[cols="2*<"]
|===
a| `xpack.reporting.capture.timeouts`
`.openUrl` {ess-icon}
| Specify the {ref}/common-options.html#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.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`.
a| `xpack.reporting.capture.timeouts`
`.waitForElements` {ess-icon}
| Specify the {ref}/common-options.html#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.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`.
a| `xpack.reporting.capture.timeouts`
`.renderComplete` {ess-icon}
| Specify the {ref}/common-options.html#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`.
`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
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.
============
[cols="2*<"]
|===
| `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.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 {ref}/common-options.html#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.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`.
|===
[[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]]
@ -180,42 +171,85 @@ available, but there will likely be errors in the visualizations in the report.
When <<xpack-reporting-browser, `xpack.reporting.capture.browser.type`>> is set to `chromium` (default) you can also specify the following settings.
[cols="2*<"]
|===
a| `xpack.reporting.capture.browser`
`.chromium.disableSandbox`
| It is recommended that you research the feasibility of enabling unprivileged user namespaces.
See Chromium Sandbox for additional information. Defaults to false for all operating systems except Debian,
Red Hat Linux, and CentOS which use true.
`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`.
a| `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.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`.
a| `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.server`::
The uri for the proxy server. Providing the username and password for the proxy server via the uri is not supported.
a| `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".
`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
[cols="2*<"]
|===
| [[xpack-reporting-csv]] `xpack.reporting.csv.maxSizeBytes` {ess-icon}
| The maximum {ref}/common-options.html#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`.
|===
[[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]
============
@ -230,69 +264,33 @@ on multiple factors:
For information about {kib} memory limits, see <<production, using {kib} in a production environment>>.
============
[cols="2*<"]
|===
`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.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.scroll.duration`
| Amount of {ref}/common-options.html#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.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.
|===
`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]]
==== Advanced settings
==== Security settings
[cols="2*<"]
|===
| `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. You can configure what type of requests to allow or filter by setting a
<<reporting-network-policy, network policy>> for Reporting.
| `xpack.reporting.index`
| deprecated:[7.11.0,This setting will be removed in 8.0.] Multitenancy by
changing `kibana.index` will not be supported starting in 8.0. See
https://ela.st/kbn-remove-legacy-multitenancy[8.0 Breaking Changes] for more
details. Reporting uses a weekly index in {es} to store the reporting job and
the report content. The index is automatically created if it does not already
exist. Configure this to a unique value, beginning with `.reporting-`, for
every {kib} instance that has a unique <<kibana-index, `kibana.index`>>
setting. Defaults to `.reporting`.
| [[xpack-reporting-roles-enabled]] `xpack.reporting.roles.enabled`
| deprecated:[7.14.0,This setting must be set to `false` in 8.0.] When `true`, grants users
access to the {report-features} by assigning reporting roles, specified by `xpack.reporting.roles.allow`.
Granting access to users this way is deprecated. Set to `false` and use
{kibana-ref}/kibana-privileges.html[{kib} privileges] instead.
Defaults to `true`.
| `xpack.reporting.roles.allow`
| deprecated:[7.14.0,This setting will be removed in 8.0.] Specifies the roles,
in addition to superusers, 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`.
Granting access to users this way is deprecated. Use
{kibana-ref}/kibana-privileges.html[{kib} privileges] instead.
Defaults to `[ "reporting_user" ]`.
|===
[[xpack-reporting-roles-enabled]] `xpack.reporting.roles.enabled`::
deprecated:[7.14.0,This setting must be set to `false` in 8.0.] When `true`, grants users access to the {report-features} by assigning reporting roles, specified by `xpack.reporting.roles.allow`. Granting access to users this way is deprecated. Set to `false` and use {kibana-ref}/kibana-privileges.html[{kib} privileges] instead. Defaults to `true`.
[NOTE]
============
Each user has access to only their own reports.
============
============================================================================
In 7.x, the default value of `xpack.reporting.roles.enabled` is `true`. To migrate users to the
new method of securing access to *Reporting*, you must set `xpack.reporting.roles.enabled: false`. In the next major version of {kib}, `false` will be the only valid configuration.
============================================================================
`xpack.reporting.roles.allow`::
deprecated:[7.14.0,This setting will be removed in 8.0.] Specifies the roles, in addition to superusers, 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`. Granting access to users this way is deprecated. Use {kibana-ref}/kibana-privileges.html[{kib} privileges] instead. Defaults to `[ "reporting_user" ]`.
NOTE: Each user has access to only their own reports.

235
docs/setup/configuring-reporting.asciidoc Normal file
View file

@ -0,0 +1,235 @@
[role="xpack"]
[[secure-reporting]]
== Configure reporting in {kib}
++++
<titleabbrev>Configure reporting</titleabbrev>
++++
To enable users to manually and automatically generate reports, install the reporting packages, grant users access to the {report-features}, and secure the reporting endpoints.
[float]
[[install-reporting-packages]]
=== Install the reporting packages
Make sure the {kib} server operating system has the appropriate packages installed for the distribution.
If you are using CentOS/RHEL systems, install the following packages:
* `ipa-gothic-fonts`
* `xorg-x11-fonts-100dpi`
* `xorg-x11-fonts-75dpi`
* `xorg-x11-utils`
* `xorg-x11-fonts-cyrillic`
* `xorg-x11-fonts-Type1`
* `xorg-x11-fonts-misc`
* `fontconfig`
* `freetype`
If you are using Ubuntu/Debian systems, install the following packages:
* `fonts-liberation`
* `libfontconfig1`
If the system is missing dependencies, *Reporting* fails in a non-deterministic way. {kib} runs a self-test at server startup, and
if it encounters errors, logs them in the Console. The error message does not include
information about why Chromium failed to run. The most common error message is `Error: connect ECONNREFUSED`, which indicates
that {kib} could not connect to the Chromium process.
To troubleshoot the problem, start the {kib} server with environment variables that tell Chromium to print verbose logs. For more information, refer to <<reporting-troubleshooting-puppeteer-debug-logs>>.
[float]
[[grant-user-access]]
=== Grant users access to reporting
When security is enabled, access to the {report-features} is controlled by roles and privileges.
[[reporting-app-users]]
In 7.12.0 and earlier, you grant access to the {report-features} by assigning users the `reporting_user` role in {es}.
In 7.14.0 and later, you configure *Reporting* to use <<kibana-privileges, {kib} privileges>>. By using {kib} privileges, you can define custom roles that grant *Reporting* privileges as sub-features of {kib} applications.
To grant users permission to generate reports and view their reports in *Reporting*, create and assign the reporting role.
. Create the reporting role.
.. Open the main menu, then click *Stack Management*.
.. Click *Roles > 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.
+
For more information, refer to {ref}/security-privileges.html[Security privileges].
+
[role="screenshot"]
image::user/security/images/reporting-privileges-example.png["Reporting privileges"]
. Add the {kib} privileges.
.. Click *Add Kibana privilege*.
.. Select one or more *Spaces* that you want to grant reporting privileges to.
.. Click *Customize*, then click *Analytics*.
.. Next to each application you want to grant reporting privileges to, click *All*.
+
[role="screenshot"]
image::user/security/images/reporting-custom-role.png["Reporting custom role"]
.. Click *Add {kib} privilege*.
. Click *Create role*.
. Assign the reporting role to a user.
.. Open the main menu, then click *Stack Management*.
.. Click *Users*, then click the user you want to assign the reporting role to.
.. From the *Roles* dropdown, select *custom_reporting_user*.
.. Click *Update user*.
[float]
[[reporting-roles-user-api]]
==== Grant access with the role API
You can also use the {ref}/security-api-put-role.html[role API] to grant access to the reporting features. Grant the reporting role to users in combination with other roles that grant read access to the data in {es}, and at least read access in the applications where users can generate reports.
[source, sh]
---------------------------------------------------------------
POST /_security/role/custom_reporting_user
{
metadata: {},
elasticsearch: { cluster: [], indices: [], run_as: [] },
kibana: [
{
base: [],
feature: {
dashboard: [
'generate_report', <1>
'download_csv_report' <2>
],
discover: ['generate_report'], <3>
canvas: ['generate_report'], <4>
visualize: ['generate_report'], <5>
},
spaces: ['*'],
}
]
}
---------------------------------------------------------------
// CONSOLE
<1> Grants access to generate PNG and PDF reports in *Dashboard*.
<2> Grants access to download CSV files from saved search panels in *Dashboard*.
<3> Grants access to generate CSV reports from saved searches 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 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]
==== Grant access with a custom index
If you are using a custom index, the `xpack.reporting.index` setting must begin with `.reporting-*`. The default {kib} system user has `all` privileges against the `.reporting-*` pattern of indices.
If you use a different pattern for the `xpack.reporting.index` setting, you must create a custom `kibana_system` user with appropriate access to the index.
NOTE: In the next major version of Kibana, granting access with a custom index is unsupported.
. Create the reporting role.
.. Open the main menu, then click *Stack Management*.
.. Click *Roles > Create role*.
. Specify the role settings.
.. Enter the *Role name*. For example, `custom-reporting-user`.
.. From the *Indices* dropdown, select the custom index.
.. From the *Privileges* dropdown, select *all*.
.. Click *Add Kibana privilege*.
.. Select one or more *Spaces* that you want to grant reporting privileges to.
.. Click *Customize*, then click *Analytics*.
.. Next to each application you want to grant reporting privileges to, click *All*.
.. Click *Add {kib} privilege*, then click *Create role*.
. Assign the reporting role to a user.
.. Open the main menu, then click *Stack Management*.
.. Click *Users*, then click the user you want to assign the reporting role to.
.. From the *Roles* dropdown, select *kibana_system* and *custom-reporting-user*.
.. Click *Update user*.
. Configure {kib} to use the new account.
+
[source,js]
--------------------------------------------------------------------------------
elasticsearch.username: 'custom_kibana_system'
--------------------------------------------------------------------------------
[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.

14
docs/user/canvas.asciidoc
View file

@ -194,14 +194,24 @@ Organize and separate your ideas by adding more pages.
[role="screenshot"]
image::images/canvas-add-pages.gif[Add pages]
[float]
[[workpad-share-options]]
== Share your workpad
To share workpads with a larger audience, click *Share* in the toolbar. For detailed information about the sharing options, refer to <<reporting-getting-started,Reporting>>.
[float]
[[export-single-workpad]]
== Export workpads
Want to export multiple workpads? Go to the *Canvas* home page, select the workpads you want to export, then click *Export*.
--
include::{kib-repo-dir}/canvas/canvas-edit-workpads.asciidoc[]
include::{kib-repo-dir}/canvas/canvas-present-workpad.asciidoc[]
include::{kib-repo-dir}/canvas/canvas-share-workpad.asciidoc[]
include::{kib-repo-dir}/canvas/canvas-tutorial.asciidoc[]
include::{kib-repo-dir}/canvas/canvas-expression-lifecycle.asciidoc[]

2
docs/user/dashboard/dashboard.asciidoc
View file

@ -301,7 +301,7 @@ image:images/Dashboard_inspect.png[Inspect in dashboard]
[[share-the-dashboard]]
== Share dashboards
To share the dashboard with a larger audience, click *Share* in the toolbar. For detailed information, refer to <<reporting-getting-started,Reporting>>.
To share the dashboard with a larger audience, click *Share* in the toolbar. For detailed information about the sharing options, refer to <<reporting-getting-started,Reporting>>.
[float]
[[import-dashboards]]

6
docs/user/discover.asciidoc
View file

@ -272,6 +272,12 @@ your data appears in a map.
[role="screenshot"]
image:images/discover-maps.png[Map containing documents]
[float]
[[share-your-findings]]
=== Share your findings
To share your findings with a larger audience, click *Share* in the toolbar. For detailed information about the sharing options, refer to <<reporting-getting-started,Reporting>>.
[float]
=== What’s next?

11
docs/user/index.asciidoc
View file

@ -8,13 +8,6 @@ include::{kib-repo-dir}/getting-started/quick-start-guide.asciidoc[]
include::setup.asciidoc[]
include::monitoring/configuring-monitoring.asciidoc[leveloffset=+1]
include::monitoring/monitoring-metricbeat.asciidoc[leveloffset=+2]
include::monitoring/viewing-metrics.asciidoc[leveloffset=+2]
include::monitoring/monitoring-kibana.asciidoc[leveloffset=+2]
include::security/securing-kibana.asciidoc[]
include::production-considerations/index.asciidoc[]
include::discover.asciidoc[]
@ -25,6 +18,8 @@ include::canvas.asciidoc[]
include::{kib-repo-dir}/maps/index.asciidoc[]
include::reporting/index.asciidoc[]
include::ml/index.asciidoc[]
include::graph/index.asciidoc[]
@ -45,8 +40,6 @@ include::management.asciidoc[]
include::{kib-repo-dir}/fleet/fleet.asciidoc[]
include::reporting/index.asciidoc[]
include::api.asciidoc[]
include::plugins.asciidoc[]

1
docs/user/production-considerations/index.asciidoc
View file

@ -1,5 +1,6 @@
include::production.asciidoc[]
include::alerting-production-considerations.asciidoc[]
include::reporting-production-considerations.asciidoc[]
include::task-manager-production-considerations.asciidoc[]
include::task-manager-health-monitoring.asciidoc[]
include::task-manager-troubleshooting.asciidoc[]

36
docs/user/production-considerations/reporting-production-considerations.asciidoc Normal file
View file

@ -0,0 +1,36 @@
[role="xpack"]
[[reporting-production-considerations]]
== Reporting production considerations
++++
<titleabbrev>Reporting</titleabbrev>
++++
:keywords: administrator, analyst, concept, setup, reporting
:description: Consider the production components that are used to generate reports.
To generate reports, {kib} uses a custom build of the Chromium web browser, which runs on the {kib} server in headless mode to load {kib} and capture the rendered {kib} visualizations as images. Chromium is an open-source project not related to Elastic, but the Chromium binary for {kib} has been custom-built by Elastic to make sure it works with minimal setup. The operating system that the {kib} server uses can require additional dependencies for Chromium.
[float]
[[reporting-chromium-sandbox]]
=== Chromium sandbox
For an additional layer of security, use the sandbox. The Chromium sandbox uses operating system-provided mechanisms to ensure that code execution cannot make persistent changes to the computer or access confidential information. The specific sandboxing techniques differ for each operating system.
[float]
[[reporting-linux-sandbox]]
==== Linux sandbox
The Linux sandbox depends on user namespaces, which were introduced with the 3.8 Linux kernel. However, many
distributions don't have user namespaces enabled by default, or they require the CAP_SYS_ADMIN capability. The {report-features}
automatically disable the sandbox when it is running on Debian and CentOS, as additional steps are required to enable
unprivileged usernamespaces. In these situations, you'll see the following message in your {kib} startup logs:
`Chromium sandbox provides an additional layer of protection, but is not supported for your OS.
Automatically setting 'xpack.reporting.capture.browser.chromium.disableSandbox: true'.`
Reporting automatically enables the Chromium sandbox at startup when a supported OS is detected. However, if your kernel is 3.8 or newer, it's
recommended to set `xpack.reporting.capture.browser.chromium.disableSandbox: false` in your `kibana.yml` to explicitly enable usernamespaces.
[float]
[[reporting-docker-sandbox]]
==== Docker
When running {kib} in a Docker container, all container processes are run within a usernamespace with seccomp-bpf and
AppArmor profiles that prevent the Chromium sandbox from being used. In these situations, disabling the sandbox is recommended,
as the container implements similar security mechanisms.

49
docs/user/reporting/automating-report-generation.asciidoc
View file

@ -1,69 +1,62 @@
[role="xpack"]
[[automating-report-generation]]
== Automating report generation
Automatically generate PDF and CSV reports by submitting HTTP `POST` requests using {watcher} or a script.
== Automatically generate reports
include::report-intervals.asciidoc[]
To automatically generate PDF and CSV reports, generate a POST URL, then submit the HTTP `POST` request using {watcher} or a script.
[float]
[[create-a-post-url]]
=== Create a POST URL
Create the POST URL that triggers a report to generate PDF and CSV reports.
To create the POST URL for PDF reports:
. Open the  dashboard, visualization, or **Canvas** workpad.
. Open the main menu, then click *Dashboard, *Visualize Library*, or *Canvas*.
. From the {kib} toolbar, click *Share*, then select *PDF Reports*.
. Open the dashboard, visualization, or **Canvas** workpad you want to view as a report.
. If you are using **Canvas**, click *Advanced options*.
. From the toolbar, click *Share > PDF Reports*, then choose an option:
. Click *Copy POST URL*.
+
[role="screenshot"]
image::images/report-automate-pdf.png[Automatically generate *Dashboard* and *Visualize Library* reports]
* If you are using *Dashboard* or *Visulize Library*, click *Copy POST URL*.
* If you are using *Canvas*, click *Advanced options > Copy POST URL*.
To create the POST URL for CSV reports:
. In *Discover*, open the saved search.
. Open the main menu, then click *Discover*.
. From the {kib} toolbar, click *Share*, then select *CSV Reports*.
. Open the saved search you want to share.
. Click *Copy POST URL*.
+
[role="screenshot"]
image::images/report-automate-csv.png[Generate Discover reports]
. In the toolbar, click *Share > CSV Reports > Copy POST URL*.
[float]
[[use-watcher]]
=== Use Watcher
include::watch-example.asciidoc[]
[float]
[[use-a-script]]
=== Use a script
include::script-example.asciidoc[]
[float]
[[reporting-response-codes]]
=== HTTP response codes
include::response-codes.asciidoc[]
[float]
[[deprecated-report-urls]]
=== Deprecated report URLs
The following POST URL paths are deprecated. If there are
any problems with using these paths after you upgrade {kib}, use
{kib} to regenerate the POST URL for a particular report.
If you experience issues with the deprecated report URLs after you upgrade {kib}, regenerate the POST URL for your reports.
* Dashboard reports: `/api/reporting/generate/dashboard/<dashboard-id>`
* Visualize reports: `/api/reporting/generate/visualization/<visualization-id>`
* Saved Search reports: `/api/reporting/generate/search/<saved-search-id>`
* *Dashboard* reports: `/api/reporting/generate/dashboard/<dashboard-id>`
* *Visualize Library* reports: `/api/reporting/generate/visualization/<visualization-id>`
* *Discover* saved search reports: `/api/reporting/generate/search/<saved-search-id>`
[IMPORTANT]
===================
Previously there was a `&sync` parameter appended to generation URLs which would hold
the request open until the document was fully generated. This feature has been removed.
Existing use of the `&sync` parameter, in Watcher for example, will need to be updated.
===================
IMPORTANT:
In earlier {kib} versions, you could use the `&sync` parameter to append to report URLs that held the request open until the document was fully generated. The `&sync` parameter is now unsupported. If you use the `&sync` parameter in Watcher, you must update the parameter.

26
docs/user/reporting/chromium-sandbox.asciidoc
View file

@ -1,26 +0,0 @@
[role="xpack"]
[[reporting-chromium-sandbox]]
=== Chromium sandbox
When {report-features} uses the Chromium browser for generating PDF reports,
it's recommended to use the sandbox for an additional layer of security. The
Chromium sandbox uses operating system provided mechanisms to ensure that
code execution cannot make persistent changes to the computer or access
confidential information. The specific sandboxing techniques differ for each
operating system.
==== Linux sandbox
The Linux sandbox depends on user namespaces, which were introduced with the 3.8 Linux kernel. However, many
distributions don't have user namespaces enabled by default, or they require the CAP_SYS_ADMIN capability. The {report-features}
will automatically disable the sandbox when it is running on Debian and CentOS as additional steps are required to enable
unprivileged usernamespaces. In these situations, you'll see the following message in your {kib} startup logs:
`Chromium sandbox provides an additional layer of protection, but is not supported for your OS.
Automatically setting 'xpack.reporting.capture.browser.chromium.disableSandbox: true'.`
Reporting will automatically enable the Chromium sandbox at startup when a supported OS is detected. However, if your kernel is 3.8 or newer, it's
recommended to set `xpack.reporting.capture.browser.chromium.disableSandbox: false` in your `kibana.yml` to explicitly enable usernamespaces.
==== Docker
When running {kib} in a Docker container, all container processes are run within a usernamespace with seccomp-bpf and
AppArmor profiles that prevent the Chromium sandbox from being used. In these situations, disabling the sandbox is recommended,
as the container implements similar security mechanisms.

78
docs/user/reporting/configuring-reporting.asciidoc
View file

@ -1,78 +0,0 @@
[role="xpack"]
[[configuring-reporting]]
== Reporting configuration
You can configure settings in `kibana.yml` to control how the {report-features}
communicate with the {kib} server, manages background jobs, and captures
screenshots. See <<reporting-settings-kb, Reporting Settings>> for the complete
list of settings.
[float]
[[encryption-keys]]
=== Encryption keys for multiple {kib} instances
By default, a new encryption key is generated for the {report-features} each
time you start {kib}. This means if a static encryption key is not persisted in
the {kib} configuration, any pending reports will fail when you restart {kib}.
If you are load balancing across multiple {kib} instances, they need to have
the same reporting encryption key. Otherwise, report generation will fail if a
report is queued through one instance and another instance picks up the job
from the report queue. The other instance will not be able to decrypt the
reporting job metadata.
To set a static encryption key for reporting, set the
`xpack.reporting.encryptionKey` property in the `kibana.yml`
configuration file. You can use any alphanumeric, at least 32 characters long text string as the encryption key.
[source,yaml]
--------------------------------------------------------------------------------
xpack.reporting.encryptionKey: "something_secret"
--------------------------------------------------------------------------------
[float]
[[report-indices]]
=== Report indices for multiple {kib} workspaces
If you divide workspaces in an Elastic cluster using multiple {kib} instances
with a different `kibana.index` setting per instance, you must set a unique `xpack.reporting.index`
setting per `kibana.index`. Otherwise, report generation will periodically fail
if a report is queued through an instance with one `kibana.index` setting, and
an instance with a different `kibana.index` attempts to claim the job.
Kibana instance A:
[source,yaml]
--------------------------------------------------------------------------------
kibana.index: ".kibana-a"
xpack.reporting.index: ".reporting-a"
xpack.reporting.encryptionKey: "something_secret"
--------------------------------------------------------------------------------
Kibana instance B:
[source,yaml]
--------------------------------------------------------------------------------
kibana.index: ".kibana-b"
xpack.reporting.index: ".reporting-b"
xpack.reporting.encryptionKey: "something_secret"
--------------------------------------------------------------------------------
NOTE: If security is enabled, the `xpack.reporting.index` setting should begin
with `.reporting-` in order for the `kibana_system` role to have the necessary
privileges over the index.
[float]
[[using-reverse-proxies]]
=== Use reverse proxies
If your {kib} instance requires a reverse proxy (NGINX, Apache, etc.) for
access, because of rewrite rules or special headers being added by the proxy,
then you need to configure the `xpack.reporting.kibanaServer` settings to make
the headless browser process connect to the proxy in <<reporting-kibana-server-settings, Kibana server settings>>.
NOTE: A headless browser runs on the Kibana server to open a Kibana page for
capturing screenshots. Configuring the `xpack.reporting.kibanaServer` settings
to point to a proxy host requires that the Kibana server has network access to
the proxy.
include::{kib-repo-dir}/user/security/reporting.asciidoc[]
include::network-policy.asciidoc[]

1
docs/user/reporting/generating-reports.asciidoc
View file

@ -1 +0,0 @@
[role="xpack"]

28
docs/user/reporting/gs-index.asciidoc
View file

@ -1,28 +0,0 @@
[role="xpack"]
[[xpack-reporting]]
= Reporting from Kibana
[partintro]
--
You can generate reports that contain {kib} dashboards,
visualizations, and saved searches. The reports are exported as
print-optimized PDF documents.
NOTE: On Linux, the `libfontconfig` and `libfreetype6` packages and system
fonts are required to generate reports. If no system fonts are available,
labels are not rendered correctly in the reports.
The following Reporting button appears in the {kib} toolbar:
image:images/reporting.jpg["Reporting",link="reporting.jpg"]
You can also <<automating-report-generation,generate reports automatically>>.
IMPORTANT: Reports are stored in the `.reporting-*` indices. Any user with
access to these indices has access to every report generated by all users.
To use {report-features} in a production environment,
<<securing-reporting,secure the Reporting endpoints>>.
--
include::getting-started.asciidoc[]

BIN
docs/user/reporting/images/embed-code-public-url.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 37 KiB

BIN
docs/user/reporting/images/permalink-public-url.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 24 KiB

201
docs/user/reporting/index.asciidoc
View file

@ -1,125 +1,166 @@
[role="xpack"]
[[reporting-getting-started]]
= Reporting
= Reporting and sharing
[partintro]
--
You can generate a report that contains a {kib} dashboard, visualization,
saved search, or Canvas workpad. Depending on the object type, you can export the data as
a PDF, PNG, or CSV document, which you can keep for yourself, or share with others.
:keywords: analyst, concept, task, reporting
:description: {kib} provides you with several options to share *Discover* saved searches, dashboards, *Visualize Library* visualizations, and *Canvas* workpads with others, or on a website.
Reporting is available from the *Share* menu
in *Discover*, *Dashboard*, *Visualize Library*, and *Canvas*.
{kib} provides you with several options to share *Discover* saved searches, dashboards, *Visualize Library* visualizations, and *Canvas* workpads.
[role="screenshot"]
image::user/reporting/images/share-menu.png["Share"]
You access the options from the *Share* menu in the toolbar. The sharing options include the following:
[float]
== Setup
* *PDF Reports* &mdash; Generate and download a PDF file of a dashboard, visualization, or *Canvas* workpad.
The {report-features} are automatically enabled in {kib}. It runs a custom build of the Chromium web browser, which
runs on the server in headless mode to load {kib} and capture the rendered {kib} charts as images.
* *PNG Reports* &mdash; Generate and download a PNG file of a dashboard or visualization.
Chromium is an open-source project not related to Elastic, but the Chromium binary for {kib} has been custom-built by Elastic to ensure it
works with minimal setup. However, the {kib} server OS might still require additional dependencies for Chromium. See the
<<reporting-troubleshooting-system-dependencies, Reporting troubleshooting>> section for more information about the system dependencies
for different operating systems.
* *CSV Reports* &mdash; Generate and download a CSV file of a saved search.
[float]
[[reporting-required-privileges]]
== Roles and privileges
* *Permalinks* &mdash; Share a direct link to a *Discover* saved search, dashboard, or visualization.
When security is enabled, access to the {report-features} is controlled by security privileges. In versions 7.12 and earlier, you can grant access to the {report-features}
by assigning users the `reporting_user` role in {es}. In 7.14 and later, you can configure *Reporting* to use
<<kibana-privileges, {kib} privileges>>. It is recommended that *Reporting* is configured to
use {kib} privileges by setting <<xpack-reporting-roles-enabled,`xpack.reporting.roles.enabled`>> to `false`. By using {kib} privileges, you can define
custom roles that grant *Reporting* privileges as sub-features of {kib} applications in *Role Management*.
* *Download as JSON* &mdash; Generate and download a JSON file of a *Canvas* workpad.
Users must also have the {kib} privileges to access the saved objects and associated {es} indices included in the generated reports.
For an example, refer to <<secure-reporting, Reporting and
security>>.
* beta[] *Share on a website* &mdash; Download and securely share *Canvas* workpads on any website.
* *Embed code* &mdash; Embed a fully interactive dashboard or visualization as an iframe on a web page.
[float]
[[manually-generate-reports]]
== Manually generate and download reports
== Create reports
Generate and download PDF, PNG, and CSV files of dashboards, visualizations, **Canvas** workpads, and saved searches.
Create and download PDF, PNG, or CSV reports of saved searches, dashboards, visualizations, and workpads.
. Open the dashboard, visualization, **Canvas** workpad, or saved search.
. From the {kib} toolbar, click **Share**, then select one of the following options:
** **PDF Reports** &mdash; Generates a PDF file of the dashboard, visualization, or **Canvas** workpad.
** **PNG Reports** &mdash; Generates a PNG file of the dashboard or visualization.
** **CSV Reports** &mdash; Generates a CSV report of the saved search.
. Generate the report.
+
When the report completes, a notification appears.
. Click **Download report**.
NOTE: When you create a dashboard report that includes a data table or saved search, the PDF includes only the visible data.
[float]
[[reporting-layout-sizing]]
== Layout and sizing
The layout and size of the PDF or PNG image depends on the {kib} app
with which the Reporting plugin is integrated. For *Canvas*, the
worksheet dimensions determine the size for reports. In other apps,
the dimensions are taken on the fly by looking at
the size of the visualization elements or panels on the page.
The layout and size of the report depends on what you are sharing.
For saved searches, dashboards, and visualizations, the layout depends on the size of the panels.
For workpads, the layout depends on the size of the worksheet dimensions.
The size dimensions are part of the reporting job parameters. Therefore, to
make the report output larger or smaller, you can change the size of the browser.
This resizes the shareable container before generating the
report, so the desired dimensions are passed in the job parameters.
To change the output size, change the size of the browser, which resizes the shareable container before the report generates. It might take some trial and error before you're satisfied.
In the following {kib} dashboard, the shareable container is highlighted.
The shareable container is captured when you click
*Generate* or *Copy POST URL* from the *Share* menu. It might take some trial and error
before you're satisfied with the layout and dimensions in the
PNG or PDF image.
In the following dashboard, the shareable container is highlighted:
[role="screenshot"]
image::user/reporting/images/shareable-container.png["Shareable Container"]
. Open the main menu, then open the saved search, dashboard, visualization, or workpad you want to share.
. From the toolbar, click *Share*, then select one of the following options:
** **PDF Reports** &mdash; Generates a PDF file of the dashboard, visualization, or workpad.
** **PNG Reports** &mdash; Generates a PNG file of the dashboard or visualization.
** **CSV Reports** &mdash; Generates a CSV report of the saved search.
. If you are creating a PDF report of a dashboard, select *Optimize for printing* to create a printer-friendly PDF with multiple A4 portrait pages and two visualizations per page.
+
NOTE: When you create a dashboard report that includes a data table or saved search, the PDF includes only the visible data.
. If you are creating a PDF report of a workpad, select *Full page layout* to create a PDF without margins that surround the workpad.
. Generate the report.
. When the report generates, a message appears. On the message, click **Download report**.
. To view and manage reports, open the main menu, then click *Stack Management > Reporting*.
[float]
[[optimize-pdf]]
== Optimize PDF for print&mdash;dashboard only
[[share-a-direct-link]]
== Share a direct link
To create a printer-friendly PDF with multiple A4 portrait pages and two visualizations per page, turn on *Optimize for printing*.
Share a direct link to a saved search, dashboard, or visualization. To access the shared object, authentication is required.
. Open the main menu, then open the saved search, dashboard, or visualization you want to share.
. From the toolbar, click *Share*, then select *Permalinks*.
. Specify how you want to generate the link:
* To display only the current state of the object, select *Snapshot*.
* To display up-to-date changes, select *Saved object*.
* To generate a shortened link, select *Short URL*.
* To automatically log in anonymous users when you have multiple authentication providers enabled, select *Public URL*.
+
[role="screenshot"]
image::user/reporting/images/preserve-layout-switch.png["Share"]
image::images/permalink-public-url.png[Permalink share menu with Public URL option highlighted]
+
NOTE: *Public URL* is available only when anonymous access is configured and your anonymous service account has privileges to access what you want to share.
. Click *Copy link*.
[float]
[[full-page-pdf]]
== Full page PDF layout &mdash;Canvas only
[[download-as-json]]
== Create a JSON file
To create a PDF without margins surrounding the Canvas workpad, turn on *Full page layout* before generating the PDF.
Create a JSON file for a workpad.
. Open the main menu, then click *Canvas*.
. Open the workpad you want to share.
. From the toolbar, click *Share*, then select *Download as JSON*.
[float]
[[add-workpad-website]]
== Share workpads on a website
beta[] *Canvas* allows you to create _shareables_, which are workpads that you download and securely share on a website.
To customize the behavior of the workpad on your website, you can choose to autoplay the pages or hide the workpad toolbar.
. Open the main menu, then click *Canvas*.
. Open the workpad you want to share.
. Click *Share > Share on a website*.
. Follow the instructions.
. To customize the workpad behavior to autoplay the pages or hide the toolbar, use the inline parameters.
+
To make sure that your data remains secure, the data in the JSON file is not connected to {kib}. *Canvas* does not display elements that manipulate the data on the workpad.
+
NOTE: Shareable workpads encode the current state of the workpad in a JSON file. When you make changes to the workpad, the changes do not appear in the shareable workpad on your website.
. To change the settings, click the settings icon, then choose the settings you want to use.
[float]
[[embed-code]]
== Embed code
Display your dashboard or visualization on an internal company website or personal web page with an iframe. Embedding other {kib} objects is generally supported, but you might need to manually craft the proper HTML code.
Some users might not have access to the dashboard or visualization. For more information, refer to <<anonymous-access-and-embedding>> and <<embedded-content-authentication>>.
. Open the main menu, then open the dashboard or visualization you want to share.
. Click *Share > Embed code*.
. Specify how you want to generate the code:
* To display only the current state, select *Snapshot*.
* To display up-to-date changes, select *Saved object*.
* Select the dashboard or visualization elements you want to include.
* To generate a shortened link, select *Short URL*.
* To automatically log in anonymous users when you have multiple authentication providers enabled, select *Public URL*.
+
[role="screenshot"]
image::user/reporting/images/canvas-full-page-layout.png["Full Page Layout"]
image::images/embed-code-public-url.png[Embed code share menu with Public URL option highlighted]
+
NOTE: *Public URL* is available only when anonymous access is configured and your anonymous service account has privileges to access what you want to embed.
[float]
[[manage-report-history]]
== View and manage report history
For a list of your reports, open the main menu, then click *Stack Management > Reporting*.
From this view, you can monitor the status of a report and
download reports that you previously generated.
. Click *Copy iFrame code*.
--
include::automating-report-generation.asciidoc[]
include::configuring-reporting.asciidoc[]
include::chromium-sandbox.asciidoc[]
include::reporting-troubleshooting.asciidoc[]
include::development/index.asciidoc[]

71
docs/user/reporting/network-policy.asciidoc
View file

@ -1,71 +0,0 @@
[role="xpack"]
[[reporting-network-policy]]
=== Restrict requests with a Reporting network policy
When Reporting generates PDF reports, it 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 Kibana 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.
============
==== Configure a Reporting network policy
You configure the network policy by specifying the `xpack.reporting.capture.networkPolicy.rules` setting in `kibana.yml`. 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 will allow 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.
============
==== Disable a Reporting network policy
You can use the `xpack.reporting.capture.networkPolicy.enabled: false` setting to disable the network policy feature. The default for
this configuration property is `true`, so it is not necessary to explicitly enable it.

12
docs/user/reporting/report-intervals.asciidoc
View file

@ -1,12 +0,0 @@
[IMPORTANT]
===================
The interval between report requests must be longer than the time it
takes to generate the reports--otherwise, the report queue can back up. To
avoid this, increase the time between report requests.
By default, report generation times out if the report cannot be generated
within two minutes. If you are generating reports that contain many complex
visualizations or your machine is slow or under constant heavy load, it
might take longer than two minutes to generate a report. You can increase
the timeout by setting `xpack.reporting.queue.timeout` in `kibana.yml`.
===================

37
docs/user/reporting/reporting-troubleshooting.asciidoc
View file

@ -8,7 +8,6 @@
Having trouble? Here are solutions to common problems you might encounter while using Reporting.
* <<reporting-diagnostics>>
* <<reporting-troubleshooting-system-dependencies>>
* <<reporting-troubleshooting-text-incorrect>>
* <<reporting-troubleshooting-missing-data>>
* <<reporting-troubleshooting-file-permissions>>
@ -26,40 +25,6 @@ When {kib} is running, navigate to the Report Listing page, and click *Run repor
This will open up a diagnostic tool that checks various parts of the {kib} deployment and
come up with any relevant recommendations.
[float]
[[reporting-troubleshooting-system-dependencies]]
=== System dependencies
Reporting launches a "headless" web browser called Chromium on the Kibana server. It is a custom build made by Elastic of an open source
project, and it is intended to have minimal dependencies on OS libraries. However, the Kibana server OS might still require additional
dependencies to run the Chromium executable.
Make sure Kibana server OS has the appropriate packages installed for the distribution.
If you are using CentOS/RHEL systems, install the following packages:
* `ipa-gothic-fonts`
* `xorg-x11-fonts-100dpi`
* `xorg-x11-fonts-75dpi`
* `xorg-x11-utils`
* `xorg-x11-fonts-cyrillic`
* `xorg-x11-fonts-Type1`
* `xorg-x11-fonts-misc`
* `fontconfig`
* `freetype`
If you are using Ubuntu/Debian systems, install the following packages:
* `fonts-liberation`
* `libfontconfig1`
If the system is missing dependencies, then Reporting will fail in a non-deterministic way. {kib} runs a self-test at server startup, and
if it encounters errors, logs them in the Console. Unfortunately, the error message does not include
information about why Chromium failed to run. The most common error message is `Error: connect ECONNREFUSED`, which indicates
that {kib} could not connect to the Chromium process.
To troubleshoot the problem, start the {kib} server with environment variables that tell Chromium to print verbose logs. See the
<<reporting-troubleshooting-puppeteer-debug-logs, Puppeteer debug method>> for more information.
[float]
[[reporting-troubleshooting-text-incorrect]]
=== Text rendered incorrectly in generated reports
@ -100,7 +65,7 @@ multiple instances to find the same job in these searches. Only the instance tha
"processing" will actually execute the report job. The other instances that unsuccessfully tried to make the same update will log
something similar to this:
[source]
[source,text]
--------------------------------------------------------------------------------
StatusCodeError: [version_conflict_engine_exception] [...]: version conflict, required seqNo [6124], primary term [1]. current document has seqNo [6125] and primary term [1], with { ... }
status: 409,

28
docs/user/reporting/script-example.asciidoc
View file

@ -1,12 +1,7 @@
To automatically generate reports from a script, you'll make a request to the `POST` URL.
The response from this request will be JSON, and will contain a `path` property with a
URL to use to download the generated report. Use the `GET` method in the HTTP request to
download the report.
To automatically generate reports from a script, make a request to the `POST` URL. The request returns a JSON and contains a `path` property with a
URL that you use to download the report. Use the `GET` method in the HTTP request to download the report.
The request method must be `POST` and it must include a `kbn-xsrf` header for Kibana
to allow the request.
The following example queues CSV report generation using the `POST` URL with cURL:
To queue CSV report generation using the `POST` URL with cURL:
["source","sh",subs="attributes"]
---------------------------------------------------------
@ -18,14 +13,12 @@ curl \
---------------------------------------------------------
// CONSOLE
<1> `POST` method is required.
<2> Provide user credentials for a user with permission to access Kibana and
{report-features}.
<3> The `kbn-xsrf` header is required for all `POST` requests to Kibana. For more information, see <<api-request-headers, API Request
Headers>>.
<4> The POST URL. You can copy and paste the URL for any report from the Kibana UI.
<1> The required `POST` method.
<2> The user credentials for a user with permission to access {kib} and {report-features}.
<3> The required `kbn-xsrf` header for all `POST` requests to {kib}. For more information, refer to <<api-request-headers, API Request Headers>>.
<4> The POST URL. You can copy and paste the URL for any report.
Here is an example response for a successfully queued report:
An example response for a successfully queued report:
[source,json]
---------------------------------------------------------
@ -45,6 +38,5 @@ Here is an example response for a successfully queued report:
---------------------------------------------------------
// CONSOLE
<1> The relative path on the Kibana host for downloading the report.
<2> (Not included in the example) Internal representation of the reporting job, as
found in the `.reporting-*` index.
<1> The relative path on the {kib} host for downloading the report.
<2> (Not included in the example) Internal representation of the reporting job, as found in the `.reporting-*` index.

36
docs/user/reporting/watch-example.asciidoc
View file

@ -1,10 +1,4 @@
To automatically generate reports with a watch, you need to configure
{watcher} to trust the {kib} server’s certificate. For more information,
see {kibana-ref}/secure-reporting.html[Securing Reporting].
To configure a watch to email reports, you use the `reporting` attachment type
in an `email` action. For more information, see
{ref}/actions-email.html#configuring-email[Configuring email accounts].
To configure a watch to email reports, use the `reporting` attachment type in an `email` action. For more information, refer to {ref}/actions-email.html#configuring-email[Configuring email accounts].
For example, the following watch generates a PDF report and emails the report every hour:
@ -44,28 +38,18 @@ PUT _watcher/watch/error_report
---------------------------------------------------------
// CONSOLE
<1> You must configure at least one email account to enable Watcher to send email.
For more information, see
{ref}/actions-email.html#configuring-email[Configuring email accounts].
<2> This is an example POST URL. You can copy and paste the URL for any
report from the Kibana UI.
<3> Optional, default is 40
<4> Optional, default is 15s
<5> Provide user credentials for a user with permission to access Kibana and
the {report-features}.
//For more information, see <<secure-reporting>>.
//<<reporting-app-users, Setting up a Reporting Role>>.
<1> Configure at least one email account to enable Watcher to send email. For more information, refer to {ref}/actions-email.html#configuring-email[Configuring email accounts].
<2> An example POST URL. You can copy and paste the URL for any report.
<3> Optional, default is `40`.
<4> Optional, default is `15s`.
<5> User credentials for a user with permission to access {kib} and the {report-features}. For more information, refer to <<secure-reporting>>.
[NOTE]
====
Reporting is integrated with Watcher only as an email attachment type.
*Reporting* is integrated with Watcher only as an email attachment type.
The report Generation URL might contain date-math expressions
that cause the watch to fail with a `parse_exception`.
Remove curly braces `{` `}` from date-math expressions and
URL-encode characters to avoid this.
For example: `...(range:(%27@timestamp%27:(gte:now-15m%2Fd,lte:now%2Fd))))...`
The report generation URL might contain date-math expressions that cause the watch to fail with a `parse_exception`. To avoid a failed watch, remove curly braces `{` `}` from date-math expressions and URL-encode characters.
For example, `...(range:(%27@timestamp%27:(gte:now-15m%2Fd,lte:now%2Fd))))...`
For more information about configuring watches, see
{ref}/how-watcher-works.html[How Watcher works].
For more information about configuring watches, refer to {ref}/how-watcher-works.html[How Watcher works].
====

55
docs/user/security/authentication/index.asciidoc
View file

@ -4,6 +4,8 @@
++++
<titleabbrev>Authentication</titleabbrev>
++++
:keywords: administrator, concept, security, authentication
:description: A list of the supported authentication mechanisms in {kib}.
{kib} supports the following authentication mechanisms:
@ -16,6 +18,8 @@
- <<kerberos>>
- <<anonymous-authentication>>
- <<http-authentication>>
- <<embedded-content-authentication>>
For an introduction to {kib}'s security features, including the login process, refer to <<tutorial-secure-access-to-kibana>>.
@ -395,17 +399,7 @@ xpack.security.authc.providers:
One of the most popular use cases for anonymous access is when you embed {kib} into other applications and don't want to force your users to log in to view it.
If you configured {kib} to use anonymous access as the sole authentication mechanism, you don't need to do anything special while embedding {kib}.
If you have multiple authentication providers enabled, and you want to automatically log in anonymous users when embedding dashboards and visualizations:
. Open the main menu, then click *Dashboard* or *Visualize Library*.
. Open then dashboard or visualization you want to embed.
. Open the *Share* menu, then click *Embed code > Public URL*.
+
You can also use *Public URL* when you're generating permanent links to dashboards, visualizations, and saved searches.
+
NOTE: *Public URL* is available only when anonymous access is configured and your anonymous service account has privileges to access what you want to embed or share.
+
For more information, refer to <<embedding, Embed {kib} content in a web page>>.
For information on how to embed, refer to <<embedding, Embed {kib} content in a web page>>.
[float]
[[anonymous-access-session]]
@ -437,3 +431,42 @@ xpack.security.authc.http.schemes: [apikey, basic, something-custom]
--------------------------------------------------------------------------------
With this configuration, you can send requests to {kib} with the `Authorization` header using `ApiKey`, `Basic` or `Something-Custom` HTTP schemes (case insensitive). Under the hood, {kib} relays this header to {es}, then {es} authenticates the request using the credentials in the header.
[float]
[[embedded-content-authentication]]
==== Embedded content authentication
Once you create a dashboard or a visualization, you might want to share it with your colleagues or friends. The easiest way to do this is to share a direct link to your dashboard or visualization. However, some users might not have access to your {kib}. With the {kib} embedding functionality, you can display the content you created in {kib} to an internal company website or a personal web page.
[[embedding-cookies]]
To minimize security risk, embedding with iframes requires careful consideration. By default, modern web browsers enforce the
https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy[same-origin policy] to restrict the behavior of framed pages. When
{stack-security-features} are enabled on your cluster, make sure the browsers can transmit session cookies to a {kib} server. The setting you need to be aware of is <<xpack-security-sameSiteCookies, `xpack.security.sameSiteCookies`>>. To support modern browsers, you must set it to `None`:
[source,yaml]
--
xpack.security.sameSiteCookies: "None"
--
For more information about possible values and implications, refer to <<xpack-security-sameSiteCookies, xpack.security.sameSiteCookies>>.
For more information about iframe and cookies, refer to https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe[iframe] and https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite[SameSite cookies].
If you're embedding {kib} in a website that supports Single Sign-On with SAML, OpenID Connect, Kerberos, or PKI, it's highly advisable to configure {kib} as a part of the Single Sign-On setup. Operating in a single and properly configured security domain provides you with the most secure and seamless user experience.
If you have multiple authentication providers enabled, and you want to automatically log in anonymous users when embedding anything other than dashboards and visualizations, then you will need to add the `auth_provider_hint=<anonymous-provider-name>` query string parameter to the {kib} URL that you're embedding.
For example, if you craft the iframe code to embed {kib}, it might look like this:
```html
<iframe src="https://localhost:5601/app/monitoring#/elasticsearch/nodes?embed=true&_g=(....)" height="600" width="800"></iframe>
```
To make this iframe leverage anonymous access automatically, you will need to modify a link to {kib} in the `src` iframe attribute to look like this:
```html
<iframe src="https://localhost:5601/app/monitoring?auth_provider_hint=anonymous1#/elasticsearch/nodes?embed=true&_g=(....)" height="600" width="800"></iframe>
```
NOTE: `auth_provider_hint` query string parameter goes *before* the hash URL fragment.
For more information on how to embed, refer to <<embedding, Embed {kib} content in a web page>>.

213
docs/user/security/reporting.asciidoc
View file

@ -1,213 +0,0 @@
[role="xpack"]
[[secure-reporting]]
=== Reporting and security
Reporting operates by creating and updating documents in {es} in response to
user actions in {kib}.
To use {report-features} with {security-features} enabled, you need to
<<using-kibana-with-security,configure security in {kib}>>.
If you are automatically generating reports with
{ref}/xpack-alerting.html[{watcher}], you also need to configure {watcher}
to trust the {kib} server's certificate.
////
For more information, see
<<securing-reporting>>.
////
[[reporting-app-users]]
Access to reporting features is limited to privileged users. In older versions of Kibana, you could only grant
users the privilege by assigning them the `reporting_user` role in Elasticsearch. In 7.14 and above, you have
the option to create your own roles that grant access to reporting features using <<kibana-privileges, {kib} privileges>>.
It is recommended that you set `xpack.reporting.roles.enabled: false` in your kibana.yml to begin using Kibana
privileges. This will allow users to only see Reporting widgets in applications when they have privilege to use
them.
[NOTE]
============================================================================
The default value of `xpack.reporting.roles.enabled` is `true` for 7.x versions of Kibana. To migrate users to the
new method of securing access to *Reporting*, you must explicitly set `xpack.reporting.roles.enabled: false` in
`kibana.yml`. In the next major version of Kibana, having this set to `false` will be the only valid configuration.
============================================================================
This document discusses how to create a role that grants access to reporting features using the new method of
Kibana application privileges.
[float]
[[reporting-roles-management-ui]]
=== Create the role in the `native` realm
To create roles, use the *Roles* UI or <<reporting-roles-user-api, user API>>. This example shows how to
create a role that grants reporting feature privileges in {kib} applications.
. Open the main menu, then click *Stack Management > Roles*.
. Click *Create role*, then give the role a name, for example, `custom_reporting_user`.
. Specify the indices and privileges.
+
Access to data is an index-level privilege, so in *Create role*,
add a line for each index that contains the data for the report and give each
index `read` and `view_index_metadata` privileges.
For more information, see {ref}/security-privileges.html[Security privileges].
+
[role="screenshot"]
image::user/security/images/reporting-privileges-example.png["Reporting privileges"]
. Add space privileges for the {kib} applications that allow access to the reporting options.
+
To allow users to create CSV reports in *Discover*, or PDF reports in *Canvas*,
*Visualize Library*, and *Dashboard*, click *Add Kibana privilege* for each application,
then select the privileges to generate
reports. For example, select *All* privileges for all features, or *Customize* to grant
the privilege to generate reports for only specific applications.
+
[role="screenshot"]
image::user/security/images/reporting-custom-role.png["Reporting custom role"]
+
[NOTE]
============================================================================
Granting users access to reporting features in any application also grants them access to manage their reports in *Stack Management > Reporting*.
============================================================================
+
. Save your new role.
. Open the main menu, then click *Stack Management > Users*, add a new user, and assign the user
your new `custom_reporting_user` role.
[float]
[[reporting-roles-user-api]]
==== With the user API
This example uses the {ref}/security-api-put-role.html[role API] to create a role that
grants the privilege to generate reports in *Canvas*, *Discover*, *Visualize Library*, and *Dashboard*.
This role is meant to be granted to users in combination with other roles that grant read access
to the data in {es}, and at least read access in the applications
where they'll generate reports.
[source, sh]
---------------------------------------------------------------
POST /_security/role/custom_reporting_user
{
metadata: {},
elasticsearch: { cluster: [], indices: [], run_as: [] },
kibana: [
{
base: [],
feature: {
dashboard: [
'generate_report', <1>
'download_csv_report' <2>
],
discover: ['generate_report'], <3>
canvas: ['generate_report'], <4>
visualize: ['generate_report'], <5>
},
spaces: ['*'],
}
]
}
---------------------------------------------------------------
// CONSOLE
<1> Grants access to generate PNG and PDF reports in *Dashboard*.
<2> Grants access to download CSV files from saved search panels in *Dashboard*.
<3> Grants access to generate CSV reports from saved searches in *Discover*.
<4> Grants access to generate PDF reports in *Canvas*.
<5> Grants access to generate PNG and PDF reports in *Visualize Library*.
[float]
=== When using an external provider
If you are using an external identity provider, such as
LDAP or Active Directory, you can either assign
roles on a per user basis, or assign roles to groups of users. By default, role
mappings are configured in
{ref}/mapping-roles.html[`config/role_mapping.yml`].
For example, the following snippet assigns the user named Bill Murray the
`kibana_admin` and `reporting_user` roles:
[source,yaml]
--------------------------------------------------------------------------------
kibana_admin:
- "cn=Bill Murray,dc=example,dc=com"
reporting_user:
- "cn=Bill Murray,dc=example,dc=com"
--------------------------------------------------------------------------------
[float]
=== With a custom index
If you are using a custom index,
the `xpack.reporting.index` setting should begin
with `.reporting-*`. The default {kib} system user has
`all` privileges against the `.reporting-*` pattern of indices.
[source,js]
xpack.reporting.index: '.reporting-custom-index'
If you use a different pattern for the `xpack.reporting.index` setting,
you must create a custom `kibana_system` user with appropriate access to the index, similar
to the following:
. Open the main menu, then click *Stack Management > Roles*.
. Click *Create role*, then name the role `custom-reporting-user`.
. Specify the custom index and assign it the `all` index privilege.
. Open the main menu, then click *Stack Management > Users* and create a new user with
the `kibana_system` role and the `custom-reporting-user` role.
. Configure {kib} to use the new account:
[source,js]
elasticsearch.username: 'custom_kibana_system'
[NOTE]
============================================================================
Setting a custom index for *Reporting* is not supported in the next major version of Kibana.
============================================================================
[role="xpack"]
[[securing-reporting]]
=== Secure the reporting endpoints
In a production environment, you should restrict access to
the reporting endpoints to authorized users. This requires that you:
. 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's 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 the permissions
necessary to use {kib} and {report-features}. For more information, see
<<secure-reporting>>.
Once you've enabled SSL for {kib}, all requests to the reporting endpoints
must include valid credentials. For example, see the following page which
includes a watch that submits requests as the built-in `elastic` user:
<<automating-report-generation>>.
For more information about configuring watches, see
{ref}/how-watcher-works.html[How {watcher} works].

9
docs/user/setup.asciidoc
View file

@ -60,4 +60,11 @@ include::{kib-repo-dir}/setup/connect-to-elasticsearch.asciidoc[]
include::{kib-repo-dir}/setup/upgrade.asciidoc[]
include::{kib-repo-dir}/setup/embedding.asciidoc[]
include::security/securing-kibana.asciidoc[]
include::{kib-repo-dir}/setup/configuring-reporting.asciidoc[]
include::monitoring/configuring-monitoring.asciidoc[leveloffset=+1]
include::monitoring/monitoring-metricbeat.asciidoc[leveloffset=+2]
include::monitoring/viewing-metrics.asciidoc[leveloffset=+2]
include::monitoring/monitoring-kibana.asciidoc[leveloffset=+2]