Solr Control Script Reference

Solr includes a script known as “bin/solr” that allows you to perform many common operations on your Solr installation or cluster.

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 this Guide, but particularly in the sections Starting Solr and Getting Started with SolrCloud.

Starting and Stopping

Start and Restart

The start command starts 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 proceed to starting Solr.

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

-a "<string>"

Optional

Default: none

Start Solr with additional JVM parameters, such as those starting with -X. If you are passing JVM parameters that begin with -D, you can omit the -a option.

Example:

bin/solr start -a "-Xdebug -Xrunjdwp:transport=dt_socket, server=y,suspend=n,address=1044"

-cloud or -c

Optional

Default: none

Start Solr in SolrCloud mode, which will also launch the embedded ZooKeeper instance included with Solr.

This option can be shortened to simply -c.

If you are already running a ZooKeeper ensemble that you want to use instead of the embedded (single-node) ZooKeeper, you should also either specify ZK_HOST in solr.in.sh/solr.in.cmd (see Updating Solr Include Files) or pass the -z parameter.

For more details, see the section SolrCloud Mode below.

Example: bin/solr start -c

-d <dir>

Optional

Default: server/

Define a server directory, defaults to server (as in, $SOLR_TIP/server). It is uncommon to override this option. When running multiple instances of Solr on the same host, it is more common to use the same server directory for each instance and use a unique Solr home directory using the -s option.

Example: bin/solr start -d newServerDir

-e <name>

Optional

Default: none

Start Solr with an example configuration. These examples are provided to help you get started faster with Solr generally, or just try a specific feature.

The available options are:

cloud
techproducts
schemaless
films

See the section Running with Example Configurations below for more details on the example configurations.

Example: bin/solr start -e schemaless

-f

Optional

Default: none

Start Solr in the foreground. You cannot use this option when running examples with the -e option.

Example: bin/solr start -f

-h <hostname>

Optional

Default: localhost

Start Solr with the defined hostname. If this is not specified, localhost is assumed.

Example: bin/solr start -h search.mysolr.com

-m <memory>

Optional

Default: none

Start Solr with the defined value as the min (-Xms) and max (-Xmx) heap size for the JVM.

Example: bin/solr start -m 1g

-noprompt

Optional

Default: none

Start Solr and suppress any prompts that may be seen with another option. This would have the side effect of accepting all defaults implicitly.

For example, when using the "cloud" example, an interactive session guides you through several options for your SolrCloud cluster. If you want to accept all of the defaults, you can simply add the -noprompt option to your request.

Example: bin/solr start -e cloud -noprompt

-p <port>

Optional

Default: 8983

Start Solr on the defined port. If this is not specified, 8983 will be used.

Example: bin/solr start -p 8655

-s <dir>

Optional

Default: server/solr

Sets the solr.solr.home system property. Solr will create core directories under this directory. This allows you to run multiple Solr instances on the same host while reusing the same server directory set using the -d parameter.

This parameter is ignored when running examples (-e), as the solr.solr.home depends on which example is run.

Example: bin/solr start -s newHome

-v

Optional

Default: none

Be more verbose. This changes the logging level of Log4j from INFO to DEBUG, having the same effect as if you edited log4j2.xml.

Example: bin/solr start -f -v

-q

Optional

Default: none

Be more quiet. This changes the logging level of Log4j from INFO to WARN, having the same effect as if you edited log4j2.xml. This can be useful in a production setting where you want to limit logging to warnings and errors.

Example: bin/solr start -f -q

-V

Optional

Default: none

Start Solr with verbose messages from the start script.

Example: bin/solr start -V

-z <zkHost>

Optional

Default: see description

Start Solr with the defined ZooKeeper connection string.

This option is only used with the -c option, to start Solr in SolrCloud mode. If ZK_HOST is not specified in solr.in.sh/solr.in.cmd and this option is not provided, Solr will start the embedded ZooKeeper instance and use that instance for SolrCloud operations.

