[jira] [Updated] (CASSANDRA-21782) DOC - Document nodetool --ssl and nodetool-ssl.properties for JMX SSL

["Erick Ramirez (Jira)" <ji...@apache.org>]

     [ https://issues.apache.org/jira/browse/CASSANDRA-21782?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Erick Ramirez updated CASSANDRA-21782:
--------------------------------------
    Change Category: Operability
         Complexity: Normal
             Status: Open  (was: Triage Needed)

> 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
>            Priority: Normal
>             Fix For: 4.0.x, 4.1.x, 5.0.x, 6.0, 7.0
>
>
> 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: commits-unsubscribe@cassandra.apache.org
For additional commands, e-mail: commits-help@cassandra.apache.org