Connect to Solr via CLI
Solr Server components installed on ADH hosts provide the /usr/lib/solr/bin/solr script that allows you to run CLI commands to manage your Solr cluster. Although it is recommended to control the activity of your Solr cluster via ADCM, some of the Solr CLI commands can be useful to perform actions that are unavailable in the Solr Admin UI. These commands are highlighted further in the article.
The general usage of the /usr/lib/solr/bin/solr script is as follows:
$ /usr/lib/solr/bin/solr <COMMAND> [<PARAMETERS>]
The detailed information about all the supported COMMAND
and PARAMETERS
values is available in the Solr reference documentation.
To get help information for a particular command, use the following syntax:
$ /usr/lib/solr/bin/solr <COMMAND> -help
For more verbose command output, append the -V
flag to your commands.
NOTE
As an ADH service, Solr always runs in the SolrCloud mode.
Thus, some commands related to the standalone mode may have no effect at all.
|
Сontrol commands: start, stop, restart
Although the /usr/lib/solr/bin/solr script accepts commands like start
, stop
, and restart
, it is highly recommended to use ADCM to perform these actions.
Under the hood, ADCM invokes these commands to control Solr processes.
However, ADCM additionally takes care about running these commands properly.
For example, setting environment variables, submitting commands with sufficient user permissions, handling errors, etc.
Running start
, stop
, and restart
commands via /usr/lib/solr/bin/solr may lead to Solr startup issues and the malfunction of the entire Solr cluster.
System information commands
Solr provides several commands that might be useful for getting status information and diagnosing your Solr cluster. These commands are shown below:
$ /usr/lib/solr/bin/solr version
$ /usr/lib/solr/bin/solr status
$ /usr/lib/solr/bin/solr healthcheck [<PARAMETERS>]
Command parameters
Parameter | Description |
---|---|
-c <collection_name> |
The name of the collection |
-z <zk_connection_string> |
Optional. The ZooKeeper connection string. Can be omitted unless you have modified your ZooKeeper connection string |
Examples
$ /usr/lib/solr/bin/solr version
Sample output:
8.11.2
$ /usr/lib/solr/bin/solr status
Sample output:
Found 1 Solr nodes: Solr process 23658 running on port 8983 { "solr_home":"/srv/solr/server", "version":"8.11.2 3cb85f40e394dcfb50fe77310908cce385381ba2 - jenkins - 2024-03-20 17:52:09", "startTime":"2024-05-23T22:52:07.271Z", "uptime":"0 days, 0 hours, 0 minutes, 6 seconds", "memory":"105.9 MB (%21.6) of 491 MB", "cloud":{ "ZooKeeper":"ka-adh-1.ru-central1.internal:2181,ka-adh-2.ru-central1.internal:2181,ka-adh-3.ru-central1.internal:2181/Arenadata.Hadoop-7.solr.server", "liveNodes":"3", "collections":"0"}}
$ /usr/lib/solr/bin/solr healthcheck -c test_collection
Sample output:
{ "collection":"test_collection", "status":"healthy", "numDocs":0, "numShards":2, "shards":[ { "shard":"shard1", "status":"healthy", "replicas":[ { "name":"core_node3", "url":"http://ka-adh-3.ru-central1.internal:8983/solr/test_collection_shard1_replica_n1/", "numDocs":0, "status":"active", "uptime":"0 days, 11 hours, 21 minutes, 7 seconds", "memory":"143.6 MB (%29.4) of 489 MB"}, { "name":"core_node5", "url":"http://ka-adh-1.ru-central1.internal:8983/solr/test_collection_shard1_replica_n2/", "numDocs":0, "status":"active", "uptime":"0 days, 11 hours, 21 minutes, 7 seconds", "memory":"67.9 MB (%14) of 485 MB", "leader":true}, { "name":"core_node7", "url":"http://ka-adh-2.ru-central1.internal:8983/solr/test_collection_shard1_replica_n4/", "numDocs":0, "status":"active", "uptime":"0 days, 11 hours, 21 minutes, 7 seconds", "memory":"63 MB (%13) of 485 MB"}]}, { "shard":"shard2", "status":"healthy", "replicas":[ { "name":"core_node9", "url":"http://ka-adh-3.ru-central1.internal:8983/solr/test_collection_shard2_replica_n6/", "numDocs":0, "status":"active", "uptime":"0 days, 11 hours, 21 minutes, 7 seconds", "memory":"144.8 MB (%29.6) of 489 MB"}, { "name":"core_node11", "url":"http://ka-adh-1.ru-central1.internal:8983/solr/test_collection_shard2_replica_n8/", "numDocs":0, "status":"active", "uptime":"0 days, 11 hours, 21 minutes, 7 seconds", "memory":"69.3 MB (%14.3) of 485 MB"}, { "name":"core_node12", "url":"http://ka-adh-2.ru-central1.internal:8983/solr/test_collection_shard2_replica_n10/", "numDocs":0, "status":"active", "uptime":"0 days, 11 hours, 21 minutes, 7 seconds", "memory":"65.1 MB (%13.4) of 485 MB", "leader":true}]}]}
Collection & core commands
You can use the /usr/lib/solr/bin/solr script to create and delete Solr collections.
The usage is as follows:
$ /usr/lib/solr/bin/solr create [<PARAMETERS>]
$ /usr/lib/solr/bin/solr create_collection [<PARAMETERS>]
$ /usr/lib/solr/bin/solr delete [<PARAMETERS>]
NOTE
In ADH, the Solr’s create and create_collection commands are equivalent.
Running create detects the current Solr mode (which is always SolrCloud in ADH) and invokes the create_collection command with the same set of parameters.
|
Command parameters
Parameter | Description |
---|---|
-c <collection> |
A name for the new collection |
-d <conf_dir> |
Specifies a configuration directory (configset) to use when creating a collection. If not specified, the /usr/lib/solr/server/solr/configsets/_default configset is used |
-n <config_name> |
The name used to upload the configuration directory to ZooKeeper. By default, the collection name is used |
-s <shards>, -shards <shards> |
The number of shards to split the collection, defaults to |
-rf <replicas>, -replicationFactor <replicas> |
The number of copies of each document in the collection.
Defaults to |
Parameter | Description |
---|---|
-c <collection> |
The name of the collection to delete |
-deleteConfig <true|false> |
Defines whether to delete the configuration directory from ZooKeeper.
The default behavior is |
Examples
$ /usr/lib/solr/bin/solr create_collection -c test_collection1
Sample output:
Created collection 'test_collection1' with 1 shard(s), 1 replica(s) with config-set 'test_collection1'
$ /usr/lib/solr/bin/solr create_collection -c test_collection -shards 2 -replicationFactor 3 -V
Sample output:
Connecting to ZooKeeper at ka-adh-1.ru-central1.internal:2181,ka-adh-2.ru-central1.internal:2181,ka-adh-3.ru-central1.internal:2181/Arenadata.Hadoop-8.solr.server ... INFO - 2024-05-28 08:23:31.128; org.apache.solr.common.cloud.ConnectionManager; Waiting for client to connect to ZooKeeper INFO - 2024-05-28 08:23:31.145; org.apache.solr.common.cloud.ConnectionManager; zkClient has connected INFO - 2024-05-28 08:23:31.145; org.apache.solr.common.cloud.ConnectionManager; Client is connected to ZooKeeper INFO - 2024-05-28 08:23:31.158; org.apache.solr.common.cloud.ZkStateReader; Updated live nodes from ZooKeeper... (0) -> (3) INFO - 2024-05-28 08:23:31.269; org.apache.solr.client.solrj.impl.ZkClientClusterStateProvider; Cluster at ka-adh-1.ru-central1.internal:2181,ka-adh-2.ru-central1.internal:2181,ka-adh-3.ru-central1.internal:2181/Arenadata.Hadoop-8.solr.server ready Uploading /usr/lib/solr/server/solr/configsets/_default/conf for config test_collection to ZooKeeper at ka-adh-1.ru-central1.internal:2181,ka-adh-2.ru-central1.internal:2181,ka-adh-3.ru-central1.internal:2181/Arenadata.Hadoop-8.solr.server Creating new collection 'test_collection' using command: http://ka-adh-1.ru-central1.internal:8983/solr/admin/collections?action=CREATE&name=test_collection&numShards=2&replicationFactor=3&maxShardsPerNode=-1&collection.configName=test_collection { "responseHeader":{ "status":0, "QTime":2325}, "success":{ "ka-adh-1.ru-central1.internal:8983_solr":{ "responseHeader":{ "status":0, "QTime":1199}, "core":"test_collection_shard2_replica_n8"}, "ka-adh-3.ru-central1.internal:8983_solr":{ "responseHeader":{ "status":0, "QTime":1610}, "core":"test_collection_shard1_replica_n1"}, "ka-adh-2.ru-central1.internal:8983_solr":{ "responseHeader":{ "status":0, "QTime":1822}, "core":"test_collection_shard2_replica_n10"}}}
$ /usr/lib/solr/bin/solr delete -c test_collection1
Sample output:
{ "responseHeader":{ "status":0, "QTime":297}, "success":{ "ka-adh-1.ru-central1.internal:8983_solr":{"responseHeader":{ "status":0, "QTime":50}}, "ka-adh-3.ru-central1.internal:8983_solr":{"responseHeader":{ "status":0, "QTime":119}}, "ka-adh-2.ru-central1.internal:8983_solr":{"responseHeader":{ "status":0, "QTime":130}}}} Deleted collection 'test_collection1' using command: http://ka-adh-1.ru-central1.internal:8983/solr/admin/collections?action=DELETE&name=test_collection1
Cores
Since ADH Solr Server components always run in the SolrCloud mode, Solr manages the data in the form of collections (a single search index distributed across multiple cluster nodes) rather than cores. For this reason, the core management commands have no effect and are beyond the scope of this article.
Authentication
Using the /usr/lib/solr/bin/solr script, you can enable and disable Solr authentication.
The usage is as follows:
$ /usr/lib/solr/bin/solr auth enable [<PARAMETERS>]
$ /usr/lib/solr/bin/solr auth disable
Command parameters
Parameter | Description |
---|---|
-authConfDir <dir> |
Specifies a directory to store configuration files related to authentication |
-blockUnknown <true|false> |
Blocks access to all Solr endpoints for unauthenticated users |
-credentials <username:password> |
The credentials pair in the |
-prompt <true|false> |
Prompts to provide the credentials.
Either the |
-type <type> |
Defines the authentication mechanism ( |
-updateIncludeFileOnly <true|false> |
Updates only the solr.in.sh file without actually enabling or disabling the authentication |
-z <zkString> |
The ZooKeeper connection string. Can be omitted unless you have modified your ZooKeeper connection string |
-d <dir> |
Specifies the Solr server directory (defaults to /usr/lib/solr/server/). Use this option only if you have customized your Solr home directory path |
-s <dir> |
Specifies the Solr home directory to store credentials and authentication configuration files (for example, basicAuth.conf) |
Examples
Before running the following example command, ensure that a security.json file is uploaded to ZooKeeper.
You can upload the file using ZooKeeper CLI or using the /usr/lib/solr/server/scripts/cloud-scripts/zkcli.sh script.
$ /usr/lib/solr/bin/solr auth enable \
-type basicAuth \
-prompt true \
-z ka-adh-1.ru-central1.internal:2181,ka-adh-2.ru-central1.internal:2181,ka-adh-3.ru-central1.internal:2181/Arenadata.Hadoop-6.solr.server \
-blockUnknown true
Sample output:
Security is enabled. You can disable it with 'bin/solr auth disable'. Existing security.json: {"authentication":{"blockUnknown":true,"class":"solr.BasicAuthPlugin","realm":"My Solr users","forwardCredentials":false},"authorization":{"class":"solr.RuleBasedAuthorizationPlugin","permissions":[{"name":"security-edit","role":"admin"}],"user-role":{"solr":"admin"}}}
$ /usr/lib/solr/bin/solr auth disable
Sample output:
Security has been disabled. Please remove any SOLR_AUTH_TYPE or SOLR_AUTHENTICATION_OPTS configuration from solr.in.sh/solr.in.cmd.
ZooKeeper commands
The /usr/lib/solr/bin/solr script supports commands to interact with ZooKeeper.
For example, the zk upconfig
and zk downconfig
commands are used to upload/download Solr configsets from ZooKeeper.
The usage is as follows:
$ /usr/lib/solr/bin/solr zk upconfig [<PARAMETERS>]
$ /usr/lib/solr/bin/solr zk downconfig [<PARAMETERS>]
Command parameters
Parameter | Description |
---|---|
-n <name> |
A name for the configset that has to be uploaded or downloaded from ZooKeeper. All the uploaded configsets are available in the Solr Admin UI. Using an existing name overwrites the configset in ZooKeeper |
-d <configset_dir> |
The path to the configset directory to upload/download. A configset directory must contain the conf directory with the solrconfig.xml file inside |
-z <zk_host> |
Optional. The ZooKeeper connection string. Can be omitted unless you have modified your ZooKeeper connection string |
NOTE
Uploading a configset to ZooKeeper does not automatically make the changes effective.
If you modify a configset already used by a collection, use the RELOAD collection command to reload any collection that uses this configset.
|
Also, there are several zk …
commands that might be useful to perform common ZooKeeper operations.
The usage is shown below:
$ /usr/lib/solr/bin/solr zk cp <src> <dst> [-r] [-z <zk_string>] (1)
$ /usr/lib/solr/bin/solr zk rm <path> [-r] [-z <zk_string>] (2)
$ /usr/lib/solr/bin/solr zk mv <src> <dst> [-z <zk_string>] (3)
$ /usr/lib/solr/bin/solr zk ls <path> [-r] [-z <zk_string>] (4)
$ /usr/lib/solr/bin/solr zk mkroot <path> [-z <zk_string>] (5)
1 | Transfers data between the local file system and ZooKeeper Znodes.
The prefix zk: assumes a ZooKeeper location, and file: indicates the local file system.
At least one of <src> or <dest> must be prefixed with zk: . |
2 | Removes a Znode from ZooKeeper. Since <path> assumes a ZooKeeper node, no zk: prefix is necessary. |
3 | Moves (renames) a Znode. |
4 | Lists the children of a Znode. |
5 | Creates a new Znode. Intermediate Znodes are created, if necessary. |
Examples
$ /usr/lib/solr/bin/solr zk downconfig -n test_collection -d ~/my_test_collection_config
Sample output:
Downloading configset test_collection from ZooKeeper at ka-adh-1.ru-central1.internal:2181,ka-adh-2.ru-central1.internal:2181,ka-adh-3.ru-central1.internal:2181/Arenadata.Hadoop-8.solr.server to directory /home/admin/my_test_collection_config/conf
$ /usr/lib/solr/bin/solr zk cp -r file:/home/admin/test_dir/ zk:/Arenadata.Hadoop-8.solr.server/test_upload
Sample output:
Copying from 'file:/home/admin/test_dir/' to 'zk:/Arenadata.Hadoop-8.solr.server/test_upload'. ZooKeeper at ka-adh-1.ru-central1.internal:2181,ka-adh-2.ru-central1.internal:2181,ka-adh-3.ru-central1.internal:2181/Arenadata.Hadoop-8.solr.server
$ /usr/lib/solr/bin/solr zk rm -r zk:/Arenadata.Hadoop-8.solr.server/test_upload
Sample output:
Removing ZooKeeper node /Arenadata.Hadoop-8.solr.server/test_upload from ZooKeeper at ka-adh-1.ru-central1.internal:2181,ka-adh-2.ru-central1.internal:2181,ka-adh-3.ru-central1.internal:2181/Arenadata.Hadoop-8.solr.server recurse: true
Data export commands
Using the export
command, you can export documents from a Solr collection in the JSON or Javabin format.
The usage is as follows:
$ /usr/lib/solr/bin/solr export [<PARAMETERS>]
Command parameters
Parameter | Description |
---|---|
-fields <f1,f2,fn> |
A comma-separated list of fields to export. By default, all fields are exported |
-format <fmt> |
Sets the output format for exported documents (JSON or javabin), defaulting to JSON |
-limit <i> |
The maximum number of documents to export.
The default value is |
-out |
Specifies the file name to save exported data.
By default, the |
-url <collection_url> |
The URL address pointing to the collection |
Examples
$ sudo bin/solr export -url http://ka-adh-1.ru-central1.internal:8983/solr/test_collection
Sample output:
NO: of shards : 2 Export complete for : test_collection_shard1_replica_n2, docs : 0 Export complete for : test_collection_shard2_replica_n8, docs : 1 Total Docs exported: 0. Time taken: 0secs
Running this command creates the test_collection.json file in the local file system. The file stores the documents from the requested collection, for example:
{"key1":"foo","key2":"bar","id":"71b51c87-142c-45a6-8ea0-82ae924fd3c4"}
$ sudo bin/solr export -url http://ka-adh-1.ru-central1.internal:8983/solr/test_collection -fields "key1"
Sample output:
NO: of shards : 2 . Export complete for : test_collection_shard1_replica_n2, docs : 0 Export complete for : test_collection_shard2_replica_n8, docs : 1 Total Docs exported: 0. Time taken: 0secs
Running this command creates the test_export_file.json file in the local file system. The file stores the documents containing only the requested fields, for example:
{"key1":"foo"}