[solr] branch branch_9x updated: SOLR-16797: Migrate detailed help/examples/tips from Solr CLI -h output to Ref Guide (#1667)

[ep...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

epugh pushed a commit to branch branch_9x
in repository https://gitbox.apache.org/repos/asf/solr.git


The following commit(s) were added to refs/heads/branch_9x by this push:
     new 12177c91971 SOLR-16797: Migrate detailed help/examples/tips from Solr CLI -h output to Ref Guide (#1667)
12177c91971 is described below

commit 12177c9197187c532fb6bff595510064e17a7af9
Author: Eric Pugh <ep...@opensourceconnections.com>
AuthorDate: Fri Jun 9 06:32:54 2023 -0400

    SOLR-16797: Migrate detailed help/examples/tips from Solr CLI -h output to Ref Guide (#1667)
    
    * migrate content from bin/solr api -h
    
    * review export command
    
    * match same text used in create_collection and others...
    
    * match what ref guide suggest the tool takes as params.
    
    * bin/solr config command
    
    * didnt have energy to do lots of adoc, so slapped it in like we did the post tool docs ;-)
    
    * small refactor
    
    * migrate "the good stuff" from bin/solr auth -h
    
    * grab some nice words from bin/solr delete -h
    
    * expand on the create core or collection docs to have a core specific and collection specific sections, pulled from content from bin/solr create, create_core, and create_collection.
    
    * small formatting fix, nothing else from bin/solr healthcheck needed
    
    * small wording tweak
    
    * migrate some great content out of bin/solr restart -h
    
    * wordsmithing from bin/solr stop -h
    
    * go through bin/solr zk -help and pull out content
    
    * pulled out content from bin/solr package -h
---
 .../src/java/org/apache/solr/cli/AuthTool.java     |   9 +-
 .../src/java/org/apache/solr/cli/ConfigTool.java   |   4 +-
 .../core/src/java/org/apache/solr/cli/SolrCLI.java |   2 +-
 .../configuration-guide/pages/package-manager.adoc |  20 +-
 .../pages/solr-control-script-reference.adoc       | 399 +++++++++++++++++----
 5 files changed, 356 insertions(+), 78 deletions(-)

diff --git a/solr/core/src/java/org/apache/solr/cli/AuthTool.java b/solr/core/src/java/org/apache/solr/cli/AuthTool.java
index 7976fb603b4..f87ed52c6a3 100644
--- a/solr/core/src/java/org/apache/solr/cli/AuthTool.java
+++ b/solr/core/src/java/org/apache/solr/cli/AuthTool.java
@@ -223,12 +223,9 @@ public class AuthTool extends ToolBase {
               zkClient.setData(
                   "/security.json", securityJson.getBytes(StandardCharsets.UTF_8), true);
             } catch (Exception ex) {
-              if (!zkInaccessible) {
-                CLIO.out(
-                    "Unable to access ZooKeeper. Please add the following security.json to ZooKeeper (in case of SolrCloud):\n"
-                        + securityJson);
-                zkInaccessible = true;
-              }
+              CLIO.out(
+                  "Unable to access ZooKeeper. Please add the following security.json to ZooKeeper (in case of SolrCloud):\n"
+                      + securityJson);
             }
           }
         }
diff --git a/solr/core/src/java/org/apache/solr/cli/ConfigTool.java b/solr/core/src/java/org/apache/solr/cli/ConfigTool.java
index b1fac68d2b5..86ce0d9f4cd 100644
--- a/solr/core/src/java/org/apache/solr/cli/ConfigTool.java
+++ b/solr/core/src/java/org/apache/solr/cli/ConfigTool.java
@@ -54,7 +54,7 @@ public class ConfigTool extends ToolBase {
                 .hasArg()
                 .required(false)
                 .desc(
-                    "Config API action, one of: set-property, unset-property; default is 'set-property'.")
+                    "Config API action, one of: set-property, unset-property; set-user-property, unset-user-property; default is 'set-property'.")
                 .build(),
             Option.builder("property")
                 .argName("PROP")
@@ -105,7 +105,7 @@ public class ConfigTool extends ToolBase {
     }
 
     String action = cli.getOptionValue("action", "set-property");
-    String collection = cli.getOptionValue("collection", "gettingstarted");
+    String collection = cli.getOptionValue("collection");
     String property = cli.getOptionValue("property");
     String value = cli.getOptionValue("value");
 
diff --git a/solr/core/src/java/org/apache/solr/cli/SolrCLI.java b/solr/core/src/java/org/apache/solr/cli/SolrCLI.java
index af95a0711f7..cde8dbc865f 100755
--- a/solr/core/src/java/org/apache/solr/cli/SolrCLI.java
+++ b/solr/core/src/java/org/apache/solr/cli/SolrCLI.java
@@ -113,7 +113,7 @@ public class SolrCLI implements CLIO {
               .argName("COLLECTION")
               .hasArg()
               .required(false)
-              .desc("Name of collection; no default.")
+              .desc("Name of collection")
               .longOpt("collection")
               .build(),
           OPTION_VERBOSE);
diff --git a/solr/solr-ref-guide/modules/configuration-guide/pages/package-manager.adoc b/solr/solr-ref-guide/modules/configuration-guide/pages/package-manager.adoc
index e07996e656f..2456ef7f244 100644
--- a/solr/solr-ref-guide/modules/configuration-guide/pages/package-manager.adoc
+++ b/solr/solr-ref-guide/modules/configuration-guide/pages/package-manager.adoc
@@ -62,7 +62,7 @@ In order to install packages into Solr, one has to add a repository hosting the
 
 [source,bash]
 ----
-$ bin/solr package add-repo <name-of-repo> <repo-url>
+$ bin/solr package add-repo <repository-name> <repository-url>
 ----
 
 NOTE: Do not add repositories that you don't trust or control.
@@ -84,7 +84,7 @@ To list packages available for installation from added repositories:
 $ bin/solr package list-available
 ----
 
-To install a package:
+To install a package, coping over the artifacts from the repository into Solr's internal package store and setting up classloader for this package to be used:
 
 [source,bash]
 ----
@@ -99,11 +99,10 @@ There are two ways to do this: either use the CLI's `deploy` command or manually
 
 ==== deploy Command
 
-If the package author states support for it, the package can be deployed with the CLI's `deploy` command:
-
+If the package author states support for it, the package can be deployed with the CLI's `deploy` command.
 [source,bash]
 ----
-$ bin/solr package deploy <package-name>:[version] -collections <collection1>[,<collection2>,...]
+$ bin/solr package deploy <package-name>:[version] -collections <collection1>[,<collection2>,...] [-p <param1>=<val1> -p <param2>=<val2> ...
 ----
 
 or
@@ -113,6 +112,13 @@ or
 $ bin/solr package deploy <package-name>:[version] -cluster
 ----
 
+If the package accepts parameters for its setup commands, they can be specified (as per package documentation):
+
+[source,bash]
+----
+$ bin/solr package deploy <snipped...> -p <param1>=<val1> -p <param2>=<val2>
+----
+
 The author may want you to confirm deployment of a package via a prompt.
 If you pass `-y` to the command, confirmation can be skipped.
 
@@ -196,9 +202,11 @@ or
 
 [source,bash]
 ----
-$ bin/solr package deploy <package-name> -cluster
+$ bin/solr package deploy <package-name>:<package-version> -cluster
 ----
 
+Both package name and version are required.
+
 == Security
 
 The `add-repo` step should only be executed using HTTPS enabled repository urls only so as to prevent against MITM attacks when Solr is fetching the public key for the repository.
diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/solr-control-script-reference.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/solr-control-script-reference.adoc
index fb674805f04..b5be509ae78 100644
--- a/solr/solr-ref-guide/modules/deployment-guide/pages/solr-control-script-reference.adoc
+++ b/solr/solr-ref-guide/modules/deployment-guide/pages/solr-control-script-reference.adoc
@@ -51,7 +51,7 @@ If no nodes are already running, restart will skip the step to stop and proceed
 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.
 
-`-a "<string>"`::
+`-a "<jvmParams>"`::
 +
 [%autowidth,frame=none]
 |===
@@ -59,6 +59,9 @@ However, most of the defaults are adequate for most Solr installations, especial
 |===
 +
 Start Solr with additional JVM parameters, such as those starting with `-X`.
+For example setting up Java debugger to attach to the Solr JVM you could pass: `-a "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=18983"`.
+In most cases, you should wrap the additional parameters in double quotes.
++
 If you are passing JVM parameters that begin with `-D`, you can omit the `-a` option.
 +
 *Example*:
@@ -66,6 +69,17 @@ If you are passing JVM parameters that begin with `-D`, you can omit the `-a` op
 [source,bash]
 bin/solr start -a "-Xdebug -Xrunjdwp:transport=dt_socket, server=y,suspend=n,address=1044"
 
+`-j "<jettyParams>"`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+Additional parameters to pass to Jetty when starting Solr.
+For example, to add configuration folder that Jetty should read you could pass: `-j "--include-jetty-dir=/etc/jetty/custom/server/"`.
+In most cases, you should wrap the additional parameters in double quotes.
+
 `-cloud` or `-c`::
 +
 [%autowidth,frame=none]
@@ -74,8 +88,7 @@ bin/solr start -a "-Xdebug -Xrunjdwp:transport=dt_socket, server=y,suspend=n,add
 |===
 +
 Start Solr in SolrCloud mode, which will also launch the embedded ZooKeeper instance included with Solr.
-+
-This option can be shortened to simply `-c`.
+The embedded ZooKeeper instance is started on Solr port+1000, so 9983 if Solr is bound to 8983.
 +
 If you are already running a ZooKeeper ensemble that you want to use instead of the embedded (single-node) ZooKeeper, you should also either specify `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see xref:zookeeper-ensemble.adoc#updating-solr-include-files[Updating Solr Include Files]) or pass the `-z` parameter.
 +
@@ -108,10 +121,10 @@ These examples are provided to help you get started faster with Solr generally,
 +
 The available options are:
 
-* `cloud`
-* `techproducts`
-* `schemaless`
-* `films`
+* `cloud`: SolrCloud example
+* `techproducts`: Comprehensive example illustrating many of Solr's core capabilities
+* `schemaless`: Schema-less example (schema is inferred from data during indexing)
+* `films`: Example of starting with _default configset and adding explicit fields dynamically
 +
 See the section <<Running with Example Configurations>> below for more details on the example configurations.
 +
@@ -124,7 +137,7 @@ See the section <<Running with Example Configurations>> below for more details o
 |Optional |Default: none
 |===
 +
-Start Solr in the foreground.
+Start Solr in the foreground and sends stdout / stderr to `solr-PORT-console.log`.
 You cannot use this option when running examples with the `-e` option.
 +
 *Example*: `bin/solr start -f`
@@ -136,7 +149,7 @@ You cannot use this option when running examples with the `-e` option.
 |Optional |Default: `localhost`
 |===
 +
-Start Solr with the defined hostname.
+Specify the hostname for this Solr instance.
 If this is not specified, `localhost` is assumed.
 +
 *Example*: `bin/solr start -h search.mysolr.com`
@@ -145,12 +158,12 @@ If this is not specified, `localhost` is assumed.
 +
 [%autowidth,frame=none]
 |===
-|Optional |Default: none
+|Optional |Default: 512m
 |===
 +
-Start Solr with the defined value as the min (`-Xms`) and max (`-Xmx`) heap size for the JVM.
+Sets the min (`-Xms`) and max (`-Xmx`) heap size for the JVM running Solr.
 +
-*Example*: `bin/solr start -m 1g`
+*Example*: `bin/solr start -m 4g` results in `-Xms4g -Xmx4g` settings.
 
 `-noprompt`::
 +
@@ -159,8 +172,7 @@ Start Solr with the defined value as the min (`-Xms`) and max (`-Xmx`) heap size
 |Optional |Default: none
 |===
 +
-Start Solr and suppress any prompts that may be seen with another option.
-This would have the side effect of accepting all defaults implicitly.
+Don't prompt for input; accept all defaults when running examples that accept user input.
 +
 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.
@@ -174,7 +186,10 @@ If you want to accept all of the defaults, you can simply add the `-noprompt` op
 |Optional |Default: `8983`
 |===
 +
-Start Solr on the defined port.
+Specify the port to start the Solr HTTP listener on; with the classic default port for Solr being 8983.
+The specified port (SOLR_PORT) will also be used to determine the stop port.
+The stop port is defined as STOP_PORT=($SOLR_PORT-1000) and JMX RMI listen port is defined as RMI_PORT=($SOLR_PORT+10000). 
+For instance, if you set -p 8985, then the STOP_PORT=7985 and RMI_PORT=18985.
 If this is not specified, `8983` will be used.
 +
 *Example*: `bin/solr start -p 8655`
@@ -189,11 +204,25 @@ If this is not specified, `8983` will be used.
 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.
 +
 This parameter is ignored when running examples (`-e`), as the `solr.solr.home` depends on which example is run.
 +
+The default value is `server/solr`. 
+If passed relative dir, validation with current dir will be done, before trying default `server/<dir>`.
++
 *Example*: `bin/solr start -s newHome`
 
+`-t <dir>`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `solr.solr.home`
+|===
++
+Sets the `solr.data.home` system property, where Solr will store index data in <instance_dir>/data subdirectories.
+If not set, Solr uses solr.solr.home for config and data.
+
 `-v`::
 +
 [%autowidth,frame=none]
@@ -226,7 +255,7 @@ This can be useful in a production setting where you want to limit logging to wa
 |Optional |Default: none
 |===
 +
-Start Solr with verbose messages from the start script.
+Verbose messages from this script.
 +
 *Example*: `bin/solr start -V`
 
@@ -237,11 +266,11 @@ Start Solr with verbose messages from the start script.
 |Optional |Default: _see description_
 |===
 +
-Start Solr with the defined ZooKeeper connection string.
-+
-This option is only used with the `-c` option, to start Solr in SolrCloud mode.
+Zookeeper connection string, this option is only used with the `-c` option, to start Solr in SolrCloud mode.
 If `ZK_HOST` is not specified in `solr.in.sh`/`solr.in.cmd` and this option is not provided, Solr will start the embedded ZooKeeper instance and use that instance for SolrCloud operations.
 +
+Set the `ZK_CREATE_CHROOT` environment variable to true if your ZK host has a chroot path, and you want to create it automatically.
++
 *Example*: `bin/solr start -c -z server1:2181,server2:2181`
 
 `-force`::
@@ -371,7 +400,7 @@ If you are running more than one instance, or are running in SolrCloud mode, you
 |Optional |Default: none
 |===
 +
-Stop all running Solr instances that have a valid PID.
+Find and stop all running Solr servers on this host that have a valid PID.
 +
 *Example*: `bin/solr stop -all`
 
@@ -393,7 +422,7 @@ Stop key used to protect from stopping Solr inadvertently; default is "solrrocks
 |Optional |Default: none
 |===
 +
-Stop Solr with verbose messages from the stop script.
+Stop Solr with verbose messages from this script.
 +
 *Example*: `bin/solr stop -V`
 
@@ -411,7 +440,7 @@ X.Y.0
 
 === Status
 
-The `status` command displays basic JSON-formatted information for any Solr nodes found running on the local system.
+The `status` command displays basic JSON-formatted status information for all locally running Solr servers.
 
 The `status` command uses the `SOLR_PID_DIR` environment variable to locate Solr process ID files to find running Solr instances, which defaults to the `bin` directory.
 
@@ -464,7 +493,39 @@ Results in the output below:
 [source,plain]
 ERROR: Directory /opt/bin/solr does not exist.
 
-Use `bin/solr assert -help` for a full list of options.
+The basic usage of `bin/solr assert` is:
+
+[source, plain]
+----
+$ bin/solr assert -h
+usage: bin/solr assert [-m <message>] [-e] [-rR] [-s <url>] [-S <url>] [-c
+                <url>] [-C <url>] [-u <dir>] [-x <dir>] [-X <dir>]
+ -c,--cloud <url>              Asserts that Solr is running in cloud mode.
+                               Also fails if Solr not running.  URL should
+                               be for root Solr path.
+ -C,--not-cloud <url>          Asserts that Solr is not running in cloud
+                               mode.  Also fails if Solr not running.  URL
+                               should be for root Solr path.
+ -e,--exitcode                 Return an exit code instead of printing
+                               error message on assert fail.
+ -help                         Print this message
+ -m,--message <message>        Exception message to be used in place of
+                               the default error message.
+ -R,--not-root                 Asserts that we are NOT the root user.
+ -r,--root                     Asserts that we are the root user.
+ -S,--not-started <url>        Asserts that Solr is NOT running on a
+                               certain URL. Default timeout is 1000ms.
+ -s,--started <url>            Asserts that Solr is running on a certain
+                               URL. Default timeout is 1000ms.
+ -t,--timeout <ms>             Timeout in ms for commands supporting a
+                               timeout.
+ -u,--same-user <directory>    Asserts that we run as same user that owns
+                               <directory>.
+ -verbose                      Enable more verbose command output.
+ -x,--exists <directory>       Asserts that directory <directory> exists.
+ -X,--not-exists <directory>   Asserts that directory <directory> does NOT
+                               exist.
+----
 
 === Healthcheck
 
@@ -484,7 +545,7 @@ The health report provides information about the state of every replica for all
 s|Required |Default: none
 |===
 +
- Name of the collection to run a healthcheck against.
+Name of the collection to run a healthcheck against.
 +
 *Example*: `bin/solr healthcheck -c gettingstarted`
 
@@ -560,10 +621,9 @@ The `bin/solr` script can also help you create new collections or cores, or dele
 
 === Create a Core or Collection
 
-The `create` command detects the mode that Solr is running in and creates either a core or collection depending on the mode.
-When running with SolrCloud, a collection would be created.
-When running a user-managed cluster or a single-node installation, a core would be created.
-
+The `create` command creates a core or collection depending on whether Solr is running in standalone (core) or SolrCloud mode (collection). 
+In other words, this action detects which mode Solr is running in, and then takes the appropriate action (either `create_core` or `create_collection`).
+  
 `bin/solr create [options]`
 
 `bin/solr create -help`
@@ -656,10 +716,178 @@ It is possible to override this warning with the -force parameter.
 +
 *Example*: `bin/solr create -c foo -force`
 
+=== Create a Collection
+
+The `create_collection` command creates a collection, and is only available when running in SolrCloud mode. 
+  
+`bin/solr create_collection [options]`
+
+`bin/solr create_collection -help`
+
+==== Create Collection Parameters
+
+`-c <name>`::
++
+[%autowidth,frame=none]
+|===
+s|Required |Default: none
+|===
++
+Name of the collection to create.
++
+*Example*: `bin/solr create_collection -c mycollection`
+
+`-d <confdir>`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `_default`
+|===
++
+Configuration directory to copy when creating the new collection.
++
+See the section <<Configuration Directories and SolrCloud>> below for more details about this option when running in SolrCloud mode. including some built in example configurations.
++
+`_default` is also known as xref:indexing-guide:schemaless-mode.adoc[].
++
+*Example*: `bin/solr create_collection -d _default`
++
+Alternatively, you can pass the path to your own configuration directory instead of using one of the built-in configurations.
++
+*Example*: `bin/solr create_collection -c mycoll -d /tmp/myconfig`
++
+By default the script will upload the specified confdir directory into Zookeeper using the same name as the collection (-c) option. 
+Alternatively, if you want to reuse an existing directory or create a confdir in Zookeeper that can be shared by multiple collections, use the -n option
++
+
+`-n <configName>`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: _see description_
+|===
++
+Name the configuration directory in Zookeeper.
+By default, the configuration will be uploaded to Zookeeper using the collection name (-c), but if you want to use an existing directory or override the name of the configuration in Zookeeper, then use the -c option.
+UMMMM...   I COPIED THE ABOVE LINE FROM bin/solr create_collection -h output, but I don't get it.  And bin/solr create_collection -n basic -c mycoll works, it create a copy of _default as "basic" configset... UMMM?
++
+*Example*: `bin/solr create_collection -n basic -c mycoll`
+
+`-p <port>` or `-port <port>`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: _see description_
+|===
++
+Port of a local Solr instance where you want to create the new collection.
+If not specified, the script will search the local system for a running Solr instance and will use the port of the first server it finds.
++
+This option is useful if you are running multiple 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`
+
+`-s <shards>` or `-shards <shards>`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `1`
+|===
++
+Number of shards to split a collection into.
++
+*Example*: `bin/solr create_collection -s 2`
+
+`-rf <replicas>` or `-replicationFactor <replicas>`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `1`
+|===
++
+Number of copies of each document in the collection.
+The default is `1` (no replication).
++
+*Example*: `bin/solr create_collection -rf 2`
+
+`-force`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+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_collection -c foo -force`
+
+=== Create a Core
+
+The `create_core` command creates a core and is only available when running in user-managed (single-node) mode. 
+  
+`bin/solr create_core [options]`
+
+`bin/solr create_core -help`
+
+==== Create Core Parameters
+
+`-c <name>`::
++
+[%autowidth,frame=none]
+|===
+s|Required |Default: none
+|===
++
+Name of the core to create.
++
+*Example*: `bin/solr create -c mycore`
+
+`-d <confdir>`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `_default`
+|===
++
+The configuration directory to use when creating a new core.
++
+*Example*: `bin/solr create -d _default`
++
+Alternatively, you can pass the path to your own configuration directory instead of using one of the built-in configurations.
++
+*Example*: `bin/solr create_collection -c mycore -d /tmp/myconfig`
+
+`-p <port>` or `-port <port>`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: _see description_
+|===
++
+The port of a local Solr instance to create the new core.
+By default the script tries to detect the port by looking for running Solr instances.
++
+This option is useful if you are running multiple 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`
+
+`-force`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+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`
+
 ==== 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 `create` and `create_collection` commands 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.
@@ -706,11 +934,10 @@ The `delete` command detects the mode that Solr is running in and then deletes t
 
 `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.
+If you're deleting a collection in SolrCloud mode, the default behavior is to also delete the configuration directory from Zookeeper so long as it is not being used by another collection.
 
 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.
+If not, then the `/configs/contacts` directory is removed from ZooKeeper.  You can override this behavior by passing -deleteConfig false when running this command.atom
 
 ==== Delete Core or Collection Parameters
 
@@ -746,7 +973,7 @@ If the configuration directory is being used by another collection, then it will
 |===
 +
 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.
+If not specified, the script will search the local system for a running Solr instance and will use the port of the first server it finds.
 +
 This option is useful if you are running multiple Solr instances on the same host, thus requiring you to be specific about which instance to delete the core from.
 +
@@ -758,6 +985,8 @@ The `bin/solr` script allows enabling or disabling Basic Authentication, allowin
 
 Currently, this script only enables Basic Authentication, and is only available when using SolrCloud mode.
 
+Must be run on the machine hosting Solr.
+
 === Enabling Basic Authentication
 
 The command `bin/solr auth enable` configures Solr to use Basic Authentication when accessing the User Interface, using `bin/solr` and any API requests.
@@ -799,6 +1028,18 @@ SOLR_AUTHENTICATION_OPTS="-Dsolr.httpclient.config=/path/to/solr-{solr-full-vers
 ----
 * Creates the file `server/solr/basicAuth.conf` to store the credential information that is used with `bin/solr` commands.
 
+Here are some example usages:
+
+[source,plain]
+----
+Usage: solr auth enable [-type basicAuth] -credentials user:pass [-blockUnknown <true|false>] [-updateIncludeFileOnly <true|false>] [-V]
+       solr auth enable [-type basicAuth] -prompt <true|false> [-blockUnknown <true|false>] [-updateIncludeFileOnly <true|false>] [-V]
+       solr auth enable -type kerberos -config "<kerberos configs>" [-updateIncludeFileOnly <true|false>] [-V]
+       solr auth disable [-updateIncludeFileOnly <true|false>] [-V]
+----
+
+
+
 The command takes the following parameters:
 
 `-credentials <user:pass>`::
@@ -808,7 +1049,8 @@ The command takes the following parameters:
 |Optional |Default: none
 |===
 +
-The username and password in the format of `username:password` of the initial user.
+The username and password in the format of `username:password` of the initial user.  
+Applicable for basicAuth only.
 +
 If you prefer not to pass the username and password as an argument to the script, you can choose the `-prompt` option.
 Either `-credentials` or `-prompt` *must* be specified.
@@ -820,7 +1062,7 @@ Either `-credentials` or `-prompt` *must* be specified.
 |Optional |Default: none
 |===
 +
-If prompt is preferred, pass `true` as a parameter to request the script to prompt the user to enter a username and password.
+Prompts the user to provide the credentials. If prompt is preferred, pass `true` as a parameter to request the script prompt the user to enter a username and password.
 +
 Either `-credentials` or `-prompt` *must* be specified.
 
@@ -831,7 +1073,7 @@ Either `-credentials` or `-prompt` *must* be specified.
 |Optional |Default: `true`
 |===
 +
-When `true`, blocks all unauthenticated users from accessing Solr.
+When `true`, this blocks out access to unauthenticated users from accessing Solr.
 When `false`, unauthenticated users will still be able to access Solr, but only for operations not explicitly requiring a user role in the Authorization plugin configuration.
 
 `-solrIncludeFile <includeFilePath>`::
@@ -858,7 +1100,7 @@ If not specified this script looks for an include file named solr.in.sh to set e
 |Optional |Default: `false`
 |===
 +
-When `true`, only the settings in `bin/solr.in.sh` or `bin\solr.in.cmd` will be updated, and `security.json` will not be created.
+When `true`, only update the `bin/solr.in.sh` or `bin\solr.in.cmd`, and skip actual enabling/disabling authentication (i.e. don't update `security.json`).
 
 `-z <zkHost>` or `-zkHost <zkHost>`::
 +
@@ -890,6 +1132,7 @@ It is not common to need to override the default, and is only needed if you have
 +
 Defines the location of `solr.solr.home`, which by default is `server/solr`.
 If you have multiple instances of Solr on the same host, or if you have customized the `$SOLR_HOME` directory path, you likely need to define this.
+This is where any credentials or authentication configuration files (e.g. basicAuth.conf) would be placed.
 
 === Disabling Basic Authentication
 
@@ -959,7 +1202,7 @@ Config API action, one of: `set-property`, `unset-property`, `set-user-property`
 s|Required |Default: none
 |===
 +
-Name of the property to change.
+Name of the Config API property to apply the action to, such as: 'updateHandler.autoSoftCommit.maxTime'.
 
 `-value <new-value>`::
 +
@@ -968,13 +1211,13 @@ Name of the property to change.
 |Optional |Default: none
 |===
 +
-Set the property to this value.
+Set the property to this value; accepts JSON objects and strings.
 
 `-z <zkHost>` or `-zkHost <zkHost>`::
 +
 [%autowidth,frame=none]
 |===
-|Optional |Default: none
+|Optional |Default: `localhost:9983`
 |===
 +
 The ZooKeeper connection string, usable in SolrCloud mode.
@@ -993,7 +1236,7 @@ Unnecessary if `ZK_HOST` is defined in `solr.in.sh` or `solr.in.cmd`.
 +
 [%autowidth,frame=none]
 |===
-|Optional |Default: none
+|Optional |Default: `http://localhost:8983/solr`
 |===
 +
 Base Solr URL, which can be used in SolrCloud mode to determine the ZooKeeper connection string if that's not known.
@@ -1019,12 +1262,25 @@ The operations are available as sub-commands, which each have their own set of o
 
 `bin/solr zk -help`
 
+The basic usage of bin/solr zk is:
+
+[source,plain]
+----
+$ bin/solr zk -h
+Usage: solr zk upconfig|downconfig -d <confdir> -n <configName> [-z zkHost]
+         solr zk cp [-r] <src> <dest> [-z zkHost]
+         solr zk rm [-r] <path> [-z zkHost]
+         solr zk mv <src> <dest> [-z zkHost]
+         solr zk ls [-r] <path> [-z zkHost]
+         solr zk mkroot <path> [-z zkHost]
+----
+
 NOTE: Solr should have been started at least once before issuing these commands to initialize ZooKeeper with the znodes Solr expects.
 Once ZooKeeper is initialized, Solr doesn't need to be running on any node to use these commands.
 
 === Upload a Configuration Set
 
-Use the `zk upconfig` command to upload one of the pre-configured configuration set or a customized configuration set to ZooKeeper.
+Use the `zk upconfig` command to upload one of the pre-configured configuration sets or a customized configuration set to ZooKeeper.
 
 ==== ZK Upload Parameters
 
@@ -1054,7 +1310,7 @@ If a pre-existing configuration set is specified, it will be overwritten in ZooK
 s|Required |Default: none
 |===
 +
-The path of the configuration set to upload.
+The local directory 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_TIP/server/solr/configsets` will be checked for this name.
@@ -1162,8 +1418,8 @@ This command will copy from the local drive to ZooKeeper, from ZooKeeper to the
 |Optional |Default: none
 |===
 +
-Do a recursive copy.
-The command will fail if the `<src>` has children unless `-r` is specified.
+Recursively copy <src> to <dst>.
+The command will fail if the `<src>` has children and `-r` is not specified.
 +
 *Example*: `-r`
 
@@ -1176,8 +1432,8 @@ s|Required |Default: none
 +
 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.
+If no prefix or the prefix is `file:` then it is presumed to be the local drive.
+At least one of `<src>` or `<dest>` must be prefixed by `zk:` or the command will fail.
 +
 *Examples*:
 
@@ -1193,7 +1449,7 @@ s|Required |Default: none
 +
 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.
+If no prefix or the prefix is `file:` then it is presumed to be 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.
@@ -1215,15 +1471,30 @@ Optional 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:
+When `<src>` is a zk resource, `<dest>` may be '.'. 
+If `<dest>` ends with '/', then `<dest>` will be a local folder or parent znode and the last element of the <src> path will be appended unless `<src>` also ends in a slash. 
+`<dest>` may be `zk:`, which may be useful when using the `cp -r` form to backup/restore the entire zk state.
+You must enclose local paths that end in a wildcard in quotes or just end the local path in a slash. 
+That is, `bin/solr zk cp -r /some/dir/ zk:/ -z localhost:2181` is equivalent to `bin/solr zk cp -r "/some/dir/*" zk:/ -z localhost:2181` but `bin/solr zk cp -r /some/dir/\* zk:/ -z localhost:2181` will throw an error.
+
+Here's an example of backup/restore for a ZK configuration:
+
+*To copy to local*: `bin/solr zk cp -r zk:/ /some/dir -z localhost:2181`
 
-Recursively copy a directory from local to ZooKeeper.
+*To restore to ZK*: `bin/solr zk cp -r /some/dir/ zk:/ -z localhost:2181`
 
-`bin/solr zk cp -r file:/apache/confgs/whatever/conf zk:/configs/myconf -z 111.222.333.444:2181`
+The `file:` prefix is stripped, thus `file:/wherever` specifies an absolute local path and `file:somewhere` specifies a relative local path.
+All paths on Zookeeper are absolute.
 
-Copy a single file from ZooKeeper to local.
+Zookeeper nodes CAN have data, so moving a single file to a parent znode will overlay the data on the parent Znode so specifying the trailing slash can be important.
 
-`bin/solr zk cp zk:/configs/myconf/managed_schema /configs/myconf/managed_schema -z 111.222.333.444:2181`
+Trailing wildcards are supported when copying from localand must be quoted.
+
+Other examples are:
+
+*Recursively copy a directory from local to ZooKeeper*: `bin/solr zk cp -r file:/apache/confgs/whatever/conf zk:/configs/myconf -z 111.222.333.444:2181`
+
+*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`
 
 === Remove a znode from ZooKeeper
 
@@ -1238,8 +1509,8 @@ Use the `zk rm` command to remove a znode (and optionally all child nodes) from
 |Optional |Default: none
 |===
 +
-Do a recursive removal.
-The command will fail if the `<path>` has children unless `-r` is specified.
+Recursively delete if `<path>` is a directory.
+Command will fail if `<path>` has children and `-r` is not specified.
 +
 *Example*: `-r`
 
@@ -1342,6 +1613,7 @@ Use the `zk ls` command to see the children of a znode.
 |===
 +
 Recursively list all descendants of a znode.
+Only the node names are listed, not the data.
 +
 *Example*: `-r`
 
@@ -1377,7 +1649,7 @@ An example of this command with the parameters is:
 
 === Create a znode (supports chroot)
 
-Use the `zk mkroot` command to create a znode.
+Use the `zk mkroot` command to create a znode with no data.
 The primary use-case for this command to support ZooKeeper's "chroot" concept.
 However, it can also be used to create arbitrary paths.
 
@@ -1392,7 +1664,7 @@ s|Required |Default: none
 +
 The path on ZooKeeper to create.
 Intermediate znodes will be created if necessary.
-A leading slash is assumed even if not specified.
+A leading slash is assumed if not present.
 +
 *Example*: `/solr`
 
@@ -1460,9 +1732,9 @@ Choosing `javabin` exports in the native Solr format, and is compact and fast to
 |Optional |Default: _see description_
 |===
 +
-Either the path to a directory for the export to happen in, or a specific file name to populate.
+Either the path to the directory for the exported data to be written to, or a specific file to be written out.
 +
-If not provided, a file will be created with the name of the collection, as in `<collection>.json`.
+If only a directory is specified then the file will be created with the name of the collection, as in `<collection>.json`.
 
 `-compress`::
 +
@@ -1490,8 +1762,9 @@ The default is `\*:*` which will export all documents.
 |Optional |Default: none
 |===
 +
-A comma separated list of fields to be exported.
-If not provided, all fields will be included.
+Comma separated list of fields to be exported.
+By default all fields are fetched.
+
 
 `-limit <number of documents>`::
 +
@@ -1500,7 +1773,7 @@ If not provided, all fields will be included.
 |Optional |Default: `100`
 |===
 +
-The number of documents to export.
+Maximum number of docs to download.
 The value `-1` will export all documents.
 
 *Examples*
@@ -1574,7 +1847,7 @@ The `bin/solr api` command takes the following parameters:
 |Required |Default: none
 |===
 +
-Fully-qualified address to a collection.
+Send a GET request to a Solr API endpoint.
 +
 *Example*: `bin/solr api -get http://localhost:8983/solr/COLL_NAME/sql?stmt=select+id+from+COLL_NAME+limit+10`