Enabling SSL

Solr can encrypt communications to and from clients, and between nodes in SolrCloud mode, with 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

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

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

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:

keytool -genkeypair -alias solr-ssl -keyalg RSA -keysize 2048 -keypass secret -storepass secret -validity 9999 -keystore solr-ssl.keystore.jks -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.jks in the current directory.

Convert the Certificate and Key to PEM Format for Use with curl

curl isn’t capable of using JKS formatted keystores, so the JKS keystore needs to be converted to PEM format, which curl understands.

First convert the JKS keystore into PKCS12 format using keytool:

keytool -importkeystore -srckeystore solr-ssl.keystore.jks -destkeystore solr-ssl.keystore.p12 -srcstoretype jks -deststoretype pkcs12

The keytool application will prompt you to create a destination keystore password and for the source keystore password, which was set when creating the keystore ("secret" in the example shown above).

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

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:

openssl pkcs12 -nokeys -in solr-ssl.keystore.p12 -out solr-ssl.cacert.pem

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

If you setup Solr as a service on Linux using the steps outlined in Taking Solr to Production, then make these changes in /var/solr/solr.in.sh instead.
bin/solr.in.sh example SOLR_SSL_* configuration
# Enables HTTPS. It is implictly true if you set SOLR_SSL_KEY_STORE. Use this config
# to enable https module with custom jetty configuration.
SOLR_SSL_ENABLED=true
# Uncomment to set SSL-related system properties
# Be sure to update the paths to the correct keystore for your environment
SOLR_SSL_KEY_STORE=etc/solr-ssl.keystore.jks
SOLR_SSL_KEY_STORE_PASSWORD=secret
SOLR_SSL_TRUST_STORE=etc/solr-ssl.keystore.jks
SOLR_SSL_TRUST_STORE_PASSWORD=secret
# Require clients to authenticate
SOLR_SSL_NEED_CLIENT_AUTH=false
# Enable clients to authenticate (but not require)
SOLR_SSL_WANT_CLIENT_AUTH=false
# SSL Certificates contain host/ip "peer name" information that is validated by default. Setting
# this to false can be useful to disable these checks when re-using a certificate on many hosts
SOLR_SSL_CHECK_PEER_NAME=true
# Override Key/Trust Store types if necessary
SOLR_SSL_KEY_STORE_TYPE=JKS
SOLR_SSL_TRUST_STORE_TYPE=JKS

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

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
REM Enables HTTPS. It is implictly true if you set SOLR_SSL_KEY_STORE. Use this config
REM to enable https module with custom jetty configuration.
set SOLR_SSL_ENABLED=true
REM Uncomment to set SSL-related system properties
REM Be sure to update the paths to the correct keystore for your environment
set SOLR_SSL_KEY_STORE=etc/solr-ssl.keystore.jks
set SOLR_SSL_KEY_STORE_PASSWORD=secret
set SOLR_SSL_TRUST_STORE=etc/solr-ssl.keystore.jks
set SOLR_SSL_TRUST_STORE_PASSWORD=secret
REM Require clients to authenticate
set SOLR_SSL_NEED_CLIENT_AUTH=false
REM Enable clients to authenticate (but not require)
set SOLR_SSL_WANT_CLIENT_AUTH=false
REM SSL Certificates contain host/ip "peer name" information that is validated by default. Setting
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
REM Override Key/Trust Store types if necessary
set SOLR_SSL_KEY_STORE_TYPE=JKS
set SOLR_SSL_TRUST_STORE_TYPE=JKS

Run Single Node Solr using SSL

Start Solr using the command shown below; by default clients will not be required to authenticate:

*nix command
bin/solr -p 8984
Windows command
bin\solr.cmd -p 8984

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

ZooKeeper does not support encrypted communication with clients like Solr. There are several related JIRA tickets where SSL support is being planned/worked on: ZOOKEEPER-235; ZOOKEEPER-236; ZOOKEEPER-1000; and 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.

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.

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:

*nix command
server/scripts/cloud-scripts/zkcli.sh -zkhost localhost:2181 -cmd clusterprop -name urlScheme -val https
Windows command
server\scripts\cloud-scripts\zkcli.bat -zkhost localhost:2181 -cmd clusterprop -name urlScheme -val https

If you have set up your ZooKeeper cluster to use a chroot for Solr, make sure you use the correct zkhost string with zkcli, e.g., -zkhost localhost:2181/solr.

Run SolrCloud with SSL

If you have defined ZK_HOST in solr.in.sh/solr.in.cmd (see instructions) you can omit -z <zk host string> from all of the bin/solr/bin\solr.cmd commands below.

Create Solr Home Directories for Two Nodes

Create two copies of the server/solr/ directory which will serve as the Solr home directories for each of your two SolrCloud nodes:

*nix commands
mkdir cloud
cp -r server/solr cloud/node1
cp -r server/solr cloud/node2
Windows commands
mkdir cloud
xcopy /E server\solr cloud\node1\
xcopy /E server\solr cloud\node2\

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
bin/solr -cloud -s cloud/node1 -z localhost:2181 -p 8984
Windows command
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
bin/solr -cloud -s cloud/node1 -z localhost:2181 -p 8984 -Dsolr.ssl.checkPeerName=false
Windows command
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
bin/solr -cloud -s cloud/node2 -z localhost:2181 -p 7574
Windows command
bin\solr.cmd -cloud -s cloud\node2 -z localhost:2181 -p 7574

Example Client Actions

curl on OS X Mavericks (10.9) has degraded SSL support. For more information and workarounds to allow one-way SSL, see http://curl.haxx.se/mail/archive-2013-10/0036.html. curl on OS X Yosemite (10.10) is improved - 2-way SSL is possible - see http://curl.haxx.se/mail/archive-2014-10/0053.html.

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 parametr must contain only the CA certificate, and no key (see above for instructions on creating this file):

curl -E solr-ssl.keystore.p12:secret --cacert solr-ssl.cacert.pem ...
If your operating system does not include curl, you can download binaries here: http://curl.haxx.se/download.html

Create a SolrCloud Collection using bin/solr

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

*nix command
bin/solr create -c mycollection -shards 2
Windows command
bin\solr.cmd create -c mycollection -shards 2

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

Retrieve SolrCloud Cluster Status using curl

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

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:

{
  "responseHeader":{
    "status":0,
    "QTime":2041},
  "cluster":{
    "collections":{
      "mycollection":{
        "shards":{
          "shard1":{
            "range":"80000000-ffffffff",
            "state":"active",
            "replicas":{"core_node1":{
                "state":"active",
                "base_url":"https://127.0.0.1:8984/solr",
                "core":"mycollection_shard1_replica1",
                "node_name":"127.0.0.1:8984_solr",
                "leader":"true"}}},
          "shard2":{
            "range":"0-7fffffff",
            "state":"active",
            "replicas":{"core_node2":{
                "state":"active",
                "base_url":"https://127.0.0.1:7574/solr",
                "core":"mycollection_shard2_replica1",
                "node_name":"127.0.0.1:7574_solr",
                "leader":"true"}}}},
        "maxShardsPerNode":"1",
        "router":{"name":"compositeId"},
        "replicationFactor":"1"}},
    "properties":{"urlScheme":"https"}}}

Index Documents using post.jar

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

cd example/exampledocs

java -Djavax.net.ssl.keyStorePassword=secret -Djavax.net.ssl.keyStore=../../server/etc/solr-ssl.keystore.jks -Djavax.net.ssl.trustStore=../../server/etc/solr-ssl.keystore.jks -Djavax.net.ssl.trustStorePassword=secret -Durl=https://localhost:8984/solr/mycollection/update -jar post.jar *.xml

Query Using curl

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:

curl -E solr-ssl.pem:secret --cacert solr-ssl.pem "https://localhost:8984/solr/mycollection/select?q=*:*"

Index a Document using CloudSolrClient

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:

System.setProperty("javax.net.ssl.keyStore", "/path/to/solr-ssl.keystore.jks");
System.setProperty("javax.net.ssl.keyStorePassword", "secret");
System.setProperty("javax.net.ssl.trustStore", "/path/to/solr-ssl.keystore.jks");
System.setProperty("javax.net.ssl.trustStorePassword", "secret");
String zkHost = "127.0.0.1:2181";
CloudSolrClient client = new CloudSolrClient.Builder().withZkHost(zkHost).build();
client.setDefaultCollection("mycollection");
SolrInputDocument doc = new SolrInputDocument();
doc.addField("id", "1234");
doc.addField("name", "A lovely summer holiday");
client.add(doc);
client.commit();
©2018 Apache Software Foundation. All rights reserved.
Site Version: 7.5
Site last generated: 2018-09-18

Apache Solr