Adding Custom JARs to a Deployment


Overview

Users of SearchStax® from Measured Search® can now add custom JAR files to a Solr deployment. This lets you add custom analyzers, tokenizers, query parsers, and other plugins to your project.

The JAR files can be added and managed through the SearchStax dashboard.

Preparations

We assume that you have created a collection under Solr 6 and above. We assume that you have created a custom JAR file for your Solr project.

Enable Runtime Library Support

Please choose JARs from the left-side navigation menu within your desired Deployment. Runtime library support is disabled by default. When you open the JARs menu for the first time, enable it by clicking the Yes, let's enable button and confirming the action.

Upload Public Key to Zookeeper

You must upload at least one public RSA key in DER format before uploading a JAR file. If you don't already have such a key, you can generate it using openssl.

$ openssl genrsa -out priv_key.pem 512

The public portion of the key should be output in DER format so Java can read it.

$ openssl rsa -in priv_key.pem -pubout -outform DER -out pub_key.der

After enabling JAR support, you will see a row of buttons that let you upload an RSA public key. Click on the Upload Public Key button, chose a valid public RSA key in DER format and upload it.

After the key is uploaded, you will see it listed in the Uploaded Keys table:

Upload Jar Files

You can upload your JAR file by clicking the Upload Custom JAR button, selecting your JAR file, and naming the blob we will use to store your JAR file. (A "blob" is a Binary Large OBject.) Please note: SearchStax will create a ".system" collection with a replicationFactor equal to all of your Solr nodes to store and distribute your JAR files.

After a successful upload, a new Blob will be seen in the "Existing JAR blobs" table. Please note, you can have multiple versions of the same JAR within the same storage blob.

Add a Runtime Library to a Collection Config

Now we need to add the JAR blob to the collection's classpath. We will do so by clicking the add-runtimelib button, selecting a Collection and a Blob ID (in format BlobName/version) and providing a JAR signature generated by any of the private keys associated with the public keys we have uploaded to Zookeeper.

To generate a signature we will use an openssl command:

$ openssl dgst -sha1 -sign <private_key>.pem <jarfile>.jar |openssl enc -base64
<returns a signature string here>

as in this example:

$ openssl dgst -sha1 -sign secondpriv_key.pem ./parsers/helloworld.jar |openssl enc -base64
Pcf6TOZ2TjRoWaxZ6Wk6CF/ydE68+tdbsp/3Sl2NjmyrB01v+1IZbUA89R224JzKdv2mlzl6MeL/JOojYy+5Hg==

Please remove any whitespace (spaces, line breaks) from the signature string before pasting it into the field. (There will often be a line break inserted where the digest string wraps at the right edge of the window.)

Load the Parser

The last step is to load the parser so we can start using it. We will craft a cURL call in the following format:

$ curl https://<Solr load balancer URL>/solr/<collection_name>/config -H 'Content-type:application/json' -d '{
   'create-queryparser': {
      'name': '<parser name>',
      'runtimeLib': true,
      'class': '<queryparser class name>'}
}'

as in this example:

$ curl https://https://ss979914-us-west-2-aws.measuredsearch.com/solr/filmdemo/config -H 'Content-type:application/json' -d '{
   'create-queryparser': {
      'name': 'helloworld',
      'runtimeLib': true,
      'class': 'com.measuredsearch.queryparsers.HelloWorldQParserPlugin'}
}'

Test the Parser

We can now test to see if the parser works as expected:

$ curl "<Solr load balancer URL>/solr/<collection_name>/select?q=<search_string>&defType=<parser_name>&debug=true"

as in this example:

$ curl "https://ss979914-us-west-2-aws.measuredsearch.com/solr/filmdemo/select?q=MeasuredSearchRocks&defType=helloworld&debug=true"

Our example queryparser prepends "text:hello" to the querystring. We can see it here in the response. It is installed and is working correctly.

Update the Runtime Library

To update the runtime library to a newer version, or when you need to change the signing key, use the update-runtimelib button. You can select which JAR to update and to which version and whether or not to update the signature.

Delete the Runtime Library from the Collection

The delete-runtimelib button removes the JAR file from the classpath.

Please note, if we remove the JAR file from the classpath, we should unload the parser from the collection. To unload the parser from the collection, we can craft a cURL command:

$ curl https://<Solr load balancer URL>/solr/<collection_name>/config -H 'Content-type:application/json' -d '{
   'delete-queryparser': '<parser_name>'}'

Delete the JAR Blob

Click the Delete button of the corresponding JAR Blob ID and confirm. Please note, deleting JAR blob file from the .system collection does not remove the queryparser (if existing) and it will not perform a delete-runtimelib command.

Delete the Public Key

To delete the public key, click on the Delete button of the corresponding public key.

Please note, deleting the public key that is used by a runtime library will make the JAR file unusable. You should replace the original signature with one from a different public key before deleting the original public key.

Disable Runtime Library Support

By clicking the Disable Runtime Lib Support button and confirming, you will disable runtime library support on your Solr servers. This has the side-effect of restarting each node.