1.5. Solr Control Script Reference

You can start and stop Solr, create and delete collections or cores, perform operations on ZooKeeper and check the status of Solr and configured shards.

You can find the script in the bin/ directory of your Solr installation. The bin/solr script makes Solr easier to work with by providing simple commands and options to quickly accomplish common goals.

More examples of bin/solr in use are available throughout the Solr Reference Guide, but particularly in the sections Running Solr and Getting Started with SlorCloud.

Starting and Stopping

Start and Restart

The start command start Solr. The restart command allows you to restart Solr while it is already running or if it has been stopped already.

The start and restart commands have several options to allow you to run in SolrCloud mode, use an example configuration set, start with a hostname or port that is not the default and point to a local ZooKeeper ensemble.

bin/solr start [options]
bin/solr start -help
bin/solr restart [options]
bin/solr restart -help

When using the restart command, you must pass all of the parameters you initially passed when you started Solr. Behind the scenes, a stop request is initiated, so Solr will be stopped before being started again. If no nodes are already running, restart will skip the step to stop and process to starting Solr.

Available Parameters

The bin/solr script provides many options to allow you to customize the server in common ways, such as changing the listening port. However, most of the defaults are adequate for most Solr installations, especially when just getting started.

To emphasize how the default settings work take a moment to understand that the following commands are equivalent:

bin/solr start
bin/solr start -h localhost -p 8983 -d server -s solr -m 512m

Setting Java System Properties

The bin/solr script will pass any additional parameters begin with -D to the JVM, which allows you to set arbitrary Java system properties.

For example, to set the auto soft-commit frequency to 3 seconds, you can do:

bin/solr start -Dsolr.autoSoftCommit.maxTime=3000

SolrCloud Mode

The -c and -cloud options are equivalent:

bin/solr start -c
bin/solr start -cloud

If you specify a ZooKeeper connection string, such as -z 192.168.1.4:2181, then Solr will connect to ZooKeeper and join the cluster.

If you do not specify the -z option when starting Solr in cloud mode, the Solr will launch an embedded Zookeeper server listening on the Solr port + 1000 i.e., if Solr is running on port 8983, then the embedded ZooKeeper will be listening on port 9983.

If you ZooKeeper connection string uses a chroot, such as localhost:2181/solr, then you need to create the /solr znode before launching SolrCloud using the bin/solr script.
+ To do this use the mkroot command outlined below, for example: bin/solr zk mkroot/solr -z 192.168.1.4:2181

When starting in SolrCloud mode, the interactive script session will prompt you to choose a configset to use.

For more information about starting Solr in SolrCloud mode, see also the section Getting Started with SolrCloud

Running with example Configurations

bin/solr start -e <name>

The example configurations allow you to get started quickly with a configuration that mirrors what you hope to accomplish with Solr.

Each example launches Solr with a managed schema, which allows use of the Schema API to make schema edits, but does not allow manual editing of a Schema file If you would prefer to manually modify a schema.xml file directly, you can change this default as described in the section Schema Factory Definition in SolrConfig.

Unless otherwise noted in the descriptions below, the example do not enable SolrCloud nor schemaless mode.

The following examples are provided:

• cloud: This example starts a 1-4 node SolrCloud cluster on a single machine. When chosen, an interactive session will start to guide you through options to select the initial configset to use, the number of nodes for your example cluster, the prots to use, and name of the collection to be created. When using this example, you can choose from any of the available configsets found in $SOLR_HOME/server/solr/configsets.

• techproducts: This example starts Solr in standalone mode with a schema designed for the sample documents included in the $SOLR_HOME/example/exampledocs directory. The configset used can be found in $SOLR_HOME/server/solr/configsets/sample_techporducts_configs.

• dih: This example starts Solr in standalone mode with the DataImportHandler(DIH) enabled and several example dataconfig.xml files pre-configured for different types of data supported with DIH (such as, database contents, email, RSS feeds, etc.). The configset used is customized for DIH, and is found in $SOLR_HOME/example/example-DIH/solr/conf. For more information about DIH, see the section Uploading Structured Data Store Data with the Data Import Handler.

• schemaless: This example starts Solr in standalon mode using a managed schema, as described in the section Schema Factory Definition in SolrConfig, and provides a very minimal pre-defined schema. Solr will run in Schemaless Mode with this configuration, where Solr will create fields in the schema on the fly and will guess field types used in imcoming documents. The configset used can be found in $SOLR_HOME/server/solr/configsets/data_driven_schema_configs.

The run in-foreground option (-f) is not compatible with the -e option since the script needs to perform additional tasks after starting the Solr server.

Stop

The stop command sends a STOP request to running Solr node, which allows it to shutdown gracefully. The command will wait up to 5 seconds for Solr to stop gracefully and then will forcefully kill the process (kill -9).

bin/solr stop [options]
bin/solr stop -help

Available Parameters

System Information

Version

The version command simply returns the version of Solr currently installed and immediatedly exists.

$ bin/solr version
X.Y.0

Status

The status command displays basic JSON-formatted information for any Solr nodes found running on the local system.

The status command uses the SOLR_PID_DIR environment variable to locate Solr process ID files to find running Solr instances, which defaults to the bin directory.

bin/solr status

The output will includes a status of each node of the cluster, as in this example:

Found 2 Solr nodes:
Solr process 39920 running on prot 7574
{
    "solr_home":"/Applications/Solr/example/cloud/node2/solr/",
    "version":"X.Y.0",
    "startTime":"2015-02-10T17:19:54.739Z",
    "uptime":"1 days, 23 hours, 55 minutes, 48 seconds",
    "memory":"77.2 MB (%15.7) of 490.7 MB",
    "cloud":{
    "ZooKeeper":"localhost:9865",
    "liveNodes":"2",
    "collections":"2"
    }
}

Solr process 39827 running on port 8865
{
    "solr_home":"/Applications/Solr/example/cloud/node1/solr/",
    "version":"X.Y.0",
    "startTime":"2015-02-10T17:19:49.057Z",
    "uptime":"1 days, 23 hours, 55 minutes, 54 seconds",
    "memory":"94.2 MB (%19.2) of 490.7 MB",
    "cloud":{
        "ZooKeeper":"localhost:9865",
        "liveNodes":"2",
        "collections":"2"
    }
}

Healthcheck

The healthcheck command generates a JSON-formatted health report for a collection when running on SolrCloud mode. The health report provides information about the state of every replica for all shards in a collection, including the number of committed documents and its current state.

bin/solr helthcheck [options]
bin/solr healthcheck -help

Available Parameters

Below is an example healthcheck request and response using a non-standard ZooKeeper connect string, with 2 nodes running:

$ bin/solr healthcheck -c gettingstarted -z localhost:9865

{
    "collection":"gettingstarted",
    "status":"healthy",
    "numDocs":0,
    "numShards":2,
    "shards":[
    {
        "shard":"shard1",
        "status":"healthy",
        "replicas":[
            {
            "name":"core_node1",
            "url":"http://10.0.1.10:8865/solr/gettingstarted_shard1_replica2/",
            "numDocs":0,
            "status":"active",
            "uptime":"2 days, 1 hours, 18 minutes, 48 seconds",
            "memory":"25.6 MB (%5.2) of 490.7 MB",
            "leader":true},
            {
            "name":"core_node4",
            "url":"http://10.0.1.10:7574/solr/gettingstarted_shard1_replica1/",
            "numDocs":0,
            "status":"active",
            "uptime":"2 days, 1 hours, 18 minutes, 42 seconds",
            "memory":"95.3 MB (%19.4) of 490.7 MB"
            }
        ]
    },
        {
        "shard":"shard2",
        "status":"healthy",
        "replicas":[
            {
            "name":"core_node2",
            "url":"http://10.0.1.10:8865/solr/gettingstarted_shard2_replica2/",
            "numDocs":0,
            "status":"active",
            "uptime":"2 days, 1 hours, 18 minutes, 48 seconds",
            "memory":"25.8 MB (%5.3) of 490.7 MB"},
            {
            "name":"core_node3",
            "url":"http://10.0.1.10:7574/solr/gettingstarted_shard2_replica1/",
            "numDocs":0,
            "status":"active",
            "uptime":"2 days, 1 hours, 18 minutes, 42 seconds",
            "memory":"95.4 MB (%19.4) of 490.7 MB",
            "leader":true}]}]}

