Apache Solr Documentation

6.5 Ref Guide (PDF Download)
Solr Tutorial
Solr Community Wiki

Older Versions of this Guide (PDF)

Ref Guide Topics

Meta-Documentation

*** As of June 2017, the latest Solr Ref Guide is located at https://lucene.apache.org/solr/guide ***

Please note comments on these pages have now been disabled for all users.

Skip to end of metadata
Go to start of metadata

Both SolrCloud and single-node Solr can encrypt communications to and from clients, and in SolrCloud between nodes, with SSL.  This section describes enabling SSL with the example Jetty server 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:

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:

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:

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:

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

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

Run Single Node Solr using SSL

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

*nix command
Windows command

 

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-235ZOOKEEPER-236ZOOKEEPER-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
Windows command

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

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

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

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

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

Example Client Actions

cURL on OS X Mavericks (10.9) has degraded SSL support. For more information and workarounds to allow 1-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 param must be in PKCS12 format, and the file supplied with the --cacert param must contain only the CA certificate, and no key (see above for instructions on creating this file):

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 (data_driven_schema_configs):

*nix command
Windows command

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

You should get a response that looks like this:

Index documents using post.jar

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

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:

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:

  • No labels

23 Comments

  1. Very clear and informative wiki page, Thanks for writing.

    However, In "Start the first Solr node" section. Given that -Djetty.port=8984 -Djetty.ssl.port=8984, they are same and causing port collission. I tried changing the port number as -Djetty.port=8983 -Djetty.ssl.port=8984 and it worked. Same with other places in this page.

    1. Raza,

      I'm guessing you didn't comment out the non-SSL SelectChannelConnector block in example/etc/jetty.xml, as described on this page.

  2. IMHO what we really need here are instructions for converting an existing certificate, private key, and issuing CA cert from PEM to java keystore.

     

  3. Is the ZooKeeper path /clusterprops.json correct? Shouldn't it be /solr/clusterprops.json ?

    1. Hrishikesh, I think your question is answered by the following sentence on this page:

      If you have set up your ZooKeeper cluster to use a chroot for Solr, make sure you place the clusterprops.json file there instead: ... -cmd put /my_chroot/clusterprops.json '{"urlScheme":"https"}'

      1. Yes that works. Actually the zkcli command examples does not specify /solr prefix in the zkHost parameter. Hence I didn't realize this. May be we can mention the chroot concept here as well (just for completeness)?

        Command Line Utilities

  4. In paragraph "Configure ZooKeeper" we say: "If you have set up your ZooKeeper cluster to use a chroot for Solr, make sure you place the clusterprops.json file there instead...".

    Would it not work to specify the chroot as part of zkcli's zkhost (-zkhost localhost:2181/solr) - in which case /clusterprops.json will end up below /solr/??

    1. I would think that no special instructions regarding anything in zookeeper should be required when using a chroot, since it would indeed be specified on the zkhost parameter along with all the servers, and therefore automatically be handled by any tools which use that zkhost parameter.

      If somebody is using a chroot with Solr but NOT using a chroot with other tools like Solr's zkcli or Zookeeper's zkCli, then they would indeed need to be worried about putting that json file inside that path.  I would also expect typical operations like config uploading to not work right.

      1. Steve Roweyou added that paragraph, can you comment?

        1. I rewrote to use the clusterprop command of zkCli instead of overwriting the clusterprops.json file. Also changed the paragraph about chroot to a reminder to use correct zkhost with the tool.

  5. Suggestion: Rewrite this page with instructions on how to generate a free, truested SSL cert for your domain using https://letsencrypt.org/

    This can hopefully slim down this page a lot, with added benefit of a true padlock in the address bar :)

    Next step could be to provide a bin/solr script command to set up all the settings with one command. See  SOLR-8442 - Command line tool to enable SSL Open

    1. i'm not sure that's a good idea, for a variety of reasons...

      1. letsencrypt.org is 3rd party web service we have no direct control of / relationship with. making our docs (on something as important as configuring SSL) dependent on assumptions regarding the availability of that service (which might change at any time) seems like a bad idea when there are freely available command line open source tools that users are likeley to already have installed and which – worst case scenerio – we can document the specific versions of which the instructions apply to
      2. last time i checked, letsencrypt certs had very short non changable expirations that required continual renewal - that seems out of scope for trying to explain here, and w/o explaining it might seriously confuse people whos SSL testing works find one day and then suddenly stops working the next
      3. we don't want to imply / misslead folks into thinking the only way to use SSL with solr is a letsencrypt cert – this instructions show how to create a test cert, users intereted in using letsencrypt should be able to extrapolate from there.  if anything maybe we should have demo scripts to help automated the self signed cert creation/installation?

       

      Having instructions on setting up solr using letsencrypt.org seems like the perfect sort of docs  to live in the "Community Wiki" (https://wiki.apache.org/solr/)

  6. Solr does not support both HTTP and HTTPS at the same time. You can only use one of them at a time.

  7. Hi all, 

    I'd like to use Solr on Windows Server 2012 R2 to complement a .NET website. 

    Can I tell Solr to use SSL certificate in LocalMachine store instead of creating new jks file.

    Thank you very much

    1. Hi. No you can't. But yo may be able to export and convert your existing certificate into jks format. Try googling the approach.

      1. Thank you Jan. I've already done that. Just wanted to check if it were possible so that I don't have to store the certificates at multiple places.

        1. Because Solr is currently a servlet, we are at the mercy of our servlet container. Solr ships with Jetty. Because servlets and servlet containers are Java programs and the encryption services are provided by Java, they are limited to what Java can do. Java does not use system services for PKI/TLS/SSL. Sun chose to reinvent that wheel rather than rely on the system.

  8. I haven't run into this issue specifically with solr, but i suspect it is applicable - hopefully this helps someone.  

    java on linux uses /dev/random for its random seed data.   This interface may block if the kernel can't collect enough entropy - the visible effect is that connections will apparently hang.  

    This will happen much more often on lightly loaded machines - a busy server is probably going to be OK.  You may notice it at OS startup.

    In any event, /dev/urandom should be used instead.  http://www.2uo.de/myths-about-urandom/

    To do this, add the following to your java startup line:  -Djava.security.egd=file:/dev/urandom

  9. Hi,

    I keep getting -

    curl: (58) SSL: Couldn't make sense of the data in the certificate "./etc/solr-ssl.pem" and its private key.

    I am using mac Sierra and have added to the keychain giving access to all applications.

    solr is up and running fine through browser using https.

    I believe I have read the guide correctly which may or may not be the problem.

    I have in my solr.in.sh: 

    SOLR_SSL_NEED_CLIENT_AUTH=true

     #SOLR_SSL_WANT_CLIENT_AUTH 

    Curl and apache solr php client both give same error.

    Can anyone help?

    1. Please email your question to the solr-user mailing list - for subscription info, see http://lucene.apache.org/solr/community.html#mailing-lists-irc .

    2. My problem was resolved by reading the Example Client Actions section.

      This worked for me in osx 10.12.4 macSierra.

      curl -E solr-ssl.keystore.p12:secret --cacert solr-ssl.cacert.pem "https://localhost:8984/solr/mycollection/select?q=*:*&wt=json&indent=on"

       

       

  10. I installed 5.5.4 on Centos to /opt/solr. Also I installed init script using install_solr_service.sh. I've imported bought certificate to keystore and now trying to start it up with SSL, using following settings in /etc/default/solr.in.sh:

    But it doesn't start with following error:

     Expand source

    I tried to use: SOLR_SSL_KEY_STORE=/opt/solr-5.5.4/server/etc/solr-ssl.keystore.jks, but I'm still getting the same error. Can't find where the issue could be. Any ideas?

    1. Please use the solr-user mailing list for questions about using Solr (the comments section on ref guide pages is intended instead for discussions about the documentation).  See http://lucene.apache.org/solr/community.html#mailing-lists-irc