SOLR-16824: Adopt Linux Command line tool pattern of -- for long opti…

…on commands (#1768)

This goes through all the various CLI tools and moves them all to using the same long form across all our tools, replacing a mish mash of older formats.   -zkHost is now --zk-host for example.  This pattern applies to both Windows and Linux bin/solr commands.  The old forms are now deprecated, though they continue to work.  The -u short command for --credentials is now used everywhere, this did mean the Assert tools "--same-user" command no longer has a "-u" option.
---------

Co-authored-by: Jan Høydahl <[email protected]>
Co-authored-by: Solr Bot <[email protected]>
Co-authored-by: Jan Høydahl <[email protected]>
Co-authored-by: Jason Gerlowski <[email protected]>

dev-docs/FAQ.adoc

@@ -26,7 +26,7 @@ You can review instructions for running Solr in Docker in the xref:running-in-do
 === Whats the fastest build lifecycle for frontend work on Solr Admin?
 
 Run `gradle dev`, and then `cd ./packaging/build/dev/`.  Fire up your cluster
-via `bin/solr start -e cloud -noprompt` and then as you make changes to assets in `/solr/webapp/web`,
+via `bin/solr start -e cloud --no-prompt` and then as you make changes to assets in `/solr/webapp/web`,
 run `gradle dev` to redeploy the web assets. Do a  hard refresh in your browser
 to pick up your changes.
 
@@ -97,4 +97,3 @@ If you don't yet have an account, you have to ask for one in the 'users' or 'dev
 * http://fucit.org/solr-jenkins-reports/failure-report.html
 * https://ge.apache.org/scans/tests?search.relativeStartTime=P90D&search.rootProjectNames=solr*
 * https://lists.apache.org[Solr mailing list archives especially builds]
-

dev-tools/scripts/cloud.sh

@@ -352,7 +352,7 @@ stop() {
   SOLR=${CLUSTER_WD}/$(find . -maxdepth 1 -name 'solr*' -type d -print0 | xargs -0 ls -1 -td | sed -E 's/\.\/(solr.*)/\1/' | head -n1)
   popd
 
-  "${SOLR}/bin/solr" stop -all
+  "${SOLR}/bin/solr" stop --all
 }
 
 ########################

solr/CHANGES.txt

@@ -135,6 +135,10 @@ Improvements
 
 * SOLR-15591: Make using debugger in Solr easier by avoiding NPE in ExternalPaths.determineSourceHome.  (@charlygrappa via Eric Pugh)
 
+* SOLR-16824: Adopt Linux standard pattern of -- for long option commands, and make all commands "kebab" formatting.  I.e -zkHost is now -zk-host.  The old parameters
+  such as -zkHost continue to be supported in the 9.x line of Solr.  -u is now used to specify user credentials everywhere, this only impacts the bin/solr assert 
+  commands "same user" check which has -u as the short form of --same-user. (Eric Pugh, janhoy, Jason Gerlowski)
+
 Optimizations
 ---------------------
 * SOLR-17257: Both Minimize Cores and the Affinity replica placement strategies would over-gather

solr/core/build.gradle

@@ -191,5 +191,3 @@ dependencies {
     exclude group: "net.bytebuddy", module: "byte-buddy-agent"
   })
 }
-
-

solr/core/src/java/org/apache/solr/cli/ApiTool.java

@@ -21,6 +21,7 @@
 import java.net.URI;
 import java.util.List;
 import org.apache.commons.cli.CommandLine;
+import org.apache.commons.cli.DeprecatedAttributes;
 import org.apache.commons.cli.Option;
 import org.apache.solr.client.solrj.SolrRequest;
 import org.apache.solr.client.solrj.impl.JsonMapResponseParser;