Collections and Cores

The bin/solr script can also help you create new collections (in SolrCloud mode) or cores (in standalone mode), or delete collections.

Create

The create command detects the mode that Solr is running in (standalone or SolrCloud) and then creates a core or collection depending on the mode.

bin/solr create [options]
bin/solr create -help

Available Parameters

Configuration Directories and SolrCloud

Before creating a collection in SolrCloud, the configuration directory used by the collection must be uploaded to ZooKeeper. The create command supports serveral use cases for how collections and configuration directories work. The main decision you need to ake is whether a configuration directory in ZooKeeper should be shared across multiple collections.

Let's work through a few examples to illustrate hwo configuration directories work in SolrCloud.

First, if you don't provide the -d or -n options, then the defualt configuration ($SOLR_HOME/server/solr/configsets/data_driven_schema_configs/conf) is uploaded to ZooKeeper using the same name as the collection. For example, the following command will result in the data_driven_schema_configs configuration being uploaded to /config/contacts in ZooKeeper: bin/solr create -c contacts. If you careate another collection, by doing bin/solr create -c contacts2, then another copy of the data_driven_schema_configs directory will be uploaded to ZooKeeper under /configs/contacts2. Any changes you make to the configuration for the contacts collection will not affect the contacts2 collection. Put simply, the default behavior creates a unique copy of the configuration directory for each collection you create.

You can override the name given to the configuration directory in ZooKeeper by using the -n option. For instance, the command bin/solr create -c logs -d basic_configs -n basic will upload the server/solr/configsets/basic_configs/conf directory to ZooKeeper as /config/basic.

Notice that we used the -d options to specify a different configuration than the default. Solr provides several built-in configurations under server/solr/configsets. However you can also provide the path to your own configuration deirctory using the -d option. For instance the command bin/solr create -c mycoll -d /tmp/myconfigs, will upload /tmp/myconfigs into ZooKeeper under /config/mycoll. To reiterate, the configuration directory is named after the collection unless you override it using the -n option.

Other collections can share the same configuration by specifying the name of the shared configuration using the -n option. For instance, the following command will create a new collection that shares the basic configuration created previously: bin/solr create -c logs2 -n basic.

Data-driven Schema and Shared Configurations

The data_driven_schema_configs schema can mutate as data is indexed. Consequently, we recommend that you do not share data-driven configurations between collections unless you are certain that all collections should inherit the changes made when indexing data into one of the collections.

Delete

The delete command detects the mode that Solr is running in (standalone or SolrCloud) and then deletes the specified core (standalone) or collection (SolrCloud) as apporpriate.

bin/solr delete [options]
bin/solr delete -help

If running in SolrCloud mode, the delete command checks if the configuration directory used by the collection you are deleting is being used by other collections. If not, then the configuration directory is also deleted from ZooKeeper. For Example, if you created a collection by doing bin/solr create -c contacts, then the delete command bin/solr delete -c contacts will check to see if the /config/contacts configuration directory is being used by any other collections. If not, then the /configs/contacts directory is removed from ZooKeeper.

Available Parameters

Authentication

The bin/solr script allows enabling or disabling Basic Authentication, allowing you to configure authentication from the command line.

Currently, this script only enables Basic Authentication, and is only available when using SolrCloud mode.

Enabling Basic Authentication

The command bin/solr auth enable configures Solr to use Basic Authentication when accessing the User Interface, using bin/solr and any API requests.

For more information about Solr's authentication plugins, see the section Securing Solr. For more information on Basic Authentication support specifically, see the section Basic Authentication Plugin.

The bin/solr auth enable command makes several changes to enable Basic Authentication:

• Creates a security.json file and uploads it to ZooKeeper. The security.json file will look similar to:

  {

    "authentication":{
    "blockUnknown": false,
    "class":"solr.BasicAuthPlugin",
    "credentials":{
        "user":"vgGVo69YJeUg/O6AcFiowWsdyOUdqfQvOLsrpIPMCzk= 7iTnaKOWe+Uj5ZfGoKKK2G6hrcF10h6xezMQK+LBvpI="}
    },
    "authorization":{
        "class":"solr.RuleBasedAuthorizationPlugin",
        "permissions":[
            {"name":"security-edit", "role":"admin"},
            {"name":"collection-admin-edit", "role":"admin"},
            {"name":"core-admin-edit", "role":"admin"}
        ],
        "user-role":{"user":"admin"}
    }
  

  }

• Adds two lines to bin/solr.in.sh or bin/solr.in.cmd to set the authentication type, and the path to basicAuth.conf:

  The following lines added by ./solr for enabling BasicAuth

  SOLR_AUT_TYPE = "basic" SOLR_AUTHENTICATION_OPTS="_Dsolr.httpclient.config=/path/to/solr-6.6.0/server/solr/basicAuth.conf"

• Creates the file server/solr/basicAuth.conf to store the credential information that is used with bin/solr commands.

The command takes the following parameters:

-credentials

The username and password in the format of username:password of the initial user.

If you perfer not to pass the username and password as an argument to the scritp, you can choose the -prompt option. Either -credentials or -prompt` must be specified.

-prompt

If prompt is preferred, pass true as a parameter to reuest the script to prompt the user to enter a username and password.

Either -credentials or -prompt must be specified.

-blockUnknown

When true, blocks all unauthenticated users from accessing Solr. This defaults to false, which means unauthenticated users will still be able to access Solr.

updateIncludeFileOnly

When true, only the settings in bin/solr.in.sh or bin/solr.in.cmd will be updated, and secturity.json will not be created.

-z

Defines the ZooKeeper connect string. This is useful if you want to enable authentication before all your Solr nodes have come up.

-d

Defines the Solr server directory, by default $SOLR_HOME/server. It is not common to need to override the default, and is only needed if you have customized the $SOLR_HOME directory path.

-s

Defines the location of solr.solr.name, which by default is server/solr. If you have multiple instances of Solr on the same host, or if you have customized the $SOLR_HOME directory path, you likely need to define this.

Disableing Basic Authentication

You can disable Basic Authentication with bin/solr auth disable.

If the -updateIncludeFileOnly option is set to true, then only the settings in bin/solr.in.sh or bin/solr.in.cmd will be updated, and security.json will not be removed.

If the -updateIncludeFileOnly option is set to false, then the settings in bin/solr.in.sh or bin/solr.in.cmd will be updated, and security.json will be removed. however, the basicAuth.conf file is not removed with either option.

ZooKeeper Operations

The bin/solr script allows certain operations affecting ZooKeeper. These operations are for SolrCloud mode only. The operations are available as sub-commands, which each have their own set of options.

bin/solr zk [sub-command][options]

Solr should have heeen started at least once before issuing these commands to initialize ZooKeeper with the znodes solr expects. Once ZooKeeper is initialized, Solr doesn't need to be running on any node to use these commands.

Upload a configuration Set

Use the zk upconfig command to upload one of the pre-configured configuration set or a customized configuration set to ZooKeeper.