lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Jakob Furrer (JIRA)" <j...@apache.org>
Subject [jira] [Created] (SOLR-11840) Inconsistencies in the Usage Messages of bin/solr.cmd
Date Wed, 10 Jan 2018 13:27:00 GMT
Jakob Furrer created SOLR-11840:
-----------------------------------

             Summary: 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
             Fix For: 7.2
         Attachments: solr.cmd.txt, solr.txt, solr_start_help_Syntaxfehler.png

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-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org


Mime
View raw message