Erick Ramirez created CASSANDRA-21782:
-----------------------------------------
Summary: DOC - Document nodetool --ssl and nodetool-ssl.properties
for JMX SSL
Key: CASSANDRA-21782
URL: https://issues.apache.org/jira/browse/CASSANDRA-21782
Project: Apache Cassandra
Issue Type: Improvement
Components: Documentation/Website, Tool/nodetool
Reporter: Erick Ramirez
Assignee: Erick Ramirez
The docs explain how to turn on SSL for the JMX server, but never say how to
make {{nodetool}} connect to it. Nothing under {{doc/}} in 4.0, 4.1, 5.0, 6.0
or trunk mentions {{nodetool --ssl}} or
{{{}$HOME/.cassandra/nodetool-ssl.properties{}}}.
The "JMX access" section of the Security page ends by telling the reader to
"ensure that tools which use JMX, such as nodetool are correctly configured and
working as expected". It does not say how to configure nodetool.
h3. Current behaviour
Read from the 5.0 source ({{{}bin/nodetool{}}}, {{{}NodeProbe.java{}}}). The
script logic is identical on the other branches listed above.
* {{--ssl}} is handled by the {{bin/nodetool}} shell script, not by
{{{}NodeTool.java{}}}. The script adds {{-Dssl.enable=true}} to the nodetool
JVM options.
* {{NodeProbe}} checks {{ssl.enable}} and, if true, connects through
{{{}SslRMIClientSocketFactory{}}}. Otherwise it uses the default socket factory.
* When {{--ssl}} is passed, the script also reads
{{$HOME/.cassandra/nodetool-ssl.properties}} if the file exists, and appends
its contents to the JVM options. The path is hardcoded and a missing file is
skipped silently.
* The script flattens the file with {{{}cat | tr '\n' ' '{}}}. It is not a
Java properties file: each line must be a complete JVM flag, such as
{{{}-Djavax.net.ssl.trustStore=/path/to/truststore.jks{}}}, one per line.
* The same flags can be passed on the command line as {{-D}} options instead
of using the file.
* Because {{--ssl}} lives in the script, it does not appear in {{{}nodetool
help{}}}. The nodetool reference pages are generated from that output, so they
cannot show it either (see CASSANDRA-12742).
h3. Proposed change
Add a client-side subsection to the existing "JMX With SSL" section, for
example "Configuring nodetool for JMX SSL". It should cover:
* Pass {{--ssl}} to enable SSL for the connection.
* Which {{javax.net.ssl.*}} properties nodetool needs: a truststore to trust
the server certificate, and a keystore if the server sets
{{{}com.sun.management.jmxremote.ssl.need.client.auth=true{}}}.
* The {{nodetool-ssl.properties}} location, its one-flag-per-line format, and
that it is read only when {{--ssl}} is given.
* A short example of the file and of the command.
* A warning that passwords in the file are stored in plain text, so the file
should be readable by its owner only.
* A line making clear this is JMX SSL, separate from
{{client_encryption_options}} for the native protocol.
Example for the file:
{noformat}
-Djavax.net.ssl.trustStore=/path/to/truststore.jks
-Djavax.net.ssl.trustStorePassword=<truststore-password>
-Djavax.net.ssl.keyStore=/path/to/keystore.jks
-Djavax.net.ssl.keyStorePassword=<keystore-password>{noformat}
Example for the command:
{noformat}
nodetool --ssl status{noformat}
On 6.0 and trunk the server-side part of this section now uses
{{jmx_encryption_options}} in {{cassandra.yaml}} (CASSANDRA-18508,
CASSANDRA-11695), with the system properties described as legacy. The nodetool
text must be checked against that wording on those branches before it is merged
forward.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