Example: bin/solr start -c -z server1:2181,server2:2181

-force

Optional

Default: none

If attempting to start Solr as the root user, the script will exit with a warning that running Solr as "root" can cause problems. It is possible to override this warning with the -force parameter.

Example: sudo bin/solr start -force

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

It is not necessary to define all of the options when starting if the defaults are fine for your needs.

Setting Java System Properties

The bin/solr script will pass any additional parameters that 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 have defined ZK_HOST in solr.in.sh/solr.in.cmd (see xref:zookeeper-ensemble.adoc#updating-solr-include-files,Updating Solr Include Files>>) you can omit -z <zk host string> from all bin/solr commands.

When starting Solr in SolrCloud mode, if you do not define ZK_HOST in solr.in.sh/solr.in.cmd nor specify the -z option, then Solr will launch an embedded ZooKeeper server listening on the Solr port + 1000. For example, if Solr is running on port 8983, then the embedded ZooKeeper will listen on port 9983.

If your 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 Configuration.

Unless otherwise noted in the descriptions below, the examples 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 ports 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_TIP/server/solr/configsets.
techproducts: This example starts a single-node Solr instance with a schema designed for the sample documents included in the $SOLR_HOME/example/exampledocs directory.

The configset used can be found in $SOLR_TIP/server/solr/configsets/sample_techproducts_configs.

The data used can be found in $SOLR_HOME/example/exampledocs/.
schemaless: This example starts a single-node Solr instance using a managed schema, as described in the section Schema Factory Configuration, 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 incoming documents.

The configset used can be found in $SOLR_TIP/server/solr/configsets/_default.
films: This example starts a single-node Solr instance using a managed schema, as described in the section Schema Factory Configuration, and then uses the Schema API to create some custom fields. 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 incoming documents as well. It then loads some sample film data.

The configset used can be found in $SOLR_TIP/server/solr/configsets/_default.

The film data used can be found in $SOLR_HOME/example/films/films.json.

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 a running Solr node, which allows it to shutdown gracefully. The command will wait up to 180 seconds for Solr to stop gracefully and then will forcefully kill the process (kill -9).

bin/solr stop [options]

bin/solr stop -help

Stop Parameters

-p <port>

Optional

Default: none

Stop Solr running on the given port. If you are running more than one instance, or are running in SolrCloud mode, you either need to specify the ports in separate requests or use the -all option.

Example: bin/solr stop -p 8983

-all

Optional

Default: none

Stop all running Solr instances that have a valid PID.

Example: bin/solr stop -all

-k <key>

Optional

Default: none

Stop key used to protect from stopping Solr inadvertently; default is "solrrocks".

Example: bin/solr stop -k solrrocks

System Information

Version

The version command simply returns the version of Solr currently installed and immediately 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 include a status of each node of the cluster, as in this example:

Found 2 Solr nodes:

Solr process 39920 running on port 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"}}

Assert

The assert command sanity checks common issues with Solr installations. These include checking the ownership/existence of particular directories, and ensuring Solr is available on the expected URL. The command can either output a specified error message, or change its exit code to indicate errors.

As an example:

$ bin/solr assert --exists /opt/bin/solr

Results in the output below:

ERROR: Directory /opt/bin/solr does not exist.

Use bin/solr assert -help for a full list of options.

Healthcheck

The healthcheck command generates a JSON-formatted health report for a collection when running in 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 healthcheck [options]

bin/solr healthcheck -help

Healthcheck Parameters

-c <collection>

Required

Default: none

Name of the collection to run a healthcheck against.

Example: bin/solr healthcheck -c gettingstarted

-z <zkhost>

Optional

Default: localhost:9983

ZooKeeper connection string. If you are running Solr on a port other than 8983, you will have to specify the ZooKeeper connection string. By default, this will be the Solr port + 1000. This parameter is unnecessary if ZK_HOST is defined in solr.in.sh or solr.in.cmd.

Example: bin/solr healthcheck -z localhost:2181

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 or cores, or delete collections or cores.

Create a Core or Collection

The create command detects the mode that Solr is running in and creates either a core or collection depending on the mode. When running with SolrCloud, a collection would be created. When running a user-managed cluster or a single-node installation, a core would be created.

bin/solr create [options]

bin/solr create -help

Create Core or Collection Parameters

-c <name>

Required

Default: none

Name of the core or collection to create.

Example: bin/solr create -c mycollection

-d <confdir>

Optional

Default: _default

The configuration directory.

See the section Configuration Directories and SolrCloud below for more details about this option when running in SolrCloud mode.

Example: bin/solr create -d _default

-n <configName>

Optional

Default: see description

The configuration name. This defaults to the same name as the core or collection.

Example: bin/solr create -n basic

-p <port>

Optional

Default: see description

The port of a local Solr instance to send the create command to. By default the script tries to detect the port by looking for running Solr instances.

This option is useful if you are running multiple Solr instances on the same host, thus requiring you to be specific about which instance to create the core in.

Example: bin/solr create -p 8983

-s <shards> or -shards

Optional

Default: 1

Number of shards to split a collection into. Only applies when Solr is running in SolrCloud mode.

Example: bin/solr create -s 2

-rf <replicas> or -replicationFactor

Optional

Default: 1

Number of copies of each document in the collection. The default is 1 (no replication).

Example: bin/solr create -rf 2

-force

Optional

Default: none

If attempting to run create as "root" user, the script will exit with a warning that running Solr or actions against Solr as "root" can cause problems. It is possible to override this warning with the -force parameter.

Example: bin/solr create -c foo -force

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 several use cases for how collections and configuration directories work. The main decision you need to make is whether a configuration directory in ZooKeeper should be shared across multiple collections.

Let’s work through a few examples to illustrate how configuration directories work in SolrCloud.

First, if you don’t provide the -d or -n options, then the default configuration ($SOLR_TIP/server/solr/configsets/_default/conf) is uploaded to ZooKeeper using the same name as the collection.

For example, the following command will result in the _default configuration being uploaded to /configs/contacts in ZooKeeper: bin/solr create -c contacts.

If you create another collection with bin/solr create -c contacts2, then another copy of the _default 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 _default -n basic will upload the server/solr/configsets/_default/conf directory to ZooKeeper as /configs/basic.

Notice that we used the -d option 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 directory using the -d option. For instance, the command bin/solr create -c mycoll -d /tmp/myconfigs, will upload /tmp/myconfigs into ZooKeeper under /configs/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 _default schema can mutate as data is indexed, since it has schemaless functionality (i.e., data-driven changes to the schema). 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.

You can turn off schemaless functionality for a collection with the following command, assuming the collection name is mycollection.

$ bin/solr config -c mycollection -p 8983 -action set-user-property -property update.autoCreateFields -value false

See also the section Set or Unset Configuration Properties.

Delete Core or Collection

The delete command detects the mode that Solr is running in and then deletes the specified core (user-managed or single-node) or collection (SolrCloud) as appropriate.

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 with bin/solr create -c contacts, then the delete command bin/solr delete -c contacts will check to see if the /configs/contacts configuration directory is being used by any other collections. If not, then the /configs/contacts directory is removed from ZooKeeper.

Delete Core or Collection Parameters

-c <name>

Required

Default: none

Name of the core or collection to delete.

Example: bin/solr delete -c mycoll

-deleteConfig

Optional

Default: true

Whether or not the configuration directory should also be deleted from ZooKeeper.

If the configuration directory is being used by another collection, then it will not be deleted even if you pass -deleteConfig as true.

Example: bin/solr delete -deleteConfig false

-p <port>

Optional

Default: see description

The port of a local Solr instance to send the delete command to. By default the script tries to detect the port by looking for running Solr instances.

This option is useful if you are running multiple Solr instances on the same host, thus requiring you to be specific about which instance to delete the core from.

Example: bin/solr delete -p 8983

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_AUTH_TYPE="basic"
SOLR_AUTHENTICATION_OPTS="-Dsolr.httpclient.config=/path/to/solr-9.2.1/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

Optional

Default: none

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

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

-prompt

Optional

Default: none

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

Either -credentials or -prompt must be specified.

-blockUnknown

Optional

Default: true

When true, blocks all unauthenticated users from accessing Solr. When false, unauthenticated users will still be able to access Solr, but only for operations not explicitly requiring a user role in the Authorization plugin configuration.

-updateIncludeFileOnly

Optional

Default: false

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

-z

Optional

Default: none

Defines the ZooKeeper connect string. This is useful if you want to enable authentication before all your Solr nodes have come up. Unnecessary if ZK_HOST is defined in solr.in.sh or solr.in.cmd.

-d

Optional

Default: $SOLR_TIP/server

Defines the Solr server directory, by default $SOLR_TIP/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

Optional

Default: server/solr

Defines the location of solr.solr.home, 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.

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

Set or Unset Configuration Properties

The bin/solr script enables a subset of the Config API: (un)setting common properties and (un)setting user-defined properties.

bin/solr config [options]

bin/solr config -help

Set or Unset Common Properties

To set the common property updateHandler.autoCommit.maxDocs to 100 on collection mycollection:

bin/solr config -c mycollection -p 8983 -action set-property -property updateHandler.autoCommit.maxDocs -value 100

The default -action is set-property, so the above can be shortened by not mentioning it:

bin/solr config -c mycollection -p 8983 -property updateHandler.autoCommit.maxDocs -value 100

To unset a previously set common property, specify -action unset-property with no -value:

bin/solr config -c mycollection -p 8983 -action unset-property -property updateHandler.autoCommit.maxDocs

Set or Unset User-Defined Properties

To set the user-defined property update.autoCreateFields to false (to disable Schemaless Mode):

bin/solr config -c mycollection -p 8983 -action set-user-property -property update.autoCreateFields -value false

To unset a previously set user-defined property, specify -action unset-user-property with no -value:

bin/solr config -c mycollection -p 8983 -action unset-user-property -property update.autoCreateFields

Config Parameters

-c <name>

Required

Default: none

Name of the core or collection on which to change configuration.

-action <name>

Optional

Default: set-property

Config API action, one of: set-property, unset-property, set-user-property, unset-user-property.

-property <name>

Required

Default: none

Name of the property to change.

-value <new-value>

Optional

Default: none

Set the property to this value.

-z <zkHost>

Optional

Default: none

The ZooKeeper connection string, usable in SolrCloud mode. Unnecessary if ZK_HOST is defined in solr.in.sh or solr.in.cmd.

-p <port>

Optional

Default: none

localhost port of the Solr node to use when applying the configuration change.

-solrUrl <url>

Optional

Default: none

Base Solr URL, which can be used in SolrCloud mode to determine the ZooKeeper connection string if that’s not known.

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]

