From 9caac7a9dc1822ccbe43519551dc6bca16268d35 Mon Sep 17 00:00:00 2001 From: Matthew Bargar Date: Wed, 30 Nov 2016 17:26:57 -0500 Subject: [PATCH] Add docs on all available console server config options --- docs/console.asciidoc | 2 +- docs/console/configuring-console.asciidoc | 57 +++++++++++++++++++++++ docs/console/disabling-console.asciidoc | 10 ---- docs/setup/settings.asciidoc | 4 ++ 4 files changed, 62 insertions(+), 11 deletions(-) create mode 100644 docs/console/configuring-console.asciidoc delete mode 100644 docs/console/disabling-console.asciidoc diff --git a/docs/console.asciidoc b/docs/console.asciidoc index 11d28df26531f..895a632b45d06 100644 --- a/docs/console.asciidoc +++ b/docs/console.asciidoc @@ -83,4 +83,4 @@ include::console/history.asciidoc[] include::console/settings.asciidoc[] -include::console/disabling-console.asciidoc[] +include::console/configuring-console.asciidoc[] diff --git a/docs/console/configuring-console.asciidoc b/docs/console/configuring-console.asciidoc new file mode 100644 index 0000000000000..deb9d6e190d1b --- /dev/null +++ b/docs/console/configuring-console.asciidoc @@ -0,0 +1,57 @@ +[[configuring-console]] +== Configuring Console + +You can add the following options in the `config/kibana.yml` file: + +`console.enabled`:: *Default: true* Set to false to disable Console. Toggling this will cause the server to regenerate assets on the next startup, which may cause a delay before pages start being served. + +`console.proxyFilter`:: *Default: `.*`* A list of regular expressions that are used to validate any outgoing request from Console. If none + of these match, the request will be rejected. See <> for more details. + +`console.proxyConfig`:: A list of configuration options that are based on the proxy target. Use this to set custom timeouts or SSL settings for specific hosts. This is done by defining a set of `match` criteria using wildcards/globs which will be checked against each request. The configuration from all matching rules will then be merged together to configure the proxy used for that request. ++ +The valid match keys are `match.protocol`, `match.host`, `match.port`, and `match.path`. All of these keys default to `*`, which means they will match any value. ++ +Example: ++ +[source,yaml] +-------- +console.proxyConfig: + - match: + host: "*.internal.org" # allow any host that ends in .internal.org + port: "{9200..9299}" # allow any port from 9200-9299 + + ssl: + ca: "/opt/certs/internal.ca" + # "key" and "cert" are also valid options here + + - match: + protocol: "https" + + ssl: + verify: false # allows any certificate to be used, even self-signed certs + + # since this rule has no "match" section it matches everything + - timeout: 180000 # 3 minutes +-------- + +[[securing-console]] +=== Securing Console + +Console is meant to be used as a local development tool. As such, it will send requests to any host & port combination, +just as a local curl command would. To overcome the CORS limitations enforced by browsers, Console's Node.js backend +serves as a proxy to send requests on behalf of the browser. However, if put on a server and exposed to the internet +this can become a security risk. In those cases, we highly recommend you lock down the proxy by setting the +`console.proxyFilter` setting. The setting accepts a list of regular expressions that are evaluated against each URL + the proxy is requested to retrieve. If none of the regular expressions match the proxy will reject the request. + +Here is an example configuration the only allows Console to connect to localhost: + +[source,yaml] +-------- +console.proxyFilter: + - ^https?://(localhost|127\.0\.0\.1|\[::0\]).* +-------- + +You will need to restart Kibana for these changes to take effect. + diff --git a/docs/console/disabling-console.asciidoc b/docs/console/disabling-console.asciidoc deleted file mode 100644 index 7aa1fa56e77f7..0000000000000 --- a/docs/console/disabling-console.asciidoc +++ /dev/null @@ -1,10 +0,0 @@ -[[disabling-console]] -== Disable Console - -If the users of Kibana have no requirements or need to access any of the Console functionality, it can -be disabled completely and not even show up as an available app by setting the `console.enabled` Kibana server setting to `false`: - -[source,yaml] --------- -console.enabled: false --------- diff --git a/docs/setup/settings.asciidoc b/docs/setup/settings.asciidoc index 4cdc402e562c5..bf31ba692dec9 100644 --- a/docs/setup/settings.asciidoc +++ b/docs/setup/settings.asciidoc @@ -65,3 +65,7 @@ The minimum value is 100. `status.allowAnonymous`:: *Default: false* If authentication is enabled, setting this to `true` allows unauthenticated users to access the Kibana server status API and status page. `console.enabled`:: *Default: true* Set to false to disable Console. Toggling this will cause the server to regenerate assets on the next startup, which may cause a delay before pages start being served. +`console.proxyFilter`:: *Default: `.*`* A list of regular expressions that are used to validate any outgoing request from Console. If none of these match, the request will be rejected. +`console.proxyConfig`:: A list of configuration options that are based on the proxy target. Use this to set custom timeouts or SSL settings for specific hosts. This is done by defining a set of `match` criteria using wildcards/globs which will be checked against each request. The configuration from all matching rules will then be merged together to configure the proxy used for that request. ++ +The valid match keys are `match.protocol`, `match.host`, `match.port`, and `match.path`. All of these keys default to `*`, which means they will match any value. See <> for an example.