From df5540acc99fe287758433701108303fedb2c5b6 Mon Sep 17 00:00:00 2001
From: Cassandra Targett <ctargett@apache.org>
Date: Wed, 14 Nov 2018 18:44:02 -0600
Subject: [PATCH] SOLR-12497: Add documentation for Hadoop credential
 provider-based keystore/truststore

---
 solr/CHANGES.txt                          |  3 +
 solr/bin/solr.in.cmd                      |  1 +
 solr/bin/solr.in.sh                       |  1 +
 solr/solr-ref-guide/src/css/ref-guide.css |  4 +-
 solr/solr-ref-guide/src/enabling-ssl.adoc | 72 ++++++++++++++++++++++-
 5 files changed, 77 insertions(+), 4 deletions(-)

diff --git a/solr/CHANGES.txt b/solr/CHANGES.txt
index 47eb3d1bb28..67e649ea328 100644
--- a/solr/CHANGES.txt
+++ b/solr/CHANGES.txt
@@ -263,6 +263,9 @@ Other Changes
 
 * SOLR-12600: Fix parameter names in Solr JSON documentation (Alexandre Rafalovitch)
 
+* SOLR-12497: Add documentation to use Hadoop credential provider-based keystore/trustsore.
+(Mano Kovacs, Cassandra Targett)
+
 Bug Fixes
 ----------------------
 
diff --git a/solr/bin/solr.in.cmd b/solr/bin/solr.in.cmd
index 86ad7084f10..4b86d25865f 100755
--- a/solr/bin/solr.in.cmd
+++ b/solr/bin/solr.in.cmd
@@ -135,6 +135,7 @@ REM * javax.net.ssl.keyStorePassword
 REM * javax.net.ssl.trustStorePassword
 REM More info: https://hadoop.apache.org/docs/current/hadoop-project-dist/hadoop-common/CredentialProviderAPI.html
 REM set SOLR_HADOOP_CREDENTIAL_PROVIDER_PATH=localjceks://file/home/solr/hadoop-credential-provider.jceks
+REM set SOLR_OPTS=" -Dsolr.ssl.credential.provider.chain=hadoop"
 
 REM Settings for authentication
 REM Please configure only one of SOLR_AUTHENTICATION_CLIENT_BUILDER or SOLR_AUTH_TYPE parameters
diff --git a/solr/bin/solr.in.sh b/solr/bin/solr.in.sh
index 9b15beaa2db..af1cd7a02c2 100644
--- a/solr/bin/solr.in.sh
+++ b/solr/bin/solr.in.sh
@@ -152,6 +152,7 @@
 # * javax.net.ssl.trustStorePassword
 # More info: https://hadoop.apache.org/docs/current/hadoop-project-dist/hadoop-common/CredentialProviderAPI.html
 #SOLR_HADOOP_CREDENTIAL_PROVIDER_PATH=localjceks://file/home/solr/hadoop-credential-provider.jceks
+#SOLR_OPTS=" -Dsolr.ssl.credential.provider.chain=hadoop"
 
 # Settings for authentication
 # Please configure only one of SOLR_AUTHENTICATION_CLIENT_BUILDER or SOLR_AUTH_TYPE parameters
diff --git a/solr/solr-ref-guide/src/css/ref-guide.css b/solr/solr-ref-guide/src/css/ref-guide.css
index a8224a95f67..1005ab900a9 100644
--- a/solr/solr-ref-guide/src/css/ref-guide.css
+++ b/solr/solr-ref-guide/src/css/ref-guide.css
@@ -447,7 +447,6 @@ p.lead
 .exampleblock > .title,
 .hdlist > .title,
 .imageblock > .title,
-.imageblock > figcaption,
 .listingblock > .title,
 .literalblock > .title,
 .olist > .title,
@@ -460,7 +459,8 @@ p.lead
 .ulist > .title,
 .verseblock > .title,
 .videoblock > .title,
-table.tableblock > .title
+table.tableblock > .title,
+figcaption
 {
     margin-top: 0;
     margin-bottom: .25em;
diff --git a/solr/solr-ref-guide/src/enabling-ssl.adoc b/solr/solr-ref-guide/src/enabling-ssl.adoc
index 96262bd4e3e..cfb2da9b622 100644
--- a/solr/solr-ref-guide/src/enabling-ssl.adoc
+++ b/solr/solr-ref-guide/src/enabling-ssl.adoc
@@ -133,17 +133,85 @@ set SOLR_SSL_TRUST_STORE_TYPE=JKS
 
 Start Solr using the command shown below; by default clients will not be required to authenticate:
 
-.*nix command
+[.dynamic-tabs]
+--
+[example.tab-pane#single-unix]
+====
+[.tab-label]**nix Command*
 [source,bash]
 ----
 bin/solr -p 8984
 ----
+====
 
-.Windows command
+[example.tab-pane#single-windows]
+====
+[.tab-label]*Windows Command*
 [source,text]
 ----
 bin\solr.cmd -p 8984
 ----
+====
+--
+
+== Password Distribution via Hadoop Credential Store
+
+Solr supports reading keystore and truststore passwords from Hadoop credential store. This approach can be beneficial
+if password rotation and distribution is already handled by credential stores.
+
+Hadoop credential store can be used with Solr using the following two steps.
+
+=== Provide a Hadoop Credential Store
+Create a Hadoop credstore file and define the entries below with the actual keystore passwords.
+
+[source,text]
+----
+solr.jetty.keystore.password
+solr.jetty.truststore.password
+javax.net.ssl.keyStorePassword
+javax.net.ssl.trustStorePassword
+----
+
+Note that if the `javax.net.ssl.\*` configurations are not set, they will fallback to the corresponding `solr.jetty.*` configurations.
+
+=== Configure Solr to use Hadoop Credential Store
+
+Solr needs requires three parameters to be configured in order to use the credential store file for keystore passwords.
+
+`solr.ssl.credential.provider.chain`::
+The credential provider chain. This should be set to `hadoop`.
+
+`SOLR_HADOOP_CREDENTIAL_PROVIDER_PATH`::
+The path to the credential store file.
+
+`HADOOP_CREDSTORE_PASSWORD`::
+The password to the credential store.
+
+[.dynamic-tabs]
+--
+[example.tab-pane#credstore-unix]
+====
+[.tab-label]**nix Example*
+[source,text]
+----
+SOLR_OPTS=" -Dsolr.ssl.credential.provider.chain=hadoop"
+SOLR_HADOOP_CREDENTIAL_PROVIDER_PATH=localjceks://file/home/solr/hadoop-credential-provider.jceks
+HADOOP_CREDSTORE_PASSWORD="credStorePass123"
+----
+====
+
+[example.tab-pane#credstore-windows]
+=====
+[.tab-label]*Windows Example*
+[source,text]
+----
+set SOLR_OPTS=" -Dsolr.ssl.credential.provider.chain=hadoop"
+set SOLR_HADOOP_CREDENTIAL_PROVIDER_PATH=localjceks://file/home/solr/hadoop-credential-provider.jceks
+set HADOOP_CREDSTORE_PASSWORD="credStorePass123"
+----
+=====
+--
+
 
 == SSL with SolrCloud