solrctl Reference
The solrctl
utility is a wrapper shell script included with Cloudera
Search for managing collections, instance directories, configs, and more.
Make sure that the host on which you are running the solrctl
utility has
either a Gateway or Solr Server role
assigned.
In general, if an operation succeeds, solrctl
exits silently with a success
exit code. If an error occurs, solrctl
prints a diagnostics message combined
with a failure exit code. solrctl
supports specifying a
log4j.properties
file by setting the LOG4J_PROPS
environment variable. By default, the LOG4J_PROPS
setting specifies the
log4j.properties
in the Solr configuration directory (for example,
/etc/solr/conf/log4j.properties
). Many solrctl
commands
redirect stderr
to /dev/null
, so Cloudera recommends that
your log4j
properties file specify a location other than
stderr
for log output.
You can run solrctl
on any host that is configured as part of the SolrCloud
deployment (the Solr service in Cloudera Manager environments) . To run
any solrctl
command on a host outside of SolrCloud deployment, ensure that
SolrCloud hosts are reachable and provide --zk
and --solr
command line options.
If you are using solrctl
to manage your deployment in an environment that
requires Kerberos authentication, you must have a valid Kerberos ticket, which you can get
using kinit
.
For collection configuration, users have the option of interacting directly with ZooKeeper
using the instancedir
option or using the Solr ConfigSets API using the
config
option. For more information, see Managing Configuration Using Configs or Instance
Directories.
Command Syntax
The general solrctl
command syntax is:
solrctl [options] command [command-arg] [command [command-arg]] ...
Each element and its possible values are described in the following sections.
solrctl Options
Option | Description |
---|---|
--solr <solr_uri> |
Directs solrctl to a SolrCloud web API available at the
specified URI. This option is required for hosts running outside of SolrCloud. A
sample URI might be:
http://search01.example.com:8983/solr . |
--zk <zk_ensemble> |
Directs solrctl to a particular ZooKeeper quorum. This
option is required for hosts running outside of SolrCloud. For example:
zk01.example.com:2181,zk02.example.com:2181,zk03.example.com:2181/solr .
Output from solrctl commands that use the --zk
option is sent to /dev/null , so no results are displayed. |
--jaas /path/to/jaas.conf |
Used to identify a JAAS configuration that specifies the principal with
permissions to modify Solr metadata. The principal is typically
solr@EXAMPLE.COM . In Kerberos-enabled environments where
ZooKeeper ACLs protect Solr metadata, you must use this parameter when modifying
metadata. |
--help |
Prints help. |
--quiet |
Suppresses most solrctl messages. |
--debug |
Prints errors to stdout . |
--trace |
Prints the executed commands to stdout . |
Commands and Arguments
The solrctl
commands init
, instancedir
,
config
, collection
and cluster
affect
the entire SolrCloud deployment and only need to be run once per required operation.
The solrctl core
command affects a single SolrCloud host.
Command | Argument | Description |
---|---|---|
init |
Initializes a SolrCloud deployment. Must be run before starting solr-server daemons for the first time. The command has a built-in security check that prevents it from running on a deployment that has already been initialized. | |
[--force] | Allows you to re-initialize an already initialized SolrCloud deployment. Use this command cautiously because it erases all SolrCloud deployment state information from ZooKeeper, including all configuration files. It does not delete collections. | |
instancedir |
Manipulates instance directories. | |
--generate <path> [-schemaless] |
--generate <path> : Generates an instance
directory template on the local filesystem at <path>. The
configuration files are located in the conf subdirectory under
<path>. If used with the -schemaless
option, it generates a schemaless instance directory template. For more information
on schemaless support, see Schemaless Mode Overview and Best
Practices. |
|
--create <name>
<path> |
Uploads a copy of the instance directory from <path> on
the local filesystem to ZooKeeper. If an instance directory with the specified
<name> already exists, this command fails. Use
--update to modify existing instance directories. |
|
--update <name>
<path> |
Overwrites an existing instance directory in ZooKeeper using the specified
files on the local filesystem. This command is analogous to first running
--delete <name> followed by
--create <name>
<path> . |
|
--get <name>
<path> |
Downloads the specified instance directory from ZooKeeper to the specified path
on the local filesystem. You can then edit the configuration and then re-upload it
using --update . |
|
--delete <name> |
Deletes the specified instance directory from ZooKeeper. | |
--list |
Lists existing instance directories, including configs created by the
solrctl config command. |
|
config |
Manipulates configs. | |
--create name <baseConfig> [-p
<name>=<value> |
Creates a new config based on an existing config. The config is created with
the specified name, using <baseConfig> as
the template. For more information about config templates, see Config Templates. The -p
name=value option overrides a <baseConfig> setting.
The only config property that you can override is immutable , so the
possible options are -p immutable=true and -p
immutable=false . If you are copying an immutable config, such as a
template, use -p immutable=false to make sure that you can edit the
new config. |
|
--upload name
path |
Uploads a new configset in zip file format. You cannot use this option to
update an existing config. The script will ask you to delete the existing version
before allowing you to upload the new one. The path argument of
this command needs to point to the local directory containing the instance
configuration (meaning it has a conf subdirectory and the config files like
conf/solrconfig.xml ). This can also be an instance
configuration directory generated using solrctl instancedir --generate
name or downloaded using solrctl
instancedir --get name
path . The underlying Solr API requires a .zip
archive to be created, this is automatically performed by the command. |
|
--delete name |
Deletes the specified config. You cannot delete an immutable config without
accessing ZooKeeper directly as the solr super user. |
|
collection |
Manipulates collections. | |
--create <name> -s
<numShards> [-a] [-c
<configName>] [-r
<replicationFactor>] [-m
<maxShardsPerHost>] [-n
<hostList>]] |
Creates a new collection with
<numShards> shards.The
The collection uses the specified
The maximum shards per host is
determined by The only required
parameters are |
|
--delete <name> |
Deletes a collection. | |
--reload <name> |
Reloads a collection. | |
--stat <name> |
Outputs SolrCloud specific run-time information for a collection. | |
--deletedocs <name> |
Purges all indexed documents from a collection. | |
--list |
Lists all collections. | |
--create-snapshot <snapshotName> -c
<collectionName> |
Creates a named snapshot for the specified collection. | |
--delete-snapshot <snapshotName> -c
<collectionName> |
Deletes the specified snapshot for the specified collection. | |
--describe-snapshot <snapshotName> -c
<collectionName> |
Provides detailed information about a snapshot for the specified collection. | |
--list-snapshots
<collectionName> |
Lists all snapshots for the specified collection. | |
--prepare-snapshot-export <snapshotName> -c
<collectionName> -d
<destDir> |
Prepares the snapshot for export to a remote cluster. If you are exporting the snapshot to the local cluster, you do not need to run this command. This command generates collection metadata as well as information about the Lucene index files corresponding to the snapshot. The destination HDFS directory path (specified by the If you are running the snapshot export command on a remote cluster, specify the
HDFS protocol (such as WebHDFS or HFTP) to be used for accessing the Lucene index
files corresponding to the snapshot on the source cluster. This configuration is
driven by the |
|
--export-snapshot <snapshotName> -c
<collectionName>|-s <sourceDir> -d
<destDir> |
Creates a backup copy of the Solr collection metadata as well as the associated
Lucene index files at the specified location. If exporting to a local cluster, use
the -c <collectionName> argument. If
exporting to a remote cluster, use the -s
<sourceDir> argument. The
configuration option specifies the
directory path where this backup copy is be created. This directory must exist
before exporting the snapshot, and the Solr superuser (solr , by
default) must be able to write to it. |
|
--restore <restoreCollectionName> -l
<backupLocation> -b <snapshotName>
-i <requestId> [-a] [-c <configName>]
[-r <replicationFactor>] [-m
<maxShardsPerHost>] [-n
<selectedNodes>] |
Restores the state of an earlier created backup as a new Solr collection. Run this command on the cluster on which you want to restore the backup. The The Because the restore operation can take a long time to complete depending on the
size of the exported snapshot, it is run asynchronously. The The optional The optional The optional The optional The optional |
|
--request-status <requestId> |
Displays the status of the specified operation. The status can be one of the following:
|
|
core |
Manipulates cores. | |
--create <name> [-p
<name>=<value>] |
Creates a new core. The core is configured using
<name>=<value>
pairs. For more information about configuration options, see Solr documentation |
|
--reload <name> |
Reloads a core. | |
--unload <name> |
Unloads a core. | |
--status <name> |
Prints the status of a core. | |
cluster |
Manages cluster configuration. | |
--get-solrxml <file> |
Downloads the cluster configuration file solr.xml from
ZooKeeper to the local system. |
|
--put-solrxml <file> |
Uploads the specified file to ZooKeeper as the cluster configuration file
solr.xml . |
|
--set-property <name>
<value> |
Sets property names and values. For example, to configure a cluster to use
TLS/SSL:
|
|
--remove-property <name> |
Removes the specified property. | |
--get-clusterstate <file> |
Downloads the clusterstate.json file from ZooKeeper to the
local system. |