You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucene.apache.org by ct...@apache.org on 2020/06/02 19:11:37 UTC
[lucene-solr] branch branch_8x updated: Ref Guide: Add docs for
updating urlscheme on existing collections; reorg page;
fix hover color on tabs
This is an automated email from the ASF dual-hosted git repository.
ctargett pushed a commit to branch branch_8x
in repository https://gitbox.apache.org/repos/asf/lucene-solr.git
The following commit(s) were added to refs/heads/branch_8x by this push:
new ec44271 Ref Guide: Add docs for updating urlscheme on existing collections; reorg page; fix hover color on tabs
ec44271 is described below
commit ec44271b8ef20b06305b7ca34b1f70a9e00ddd93
Author: Cassandra Targett <ca...@lucidworks.com>
AuthorDate: Tue Jun 2 14:09:44 2020 -0500
Ref Guide: Add docs for updating urlscheme on existing collections; reorg page; fix hover color on tabs
---
.../src/common-query-parameters.adoc | 4 +-
solr/solr-ref-guide/src/css/decoration.css | 2 +-
solr/solr-ref-guide/src/css/ref-guide.css | 6 +-
solr/solr-ref-guide/src/enabling-ssl.adoc | 238 ++++++++++-----------
4 files changed, 123 insertions(+), 127 deletions(-)
diff --git a/solr/solr-ref-guide/src/common-query-parameters.adoc b/solr/solr-ref-guide/src/common-query-parameters.adoc
index 594f513..1383b81 100644
--- a/solr/solr-ref-guide/src/common-query-parameters.adoc
+++ b/solr/solr-ref-guide/src/common-query-parameters.adoc
@@ -193,7 +193,7 @@ The default behavior is not to include debugging information.
== explainOther Parameter
-The `explainOther` parameter specifies a Lucene query in order to identify a set of documents. If this parameter is included and is set to a non-blank value, the query will return debugging information, along with the "explain info" of each document that matches the Lucene query, relative to the main query (which is specified by the q parameter). For example:
+The `explainOther` parameter specifies a Lucene query in order to identify a set of documents. If this parameter is included and is set to a non-blank value, the query will return debugging information, along with the "explain info" of each document that matches the Lucene query, relative to the main query (which is specified by the `q` parameter). For example:
[source,text]
----
@@ -371,7 +371,7 @@ More about approximate document counting and `minExactCount`:
* The documents returned in the response are guaranteed to be the docs with the top scores. This parameter will not make Solr skip documents that are to be returned in the response, it will only allow Solr to skip counting docs that, while they match the query, their score is low enough to not be in the top N.
* Providing `minExactCount` doesn't guarantee that Solr will use approximate hit counting (and thus, provide the speedup). Some types of queries, or other parameters (like if facets are requested) will require accurate counting. The value of `numFoundExact` indicates if the approximation was used or not.
* Approximate counting can only be used when sorting by `score desc` first (which is the default sort in Solr). Other fields can be used after `score desc`, but if any other type of sorting is used before score, then the approximation won't be applied.
-* When doing distributed queries across multiple shards, each shard will accurately count hits until `minExactCount` (which means the query could be hitting `numShards * minExactCount` docs and `numFound` in the response would still be accurate)
+* When doing distributed queries across multiple shards, each shard will accurately count hits until `minExactCount` (which means the query could be hitting `numShards * minExactCount` docs and `numFound` in the response would still be accurate)
For example:
[source,text]
diff --git a/solr/solr-ref-guide/src/css/decoration.css b/solr/solr-ref-guide/src/css/decoration.css
index 1c8d335..ff3a3e2 100644
--- a/solr/solr-ref-guide/src/css/decoration.css
+++ b/solr/solr-ref-guide/src/css/decoration.css
@@ -113,7 +113,7 @@ b.button:after
.nav-pills .nav-link.active:hover,
.nav-pills .nav-link.active:focus
{
- background-color: #FF833D;
+ background-color: #D9411E;
color: white;
}
diff --git a/solr/solr-ref-guide/src/css/ref-guide.css b/solr/solr-ref-guide/src/css/ref-guide.css
index 19edf0d..efac8a0 100644
--- a/solr/solr-ref-guide/src/css/ref-guide.css
+++ b/solr/solr-ref-guide/src/css/ref-guide.css
@@ -267,11 +267,7 @@ pre > code
font-weight: 400;
font-family: 'Inconsolata', monospace;
line-height: 1.45;
- white-space: pre-wrap;
-}
-
-table code {
- background-color: transparent;
+ white-space: pre-wrap;
}
a code {
diff --git a/solr/solr-ref-guide/src/enabling-ssl.adoc b/solr/solr-ref-guide/src/enabling-ssl.adoc
index 5840e3f..6d1be3b 100644
--- a/solr/solr-ref-guide/src/enabling-ssl.adoc
+++ b/solr/solr-ref-guide/src/enabling-ssl.adoc
@@ -16,27 +16,30 @@
// specific language governing permissions and limitations
// under the License.
-Solr can encrypt communications to and from clients, and between nodes in SolrCloud mode, with SSL.
+Solr can encrypt communications to and from clients and between nodes in SolrCloud mode with Secure Sockets Layer encryption (SSL).
This section describes enabling SSL using a self-signed certificate.
For background on SSL certificates and keys, see http://www.tldp.org/HOWTO/SSL-Certificates-HOWTO/.
-== Basic SSL Setup
+== Configuring Solr for SSL
=== Generate a Self-Signed Certificate and a Key
-To generate a self-signed certificate and a single key that will be used to authenticate both the server and the client, we'll use the JDK https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html[`keytool`] command and create a separate keystore. This keystore will also be used as a truststore below. It's possible to use the keystore that comes with the JDK for these purposes, and to use a separate truststore, but those options aren't covered here.
+To generate a self-signed certificate and a single key that will be used to authenticate both the server and the client, we'll use the JDK https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html[`keytool`] command and create a separate keystore.
+This keystore will also be used as a truststore below.
+It's possible to use the keystore that comes with the JDK for these purposes, and to use a separate truststore, but those options aren't covered here.
-Run the commands below in the `server/etc/` directory in the binary Solr distribution. It's assumed that you have the JDK `keytool` utility on your `PATH`, and that `openssl` is also on your `PATH`. See https://www.openssl.org/related/binaries.html for OpenSSL binaries for Windows and Solaris.
+Run the commands below in the `server/etc/` directory in the binary Solr distribution.
+It's assumed that you have the JDK `keytool` utility on your `PATH`, and that `openssl` is also on your `PATH`. See https://www.openssl.org/related/binaries.html for OpenSSL binaries for Windows and Solaris.
-The `-ext SAN=...` `keytool` option allows you to specify all the DNS names and/or IP addresses that will be allowed during hostname verification (but see below for how to skip hostname verification between Solr nodes so that you don't have to specify all hosts here).
+The `-ext SAN=...` `keytool` option allows you to specify all the DNS names and/or IP addresses that will be allowed during hostname verification if you choose to require it.
In addition to `localhost` and `127.0.0.1`, this example includes a LAN IP address `192.168.1.3` for the machine the Solr nodes will be running on:
-[source,bash]
+[source,terminal]
----
-keytool -genkeypair -alias solr-ssl -keyalg RSA -keysize 2048 -keypass secret -storepass secret -validity 9999 -keystore solr-ssl.keystore.p12 -storetype PKCS12 -ext SAN=DNS:localhost,IP:192.168.1.3,IP:127.0.0.1 -dname "CN=localhost, OU=Organizational Unit, O=Organization, L=Location, ST=State, C=Country"
+$ keytool -genkeypair -alias solr-ssl -keyalg RSA -keysize 2048 -keypass secret -storepass secret -validity 9999 -keystore solr-ssl.keystore.p12 -storetype PKCS12 -ext SAN=DNS:localhost,IP:192.168.1.3,IP:127.0.0.1 -dname "CN=localhost, OU=Organizational Unit, O=Organization, L=Location, ST=State, C=Country"
----
The above command will create a keystore file named `solr-ssl.keystore.p12` in the current directory.
@@ -45,25 +48,31 @@ The above command will create a keystore file named `solr-ssl.keystore.p12` in t
Convert the PKCS12 format keystore, including both the certificate and the key, into PEM format using the http://www.openssl.org[`openssl`] command:
-[source,bash]
+[source,terminal]
----
-openssl pkcs12 -in solr-ssl.keystore.p12 -out solr-ssl.pem
+$ openssl pkcs12 -in solr-ssl.keystore.p12 -out solr-ssl.pem
----
If you want to use curl on OS X Yosemite (10.10), you'll need to create a certificate-only version of the PEM format, as follows:
-[source,bash]
+[source,terminal]
----
-openssl pkcs12 -nokeys -in solr-ssl.keystore.p12 -out solr-ssl.cacert.pem
+$ openssl pkcs12 -nokeys -in solr-ssl.keystore.p12 -out solr-ssl.cacert.pem
----
=== Set Common SSL-Related System Properties
-The Solr Control Script is already setup to pass SSL-related Java system properties to the JVM. To activate the SSL settings, uncomment and update the set of properties beginning with SOLR_SSL_* in `bin/solr.in.sh`. (or `bin\solr.in.cmd` on Windows).
+The Solr Control Script is already setup to pass SSL-related Java system properties to the JVM.
+To activate the SSL settings, uncomment and update the set of properties beginning with `SOLR_SSL_*` in `bin/solr.in.sh` on *nix systems or `bin\solr.in.cmd` on Windows.
+
+[.dynamic-tabs]
+--
+[example.tab-pane#solr-in-sh]
+====
+[.tab-label]**nix (solr.in.sh)*
-NOTE: If you setup Solr as a service on Linux using the steps outlined in <<taking-solr-to-production.adoc#taking-solr-to-production,Taking Solr to Production>>, then make these changes in `/var/solr/solr.in.sh` instead.
+NOTE: If you setup Solr as a service on Linux using the steps outlined in <<taking-solr-to-production.adoc#taking-solr-to-production,Taking Solr to Production>>, then make these changes in `/var/solr/solr.in.sh`.
-.bin/solr.in.sh example SOLR_SSL_* configuration
[source,bash]
----
# Enables HTTPS. It is implicitly true if you set SOLR_SSL_KEY_STORE. Use this config
@@ -83,16 +92,12 @@ SOLR_SSL_WANT_CLIENT_AUTH=false
# this to false can be useful to disable these checks when re-using a certificate on many hosts
SOLR_SSL_CHECK_PEER_NAME=true
----
+====
-When you start Solr, the `bin/solr` script includes the settings in `bin/solr.in.sh` and will pass these SSL-related system properties to the JVM.
-
-.Client Authentication Settings
-WARNING: Enable either SOLR_SSL_NEED_CLIENT_AUTH or SOLR_SSL_WANT_CLIENT_AUTH but not both at the same time. They are mutually exclusive and Jetty will select one of them which may not be what you expect. SOLR_SSL_CLIENT_HOSTNAME_VERIFICATION should be set to false if you want to disable hostname verification.
-
-Similarly, when you start Solr on Windows, the `bin\solr.cmd` script includes the settings in `bin\solr.in.cmd` - uncomment and update the set of properties beginning with `SOLR_SSL_*` to pass these SSL-related system properties to the JVM:
-
-.bin\solr.in.cmd example SOLR_SSL_* configuration
-[source,text]
+[example.tab-pane#solr-in-cmd]
+====
+[.tab-label]*Windows (solr.in.cmd)*
+[source,powershell]
----
REM Enables HTTPS. It is implicitly true if you set SOLR_SSL_KEY_STORE. Use this config
REM to enable https module with custom jetty configuration.
@@ -111,40 +116,28 @@ REM SSL Certificates contain host/ip "peer name" information that is validated b
REM this to false can be useful to disable these checks when re-using a certificate on many hosts
set SOLR_SSL_CHECK_PEER_NAME=true
----
+====
+--
-=== Run Single Node Solr using SSL
+.Client Authentication Settings
+WARNING: Enable either `SOLR_SSL_NEED_CLIENT_AUTH` or `SOLR_SSL_WANT_CLIENT_AUTH` but not both at the same time. They are mutually exclusive and Jetty will select one of them which may not be what you expect. `SOLR_SSL_CLIENT_HOSTNAME_VERIFICATION` should be set to false if you want to disable hostname verification.
-Start Solr using the command shown below; by default clients will not be required to authenticate:
+When you start Solr, the `bin/solr` script includes these settings and will pass them as system properties to the JVM.
-[.dynamic-tabs]
---
-[example.tab-pane#single-unix]
-====
-[.tab-label]**nix Command*
-[source,bash]
-----
-bin/solr -p 8984
-----
-====
+If you are running Solr in standalone mode, you can skip to <<Run Single Node Solr using SSL>>.
-[example.tab-pane#single-windows]
-====
-[.tab-label]*Windows Command*
-[source,text]
-----
-bin\solr.cmd -p 8984
-----
-====
---
+If you are using SolrCloud, however, you need to <<Configure ZooKeeper>> before starting Solr.
+
+=== Password Distribution via Hadoop Credential Store
-== 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.
-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.
+If you are not using a Hadoop credential store, you can skip this step.
Hadoop credential store can be used with Solr using the following two steps.
-=== Provide a Hadoop Credential Store
+==== Provide a Hadoop Credential Store
Create a Hadoop credstore file and define the entries below with the actual keystore passwords.
[source,text]
@@ -157,7 +150,7 @@ 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
+==== Configure Solr to use Hadoop Credential Store
Solr requires three parameters to be configured in order to use the credential store file for keystore passwords.
@@ -174,8 +167,8 @@ The password to the credential store.
--
[example.tab-pane#credstore-unix]
====
-[.tab-label]**nix Example*
-[source,text]
+[.tab-label]**nix (solr.in.sh)*
+[source,bash]
----
SOLR_OPTS=" -Dsolr.ssl.credential.provider.chain=hadoop"
SOLR_HADOOP_CREDENTIAL_PROVIDER_PATH=localjceks://file/home/solr/hadoop-credential-provider.jceks
@@ -185,8 +178,8 @@ HADOOP_CREDSTORE_PASSWORD="credStorePass123"
[example.tab-pane#credstore-windows]
=====
-[.tab-label]*Windows Example*
-[source,text]
+[.tab-label]*Windows (solr.in.cmd)*
+[source,powershell]
----
set SOLR_OPTS=" -Dsolr.ssl.credential.provider.chain=hadoop"
set SOLR_HADOOP_CREDENTIAL_PROVIDER_PATH=localjceks://file/home/solr/hadoop-credential-provider.jceks
@@ -195,106 +188,113 @@ set HADOOP_CREDSTORE_PASSWORD="credStorePass123"
=====
--
-
-== SSL with SolrCloud
-
-This section describes how to run a two-node SolrCloud cluster with no initial collections and a single-node external ZooKeeper. The commands below assume you have already created the keystore described above.
-
=== Configure ZooKeeper
NOTE: ZooKeeper does not support encrypted communication with clients like Solr. There are several related JIRA tickets where SSL support is being planned/worked on: https://issues.apache.org/jira/browse/ZOOKEEPER-235[ZOOKEEPER-235]; https://issues.apache.org/jira/browse/ZOOKEEPER-236[ZOOKEEPER-236]; https://issues.apache.org/jira/browse/ZOOKEEPER-1000[ZOOKEEPER-1000]; and https://issues.apache.org/jira/browse/ZOOKEEPER-2120[ZOOKEEPER-2120].
-Before you start any SolrCloud nodes, you must configure your Solr cluster properties in ZooKeeper, so that Solr nodes know to communicate via SSL.
+After creating the keystore described above and before you start any SolrCloud nodes, you must configure your Solr cluster properties in ZooKeeper so that Solr nodes know to communicate via SSL.
-This section assumes you have created and started a single-node external ZooKeeper on port 2181 on localhost - see <<setting-up-an-external-zookeeper-ensemble.adoc#setting-up-an-external-zookeeper-ensemble,Setting Up an External ZooKeeper Ensemble>>.
+This section assumes you have created and started an external ZooKeeper.
+See <<setting-up-an-external-zookeeper-ensemble.adoc#setting-up-an-external-zookeeper-ensemble,Setting Up an External ZooKeeper Ensemble>> for more information.
-The `urlScheme` cluster-wide property needs to be set to `https` before any Solr node starts up. The example below uses the `zkcli` tool that comes with the binary Solr distribution to do this:
+The `urlScheme` cluster-wide property needs to be set to `https` before any Solr node starts up.
+The examples below use the `zkcli` tool that comes with Solr to do this.
-.*nix command
-[source,bash]
+[.dynamic-tabs]
+--
+[example.tab-pane#zkclusterprops-unix]
+====
+[.tab-label]**nix Command*
+[source,terminal]
----
-server/scripts/cloud-scripts/zkcli.sh -zkhost localhost:2181 -cmd clusterprop -name urlScheme -val https
+$ server/scripts/cloud-scripts/zkcli.sh -zkhost server1:2181,server2:2181,server3:2181 -cmd clusterprop -name urlScheme -val https
----
+====
-.Windows command
-[source,text]
+[example.tab-pane#zkclusterprops-windows]
+=====
+[.tab-label]*Windows Command*
+[source,powershell]
----
-server\scripts\cloud-scripts\zkcli.bat -zkhost localhost:2181 -cmd clusterprop -name urlScheme -val https
+C:\> server\scripts\cloud-scripts\zkcli.bat -zkhost server1:2181,server2:2181,server3:2181 -cmd clusterprop -name urlScheme -val https
----
+=====
+--
-If you have set up your ZooKeeper cluster to use a <<taking-solr-to-production.adoc#zookeeper-chroot,chroot for Solr>>, make sure you use the correct `zkhost` string with `zkcli`, e.g., `-zkhost localhost:2181/solr`.
+Be sure to use the correct `zkhost` value for your system. If you have set up your ZooKeeper ensemble to use a <<taking-solr-to-production.adoc#zookeeper-chroot,chroot for Solr>>, make sure to include it in the `zkhost` string, e.g., `-zkhost server1:2181,server2:2181,server3:2181/solr`.
-=== Run SolrCloud with SSL
+=== Update Cluster Properties for Existing Collections
-NOTE: If you have defined `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <<setting-up-an-external-zookeeper-ensemble#updating-solr-include-files,instructions>>) you can omit `-z <zk host string>` from all of the `bin/solr`/`bin\solr.cmd` commands below.
+If you are using SolrCloud and have collections created before enabling SSL, you will need to update the cluster properties to use HTTPS.
-==== Create Solr Home Directories for Two Nodes
+If you do not have existing collections or are not using SolrCloud, you can skip ahead and start Solr.
-Create two copies of the `server/solr/` directory which will serve as the Solr home directories for each of your two SolrCloud nodes:
+Updating cluster properties can be done with the Collections API <<cluster-node-management.adoc#clusterprop,CLUSTERPROP>> command, as in this example (update the hostname and port as appropriate for your system):
-.*nix commands
-[source,bash]
-----
-mkdir cloud
-cp -r server/solr cloud/node1
-cp -r server/solr cloud/node2
-----
+[source,terminal]
+$ http://localhost:8983/solr/admin/collections?action=CLUSTERPROP&name=urlScheme&val=https
-.Windows commands
-[source,text]
-----
-mkdir cloud
-xcopy /E server\solr cloud\node1\
-xcopy /E server\solr cloud\node2\
-----
+This command only needs to be run on one node of the cluster, the change will apply to all nodes.
-==== Start the First Solr Node
+Once this and all other steps are complete, you can go ahead and start Solr.
-Next, start the first Solr node on port 8984. Be sure to stop the standalone server first if you started it when working through the previous section on this page.
+== Starting Solr After Enabling SSL
-.*nix command
-[source,bash]
-----
-bin/solr -cloud -s cloud/node1 -z localhost:2181 -p 8984
-----
-
-.Windows command
-[source,text]
-----
-bin\solr.cmd -cloud -s cloud\node1 -z localhost:2181 -p 8984
-----
-
-Notice the use of the `-s` option to set the location of the Solr home directory for node1.
+=== Run Single Node Solr using SSL
-If you created your SSL key without all DNS names/IP addresses on which Solr nodes will run, you can tell Solr to skip hostname verification for inter-Solr-node communications by setting the `solr.ssl.checkPeerName` system property to `false`:
+Start Solr using the Solr control script as shown in the examples below.
+Customize the values for the parameters shown as needed and add any used in your system.
-.*nix command
-[source,bash]
+[.dynamic-tabs]
+--
+[example.tab-pane#single-unix]
+====
+[.tab-label]**nix Command*
+[source,terminal]
----
-bin/solr -cloud -s cloud/node1 -z localhost:2181 -p 8984 -Dsolr.ssl.checkPeerName=false
+$ bin/solr -p 8984
----
+====
-.Windows command
-[source,text]
+[example.tab-pane#single-windows]
+====
+[.tab-label]*Windows Command*
+[source,powershell]
----
-bin\solr.cmd -cloud -s cloud\node1 -z localhost:2181 -p 8984 -Dsolr.ssl.checkPeerName=false
+C:\> bin\solr.cmd -p 8984
----
+====
+--
-==== Start the Second Solr Node
+=== Run SolrCloud with SSL
-Finally, start the second Solr node on port 7574 - again, to skip hostname verification, add `-Dsolr.ssl.checkPeerName=false`;
+NOTE: If you have defined `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <<setting-up-an-external-zookeeper-ensemble#updating-solr-include-files,instructions>>) you can omit `-z <zk host string>` from all of the `bin/solr`/`bin\solr.cmd` commands below.
-.*nix command
-[source,text]
+Start each Solr node with the Solr control script as shown in the examples below. Customize the values for the parameters shown as necessary and add any used in your system.
+
+If you created the SSL key without all DNS names or IP addresses on which Solr nodes run, you can tell Solr to skip hostname verification for inter-node communications by setting the `-Dsolr.ssl.checkPeerName=false` system property.
+
+[.dynamic-tabs]
+--
+[example.tab-pane#cloud-unix]
+====
+[.tab-label]*\*nix*
+[source,terminal]
----
-bin/solr -cloud -s cloud/node2 -z localhost:2181 -p 7574
+$ bin/solr -cloud -s cloud/node1 -z server1:2181,server2:2181,server3:2181 -p 8984
----
+====
-.Windows command
-[source,text]
+[example.tab-pane#cloud-windows]
+====
+[.tab-label]*Windows*
+[source,powershell]
----
-bin\solr.cmd -cloud -s cloud\node2 -z localhost:2181 -p 7574
+C:\> bin\solr.cmd -cloud -s cloud\node1 -z server1:2181,server2:2181,server3:2181
+
----
+====
+--
== Example Client Actions
@@ -305,7 +305,7 @@ curl on OS X Mavericks (10.9) has degraded SSL support. For more information and
The curl commands in the following sections will not work with the system `curl` on OS X Yosemite (10.10). Instead, the certificate supplied with the `-E` parameter must be in PKCS12 format, and the file supplied with the `--cacert` parameter must contain only the CA certificate, and no key (see <<Convert the Certificate and Key to PEM Format for Use with curl,above>> for instructions on creating this file):
[source,bash]
-curl -E solr-ssl.keystore.p12:secret --cacert solr-ssl.cacert.pem ...
+$ curl -E solr-ssl.keystore.p12:secret --cacert solr-ssl.cacert.pem ...
====
@@ -333,9 +333,9 @@ The `create` action will pass the `SOLR_SSL_*` properties set in your include fi
To get the resulting cluster status (again, if you have not enabled client authentication, remove the `-E solr-ssl.pem:secret` option):
-[source,bash]
+[source,terminal]
----
-curl -E solr-ssl.pem:secret --cacert solr-ssl.pem "https://localhost:8984/solr/admin/collections?action=CLUSTERSTATUS&indent=on"
+$ curl -E solr-ssl.pem:secret --cacert solr-ssl.pem "https://localhost:8984/solr/admin/collections?action=CLUSTERSTATUS&indent=on"
----
You should get a response that looks like this: