Uploaded image for project: 'Solr'
  1. Solr
  2. SOLR-11840

Inconsistencies in the Usage Messages of bin/solr.cmd

    XMLWordPrintableJSON

    Details

    • Type: Improvement
    • Status: Closed
    • Priority: Major
    • Resolution: Fixed
    • Affects Version/s: 7.2
    • Fix Version/s: 7.4, 8.0
    • Component/s: None

      Description

      I noticed a number of errors/problems/peculiarities in the Usage Messages that are displayed when using bin/solr.cmd with the parameter -help.

      The items are listed in no particular order and may be addressed independantly.

      To spot the differences between the Usage Messages of bin/solr and bin/solr.cmd I compiled an extract of the Usage Messages of the two files so that they can be compared using WinMerge or a similar diff tool.
      See the attached files solr.cmd.txt and solr.txt.

      Note that I work on a German Windows 10, therefore some error messages I quote here are in German.

      1. solr start -help results in a syntax error
        The special characters '<' and '>' are not escaped.
        The line 314 must be changed as follows:
        CURRENT : ... the default server/<dir>
        SHALL_BE: ... the default server/^<dir^>
        


      2. solr auth -help ends is empty
        A goto label ':auth_usage' with the appropriate Usage Messages already exists.
        At line 266 an additional if-statement is required.
        Also, a respective if-statement will be required on line 1858.
        NEW_CODE: IF "%SCRIPT_CMD%"=="auth" goto auth_usage
        

        Some additional bugs in the section ':auth_usage' must then also be addressed.
        The special character '|' is not escaped at a number of locations.
        The lines 568, 569, 570, 577, 580 and 585 must be changed, e.g.

        CURRENT : echo Usage: solr auth enable [-type basicAuth] -credentials user:pass [-blockUnknown ^<true|false^>] [-updateIncludeFileOnly ^<true|false^>] [-V]
        SHALL_BE: echo Usage: solr auth enable [-type basicAuth] -credentials user:pass [-blockUnknown ^<true^|false^>] [-updateIncludeFileOnly ^<true^|false^>] [-V]
        

        The empty 'echo' statement (i.e. 'newline') needs the be written with a dot ('echo.') to avoid "ECHO ist ausgeschaltet (OFF)." statements.
        The lines 571, 573, 576, 577, 579, 584, 587, 589, 591, 594 and 596 must be changed:

        CURRENT : echo
        SHALL_BE: echo.
        


      3. solr -help does not mention the command status
        The line 271 must be changed as follows:
        CURRENT : @echo        where COMMAND is one of: start, stop, restart, healthcheck, create, create_core, create_collection, delete, version, zk, auth, assert
        SHALL_BE: @echo        where COMMAND is one of: start, stop, restart, status, healthcheck, create, create_core, create_collection, delete, version, zk, auth, assert
        


      4. In bin/solr.cmd the description of solr start -p port does not mention the STOP_PORT and the RMI_PORT, see line 324 to 326 of bin/solr.
        echo "  -p <port>     Specify the port to start the Solr HTTP listener on; default is 8983"
        echo "                  The specified port (SOLR_PORT) will also be used to determine the stop port"
        echo "                  STOP_PORT=(\$SOLR_PORT-1000) and JMX RMI listen port RMI_PORT=(\$SOLR_PORT+10000). "
        echo "                  For instance, if you set -p 8985, then the STOP_PORT=7985 and RMI_PORT=18985"
        


      5. The description of solr start -s dir seems to have been revised in bin/solr.cmd but not in bin/solr.
                          on which example is run. The default value is server/solr. If passed a relative dir
                          validation with the current dir will be done before trying the default server/<dir>
        

        vs.

        		  
                          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>
        


      6. The description of solr start -t dir is different
          -t dir        Sets the solr.data.home system property, used as root for ^<instance_dir^>/data directories.
                          If not set, Solr uses solr.solr.home for both config and data.
        

        vs.

          -t <dir>      Sets the solr.data.home system property, where Solr will store data (index).
                          If not set, Solr uses solr.solr.home for config and data.
        


      7. The description of solr start -V does not mention -verbose
          -V            Verbose messages from this script
        

        vs.

          -V or -verbose Verbose messages from this script
        


      8. The syntax of solr stop does not mention the parameter -V
        Usage: solr stop [-k key] [-p port]
        

        vs.

        Usage: solr stop [-k key] [-p port] [-V]
        

        Note that there is also no description of -V in bin/solr, even though the parameter is mentioned in the syntax.

      9. The description of solr stop does not mention the command status
        This additional information is present in bin/solr.
          NOTE: To see if any Solr servers are running, do: solr status
        

        This can be added in the section ':stop_usage' at line 352.

      10. The syntax of solr healthcheck does not mention the parameter -V
        Usage: solr healthcheck [-c collection] [-z zkHost]
        

        vs.

        Usage: solr healthcheck [-c collection] [-z zkHost] [-V]
        


      11. There is no Usage Message for solr status.
        The command solr status -help does not output any help message, it actually runs the solr status instead.
        Usage: solr status
        
          NOTE: This command will show the status of all running Solr servers
        

        A new goto label ':status_usage' is required, probably right after the label ':start_usage'.
        At line 266 an additional if-statement is required.
        Also, a respective if-statement will be required on line 1858.

      12. The syntax of solr stop -deleteConfig mentions boolean, while everywhere else this is indicated as true|false
        Usage: solr delete [-c name] [-deleteConfig boolean] [-p port] [-V]
        

        vs.

        Usage: solr delete [-c name] [-deleteConfig true|false] [-p port] [-V]
        


      13. The description of solr delete -c name is different
        Note: The documentation should say delete, not create a core.
          -c name     Name of core to create
        

        vs.

          -c <name>               Name of the core / collection to delete
        


      14. The description of solr delete -p port is different
        Note: The documentation should say delete, not create a core.
          -p port     Port of a local Solr instance where you want to create the new core
        

        vs.

          -p <port>               Port of a local Solr instance where you want to delete the core/collection
        


      15. The description of solr delete -V is spelt differently
          -V            Enable more verbose output.
        

        vs.

          -V                      Enables more verbose output.
        


      16. The description of solr create_core -c uses a different parameter name
        Usage: solr create_core [-c name] [-d confdir] [-p port] [-V]
          -c name     Name of core to create
        

        vs.

        Usage: solr create_core [-c core] [-d confdir] [-p port] [-V]
          -c <core>     Name of core to create
        


      17. The description of solr create_collection -c and -n uses a different parameter name
        Usage: solr create_collection [-c name] [-d confdir] [-n confname] [-shards #] [-replicationFactor #] [-p port] [-V]
          -c name               Name of collection to create
          -d confdir            Configuration directory to copy when creating the new collection, built-in options are:
        

        vs.

        Usage: solr create_collection [-c collection] [-d confdir] [-n configName] [-shards #] [-replicationFactor #] [-p port] [-V]
          -c <collection>         Name of collection to create
          -d <confdir>            Configuration directory to copy when creating the new collection, built-in options are:
        


      18. The description of solr create_collection -shards does not mention the default value
          -shards #             Number of shards to split the collection into
        

        vs.

          -shards <#>             Number of shards to split the collection into; default is 1
        


      19. The description of solr create_collection -replicationFactor does not mention the default value
          -replicationFactor #  Number of copies of each document in the collection
        

        vs.

          -replicationFactor <#>  Number of copies of each document in the collection, default is 1 (no replication)
        


      20. The description of solr zk cp <src>, <dest> is missing a sentence
                     ^<src^>, ^<dest^> : [file:][/]path/to/local/file or zk:/path/to/zk/node
                                     NOTE: ^<src^> and ^<dest^> may both be Zookeeper resources prefixed by 'zk:'
                    When ^<src^> is a zk resource, ^<dest^> may be '.'
                    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 
        

        vs.

                     <src>, <dest> : [file:][/]path/to/local/file or zk:/path/to/zk/node
                                     NOTE: <src> and <dest> may both be Zookeeper resources prefixed by 'zk:'
                     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 
        

        Also, the fullstop here should be at the end of the sentence, not on the next line.

                     but 'bin/solr zk cp -r /some/dir/* zk:/ -z localhost:2181' will throw an error
        .
        

        The sentence "here's an example of backup/restore ..." should start with a captial letter.
        The paragraph from "... the entire zk state." to "... /some/dir/ zk:/ -z localhost:2181'" has one space too much indentation.

      21. The description of solr zk mkroot is different
                mkroot makes a znode in Zookeeper with no data. Can be used to make a path of arbitrary
        

        vs.

                 mkroot makes a znode on Zookeeper with no data. Can be used to make a path of arbitrary
        


      22. The description of solr auth is different
        Basic usage does not mention -type kerberos:
        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 disable [-updateIncludeFileOnly ^<true|false^>] [-V]
        

        vs.

        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 description of the paramter -type is different

          -type ^<type^>                 The authentication mechanism to enable. Defaults to 'basicAuth'.
        

        vs.

          -type <type>                           The authentication mechanism (basicAuth or kerberos) to enable. Defaults to 'basicAuth'.
        


        The description of the paramter -credentials is different

          -credentials ^<user:pass^>     The username and password of the initial user
        

        vs.

          -credentials <user:pass>               The username and password of the initial user. Applicable for basicAuth only.
        


        The description of the paramter -config is missing

          -config \"<configs>\"                    Configuration parameters (Solr startup parameters). Required and applicable only for Kerberos
        


        The description of the paramter -blockUnknown is different

                                       guide for Basic Authentication for more details.
        

        vs.

                                                 guide for Basic Authentication for more details. Applicable for basicAuth only.
        


        The descriptions of the paramters -updateIncludeFileOnly, -d and -s contain an annoying double quote at the end of the line
        The descriptions of the paramters -d and -s do not escape '<' and '>', resulting in error messages in the command line (note that before fixing the call to ':auth_usage' there is no output at all, see point 2 above).


        C:\solr-7.2.0_test\bin>solr.cmd auth -help

        Usage: ... <blablabla> ...

        -updateIncludeFileOnly <true|false> Only update the solr.in.sh or solr.in.cmd file, and skip actual enabling/disabling"
        authentication (i.e. don't update security.json)"

        -z zkHost Zookeeper connection string

        Das System kann die angegebene Datei nicht finden.

        Das System kann die angegebene Datei nicht finden.
        configuration files (e.g. basicAuth.conf) would be placed."

        -V Enable more verbose output

        Attachments

        1. SOLR-11840.patch
          16 kB
          Jason Gerlowski
        2. SOLR-11840.patch
          16 kB
          Jason Gerlowski
        3. SOLR-11840.patch
          16 kB
          Jason Gerlowski
        4. solr.txt
          16 kB
          Jakob Furrer
        5. solr.cmd.txt
          15 kB
          Jakob Furrer
        6. solr_start_help_Syntaxfehler.png
          34 kB
          Jakob Furrer

          Issue Links

            Activity

              People

              • Assignee:
                gerlowskija Jason Gerlowski
                Reporter:
                jafurrer Jakob Furrer
              • Votes:
                1 Vote for this issue
                Watchers:
                3 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved:

                  Time Tracking

                  Estimated:
                  Original Estimate - 2h
                  2h
                  Remaining:
                  Remaining Estimate - 2h
                  2h
                  Logged:
                  Time Spent - Not Specified
                  Not Specified