You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucene.apache.org by sh...@apache.org on 2017/06/27 05:19:31 UTC
[20/27] lucene-solr:feature/autoscaling: SOLR-10892: Phase 2: large
pages with lots of tables + lots of heading cleanups & TOC placement changes
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/93c96b06/solr/solr-ref-guide/src/solr-control-script-reference.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/solr-control-script-reference.adoc b/solr/solr-ref-guide/src/solr-control-script-reference.adoc
index c3a0805..c933114 100644
--- a/solr/solr-ref-guide/src/solr-control-script-reference.adoc
+++ b/solr/solr-ref-guide/src/solr-control-script-reference.adoc
@@ -1,6 +1,7 @@
= Solr Control Script Reference
:page-shortname: solr-control-script-reference
:page-permalink: solr-control-script-reference.html
+:page-tocclass: right
// 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
@@ -26,10 +27,8 @@ You can find the script in the `bin/` directory of your Solr installation. The `
More examples of `bin/solr` in use are available throughout the Solr Reference Guide, but particularly in the sections <<running-solr.adoc#running-solr,Running Solr>> and <<getting-started-with-solrcloud.adoc#getting-started-with-solrcloud,Getting Started with SolrCloud>>.
-[[SolrControlScriptReference-StartingandStopping]]
== Starting and Stopping
-[[SolrControlScriptReference-StartandRestart]]
=== 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.
@@ -46,62 +45,106 @@ The `start` and `restart` commands have several options to allow you to run in S
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.
-[[SolrControlScriptReference-AvailableParameters]]
-==== Available Parameters
+==== 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.
+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.
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+`-a "<string>"`::
+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.
-[cols="20,40,40",options="header"]
-|===
-|Parameter |Description |Example
-|-a "<string>" |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. |`bin/solr start -a "-Xdebug -Xrunjdwp:transport=dt_socket, server=y,suspend=n,address=1044"`
-|-cloud a|
-Start Solr in SolrCloud mode, which will also launch the embedded ZooKeeper instance included with Solr.
+*Example*:
-This option can be shortened to simply `-c`.
+[source,bash]
+bin/solr start -a "-Xdebug -Xrunjdwp:transport=dt_socket, server=y,suspend=n,address=1044"
+`-cloud`::
+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 pass the -z parameter.
++
+For more details, see the section <<SolrCloud Mode>> below.
++
+*Example*: `bin/solr start -c`
-For more details, see the section <<SolrControlScriptReference-SolrCloudMode,SolrCloud Mode>> below.
+`-d <dir>`::
+Define a server directory, defaults to `server` (as in, `$SOLR_HOME/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`
- |`bin/solr start -c`
-|-d <dir> |Define a server directory, defaults to `server` (as in, `$SOLR_HOME/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. |`bin/solr start -d newServerDir`
-|-e <name> a|
+`-e <name>`::
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
* dih
* schemaless
-
++
See the section <<SolrControlScriptReference-RunningwithExampleConfigurations,Running with Example Configurations>> below for more details on the example configurations.
- |`bin/solr start -e schemaless`
-|-f |Start Solr in the foreground; you cannot use this option when running examples with the -e option. |`bin/solr start -f`
-|-h <hostname> |Start Solr with the defined hostname. If this is not specified, 'localhost' will be assumed. |`bin/solr start -h search.mysolr.com`
-|-m <memory> |Start Solr with the defined value as the min (-Xms) and max (-Xmx) heap size for the JVM. |`bin/solr start -m 1g`
-|-noprompt a|
-Start Solr and suppress any prompts that may be seen with another option. This would have the side effect of accepting all defaults implicitly.
++
+*Example*: `bin/solr start -e schemaless`
+`-f`::
+Start Solr in the foreground; you cannot use this option when running examples with the -e option.
++
+*Example*: `bin/solr start -f`
+
+`-h <hostname>`::
+Start Solr with the defined hostname. If this is not specified, 'localhost' will be assumed.
++
+*Example*: `bin/solr start -h search.mysolr.com`
+
+`-m <memory>`::
+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`::
+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`
- |`bin/solr start -e cloud -noprompt`
-|-p <port> |Start Solr on the defined port. If this is not specified, '8983' will be used. |`bin/solr start -p 8655`
-|-s <dir> a|
-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. If set, the specified directory should contain a solr.xml file, unless solr.xml exists in ZooKeeper. The default value is `server/solr`.
+`-p <port>`::
+Start Solr on the defined port. If this is not specified, '8983' will be used.
++
+*Example*: `bin/solr start -p 8655`
+`-s <dir>`::
+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. If set, the specified directory should contain a solr.xml file, unless solr.xml exists in ZooKeeper. The default value is `server/solr`.
++
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`::
+Be more verbose. This changes the logging level of log4j from `INFO` to `DEBUG`, having the same effect as if you edited `log4j.properties` accordingly.
++
+*Example*: `bin/solr start -f -v`
+
+`-q`::
+Be more quiet. This changes the logging level of log4j from `INFO` to `WARN`, having the same effect as if you edited `log4j.properties` accordingly. 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`::
+Start Solr with verbose messages from the start script.
++
+*Example*: `bin/solr start -V`
+
+`-z <zkHost>`::
+Start Solr with the defined ZooKeeper connection string. This option is only used with the -c option, to start Solr in SolrCloud mode. If 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`
- |`bin/solr start -s newHome`
-|-v |Be more verbose. This changes the logging level of log4j from `INFO` to `DEBUG`, having the same effect as if you edited `log4j.properties` accordingly. |`bin/solr start -f -v`
-|-q |Be more quiet. This changes the logging level of log4j from `INFO` to `WARN`, having the same effect as if you edited `log4j.properties` accordingly. This can be useful in a production setting where you want to limit logging to warnings and errors. |`bin/solr start -f -q`
-|-V |Start Solr with verbose messages from the start script. |`bin/solr start -V`
-|-z <zkHost> |Start Solr with the defined ZooKeeper connection string. This option is only used with the -c option, to start Solr in SolrCloud mode. If this option is not provided, Solr will start the embedded ZooKeeper instance and use that instance for SolrCloud operations. |`bin/solr start -c -z server1:2181,server2:2181`
-|-force |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. |`sudo bin/solr start -force`
-|===
+`-force`::
+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:
@@ -111,7 +154,6 @@ To emphasize how the default settings work take a moment to understand that the
It is not necessary to define all of the options when starting if the defaults are fine for your needs.
-[[SolrControlScriptReference-SettingJavaSystemProperties]]
==== 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.
@@ -120,7 +162,6 @@ For example, to set the auto soft-commit frequency to 3 seconds, you can do:
`bin/solr start -Dsolr.autoSoftCommit.maxTime=3000`
-[[SolrControlScriptReference-SolrCloudMode]]
==== SolrCloud Mode
The `-c` and `-cloud` options are equivalent:
@@ -151,23 +192,34 @@ For more information about starting Solr in SolrCloud mode, see also the section
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.adoc#schema-api,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-definition-in-solrconfig.adoc#schema-factory-definition-in-solrconfig,Schema Factory Definition in SolrConfig>>.
+Each example launches Solr with a managed schema, which allows use of the <<schema-api.adoc#schema-api,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-definition-in-solrconfig.adoc#schema-factory-definition-in-solrconfig,Schema Factory Definition in SolrConfig>>.
Unless otherwise noted in the descriptions below, the examples do not enable <<solrcloud.adoc#solrcloud,SolrCloud>> nor <<schemaless-mode.adoc#schemaless-mode,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_HOME/server/solr/configsets`.
-* *techproducts*: This example starts Solr in standalone mode with a schema designed for the sample documents included in the `$SOLR_HOME/example/exampledocs` directory. The configset used can be found in `$SOLR_HOME/server/solr/configsets/sample_techproducts_configs`.
-* *dih*: This example starts Solr in standalone mode with the DataImportHandler (DIH) enabled and several example `dataconfig.xml` files pre-configured for different types of data supported with DIH (such as, database contents, email, RSS feeds, etc.). The configset used is customized for DIH, and is found in `$SOLR_HOME/example/example-DIH/solr/conf`. For more information about DIH, see the section <<uploading-structured-data-store-data-with-the-data-import-handler.adoc#uploading-structured-data-store-data-with-the-data-import-handler,Uploading Structured Data Store Data with the Data Import Handler>>.
-* *schemaless*: This example starts Solr in standalone mode using a managed schema, as described in the section <<schema-factory-definition-in-solrconfig.adoc#schema-factory-definition-in-solrconfig,Schema Factory Definition in SolrConfig>>, and provides a very minimal pre-defined schema. Solr will run in <<schemaless-mode.adoc#schemaless-mode,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_HOME/server/solr/configsets/data_driven_schema_configs`.
+* *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_HOME/server/solr/configsets`.
+* *techproducts*: This example starts Solr in standalone mode with a schema designed for the sample documents included in the `$SOLR_HOME/example/exampledocs` directory.
++
+The configset used can be found in `$SOLR_HOME/server/solr/configsets/sample_techproducts_configs`.
+* *dih*: This example starts Solr in standalone mode with the DataImportHandler (DIH) enabled and several example `dataconfig.xml` files pre-configured for different types of data supported with DIH (such as, database contents, email, RSS feeds, etc.).
++
+The configset used is customized for DIH, and is found in `$SOLR_HOME/example/example-DIH/solr/conf`.
++
+For more information about DIH, see the section <<uploading-structured-data-store-data-with-the-data-import-handler.adoc#uploading-structured-data-store-data-with-the-data-import-handler,Uploading Structured Data Store Data with the Data Import Handler>>.
+* *schemaless*: This example starts Solr in standalone mode using a managed schema, as described in the section <<schema-factory-definition-in-solrconfig.adoc#schema-factory-definition-in-solrconfig,Schema Factory Definition in SolrConfig>>, and provides a very minimal pre-defined schema. Solr will run in <<schemaless-mode.adoc#schemaless-mode,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_HOME/server/solr/configsets/data_driven_schema_configs`.
[IMPORTANT]
====
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.
====
-[[SolrControlScriptReference-Stop]]
=== 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 5 seconds for Solr to stop gracefully and then will forcefully kill the process (kill -9).
@@ -176,23 +228,26 @@ The `stop` command sends a STOP request to a running Solr node, which allows it
`bin/solr stop -help`
-[[SolrControlScriptReference-AvailableParameters.1]]
-==== Available Parameters
+==== Stop Parameters
+
+`-p <port>`::
+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`::
+Stop all running Solr instances that have a valid PID.
++
+*Example*: `bin/solr stop -all`
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+`-k <key>`::
+Stop key used to protect from stopping Solr inadvertently; default is "solrrocks".
++
+*Example*: `bin/solr stop -k solrrocks`
-[cols="20,40,40",options="header"]
-|===
-|Parameter |Description |Example
-|-p <port> |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. |`bin/solr stop -p 8983`
-|-all |Stop all running Solr instances that have a valid PID. |`bin/solr stop -all`
-|-k <key> |Stop key used to protect from stopping Solr inadvertently; default is "solrrocks". |`bin/solr stop -k solrrocks`
-|===
-[[SolrControlScriptReference-SystemInformation]]
== System Information
-[[SolrControlScriptReference-Version]]
=== Version
The `version` command simply returns the version of Solr currently installed and immediately exists.
@@ -203,7 +258,6 @@ $ bin/solr version
X.Y.0
----
-[[SolrControlScriptReference-Status]]
=== Status
The `status` command displays basic JSON-formatted information for any Solr nodes found running on the local system.
@@ -253,16 +307,17 @@ The `healthcheck` command generates a JSON-formatted health report for a collect
`bin/solr healthcheck -help`
[[SolrControlScriptReference-AvailableParameters.2]]
-==== Available Parameters
+==== Healthcheck Parameters
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+`-c <collection>`::
+ Name of the collection to run a healthcheck against (required).
++
+*Example*: `bin/solr healthcheck -c gettingstarted`
-[cols="20,40,40",options="header"]
-|===
-|Parameter |Description |Example
-|-c <collection> |Name of the collection to run a healthcheck against (required). |`bin/solr healthcheck -c gettingstarted`
-|-z <zkhost> |ZooKeeper connection string, defaults to localhost:9983. 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. |`bin/solr healthcheck -z localhost:2181`
-|===
+`-z <zkhost>`::
+ZooKeeper connection string, defaults to `localhost:9983`. 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.
++
+*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:
@@ -321,8 +376,7 @@ Below is an example healthcheck request and response using a non-standard ZooKee
The `bin/solr` script can also help you create new collections (in SolrCloud mode) or cores (in standalone mode), or delete collections.
-[[SolrControlScriptReference-Create]]
-=== Create
+=== Create a Core or Collection
The `create` command detects the mode that Solr is running in (standalone or SolrCloud) and then creates a core or collection depending on the mode.
@@ -330,65 +384,74 @@ The `create` command detects the mode that Solr is running in (standalone or Sol
`bin/solr create -help`
-[[SolrControlScriptReference-AvailableParameters.3]]
-==== Available Parameters
+==== Create Core or Collection Parameters
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+`-c <name>`::
+Name of the core or collection to create (required).
++
+*Example*: `bin/solr create -c mycollection`
-[cols="20,40,40",options="header"]
-|===
-|Parameter |Description |Example
-|-c <name> |Name of the core or collection to create (required). |`bin/solr create -c mycollection`
-|-d <confdir> a|
+`-d <confdir>`::
The configuration directory. This defaults to `data_driven_schema_configs`.
++
+See the section <<Configuration Directories and SolrCloud>> below for more details about this option when running in SolrCloud mode.
++
+*Example*: `bin/solr create -d basic_configs`
-See the section <<SolrControlScriptReference-ConfigurationDirectoriesandSolrCloud,Configuration Directories and SolrCloud>> below for more details about this option when running in SolrCloud mode.
+`-n <configName>`::
+The configuration name. This defaults to the same name as the core or collection.
++
+*Example*: `bin/solr create -n basic`
- |`bin/solr create -d basic_configs`
-|-n <configName> |The configuration name. This defaults to the same name as the core or collection. |`bin/solr create -n basic`
-|-p <port> a|
+`-p <port>`::
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 standalone 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`
- |`bin/solr create -p 8983`
-a|
--s <shards>
-
--shards
-
- |Number of shards to split a collection into, default is 1; only applies when Solr is running in SolrCloud mode. |`bin/solr create -s 2`
-a|
--rf <replicas>
+`-s <shards>` or `-shards`::
+Number of shards to split a collection into, default is 1; only applies when Solr is running in SolrCloud mode.
++
+*Example*: `bin/solr create -s 2`
--replicationFactor
+`-rf <replicas>` or `-replicationFactor`::
+Number of copies of each document in the collection. The default is 1 (no replication).
++
+*Example*: `bin/solr create -rf 2`
- |Number of copies of each document in the collection. The default is 1 (no replication). |`bin/solr create -rf 2`
-|-force |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. |`bin/solr create -c foo -force`
-|===
+`-force`::
+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`
-[[SolrControlScriptReference-ConfigurationDirectoriesandSolrCloud]]
==== 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.
+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_HOME/server/solr/configsets/data_driven_schema_configs/conf`) is uploaded to ZooKeeper using the same name as the collection. For example, the following command will result in the *data_driven_schema_configs* configuration being uploaded to `/configs/contacts` in ZooKeeper: `bin/solr create -c contacts`. If you create another collection, by doing `bin/solr create -c contacts2`, then another copy of the `data_driven_schema_configs` 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.
+First, if you don't provide the `-d` or `-n` options, then the default configuration (`$SOLR_HOME/server/solr/configsets/data_driven_schema_configs/conf`) is uploaded to ZooKeeper using the same name as the collection.
+
+For example, the following command will result in the `data_driven_schema_configs` 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 `data_driven_schema_configs` 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 basic_configs -n basic` will upload the `server/solr/configsets/basic_configs/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.
+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`.
-[[SolrControlScriptReference-Data-drivenSchemaandSharedConfigurations]]
==== Data-driven Schema and Shared Configurations
The `data_driven_schema_configs` schema can mutate as data is indexed. 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.
-[[SolrControlScriptReference-Delete]]
-=== Delete
+=== Delete Core or Collection
The `delete` command detects the mode that Solr is running in (standalone or SolrCloud) and then deletes the specified core (standalone) or collection (SolrCloud) as appropriate.
@@ -396,33 +459,33 @@ The `delete` command detects the mode that Solr is running in (standalone or Sol
`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 by doing `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.
+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.
-[[SolrControlScriptReference-AvailableParameters.4]]
-==== Available Parameters
+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.
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+==== Delete Core or Collection Parameters
-[cols="20,40,40",options="header"]
-|===
-|Parameter |Description |Example
-|-c <name> |Name of the core / collection to delete (required). |`bin/solr delete -c mycoll`
-|-deleteConfig <true\|false> a|
-Delete the configuration directory from ZooKeeper. The default is true.
+`-c <name>`::
+Name of the core / collection to delete (required).
++
+*Example*: `bin/solr delete -c mycoll`
-If the configuration directory is being used by another collection, then it will not be deleted even if you pass `-deleteConfig` as true.
-|`bin/solr delete -deleteConfig false`
-|-p <port> a|
-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.
+`-deleteConfig`::
+Whether or not the configuration directory should also be deleted from ZooKeeper. The default is `true`.
++
+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>`::
+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 standalone Solr instances on the same host, thus requiring you to be specific about which instance to delete the core from.
-|`bin/solr delete -p 8983`
-|===
++
+*Example*: `bin/solr delete -p 8983`
== Authentication
-// TODO 6.6 check this whole section for accuracy
-
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.
@@ -517,39 +580,38 @@ NOTE: Solr should have been started at least once before issuing these commands
Use the `zk upconfig` command to upload one of the pre-configured configuration set or a customized configuration set to ZooKeeper.
+==== ZK Upload Parameters
-[[SolrControlScriptReference-AvailableParameters_allparametersarerequired_]]
-==== Available Parameters (all parameters are required)
+All parameters below are required.
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
-
-[cols="20,40,40",options="header"]
-|===
-|Parameter |Description |Example
-|-n <name> a|
+`-n <name>`::
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`
- |`-n myconfig`
-|-d <configset dir> a|
+`-d <configset dir>`::
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_HOME/server/solr/configsets` will be checked for this name. An absolute path may be supplied instead.
++
+*Examples*:
- a|
-`-d directory_under_configsets`
-
-`-d /path/to/configset/source`
+* `-d directory_under_configsets`
+* `-d /path/to/configset/source`
-|-z <zkHost> |The ZooKeeper connection string. Unnecessary if ZK_HOST is defined in `solr.in.sh` or `solr.in.cmd`. |`-z 123.321.23.43:2181`
-|===
+`-z <zkHost>`::
+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 these parameters is:
+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`
+[source,bash]
+bin/solr zk upconfig -z 111.222.333.444:2181 -n mynewconfig -d /path/to/configset
.Reload Collections When Changing Configurations
[WARNING]
@@ -562,57 +624,70 @@ This command does *not* automatically make changes effective! It simply uploads
Use the `zk downconfig` command to download a configuration set from ZooKeeper to the local filesystem.
+==== ZK Download Parameters
-[[SolrControlScriptReference-AvailableParameters_allparametersarerequired_.1]]
-==== Available Parameters (all parameters are required)
+All parameters listed below are required.
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+`-n <name>`::
+Name of config set in ZooKeeper to download. The Admin UI Cloud \-> Tree \-> configs node lists all available configuration sets.
++
+*Example*: `-n myconfig`
-[cols="20,40,40",options="header"]
-|===
-|Parameter |Description |Example
-|-n <name> |Name of config set in ZooKeeper to download. The Admin UI Cloud \-> Tree \-> configs node lists all available configuration sets. |`-n myconfig`
-|-d <configset dir> a|
+`-d <configset dir>`::
The path to write the downloaded configuration set into. If just a name is supplied, `$SOLR_HOME/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*:
- a|
-`-d directory_under_configsets`
-
-`-d /path/to/configset/destination`
+* `-d directory_under_configsets`
+* `-d /path/to/configset/destination`
-|-z <zkHost> |The ZooKeeper connection string. Unnecessary if ZK_HOST is defined in `solr.in.sh` or `solr.in.cmd`. |`-z 123.321.23.43:2181`
-|===
+`-z <zkHost>`::
+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 the parameters is:
+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`
+[source,bash]
+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.
-[[SolrControlScriptReference-CopybetweenLocalFilesandZooKeeperznodes]]
=== 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.
-[[SolrControlScriptReference-AvailableParameters.5]]
-==== Available Parameters
+==== ZK Copy Parameters
+
+`-r`::
+Optional. Do a recursive copy. The command will fail if the <src> has children unless '-r' is specified.
++
+*Example*: `-r`
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+`<src>`::
+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*:
-[cols="20,40,40",options="header"]
-|===
-|Parameter |Description |Example
-|-r |Optional. Do a recursive copy. The command will fail if the <src> has children unless '-r' is specified. |`-r`
-|<src> |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. a|
-`zk:/configs/myconfigs/solrconfig.xml`
+* `zk:/configs/myconfigs/solrconfig.xml`
+* `file:/Users/apache/configs/src`
-`file:/Users/apache/configs/src`
+`<dest>`::
+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*:
-|<dest> |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. |`zk:/configs/myconfigs/solrconfig.xml` `file:/Users/apache/configs/src`
-|-z <zkHost> |The ZooKeeper connection string. Unnecessary if ZK_HOST is defined in `solr.in.sh` or `solr.in.cmd`. |`-z 123.321.23.43:2181`
-|===
+* `zk:/configs/myconfigs/solrconfig.xml`
+* `file:/Users/apache/configs/src`
+
+`-z <zkHost>`::
+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 the parameters is:
@@ -624,84 +699,88 @@ 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`
-[[SolrControlScriptReference-RemoveaznodefromZooKeeper]]
=== Remove a znode from ZooKeeper
Use the `zk rm` command to remove a znode (and optionally all child nodes) from ZooKeeper
-[[SolrControlScriptReference-AvailableParameters.6]]
-==== Available Parameters
+==== ZK Remove Parameters
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+`-r`::
+Optional. Do a recursive removal. The command will fail if the <path> has children unless '-r' is specified.
++
+*Example*: `-r`
-[cols="20,40,40",options="header"]
-|===
-|Parameter |Description |Example
-|-r |Optional. Do a recursive removal. The command will fail if the <path> has children unless '-r' is specified. |`-r`
-|<path> a|
+`<path>`::
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*:
- a|
-`/configs`
-
-`/configs/myconfigset`
-
-`/configs/myconfigset/solrconfig.xml`
+* `/configs`
+* `/configs/myconfigset`
+* `/configs/myconfigset/solrconfig.xml`
-|-z <zkHost> |The ZooKeeper connection string. Unnecessary if ZK_HOST is defined in `solr.in.sh` or `solr.in.cmd`. |`-z 123.321.23.43:2181`
-|===
+`-z <zkHost>`::
+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 the parameters is:
+Examples of this command with the parameters are:
`bin/solr zk rm -r /configs`
`bin/solr zk rm /configs/myconfigset/schema.xml`
-[[SolrControlScriptReference-MoveOneZooKeeperznodetoAnother_Rename_]]
=== Move One ZooKeeper znode to Another (Rename)
Use the `zk mv` command to move (rename) a ZooKeeper znode
-[[SolrControlScriptReference-AvailableParameters.7]]
-==== Available Parameters
+==== ZK Move Parameters
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+`<src>`::
+The znode to rename. The `zk:` prefix is assumed.
++
+*Example*: `/configs/oldconfigset`
-[cols="20,40,40",options="header"]
-|===
-|Parameter |Description |Example
-|<src> |The znode to rename. The `zk:` prefix is assumed. |`/configs/oldconfigset`
-|<dest> |The new name of the znode. The `zk:` prefix is assumed. |`/configs/newconfigset`
-|-z <zkHost> |The ZooKeeper connection string. Unnecessary if ZK_HOST is defined in `solr.in.sh` or `solr.in.cmd`. |`-z 123.321.23.43:2181`
-|===
+`<dest>`::
+The new name of the znode. The `zk:` prefix is assumed.
++
+*Example*: `/configs/newconfigset`
+
+`-z <zkHost>`::
+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`
-[[SolrControlScriptReference-ListaZooKeeperznode_sChildren]]
=== List a ZooKeeper znode's Children
Use the `zk ls` command to see the children of a znode.
-[[SolrControlScriptReference-AvailableParameters.8]]
-==== Available Parameters
+==== ZK List Parameters
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+`-r`
+Optional. Recursively list all descendants of a znode.
++
+*Example*: `-r`
-[cols="20,40,40",options="header"]
-|===
-|Parameter |Description |Example
-|-r |Optional. Recursively list all descendants of a znode. |`-r`
-|<path> |The path on ZooKeeper to list. |`/collections/mycollection`
-|-z <zkHost> |The ZooKeeper connection string. Unnecessary if ZK_HOST is defined in `solr.in.sh` or `solr.in.cmd`. |`-z 123.321.23.43:2181`
-|===
+`<path>`::
+The path on ZooKeeper to list.
++
+*Example*: `/collections/mycollection`
+
+`-z <zkHost>`::
+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 the parameters is:
@@ -716,16 +795,17 @@ An example of this command with the parameters is:
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.
[[SolrControlScriptReference-AvailableParameters.9]]
-==== Available Parameters
+==== Create znode Parameters
-// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
+`<path>`::
+The path on ZooKeeper to create. Intermediate znodes will be created if necessary. A leading slash is assumed even if not specified.
++
+*Example*: `/solr`
-[cols="20,40,40",options="header"]
-|===
-|Parameter |Description |Example
-|<path> |The path on ZooKeeper to create. Intermediate znodes will be created if necessary. A leading slash is assumed even if not specified. |`/solr`
-|-z <zkHost> |The ZooKeeper connection string. Unnecessary if ZK_HOST is defined in `solr.in.sh` or `solr.in.cmd`. |`-z 123.321.23.43:2181`
-|===
+`-z <zkHost>`::
+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`
Examples of this command: