diff --git a/docs/settings/reporting-settings.asciidoc b/docs/settings/reporting-settings.asciidoc index 2bd9a5b315d08..5669412364395 100644 --- a/docs/settings/reporting-settings.asciidoc +++ b/docs/settings/reporting-settings.asciidoc @@ -1,4 +1,4 @@ -[role="xpack"] +role="xpack"] [[reporting-settings-kb]] === Reporting settings in {kib} ++++ @@ -11,18 +11,27 @@ You can configure `xpack.reporting` settings in your `kibana.yml` to: * <> * <> -* <> * <> * <> * <> * <> +* <> [float] [[general-reporting-settings]] ==== Enable reporting [[xpack-enable-reporting]]`xpack.reporting.enabled` {ess-icon}:: -When `true`, enables the {report-features}. The {report-features} are automatically enabled in {kib}. The default is `true`. +When `true`, enables the {report-features}. Set this to `false` to disable {report-features} entirely. The default is `true`. + +[NOTE] +============ +Disabling the {report-features} is discouraged. If you need to turn off the ability to generate reports, +configure the roles and spaces in the <>. + +If needed, you can also prevent a {kib} instance from claiming reporting work by setting +<>. +============ [float] [[encryption-keys]] @@ -46,39 +55,6 @@ The static encryption key for reporting. Use an alphanumeric text string that is xpack.reporting.encryptionKey: "something_secret" -------------------------------------------------------------------------------- -[float] -[[reporting-kibana-server-settings]] -==== {kib} server settings - -Reporting opens the {kib} web interface in a server process to generate -screenshots of {kib} visualizations. In most cases, the default settings -work and you don't need to configure the {report-features} to communicate with {kib}. - -If your {kib} instance requires a reverse proxy (such as NGINX, Apache, etc.) for -access, because of rewrite rules or special headers being added by the proxy, -you must configure the `xpack.reporting.kibanaServer` settings to make -the headless browser process connect to the proxy. - -[NOTE] -============ -If a reverse proxy carries encrypted traffic from user -clients back to a {kib} server, the proxy port, protocol, and hostname -in `xpack.reporting.kibanaServer` must be valid for the encryption that the Reporting -browser receives. Encrypted communications fail if there are -mismatches in the host information between the request and the certificate on the server. - -Configuring the `xpack.reporting.kibanaServer` settings to point to a -proxy host requires that the {kib} server has network access to the proxy. -============ - -`xpack.reporting.kibanaServer.port`:: The port for accessing {kib}, if different from the <> 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 <> value. - [float] [[reporting-job-queue-settings]] ==== Background job settings @@ -90,8 +66,11 @@ reports, you might need to change the following settings. `xpack.reporting.queue.indexInterval`:: How often the index that stores reporting jobs rolls over to a new index. Valid values are `year`, `month`, `week`, `day`, and `hour`. Defaults to `week`. -`xpack.reporting.queue.pollEnabled` {ess-icon}:: -Set to `true` (default) to enable the {kib} instance to poll the index for pending jobs and claim them for execution. Setting this to `false` allows the {kib} instance to only add new jobs to the reporting queue, list jobs, and provide the downloads to completed report through the UI. +[[xpack-reportingQueue-pollEnabled]] `xpack.reporting.queue.pollEnabled` {ess-icon}:: +When `true`, enables the {kib} instance to poll {es} for pending jobs and claim them for +execution. When `false`, allows the {kib} instance to only add new jobs to the reporting queue, list +jobs, and provide the downloads to completed reports through the UI. This requires a deployment where at least +one other {kib} instance in the Elastic cluster has this setting to `true`. The default is `true`. NOTE: Running multiple instances of {kib} in a cluster for load balancing of reporting requires identical values for <> and, if @@ -258,7 +237,7 @@ With Security enabled, Reporting has two forms of access control: each user can [NOTE] ============================================================================ -The `xpack.reporting.roles` settings are for a deprecated system of access control in Reporting. It does not allow API Keys to generate reports, and it doesn't allow {kib} application privileges. We recommend you explicitly turn off reporting's deprecated access control feature by adding `xpack.reporting.roles.enabled: false` in kibana.yml. This will enable you to create custom roles that provide application privileges for reporting, as described in <>. +The `xpack.reporting.roles` settings are for a deprecated system of access control in Reporting. Turning off this feature allows API Keys to generate reports, and allows reporting access through {kib} application privileges. We recommend you explicitly turn off reporting's deprecated access control feature by adding `xpack.reporting.roles.enabled: false` in kibana.yml. This will enable you to create custom roles that provide application privileges for reporting, as described in <>. ============================================================================ [[xpack-reporting-roles-enabled]] `xpack.reporting.roles.enabled`:: @@ -266,3 +245,26 @@ deprecated:[7.14.0,The default for this setting will be `false` in an upcoming v `xpack.reporting.roles.allow`:: deprecated:[7.14.0] In addition to superusers, specifies the roles that can generate reports using the {ref}/security-api.html#security-role-apis[{es} role management APIs]. Requires `xpack.reporting.roles.enabled` to be `true`. Defaults to `[ "reporting_user" ]`. + +[float] +[[reporting-kibana-server-settings]] +==== {kib} server settings + +To generate screenshots for PNG and PDF reports, Reporting opens the {kib} web interface using a local +connection on the server. In most cases, using a local connection to the {kib} server presents no issue. If +you prefer the headless browser to connect to {kib} using a specific hostname, there are a number of +settings that allow the headless browser to connect to {kib} through a proxy, rather than directly. + +[NOTE] +============ +The `xpack.reporting.kibanaServer` settings are optional. Take caution when editing these settings. Adding +these settings can cause the {report-features} to fail. If report fail, +inspect the server logs. The full {kib} URL that Reporting is attempting to + open is logged during report execution. +============ + +`xpack.reporting.kibanaServer.port`:: The port for accessing {kib}.port`>> value. + +`xpack.reporting.kibanaServer.protocol`:: The protocol for accessing {kib}, typically `http` or `https`. + +[[xpack-kibanaServer-hostname]] `xpack.reporting.kibanaServer.hostname`:: The hostname for accessing {kib}. diff --git a/docs/setup/configuring-reporting.asciidoc b/docs/setup/configuring-reporting.asciidoc index ca6bf19f404e5..0b2fe48670777 100644 --- a/docs/setup/configuring-reporting.asciidoc +++ b/docs/setup/configuring-reporting.asciidoc @@ -41,7 +41,7 @@ To troubleshoot the problem, start the {kib} server with environment variables t [float] [[grant-user-access]] === Grant users access to reporting -When security is enabled, you grant users access to generate reports with <>, which allow you to create custom roles that control the spaces and applications where users generate reports. +When security is enabled, you grant users access to {report-features} with <>, which allow you to create custom roles that control the spaces and applications where users generate reports. . Enable application privileges in Reporting. To enable, turn off the default user access control features in `kibana.yml`: + @@ -60,7 +60,6 @@ NOTE: If you use the default settings, you can still create a custom role that g . Specify the role settings. - .. Enter the *Role name*. For example, `custom_reporting_user`. .. Specify the *Indices* and *Privileges*. @@ -77,9 +76,14 @@ For more information, refer to {ref}/security-privileges.html[Security privilege .. Click *Customize*, then click *Analytics*. -.. Next to the applications you want to grant reporting privileges, click *All*. +.. Next each application listed, click *All* or click *Read*. You will need to enable the *Customize sub-feature +privileges* checkbox to grant reporting privileges if you select *Read*. ++ +If you’ve followed the example above, you should end up on a screen defining your customized privileges that looks like this: +[role="screenshot"] +image::user/reporting/images/kibana-privileges-with-reporting.png["Kibana privileges with Reporting options"] + -If the *Reporting* option is unavailable, contact your administrator, or <>. +NOTE: If *Reporting* options for application features are not available, contact your administrator, or <>. .. Click *Add {kib} privilege*. diff --git a/docs/user/reporting/images/kibana-privileges-with-reporting.png b/docs/user/reporting/images/kibana-privileges-with-reporting.png new file mode 100644 index 0000000000000..0675d893e4af9 Binary files /dev/null and b/docs/user/reporting/images/kibana-privileges-with-reporting.png differ