solr/solr-ref-guide/src/using-zookeeper-to-manage-configuration-files.adoc

= Using ZooKeeper to Manage Configuration Files
:solr-root-path: ../../
:example-source-dir: {solr-root-path}solrj/src/test/org/apache/solr/client/ref_guide_examples/
// 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.

With SolrCloud your configuration files are kept in ZooKeeper.

These files are uploaded in either of the following cases:

* When you start a SolrCloud example using the `bin/solr` script.
* When you create a collection using the `bin/solr` script.
* Explicitly upload a configuration set to ZooKeeper.

== Startup Bootstrap

When you try SolrCloud for the first time using the `bin/solr -e cloud`, the related configset gets uploaded to ZooKeeper automatically and is linked with the newly created collection.

The below command would start SolrCloud with the default collection name (gettingstarted) and default configset (_default) uploaded and linked to it.

[source,bash]
----
bin/solr -e cloud -noprompt
----

You can also explicitly upload a configuration directory when creating a collection using the `bin/solr` script with the `-d` option, such as:

[source,bash]
----
bin/solr create -c mycollection -d _default
----

The create command will upload a copy of the `_default` configuration directory to ZooKeeper under `/configs/mycollection`. Refer to the <<solr-control-script-reference.adoc#,Solr Control Script Reference>> page for more details about the create command for creating collections.

Once a configuration directory has been uploaded to ZooKeeper, you can update them using the <<solr-control-script-reference.adoc#,Solr Control Script>>

IMPORTANT: It's a good idea to keep these files under version control.


== Uploading Configuration Files using bin/solr or SolrJ

In production situations, <<config-sets.adoc#,Configsets>> can also be uploaded to ZooKeeper independent of collection creation using either Solr's <<solr-control-script-reference.adoc#,Solr Control Script>> or SolrJ.

The below command can be used to upload a new configset using the bin/solr script.

[source,bash]
----
bin/solr zk upconfig -n <name for configset> -d <path to directory with configset>
----

The following code shows how this can also be achieved using SolrJ:
[source,java,indent=0]
----
include::{example-source-dir}ZkConfigFilesTest.java[tag=zk-configset-upload]
----

It is strongly recommended that the configurations be kept in a version control system, Git, SVN or similar.

== Managing Your SolrCloud Configuration Files

To update or change your SolrCloud configuration files:

. Download the latest configuration files from ZooKeeper, using the source control checkout process.
. Make your changes.
. Commit your changed file to source control.
. Push the changes back to ZooKeeper.
. Reload the collection so that the changes will be in effect.

== Preparing ZooKeeper before First Cluster Start

If you will share the same ZooKeeper instance with other applications you should use a _chroot_ in ZooKeeper. Please see <<taking-solr-to-production.adoc#zookeeper-chroot,ZooKeeper chroot>> for instructions.

There are certain configuration files containing cluster wide configuration. Since some of these are crucial for the cluster to function properly, you may need to upload such files to ZooKeeper before starting your Solr cluster for the first time. Examples of such configuration files (not exhaustive) are `solr.xml`, `security.json` and `clusterprops.json`.

If you for example would like to keep your `solr.xml` in ZooKeeper to avoid having to copy it to every node's `solr_home` directory, you can push it to ZooKeeper with the bin/solr utility (Unix example):

[source,bash]
----
bin/solr zk cp file:local/file/path/to/solr.xml zk:/solr.xml -z localhost:2181
----

NOTE: If you have defined `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <<setting-up-an-external-zookeeper-ensemble#updating-solr-include-files,instructions>>) you can omit `-z <zk host string>` from the above command.