[ https://issues.apache.org/jira/browse/SOLR-11840?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16321330#comment-16321330 ]
Jakob Furrer commented on SOLR-11840: ------------------------------------- * The description of _solr_ _assert_ has an incorrect usage message The usage message should describe the syntax for the command, instead it says *usage:* *org.apache.solr.util.SolrCLI*. {code:bgColor=#D3D3D3} C:\solr-7.2.0_test\bin>solr.cmd assert -help usage: org.apache.solr.util.SolrCLI -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 Generate verbose log messages -x,--exists <directory> Asserts that directory <directory> exists -X,--not-exists <directory> Asserts that directory <directory> does NOT exist C:\solr-7.2.0_test\bin> {code} There is no label ':assert_usage' in _bin/solr.cmd_. Apparently the help text for _>solr.cmd_ _assert_ _-help_ instead comes from the Java implementation (see _SolrCLI.java_ line 3398). > Inconsistencies in the Usage Messages of bin/solr.cmd > ----------------------------------------------------- > > Key: SOLR-11840 > URL: https://issues.apache.org/jira/browse/SOLR-11840 > Project: Solr > Issue Type: Improvement > Security Level: Public(Default Security Level. Issues are Public) > Affects Versions: 7.2 > Reporter: Jakob Furrer > Labels: documentation, easyfix > Fix For: 7.2 > > Attachments: solr.cmd.txt, solr.txt, solr_start_help_Syntaxfehler.png > > Original Estimate: 2h > Remaining Estimate: 2h > > 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. > # _solr_ _start_ _-help_ results in a syntax error > The special characters '<' and '>' are not escaped. > The line 314 must be changed as follows: > {noformat} > CURRENT : ... the default server/<dir> > SHALL_BE: ... the default server/^<dir^> > {noformat} > \\ > # _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. > {noformat} > NEW_CODE: IF "%SCRIPT_CMD%"=="auth" goto auth_usage > {noformat} > 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. > {noformat} > 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] > {noformat} > 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: > {noformat} > CURRENT : echo > SHALL_BE: echo. > {noformat} > \\ > # _solr_ _-help_ does not mention the command _status_ > The line 271 must be changed as follows: > {noformat} > 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 > {noformat} > \\ > # 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_. > {noformat} > 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" > {noformat} > \\ > # The description of _solr_ _start_ _-s_ _dir_ seems to have been revised in > _bin/solr.cmd_ but not in _bin/solr_. > {noformat} > 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> > {noformat} > vs. > {noformat} > 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> > {noformat} > \\ > # The description of _solr_ _start_ _-t_ _dir_ is different > {noformat} > -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. > {noformat} > vs. > {noformat} > -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. > {noformat} > \\ > # The description of _solr_ _start_ _-V_ does not mention _-verbose_ > {noformat} > -V Verbose messages from this script > {noformat} > vs. > {noformat} > -V or -verbose Verbose messages from this script > {noformat} > \\ > # The syntax of _solr_ _stop_ does not mention the parameter _-V_ > {noformat} > Usage: solr stop [-k key] [-p port] > {noformat} > vs. > {noformat} > Usage: solr stop [-k key] [-p port] [-V] > {noformat} > Note that there is also no description of _-V_ in _bin/solr_, even though the > parameter is mentioned in the syntax. > \\ > \\ > # The description of _solr_ _stop_ does not mention the command _status_ > This additional information is present in _bin/solr_. > {noformat} > NOTE: To see if any Solr servers are running, do: solr status > {noformat} > This can be added in the section ':stop_usage' at line 352. > \\ > \\ > # The syntax of _solr_ _healthcheck_ does not mention the parameter _-V_ > {noformat} > Usage: solr healthcheck [-c collection] [-z zkHost] > {noformat} > vs. > {noformat} > Usage: solr healthcheck [-c collection] [-z zkHost] [-V] > {noformat} > \\ > # 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. > {noformat} > Usage: solr status > NOTE: This command will show the status of all running Solr servers > {noformat} > 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. > \\ > \\ > # The syntax of _solr_ _stop_ _-deleteConfig_ mentions _boolean_, while > everywhere else this is indicated as _true|false_ > {noformat} > Usage: solr delete [-c name] [-deleteConfig boolean] [-p port] [-V] > {noformat} > vs. > {noformat} > Usage: solr delete [-c name] [-deleteConfig true|false] [-p port] [-V] > {noformat} > \\ > # The description of _solr_ _delete_ _-c_ _name_ is different > Note: The documentation should say *delete*, not *create* a core. > {noformat} > -c name Name of core to create > {noformat} > vs. > {noformat} > -c <name> Name of the core / collection to delete > {noformat} > \\ > # The description of _solr_ _delete_ _-p_ _port_ is different > Note: The documentation should say *delete*, not *create* a core. > {noformat} > -p port Port of a local Solr instance where you want to create the new > core > {noformat} > vs. > {noformat} > -p <port> Port of a local Solr instance where you want to > delete the core/collection > {noformat} > \\ > # The description of _solr_ _delete_ _-V_ is spelt differently > {noformat} > -V Enable more verbose output. > {noformat} > vs. > {noformat} > -V Enables more verbose output. > {noformat} > \\ > # The description of _solr_ _create_core_ _-c_ uses a different parameter name > {noformat} > Usage: solr create_core [-c name] [-d confdir] [-p port] [-V] > -c name Name of core to create > {noformat} > vs. > {noformat} > Usage: solr create_core [-c core] [-d confdir] [-p port] [-V] > -c <core> Name of core to create > {noformat} > \\ > # The description of _solr_ _create_collection_ _-c_ and _-n_ uses a > different parameter name > {noformat} > 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: > {noformat} > vs. > {noformat} > 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: > {noformat} > \\ > # The description of _solr_ _create_collection_ _-shards_ does not mention > the default value > {noformat} > -shards # Number of shards to split the collection into > {noformat} > vs. > {noformat} > -shards <#> Number of shards to split the collection into; > default is 1 > {noformat} > \\ > # The description of _solr_ _create_collection_ _-replicationFactor_ does not > mention the default value > {noformat} > -replicationFactor # Number of copies of each document in the collection > {noformat} > vs. > {noformat} > -replicationFactor <#> Number of copies of each document in the > collection, default is 1 (no replication) > {noformat} > \\ > # The description of _solr_ _zk_ _cp_ <src>, <dest> is missing a sentence > {noformat} > ^<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 > {noformat} > vs. > {noformat} > <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 > {noformat} > Also, the fullstop here should be at the end of the sentence, not on the next > line. > {noformat} > but 'bin/solr zk cp -r /some/dir/* zk:/ -z localhost:2181' will > throw an error > . > {noformat} > 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. > \\ > \\ > # The description of _solr_ _zk_ _mkroot_ is different > {noformat} > mkroot makes a znode in Zookeeper with no data. Can be used to make a > path of arbitrary > {noformat} > vs. > {noformat} > mkroot makes a znode on Zookeeper with no data. Can be used to make > a path of arbitrary > {noformat} > \\ > # The description of _solr_ _auth_ is different > Basic usage does not mention _-type_ _kerberos_: > {noformat} > 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] > {noformat} > vs. > {noformat} > 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] > {noformat} > \\ > The description of the paramter _-type_ is different > {noformat} > -type ^<type^> The authentication mechanism to enable. > Defaults to 'basicAuth'. > {noformat} > vs. > {noformat} > -type <type> The authentication mechanism > (basicAuth or kerberos) to enable. Defaults to 'basicAuth'. > {noformat} > \\ > The description of the paramter _-credentials_ is different > {noformat} > -credentials ^<user:pass^> The username and password of the initial user > {noformat} > vs. > {noformat} > -credentials <user:pass> The username and password of the > initial user. Applicable for basicAuth only. > {noformat} > \\ > The description of the paramter _-config_ is missing > {noformat} > -config \"<configs>\" Configuration parameters (Solr > startup parameters). Required and applicable only for Kerberos > {noformat} > \\ > The description of the paramter _-blockUnknown_ is different > {noformat} > guide for Basic Authentication for more > details. > {noformat} > vs. > {noformat} > guide for Basic Authentication for > more details. Applicable for basicAuth only. > {noformat} > \\ > 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). > {panel:bgColor=#000000} > {color:white} > 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 > {color} > {panel} -- This message was sent by Atlassian JIRA (v6.4.14#64029) --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org For additional commands, e-mail: dev-h...@lucene.apache.org