diff --git a/solr/solr-ref-guide/src/common-query-parameters.adoc b/solr/solr-ref-guide/src/common-query-parameters.adoc index 594f5136245..1383b81017d 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 1c8d3354fff..ff3a3e2f4cc 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 19edf0d20d5..efac8a05533 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 5840e3f35e0..6d1be3ba5b3 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. -NOTE: If you setup Solr as a service on Linux using the steps outlined in <>, then make these changes in `/var/solr/solr.in.sh` instead. +[.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 <>, 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 - -Start Solr using the command shown below; by default clients will not be required to authenticate: - -[.dynamic-tabs] --- -[example.tab-pane#single-unix] -==== -[.tab-label]**nix Command* -[source,bash] ----- -bin/solr -p 8984 ----- -==== - -[example.tab-pane#single-windows] -==== -[.tab-label]*Windows Command* -[source,text] ----- -bin\solr.cmd -p 8984 ----- ==== -- -== Password Distribution via Hadoop Credential Store +.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. -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. +When you start Solr, the `bin/solr` script includes these settings and will pass them as system properties to the JVM. + +If you are running Solr in standalone mode, you can skip to <>. + +If you are using SolrCloud, however, you need to <> before starting Solr. + +=== 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. + +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 <>. +This section assumes you have created and started an external ZooKeeper. +See <> 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 <>, 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 <>, make sure to include it in the `zkhost` string, e.g., `-zkhost server1:2181,server2:2181,server3:2181/solr`. + +=== Update Cluster Properties for Existing Collections + +If you are using SolrCloud and have collections created before enabling SSL, you will need to update the cluster properties to use HTTPS. + +If you do not have existing collections or are not using SolrCloud, you can skip ahead and start Solr. + +Updating cluster properties can be done with the Collections API <> command, as in this example (update the hostname and port as appropriate for your system): + +[source,terminal] +$ http://localhost:8983/solr/admin/collections?action=CLUSTERPROP&name=urlScheme&val=https + +This command only needs to be run on one node of the cluster, the change will apply to all nodes. + +Once this and all other steps are complete, you can go ahead and start Solr. + +== Starting Solr After Enabling SSL + +=== Run Single Node Solr using SSL + +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. + +[.dynamic-tabs] +-- +[example.tab-pane#single-unix] +==== +[.tab-label]**nix Command* +[source,terminal] +---- +$ bin/solr -p 8984 +---- +==== + +[example.tab-pane#single-windows] +==== +[.tab-label]*Windows Command* +[source,powershell] +---- +C:\> bin\solr.cmd -p 8984 +---- +==== +-- === Run SolrCloud with SSL NOTE: If you have defined `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <>) you can omit `-z ` from all of the `bin/solr`/`bin\solr.cmd` commands below. -==== Create Solr Home Directories for Two Nodes +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. -Create two copies of the `server/solr/` directory which will serve as the Solr home directories for each of your two SolrCloud nodes: +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. -.*nix commands -[source,bash] +[.dynamic-tabs] +-- +[example.tab-pane#cloud-unix] +==== +[.tab-label]*\*nix* +[source,terminal] ---- -mkdir cloud -cp -r server/solr cloud/node1 -cp -r server/solr cloud/node2 +$ bin/solr -cloud -s cloud/node1 -z server1:2181,server2:2181,server3:2181 -p 8984 ---- +==== -.Windows commands -[source,text] ----- -mkdir cloud -xcopy /E server\solr cloud\node1\ -xcopy /E server\solr cloud\node2\ +[example.tab-pane#cloud-windows] +==== +[.tab-label]*Windows* +[source,powershell] ---- +C:\> bin\solr.cmd -cloud -s cloud\node1 -z server1:2181,server2:2181,server3:2181 -==== Start the First Solr Node - -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. - -.*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. - -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`: - -.*nix command -[source,bash] ----- -bin/solr -cloud -s cloud/node1 -z localhost:2181 -p 8984 -Dsolr.ssl.checkPeerName=false ----- - -.Windows command -[source,text] ----- -bin\solr.cmd -cloud -s cloud\node1 -z localhost:2181 -p 8984 -Dsolr.ssl.checkPeerName=false ----- - -==== Start the Second Solr Node - -Finally, start the second Solr node on port 7574 - again, to skip hostname verification, add `-Dsolr.ssl.checkPeerName=false`; - -.*nix command -[source,text] ----- -bin/solr -cloud -s cloud/node2 -z localhost:2181 -p 7574 ----- - -.Windows command -[source,text] ----- -bin\solr.cmd -cloud -s cloud\node2 -z localhost:2181 -p 7574 ---- +==== +-- == 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 <> 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: