solr/solr-ref-guide/src/command-line-utilities.adoc

= Command Line Utilities
// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements.  See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.  The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License.  You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied.  See the License for the
// specific language governing permissions and limitations
// under the License.

A ZooKeeper Command Line Interface (CLI) script is available to allow you to interact directly with Solr configuration files stored in ZooKeeper.

While Solr's Administration UI includes pages dedicated to the state of your SolrCloud cluster, it does not allow you to download or modify related configuration files.

TIP: See the section <<cloud-screens.adoc#,Cloud Screens>> for more information about using the Admin UI screens.

The ZooKeeper CLI scripts found in `server/scripts/cloud-scripts` let you upload configuration information to ZooKeeper, in the same ways shown in the examples in <<parameter-reference.adoc#,Parameter Reference>>. It also provides a few other commands that let you link collection sets to collections, make ZooKeeper paths or clear them, and download configurations from ZooKeeper to the local filesystem.

Many of the functions provided by the zkCli.sh script are also provided by the <<solr-control-script-reference.adoc#,Solr Control Script>>, which may be more familiar as the start script ZooKeeper maintenance commands are very similar to Unix commands.

.Solr's zkcli.sh vs ZooKeeper's zkCli.sh
[IMPORTANT]
====
The `zkcli.sh` provided by Solr is not the same as the https://zookeeper.apache.org/doc/current/zookeeperStarted.html#sc_ConnectingToZooKeeper[`zkCli.sh` included in ZooKeeper distributions].

ZooKeeper's `zkCli.sh` provides a completely general, application-agnostic shell for manipulating data in ZooKeeper. Solr's `zkcli.sh` – discussed in this section – is specific to Solr, and has command line arguments specific to dealing with Solr data in ZooKeeper.
====

== Using Solr's ZooKeeper CLI

Use the `help` option to get a list of available commands from the script itself, as in `./server/scripts/cloud-scripts/zkcli.sh help`.

Both `zkcli.sh` (for Unix environments) and `zkcli.bat` (for Windows environments) support the following command line options:

`-cmd <arg>`::
The CLI Command to be executed. This parameter is *mandatory*. The following commands are supported:

* `bootstrap`
* `upconfig`
* `downconfig`
* `linkconfig`
* `makepath`
* `get` and `getfile`
* `put` and `putfile`
* `clear`
* `list`
* `ls`
* `clusterprop`

`-z` or `-zkhost <locations>`::
ZooKeeper host address. This parameter is *mandatory* for all CLI commands.

`-c` or `-collection <name>`::
For `linkconfig`: name of the collection.

`-d` or `-confdir <path>`::
For `upconfig`: a directory of configuration files. For downconfig: the destination of files pulled from ZooKeeper

`-h` or `-help`::
Display help text.

`-n` or `-confname <arg>`::
For `upconfig`, `linkconfig`, `downconfig`: name of the configuration set.

`-r` or `-runzk <port>`::
Run ZooKeeper internally by passing the Solr run port; only for clusters on one machine.

`-s` or `-solrhome <path>`:: For `bootstrap` or when using `-runzk`: the *mandatory* solrhome location.

`-name <name>`::
For `clusterprop`: the *mandatory* cluster property name.

`-val <value>`::
For `clusterprop`: the cluster property value. If not specified, *null* will be used as value.

[TIP]
====
The short form parameter options may be specified with a single dash (e.g., `-c mycollection`).

The long form parameter options may be specified using either a single dash (e.g., `-collection mycollection`) or a double dash (e.g., `--collection mycollection`)
====

== ZooKeeper CLI Examples

Below are some examples of using the `zkcli.sh` CLI which assume you have already started the SolrCloud example (`bin/solr -e cloud -noprompt`)

If you are on Windows machine, simply replace `zkcli.sh` with `zkcli.bat` in these examples.

=== Upload a Configuration Directory

[source,bash]
----
./server/scripts/cloud-scripts/zkcli.sh -zkhost 127.0.0.1:9983 -cmd upconfig -confname my_new_config -confdir server/solr/configsets/_default/conf
----

=== Bootstrap ZooKeeper from an Existing solr.home

[source,bash]
----
./server/scripts/cloud-scripts/zkcli.sh -zkhost 127.0.0.1:2181 -cmd bootstrap -solrhome /var/solr/data
----

.Bootstrap with chroot
[NOTE]
====
Using the boostrap command with a ZooKeeper chroot in the `-zkhost` parameter, e.g., `-zkhost 127.0.0.1:2181/solr`, will automatically create the chroot path before uploading the configs.
====

=== Put Arbitrary Data into a New ZooKeeper file

[source,bash]
----
./server/scripts/cloud-scripts/zkcli.sh -zkhost 127.0.0.1:9983 -cmd put /my_zk_file.txt 'some data'
----

=== Put a Local File into a New ZooKeeper File

[source,bash]
----
./server/scripts/cloud-scripts/zkcli.sh -zkhost 127.0.0.1:9983 -cmd putfile /my_zk_file.txt /tmp/my_local_file.txt
----

=== Link a Collection to a Configset

[source,bash]
----
./server/scripts/cloud-scripts/zkcli.sh -zkhost 127.0.0.1:9983 -cmd linkconfig -collection gettingstarted -confname my_new_config
----

=== Create a New ZooKeeper Path

This can be useful to create a chroot path in ZooKeeper before first cluster start.

[source,bash]
----
./server/scripts/cloud-scripts/zkcli.sh -zkhost 127.0.0.1:2181 -cmd makepath /solr
----

=== Set a Cluster Property

This command will add or modify a single cluster property in `clusterprops.json`. Use this command instead of the usual getfile \-> edit \-> putfile cycle.

Unlike the CLUSTERPROP command on the <<cluster-node-management.adoc#clusterprop,Collections API>>, this command does *not* require a running Solr cluster.

[source,bash]
----
./server/scripts/cloud-scripts/zkcli.sh -zkhost 127.0.0.1:2181 -cmd clusterprop -name urlScheme -val https
----