From 4a4bbff4058904a3af938cba0937c51f67b614b6 Mon Sep 17 00:00:00 2001 From: Morris Schreibman Date: Wed, 20 Jun 2018 18:56:15 +0300 Subject: [PATCH 1/3] Clarify difference between public and secure client settings in discussion of S3 client configuration. See Support Ticket 00231008 : https://elastic.my.salesforce.com/ui/support/servicedesk/ServiceDeskPage#/5006100000M5DFG and also https://github.com/elastic/support-dev-help-elasticsearch/issues/737. The original discussion of client settings was carried over from doc versions before there were sensitive client settings. The existing language in the documentation can make customers believe that any client setting can be added to elasticsearch.yml. The new wording that I am proposing above makes it clear from the beginning of the discussion that there are now 2 classes of client settings for S3 snapshots: public and secure, and that each class must be specified differently. --- docs/plugins/repository-s3.asciidoc | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/docs/plugins/repository-s3.asciidoc b/docs/plugins/repository-s3.asciidoc index 6701d53c24047..a112ce27f8223 100644 --- a/docs/plugins/repository-s3.asciidoc +++ b/docs/plugins/repository-s3.asciidoc @@ -34,10 +34,7 @@ PUT _snapshot/my_s3_repository [[repository-s3-client]] ==== Client Settings -The client used to connect to S3 has a number of settings available. Client setting names are of -the form `s3.client.CLIENT_NAME.SETTING_NAME` and specified inside `elasticsearch.yml`. The -default client name looked up by a `s3` repository is called `default`, but can be customized -with the repository setting `client`. For example: +The client used to connect to S3 has a number of settings available. Settings are either "public" or "secure", Public client settings may be specified in the `elasticsearch.yml` file and are of the form `s3.client.CLIENT_NAME.SETTING_NAME`. The default client name looked up by a `s3` repository is called `default`, but can be customized with the repository setting `client`. For example: [source,js] ---- @@ -53,8 +50,7 @@ PUT _snapshot/my_s3_repository // CONSOLE // TEST[skip:we don't have s3 setup while testing this] -Some settings are sensitive and must be stored in the {ref}/secure-settings.html[elasticsearch keystore]. -For example, to use explicit AWS access keys: +`Secure` settings are sensitive and must be stored in the {ref}/secure-settings.html[elasticsearch keystore].For example, to use explicit AWS access keys: [source,sh] ---- @@ -63,7 +59,7 @@ bin/elasticsearch-keystore add s3.client.default.secret_key ---- The following are the available client settings. Those that must be stored in the keystore -are marked as `Secure`. +are marked as `Secure`; all other settings are public and may be included in the `elasticsearch.yml` file. `access_key`:: From 108ee3b00f77f601b22cff3901cd0a845374b122 Mon Sep 17 00:00:00 2001 From: lcawl Date: Fri, 4 Jan 2019 11:51:12 -0800 Subject: [PATCH 2/3] [DOCS] Edits the client settings --- docs/plugins/repository-s3.asciidoc | 33 ++++++++++++++++++----------- 1 file changed, 21 insertions(+), 12 deletions(-) diff --git a/docs/plugins/repository-s3.asciidoc b/docs/plugins/repository-s3.asciidoc index a112ce27f8223..8e7f095661c21 100644 --- a/docs/plugins/repository-s3.asciidoc +++ b/docs/plugins/repository-s3.asciidoc @@ -34,7 +34,10 @@ PUT _snapshot/my_s3_repository [[repository-s3-client]] ==== Client Settings -The client used to connect to S3 has a number of settings available. Settings are either "public" or "secure", Public client settings may be specified in the `elasticsearch.yml` file and are of the form `s3.client.CLIENT_NAME.SETTING_NAME`. The default client name looked up by a `s3` repository is called `default`, but can be customized with the repository setting `client`. For example: +The client that you use to connect to S3 has a number of settings available. The +settings have the form `s3.client.CLIENT_NAME.SETTING_NAME`. The default client +name that is looked up by an `s3` repository is `default`. It can be modified +using the <> `client`. For example: [source,js] ---- @@ -50,7 +53,12 @@ PUT _snapshot/my_s3_repository // CONSOLE // TEST[skip:we don't have s3 setup while testing this] -`Secure` settings are sensitive and must be stored in the {ref}/secure-settings.html[elasticsearch keystore].For example, to use explicit AWS access keys: +Most client settings can be added to the `elasticsearch.yml` configuration file +with the exception of the secure settings, which you add to the {es} keystore. +For more information about creating and updating the {es} keystore, see +{ref}/secure-settings.html[Secure settings]. + +For example, to use explicit AWS access keys: [source,sh] ---- @@ -58,16 +66,17 @@ bin/elasticsearch-keystore add s3.client.default.access_key bin/elasticsearch-keystore add s3.client.default.secret_key ---- -The following are the available client settings. Those that must be stored in the keystore -are marked as `Secure`; all other settings are public and may be included in the `elasticsearch.yml` file. +The following list contains the available client settings. Those that must be +stored in the keystore are marked as "secure"; all other settings can be +included in the `elasticsearch.yml` file. -`access_key`:: +`access_key` ({ref}/secure-settings.html[Secure]):: - An s3 access key. The `secret_key` setting must also be specified. (Secure) + An s3 access key. The `secret_key` setting must also be specified. -`secret_key`:: +`secret_key` ({ref}/secure-settings.html[Secure]):: - An s3 secret key. The `access_key` setting must also be specified. (Secure) + An s3 secret key. The `access_key` setting must also be specified. `endpoint`:: @@ -88,13 +97,13 @@ are marked as `Secure`; all other settings are public and may be included in the The port of a proxy to connect to s3 through. -`proxy.username`:: +`proxy.username` ({ref}/secure-settings.html[Secure]):: - The username to connect to the `proxy.host` with. (Secure) + The username to connect to the `proxy.host` with. -`proxy.password`:: +`proxy.password` ({ref}/secure-settings.html[Secure]):: - The password to connect to the `proxy.host` with. (Secure) + The password to connect to the `proxy.host` with. `read_timeout`:: From c5440df806904abd916a460362a385bb77bbaccb Mon Sep 17 00:00:00 2001 From: lcawl Date: Tue, 8 Jan 2019 16:00:36 -0800 Subject: [PATCH 3/3] [DOCS] Clarifies keystore vs config file --- docs/plugins/repository-s3.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/plugins/repository-s3.asciidoc b/docs/plugins/repository-s3.asciidoc index 8e7f095661c21..44af56b886c63 100644 --- a/docs/plugins/repository-s3.asciidoc +++ b/docs/plugins/repository-s3.asciidoc @@ -67,8 +67,8 @@ bin/elasticsearch-keystore add s3.client.default.secret_key ---- The following list contains the available client settings. Those that must be -stored in the keystore are marked as "secure"; all other settings can be -included in the `elasticsearch.yml` file. +stored in the keystore are marked as "secure"; the other settings belong in the +`elasticsearch.yml` file. `access_key` ({ref}/secure-settings.html[Secure])::