SOLR-12497: Add documentation for Hadoop credential provider-based keystore/truststore

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
 ----------------------
 

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

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

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;

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