bin/solr zk -help

Solr should have been 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.

ZK Upload Parameters

All parameters below are required.

-n <name>

Required

Default: none

Name of the configuration set in ZooKeeper. This command will upload the configuration set to the "configs" ZooKeeper node giving it the name specified.

You can see all uploaded configuration sets in the Admin UI via the Cloud screens. Choose Cloud → Tree → configs to see them.

If a pre-existing configuration set is specified, it will be overwritten in ZooKeeper.

Example: -n myconfig

-d <configset dir>

Required

Default: none

The path of the configuration set to upload. It should have a conf directory immediately below it that in turn contains solrconfig.xml etc.

If just a name is supplied, $SOLR_TIP/server/solr/configsets will be checked for this name. An absolute path may be supplied instead.

Examples:

-d directory_under_configsets
-d /path/to/configset/source

-z <zkHost>

Required

Default: none

The ZooKeeper connection string. Is not required if ZK_HOST is defined in solr.in.sh or solr.in.cmd.

Example: -z 123.321.23.43:2181

An example of this command with all of the parameters is:

bin/solr zk upconfig -z 111.222.333.444:2181 -n mynewconfig -d /path/to/configset

Reload Collections When Changing Configurations

This command does not automatically make changes effective! It simply uploads the configuration sets to ZooKeeper. You can use the Collection API’s RELOAD command to reload any collections that uses this configuration set.

Download a Configuration Set

Use the zk downconfig command to download a configuration set from ZooKeeper to the local filesystem.

ZK Download Parameters

All parameters listed below are required.

-n <name>

Required

Default: none

Name of the configset in ZooKeeper to download. The Admin UI Cloud → Tree → configs node lists all available configuration sets.

Example: -n myconfig

-d <configset dir>

Required

Default: none

The path to write the downloaded configuration set into. If just a name is supplied, $SOLR_TIP/server/solr/configsets will be the parent. An absolute path may be supplied as well.

In either case, pre-existing configurations at the destination will be overwritten!

Examples:

-d directory_under_configsets
-d /path/to/configset/destination

-z <zkHost>

Required

Default: none

The ZooKeeper connection string. Unnecessary if ZK_HOST is defined in solr.in.sh or solr.in.cmd.

Example: -z 123.321.23.43:2181

An example of this command with all parameters is:

bin/solr zk downconfig -z 111.222.333.444:2181 -n mynewconfig -d /path/to/configset

A best practice is to keep your configuration sets in some form of version control as the system-of-record. In that scenario, downconfig should rarely be used.

Copy between Local Files and ZooKeeper znodes

Use the zk cp command for transferring files and directories between ZooKeeper znodes and your local drive. This command will copy from the local drive to ZooKeeper, from ZooKeeper to the local drive or from ZooKeeper to ZooKeeper.

ZK Copy Parameters

-r

Optional

Default: none

Do a recursive copy. The command will fail if the <src> has children unless -r is specified.

Example: -r

<src>

Required

Default: none

The file or path to copy from. If prefixed with zk: then the source is presumed to be ZooKeeper. If no prefix or the prefix is file: this is the local drive. At least one of <src> or <dest> must be prefixed by 'zk:' or the command will fail.

Examples:

zk:/configs/myconfigs/solrconfig.xml
file:/Users/apache/configs/src

<dest>

Required

Default: none

The file or path to copy to. If prefixed with zk: then the source is presumed to be ZooKeeper. If no prefix or the prefix is file: this is the local drive.

At least one of <src> or <dest> must be prefixed by zk: or the command will fail. If <dest> ends in a slash character it names a directory.

Examples:

zk:/configs/myconfigs/solrconfig.xml
file:/Users/apache/configs/src

-z <zkHost>

Required

Default: none

The ZooKeeper connection string. Optional if ZK_HOST is defined in solr.in.sh or solr.in.cmd.

Example: -z 123.321.23.43:2181

An example of this command with the parameters is:

Recursively copy a directory from local to ZooKeeper.

bin/solr zk cp -r file:/apache/confgs/whatever/conf zk:/configs/myconf -z 111.222.333.444:2181

Copy a single file from ZooKeeper to local.

bin/solr zk cp zk:/configs/myconf/managed_schema /configs/myconf/managed_schema -z 111.222.333.444:2181

Remove a znode from ZooKeeper

Use the zk rm command to remove a znode (and optionally all child nodes) from ZooKeeper.

ZK Remove Parameters

-r

Optional

Default: none

Do a recursive removal. The command will fail if the <path> has children unless -r is specified.

Example: -r

<path>

Required

Default: none

The path to remove from ZooKeeper, either a parent or leaf node.

There are limited safety checks, you cannot remove / or /zookeeper nodes.

The path is assumed to be a ZooKeeper node, no zk: prefix is necessary.

Examples:

/configs
/configs/myconfigset
/configs/myconfigset/solrconfig.xml

-z <zkHost>

Required

Default: none

The ZooKeeper connection string. Optional if ZK_HOST is defined in solr.in.sh or solr.in.cmd.

Example: -z 123.321.23.43:2181

Examples of this command with the parameters are:

bin/solr zk rm -r /configs

bin/solr zk rm /configs/myconfigset/schema.xml

Move One ZooKeeper znode to Another (Rename)

Use the zk mv command to move (rename) a ZooKeeper znode.

ZK Move Parameters

<src>

Required

Default: none

The znode to rename. The zk: prefix is assumed.

Example: /configs/oldconfigset

<dest>

Required

Default: none

The new name of the znode. The zk: prefix is assumed.

Example: /configs/newconfigset

-z <zkHost>

Required

Default: none

The ZooKeeper connection string. Unnecessary if ZK_HOST is defined in solr.in.sh or solr.in.cmd.

Example: -z 123.321.23.43:2181

An example of this command is:

bin/solr zk mv /configs/oldconfigset /configs/newconfigset

List a ZooKeeper znode’s Children

Use the zk ls command to see the children of a znode.

ZK List Parameters

-r

Optional

Default: none

Recursively list all descendants of a znode.

Example: -r

<path>

Required

Default: none

The path on ZooKeeper to list.

Example: /collections/mycollection

-z <zkHost>

Required

Default: none

The ZooKeeper connection string. Optional if ZK_HOST is defined in solr.in.sh or solr.in.cmd.

Example: -z 123.321.23.43:2181

An example of this command with the parameters is:

bin/solr zk ls -r /collections/mycollection

bin/solr zk ls /collections

Create a znode (supports chroot)

Use the zk mkroot command to create a znode. The primary use-case for this command to support ZooKeeper’s "chroot" concept. However, it can also be used to create arbitrary paths.

Create znode Parameters

<path>

Required

Default: none

The path on ZooKeeper to create. Intermediate znodes will be created if necessary. A leading slash is assumed even if not specified.

Example: /solr

-z <zkHost>

Required

Default: none

The ZooKeeper connection string. Optional if ZK_HOST is defined in solr.in.sh or solr.in.cmd.

Example: -z 123.321.23.43:2181

Examples of this command:

bin/solr zk mkroot /solr -z 123.321.23.43:2181

bin/solr zk mkroot /solr/production

Exporting Documents to a File

The export command will allow you to export documents from a collection in either JSON or Javabin format. All documents can be exported, or only those that match a query.

bin/solr export [options]

bin/solr export -help

The bin/solr export command takes the following parameters:

url

Required

Default: none

Fully-qualified address to a collection.

Example: -url http://localhost:8983/solr/techproducts

format

Optional

Default: jsonl

The file format of the export, jsonl or javabin. Choosing javabin exports to a file with extension .javabin which is the native Solr format. This is compact and faster to import.

-out

Optional

Default: see description

The file name of the export. If the file name ends with json.gz the output will be compressed into a .gz file.

If not provided, a file will be created with the name of the collection, as in <collection>.json.

query

Optional

Default: *:*

A custom query. The default is *:* which will export all documents.

fields

Optional

Default: none

A comma separated list of fields to be exported. If not provided, all fields will be included.

limit

Optional

Default: 100

The number of documents to export. The value -1 will export all documents.

Examples

Export all documents from a collection gettingstarted:

bin/solr export -url http://localhost:8983/solr/gettingstarted limit -1

Export all documents of collection gettingstarted into a file called 1MDocs.json.gz as a zipped JSON file:

bin/solr export -url http://localhost:8983/solr/gettingstarted -1 -out 1MDocs.json.gz

Importing Documents to a Collection

Once you have exported documents in a file, you can use the /update request handler to import them to a new Solr collection.

Example: import jsonl files

curl -X POST -d @gettingstarted.json http://localhost:8983/solr/gettingstarted/update/json/docs?commit=true

Example: import javabin files

curl -X POST --header "Content-Type: application/javabin" --data-binary @gettingstarted.javabin http://localhost:8983/solr/gettingstarted/update?commit=true