@@ -52,10 +53,24 @@ public String getName() {
   @Override
   public List<Option> getOptions() {
     return List.of(
+        Option.builder()
+            .longOpt("solr-url")
+            .argName("URL")
+            .hasArg()
+            .required(false) // swap back to required when we eliminate deprecated option
+            .desc("Send a GET request to a Solr API endpoint.")
+            .build(),
         Option.builder("get")
+            .longOpt("get")
+            .deprecated(
+                DeprecatedAttributes.builder()
+                    .setForRemoval(true)
+                    .setSince("9.7")
+                    .setDescription("Use --solr-url instead")
+                    .get())
             .argName("URL")
             .hasArg()
-            .required(true)
+            .required(false)
             .desc("Send a GET request to a Solr API endpoint.")
             .build(),
         SolrCLI.OPTION_CREDENTIALS);
@@ -64,7 +79,8 @@ public List<Option> getOptions() {
   @Override
   public void runImpl(CommandLine cli) throws Exception {
     String response = null;
-    String getUrl = cli.getOptionValue("get");
+    String getUrl =
+        cli.hasOption("solr-url") ? cli.getOptionValue("solr-url") : cli.getOptionValue("get");
     if (getUrl != null) {
       response = callGet(getUrl, cli.getOptionValue(SolrCLI.OPTION_CREDENTIALS.getLongOpt()));
     }

solr/core/src/java/org/apache/solr/cli/AssertTool.java

@@ -77,7 +77,7 @@ public List<Option> getOptions() {
             .hasArg(true)
             .argName("url")
             .build(),
-        Option.builder("u")
+        Option.builder()
             .desc("Asserts that we run as same user that owns <directory>.")
             .longOpt("same-user")
             .hasArg(true)
@@ -126,14 +126,7 @@ public List<Option> getOptions() {
             .desc("Return an exit code instead of printing error message on assert fail.")
             .longOpt("exitcode")
             .build(),
-        // u was taken, can we change that instead?
-        Option.builder("credentials")
-            .argName("credentials")
-            .hasArg()
-            .required(false)
-            .desc(
-                "Credentials in the format username:password. Example: --credentials solr:SolrRocks")
-            .build());
+        SolrCLI.OPTION_CREDENTIALS);
   }
 
   @Override
@@ -196,8 +189,8 @@ protected int runAssert(CommandLine cli) throws Exception {
     if (cli.hasOption("X")) {
       ret += assertFileNotExists(cli.getOptionValue("X"));
     }
-    if (cli.hasOption("u")) {
-      ret += sameUser(cli.getOptionValue("u"));
+    if (cli.hasOption("same-user")) {
+      ret += sameUser(cli.getOptionValue("same-user"));
     }
     if (cli.hasOption("s")) {
       ret +=

solr/core/src/java/org/apache/solr/cli/AuthTool.java

@@ -66,54 +66,55 @@ public String getName() {
   @Override
   public List<Option> getOptions() {
     return List.of(
-        Option.builder("type")
-            .argName("type")
+        Option.builder()
+            .longOpt("type")
             .hasArg()
             .desc(
                 "The authentication mechanism to enable (basicAuth or kerberos). Defaults to 'basicAuth'.")
             .build(),
-        SolrCLI.OPTION_CREDENTIALS,
-        Option.builder("prompt")
-            .argName("prompt")
+        Option.builder()
+            .longOpt("prompt")
             .hasArg()
             .desc(
-                "Prompts the user to provide the credentials. Use either -credentials or -prompt, not both.")
+                "Prompts the user to provide the credentials. Use either --credentials or --prompt, not both.")
             .build(),
-        Option.builder("config")
-            .argName("config")
+        Option.builder()
+            .longOpt("config")
             .hasArgs()
             .desc(
                 "Configuration parameters (Solr startup parameters). Required for Kerberos authentication.")
             .build(),
-        Option.builder("blockUnknown")
-            .argName("blockUnknown")
+        Option.builder()
+            .longOpt("block-unknown")
             .desc(
                 "Blocks all access for unknown users (requires authentication for all endpoints).")
             .hasArg()
             .build(),
-        Option.builder("solrIncludeFile")
-            .argName("solrIncludeFile")
+        Option.builder()
+            .longOpt("solr-include-file")
             .hasArg()
             .desc(
                 "The Solr include file which contains overridable environment variables for configuring Solr configurations.")
             .build(),
-        Option.builder("updateIncludeFileOnly")
-            .argName("updateIncludeFileOnly")
+        Option.builder()
+            .longOpt("update-include-file-only")
             .desc(
                 "Only update the solr.in.sh or solr.in.cmd file, and skip actual enabling/disabling"
                     + " authentication (i.e. don't update security.json).")
             .hasArg()
             .build(),
-        Option.builder("authConfDir")
-            .argName("authConfDir")
+        Option.builder()
+            .longOpt("auth-conf-dir")
             .hasArg()
             .required()
             .desc(
                 "This is where any authentication related configuration files, if any, would be placed.")
             .build(),
         SolrCLI.OPTION_SOLRURL,
+        SolrCLI.OPTION_SOLRURL_DEPRECATED,
         SolrCLI.OPTION_ZKHOST,
-        SolrCLI.OPTION_VERBOSE);
+        SolrCLI.OPTION_ZKHOST_DEPRECATED,
+        SolrCLI.OPTION_CREDENTIALS);
   }
 
   private void ensureArgumentIsValidBooleanIfPresent(CommandLine cli, String argName) {
@@ -130,8 +131,8 @@ private void ensureArgumentIsValidBooleanIfPresent(CommandLine cli, String argNa
   public int runTool(CommandLine cli) throws Exception {
     SolrCLI.raiseLogLevelUnlessVerbose(cli);
 
-    ensureArgumentIsValidBooleanIfPresent(cli, "blockUnknown");
-    ensureArgumentIsValidBooleanIfPresent(cli, "updateIncludeFileOnly");
+    ensureArgumentIsValidBooleanIfPresent(cli, "block-unknown");
+    ensureArgumentIsValidBooleanIfPresent(cli, "update-include-file-only");
 
     String type = cli.getOptionValue("type", "basicAuth");
     switch (type) {
@@ -149,7 +150,7 @@ public int runTool(CommandLine cli) throws Exception {
   private int handleKerberos(CommandLine cli) throws Exception {
     String cmd = cli.getArgs()[0];
     boolean updateIncludeFileOnly =
-        Boolean.parseBoolean(cli.getOptionValue("updateIncludeFileOnly", "false"));
+        Boolean.parseBoolean(cli.getOptionValue("update-include-file-only", "false"));
     String securityJson =
         "{"
             + "\n  \"authentication\":{"
@@ -219,7 +220,7 @@ private int handleKerberos(CommandLine cli) throws Exception {
                 StandardCharsets.UTF_8);
         config = config.replace("\n", "").replace("\r", "");
 
-        String solrIncludeFilename = cli.getOptionValue("solrIncludeFile");
+        String solrIncludeFilename = cli.getOptionValue("solr-include-file");
         File includeFile = new File(solrIncludeFilename);
         if (!includeFile.exists() || !includeFile.canWrite()) {
           CLIO.out(
@@ -237,7 +238,7 @@ private int handleKerberos(CommandLine cli) throws Exception {
       case "disable":
         clearSecurityJson(cli, updateIncludeFileOnly);
 
-        solrIncludeFilename = cli.getOptionValue("solrIncludeFile");
+        solrIncludeFilename = cli.getOptionValue("solr-include-file");
         includeFile = new File(solrIncludeFilename);
         if (!includeFile.exists() || !includeFile.canWrite()) {
           CLIO.out(
@@ -266,18 +267,18 @@ private int handleBasicAuth(CommandLine cli) throws Exception {
     String cmd = cli.getArgs()[0];
     boolean prompt = Boolean.parseBoolean(cli.getOptionValue("prompt", "false"));
     boolean updateIncludeFileOnly =
-        Boolean.parseBoolean(cli.getOptionValue("updateIncludeFileOnly", "false"));
+        Boolean.parseBoolean(cli.getOptionValue("update-include-file-only", "false"));
     switch (cmd) {
       case "enable":
         if (!prompt && !cli.hasOption("credentials")) {
-          CLIO.out("Option -credentials or -prompt is required with enable.");
+          CLIO.out("Option --credentials or --prompt is required with enable.");
           new HelpFormatter()
               .printHelp("bin/solr auth <enable|disable> [OPTIONS]", SolrCLI.getToolOptions(this));
           SolrCLI.exit(1);
         } else if (!prompt
             && (cli.getOptionValue(SolrCLI.OPTION_CREDENTIALS.getLongOpt()) == null
                 || !cli.getOptionValue(SolrCLI.OPTION_CREDENTIALS.getLongOpt()).contains(":"))) {
-          CLIO.out("Option -credentials is not in correct format.");
+          CLIO.out("Option --credentials is not in correct format.");
           new HelpFormatter()
               .printHelp("bin/solr auth <enable|disable> [OPTIONS]", SolrCLI.getToolOptions(this));
           SolrCLI.exit(1);
@@ -289,22 +290,22 @@ private int handleBasicAuth(CommandLine cli) throws Exception {
           try {
             zkHost = SolrCLI.getZkHost(cli);
           } catch (Exception ex) {
-            if (cli.hasOption("zkHost")) {
+            if (cli.hasOption("zk-host")) {
               CLIO.out(
-                  "Couldn't get ZooKeeper host. Please make sure that ZooKeeper is running and the correct zkHost has been passed in.");
+                  "Couldn't get ZooKeeper host. Please make sure that ZooKeeper is running and the correct zk-host has been passed in.");
             } else {
               CLIO.out(
-                  "Couldn't get ZooKeeper host. Please make sure Solr is running in cloud mode, or a zkHost has been passed in.");
+                  "Couldn't get ZooKeeper host. Please make sure Solr is running in cloud mode, or a zk-host has been passed in.");
             }
             SolrCLI.exit(1);
           }
           if (zkHost == null) {
-            if (cli.hasOption("zkHost")) {
+            if (cli.hasOption("zk-host")) {
               CLIO.out(
-                  "Couldn't get ZooKeeper host. Please make sure that ZooKeeper is running and the correct zkHost has been passed in.");
+                  "Couldn't get ZooKeeper host. Please make sure that ZooKeeper is running and the correct zk-host has been passed in.");
             } else {
               CLIO.out(
-                  "Couldn't get ZooKeeper host. Please make sure Solr is running in cloud mode, or a zkHost has been passed in.");
+                  "Couldn't get ZooKeeper host. Please make sure Solr is running in cloud mode, or a zk-host has been passed in.");
             }
             SolrCLI.exit(1);
           }
@@ -333,7 +334,7 @@ private int handleBasicAuth(CommandLine cli) throws Exception {
           } while (password.length() == 0);
         }
 
-        boolean blockUnknown = Boolean.parseBoolean(cli.getOptionValue("blockUnknown", "true"));
+        boolean blockUnknown = Boolean.parseBoolean(cli.getOptionValue("block-unknown", "true"));
 
         String resourceName = "security.json";
         final URL resource = SolrCore.class.getClassLoader().getResource(resourceName);
@@ -363,15 +364,15 @@ private int handleBasicAuth(CommandLine cli) throws Exception {
           }
         }
 
-        String solrIncludeFilename = cli.getOptionValue("solrIncludeFile");
+        String solrIncludeFilename = cli.getOptionValue("solr-include-file");
         File includeFile = new File(solrIncludeFilename);
         if (!includeFile.exists() || !includeFile.canWrite()) {
           CLIO.out(
               "Solr include file " + solrIncludeFilename + " doesn't exist or is not writeable.");
           printAuthEnablingInstructions(username, password);
           System.exit(0);
         }
-        String authConfDir = cli.getOptionValue("authConfDir");
+        String authConfDir = cli.getOptionValue("auth-conf-dir");
         File basicAuthConfFile = new File(authConfDir + File.separator + "basicAuth.conf");
 
         if (!basicAuthConfFile.getParentFile().canWrite()) {
@@ -400,7 +401,7 @@ private int handleBasicAuth(CommandLine cli) throws Exception {
       case "disable":
         clearSecurityJson(cli, updateIncludeFileOnly);
 
-        solrIncludeFilename = cli.getOptionValue("solrIncludeFile");
+        solrIncludeFilename = cli.getOptionValue("solr-include-file");
         includeFile = new File(solrIncludeFilename);
         if (!includeFile.exists() || !includeFile.canWrite()) {
           CLIO.out(

solr/core/src/java/org/apache/solr/cli/ClusterTool.java

@@ -54,19 +54,20 @@ public List<Option> getOptions() {
     return List.of(
         Option.builder()
             .longOpt("property")
-            .argName("PROP")
             .hasArg()
+            .argName("PROPERTY")
             .required(true)
             .desc("Name of the Cluster property to apply the action to, such as: 'urlScheme'.")
             .build(),
         Option.builder()
             .longOpt("value")
-            .argName("VALUE")
             .hasArg()
+            .argName("VALUE")
             .required(false)
             .desc("Set the property to this value.")
             .build(),
-        SolrCLI.OPTION_ZKHOST);
+        SolrCLI.OPTION_ZKHOST,
+        SolrCLI.OPTION_ZKHOST_DEPRECATED);
   }
 
   @Override

solr/core/src/java/org/apache/solr/cli/ConfigSetDownloadTool.java

@@ -43,23 +43,25 @@ public ConfigSetDownloadTool(PrintStream stdout) {
   @Override
   public List<Option> getOptions() {
     return List.of(
-        Option.builder("n")
-            .longOpt("confname")
-            .argName("NAME")
+        Option.builder()
+            .longOpt("conf-name")
             .hasArg()
+            .argName("NAME")
             .required(true)
             .desc("Configset name in ZooKeeper.")
             .build(),
-        Option.builder("d")
-            .longOpt("confdir")
-            .argName("DIR")
+        Option.builder()
+            .longOpt("conf-dir")
             .hasArg()
+            .argName("DIR")
             .required(true)
             .desc("Local directory with configs.")
             .build(),
-        SolrCLI.OPTION_ZKHOST,
         SolrCLI.OPTION_SOLRURL,
-        SolrCLI.OPTION_VERBOSE);
+        SolrCLI.OPTION_SOLRURL_DEPRECATED,
+        SolrCLI.OPTION_ZKHOST,
+        SolrCLI.OPTION_ZKHOST_DEPRECATED,
+        SolrCLI.OPTION_CREDENTIALS);
   }
 
   @Override
@@ -74,8 +76,8 @@ public void runImpl(CommandLine cli) throws Exception {
 
     try (SolrZkClient zkClient = SolrCLI.getSolrZkClient(cli, zkHost)) {
       echoIfVerbose("\nConnecting to ZooKeeper at " + zkHost + " ...", cli);
-      String confName = cli.getOptionValue("confname");
-      String confDir = cli.getOptionValue("confdir");
+      String confName = cli.getOptionValue("conf-name");
+      String confDir = cli.getOptionValue("conf-dir");
       Path configSetPath = Paths.get(confDir);
       // we try to be nice about having the "conf" in the directory, and we create it if it's not
       // there.