Improve sstableloader documentation for SSL configuration

patch by Maulin Vasavada; reviewed by Andrew Tolbert, Stefan Miklosovic for CASSANDRA-20779

Co-authored-by: Andrew Tolbert <6889771+tolbertam@users.noreply.github.com>

doc/modules/cassandra/pages/managing/operating/bulk_loading.adoc

@@ -63,83 +63,7 @@ As an option, to specify target keyspace name as part of `sstableloader`,
 version 4.0 adds support for the `--target-keyspace` option
 (https://issues.apache.org/jira/browse/CASSANDRA-13884[CASSANDRA-13884]).
 
-The following options are supported, with `-d,--nodes <initial hosts>` required:
+Refer to the sstableloader configuration options at xref:cassandra:/managing/tools/sstable/sstableloader.adoc[sstableloader documentation]
-
-[source,none]
-----
--alg,--ssl-alg <ALGORITHM>                                   Client SSL: algorithm
-
--ap,--auth-provider <auth provider>                          Custom
-                                                             AuthProvider class name for
-                                                             cassandra authentication
--ciphers,--ssl-ciphers <CIPHER-SUITES>                       Client SSL:
-                                                             comma-separated list of
-                                                             encryption suites to use
--cph,--connections-per-host <connectionsPerHost>             Number of
-                                                             concurrent connections-per-host.
--d,--nodes <initial hosts>                                   Required.
-                                                             Try to connect to these hosts (comma separated) initially for ring information
-
---entire-sstable-throttle-mib <throttle-mib>                 Entire SSTable throttle
-                                                             speed in MiB/s (default 0 for unlimited).
-
---entire-sstable-inter-dc-throttle-mib                       <inter-dc-throttle-mib>
-                                                             Entire SSTable inter-datacenter throttle
-                                                             speed in MiB/s (default 0 for unlimited).
-
--f,--conf-path <path to config file>                         cassandra.yaml file path for streaming throughput and client/server SSL.
-
--h,--help                                                    Display this help message
-
--i,--ignore <NODES>                                          Don't stream to this (comma separated) list of nodes
-
--idct,--inter-dc-throttle <inter-dc-throttle>                (deprecated) Inter-datacenter throttle speed in Mbits (default 0 for unlimited).
-                                                             Use --inter-dc-throttle-mib instead.
-
---inter-dc-throttle-mib <inter-dc-throttle-mib>              Inter-datacenter throttle speed in MiB/s (default 0 for unlimited)
-
--k,--target-keyspace <target keyspace name>                  Target
-                                                             keyspace name
--ks,--keystore <KEYSTORE>                                    Client SSL:
-                                                             full path to keystore
--kspw,--keystore-password <KEYSTORE-PASSWORD>                Client SSL:
-                                                             password of the keystore
---no-progress                                                Don't
-                                                             display progress
--p,--port <native transport port>                            Port used
-                                                             for native connection (default 9042)
--prtcl,--ssl-protocol <PROTOCOL>                             Client SSL:
-                                                             connections protocol to use (default: TLS)
--pw,--password <password>                                    Password for
-                                                             cassandra authentication
--sp,--storage-port <storage port>                            Port used
-                                                             for internode communication (default 7000)
--spd,--server-port-discovery <allow server port discovery>   Use ports
-                                                             published by server to decide how to connect. With SSL requires StartTLS
-                                                             to be used.
--ssp,--ssl-storage-port <ssl storage port>                   Port used
-                                                             for TLS internode communication (default 7001)
--st,--store-type <STORE-TYPE>                                Client SSL:
-                                                             type of store
--t,--throttle <throttle>                                     (deprecated) Throttle speed in Mbits (default 0 for unlimited).
-                                                             Use --throttle-mib instead.
---throttle-mib <throttle-mib>                                Throttle
-                                                             speed in MiB/s (default 0 for unlimited)
--ts,--truststore <TRUSTSTORE>                                Client SSL:
-                                                             full path to truststore
--tspw,--truststore-password <TRUSTSTORE-PASSWORD>            Client SSL:
-                                                             Password of the truststore
--u,--username <username>                                     Username for
-                                                             cassandra authentication
--v,--verbose                                                 verbose
-                                                             output
-----
-
-The `cassandra.yaml` file can be provided on the command-line with `-f` option to set up streaming throughput, client and server encryption
-options.
-Only `stream_throughput_outbound_megabits_per_sec`, `server_encryption_options` and `client_encryption_options` are read
-from the `cassandra.yaml` file.
-You can override options read from `cassandra.yaml` with corresponding command line options.
 
 === A sstableloader Demo
 

doc/modules/cassandra/pages/managing/tools/sstable/sstableloader.adoc

@@ -69,24 +69,24 @@ connections-per-host
 |-i, --ignore <NODES> |don't stream to this (comma separated) list of
 nodes
 
-|-alg, --ssl-alg <ALGORITHM> |Client SSL: algorithm (default: SunX509)
+|-alg, --ssl-alg <ALGORITHM> |Client SSL (for native connection): algorithm (default: SunX509)
 
-|-ciphers, --ssl-ciphers <CIPHER-SUITES> |Client SSL: comma-separated
+|-ciphers, --ssl-ciphers <CIPHER-SUITES> |Client SSL (for native connection): comma-separated
 list of encryption suites to use
 
-|-ks, --keystore <KEYSTORE> |Client SSL: full path to keystore
+|-ks, --keystore <KEYSTORE> |Client SSL (for native connection): full path to keystore
 
-|-kspw, --keystore-password <KEYSTORE-PASSWORD> |Client SSL: password of
+|-kspw, --keystore-password <KEYSTORE-PASSWORD> |Client SSL (for native connection): password of
 the keystore
 
-|-st, --store-type <STORE-TYPE> |Client SSL: type of store
+|-st, --store-type <STORE-TYPE> |Client SSL (for native connection): type of store
 
-|-ts, --truststore <TRUSTSTORE> |Client SSL: full path to truststore
+|-ts, --truststore <TRUSTSTORE> |Client SSL (for native connection): full path to truststore
 
-|-tspw, --truststore-password <TRUSTSTORE-PASSWORD> |Client SSL:
+|-tspw, --truststore-password <TRUSTSTORE-PASSWORD> |Client SSL (for native connection):
 password of the truststore
 
-|-prtcl, --ssl-protocol <PROTOCOL> |Client SSL: connections protocol to
+|-prtcl, --ssl-protocol <PROTOCOL> |Client SSL (for native connection): connections protocol to
 use (default: TLS)
 
 |-ap, --auth-provider <auth provider> |custom AuthProvider class name
@@ -142,11 +142,24 @@ Initial hosts must be specified (-d)
 
 == Use a Config File for SSL Clusters
 
-If SSL encryption is enabled in the cluster, use the --conf-path option
+The sstableloader tool connects to the Cassandra server's native port to fetch cluster metadata and to the storage
-with sstableloader to point the tool to the cassandra.yaml with the
+(internode) port to stream SSTables. If SSL encryption is required only for the native port, you can provide the
-relevant server_encryption_options (e.g., truststore location,
+necessary SSL options directly via the command line. However, if SSL encryption is required for both native and
-algorithm). This will work better than passing individual ssl options
+internode (storage) ports, it is recommended to use the `--conf-path` option with sstableloader to specify a
-shown above to sstableloader on the command line.
+cassandra.yaml file that includes the appropriate `client_encryption_options` for the native port and
+`server_encryption_options` for the storage port. This approach is necessary because there are no command-line options to
+configure internode SSL settings directly. In case command line options are provided for the native port connection,
+they will override the settings in the cassandra.yaml file for the native port, but the storage port will still use the
+`server_encryption_options` from the cassandra.yaml file.
+
+Also, as the client to the Cassandra nodes, the same key and/or trust stores must be configured for the sstableloader tool
+for connecting to the native or the storage port.
+
+It is noteworthy that while the sstableloader tool is essentially a client to the Cassandra nodes, overloaded usage of
+the server side encryption options mentioned above is a reasonable compromise to avoid the need for additional
+specific configuration options just for this tool. This also means that there is no significance of the
+`require_client_auth` configuration option used in the `client_encryption_options` section of the cassandra.yaml file
+used in this context as only the server can enforce client authentication.
 
 Example: