Enabling SSL

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 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://wiki.openssl.org/index.php/Binaries 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 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:

The above command will create a keystore file named solr-ssl.keystore.p12 in the current directory.

Convert the PKCS12 format keystore, including both the certificate and the key, into PEM format using the openssl command:

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:

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.

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 a user-managed cluster or single-node installation, you can skip to Start User-Managed Cluster or Single-Node Solr.

If you are using SolrCloud, however, you need to Configure ZooKeeper before starting Solr.

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.

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 an external ZooKeeper. See ZooKeeper Ensemble Configuration for more information.

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.

Be sure to use the correct zkhost value for your system. If you have set up your ZooKeeper ensemble to use a chroot for Solr, make sure to include it in the zkhost string, e.g., -zkhost server1:2181,server2:2181,server3:2181/solr.

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 CLUSTERPROP command, as in this example (update the hostname and port as appropriate for your system):

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.

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.

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.

Solr can automatically reload KeyStore/TrustStore when certificates are updated without restarting. This is enabled by default when using SSL, but can be disabled by setting the environment variable SOLR_SSL_RELOAD_ENABLED to false. By default, Solr will check for updates in the KeyStore every 30 seconds, but this interval can be updated by passing the system property solr.jetty.sslContext.reload.scanInterval with the new interval in seconds on startup. Note that the truststore file is not actively monitored, so if you need to apply changes to the truststore, you need to update it and after that touch the keystore to trigger a reload.

Http2SolrClient builder has a method withKeyStoreReloadInterval(long interval, TimeUnit unit) to initialize a scanner that will watch and update the keystore and truststore for changes. If you are using CloudHttp2SolrClient, you can use the withInternalClientBuilder(Http2SolrClient.Builder internalClientBuilder) to configure the internal http client with a keystore reload interval. The minimum reload interval is 1 second. If not set (or set to 0 or a negative value), the keystore/truststore won’t be updated in the client.

Create a 2-shard, replicationFactor=1 collection named mycollection using the _default configset:

The create action will pass the SOLR_SSL_* properties set in your include file to the SolrJ code used to create the collection.

To get the resulting cluster status (again, if you have not enabled client authentication, remove the -E solr-ssl.pem:secret option):

You should get a response that looks like this:

Use post.jar to index some example documents to the SolrCloud collection created above:

Use curl to query the SolrCloud collection created above, from a directory containing the PEM formatted certificate and key created above (e.g., example/etc/). If you have not enabled client authentication (system property -Djetty.ssl.clientAuth=true), then you can remove the -E solr-ssl.pem:secret option:

From a java client using SolrJ, index a document. In the code below, the javax.net.ssl.* system properties are set programmatically, but you could instead specify them on the java command line, as in the post.jar example above: