From 2d7f0567a045370d3a20001202b752afbcc66f76 Mon Sep 17 00:00:00 2001 From: maulin-vasavada Date: Mon, 4 Aug 2025 22:15:51 -0700 Subject: [PATCH] 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> --- .../managing/operating/bulk_loading.adoc | 78 +------------------ .../managing/tools/sstable/sstableloader.adoc | 39 ++++++---- 2 files changed, 27 insertions(+), 90 deletions(-) diff --git a/doc/modules/cassandra/pages/managing/operating/bulk_loading.adoc b/doc/modules/cassandra/pages/managing/operating/bulk_loading.adoc index 2630fbf76c..939d0fc58c 100644 --- a/doc/modules/cassandra/pages/managing/operating/bulk_loading.adoc +++ b/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 ` required: - -[source,none] ----- --alg,--ssl-alg Client SSL: algorithm - --ap,--auth-provider Custom - AuthProvider class name for - cassandra authentication --ciphers,--ssl-ciphers Client SSL: - comma-separated list of - encryption suites to use --cph,--connections-per-host Number of - concurrent connections-per-host. --d,--nodes Required. - Try to connect to these hosts (comma separated) initially for ring information - ---entire-sstable-throttle-mib Entire SSTable throttle - speed in MiB/s (default 0 for unlimited). - ---entire-sstable-inter-dc-throttle-mib - Entire SSTable inter-datacenter throttle - speed in MiB/s (default 0 for unlimited). - --f,--conf-path cassandra.yaml file path for streaming throughput and client/server SSL. - --h,--help Display this help message - --i,--ignore Don't stream to this (comma separated) list of nodes - --idct,--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-datacenter throttle speed in MiB/s (default 0 for unlimited) - --k,--target-keyspace Target - keyspace name --ks,--keystore Client SSL: - full path to keystore --kspw,--keystore-password Client SSL: - password of the keystore ---no-progress Don't - display progress --p,--port Port used - for native connection (default 9042) --prtcl,--ssl-protocol Client SSL: - connections protocol to use (default: TLS) --pw,--password Password for - cassandra authentication --sp,--storage-port Port used - for internode communication (default 7000) --spd,--server-port-discovery Use ports - published by server to decide how to connect. With SSL requires StartTLS - to be used. --ssp,--ssl-storage-port Port used - for TLS internode communication (default 7001) --st,--store-type Client SSL: - type of store --t,--throttle (deprecated) Throttle speed in Mbits (default 0 for unlimited). - Use --throttle-mib instead. ---throttle-mib Throttle - speed in MiB/s (default 0 for unlimited) --ts,--truststore Client SSL: - full path to truststore --tspw,--truststore-password Client SSL: - Password of the truststore --u,--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. +Refer to the sstableloader configuration options at xref:cassandra:/managing/tools/sstable/sstableloader.adoc[sstableloader documentation] === A sstableloader Demo diff --git a/doc/modules/cassandra/pages/managing/tools/sstable/sstableloader.adoc b/doc/modules/cassandra/pages/managing/tools/sstable/sstableloader.adoc index e980dc2e00..a4140eaac9 100644 --- a/doc/modules/cassandra/pages/managing/tools/sstable/sstableloader.adoc +++ b/doc/modules/cassandra/pages/managing/tools/sstable/sstableloader.adoc @@ -69,24 +69,24 @@ connections-per-host |-i, --ignore |don't stream to this (comma separated) list of nodes -|-alg, --ssl-alg |Client SSL: algorithm (default: SunX509) +|-alg, --ssl-alg |Client SSL (for native connection): algorithm (default: SunX509) -|-ciphers, --ssl-ciphers |Client SSL: comma-separated +|-ciphers, --ssl-ciphers |Client SSL (for native connection): comma-separated list of encryption suites to use -|-ks, --keystore |Client SSL: full path to keystore +|-ks, --keystore |Client SSL (for native connection): full path to keystore -|-kspw, --keystore-password |Client SSL: password of +|-kspw, --keystore-password |Client SSL (for native connection): password of the keystore -|-st, --store-type |Client SSL: type of store +|-st, --store-type |Client SSL (for native connection): type of store -|-ts, --truststore |Client SSL: full path to truststore +|-ts, --truststore |Client SSL (for native connection): full path to truststore -|-tspw, --truststore-password |Client SSL: +|-tspw, --truststore-password |Client SSL (for native connection): password of the truststore -|-prtcl, --ssl-protocol |Client SSL: connections protocol to +|-prtcl, --ssl-protocol |Client SSL (for native connection): connections protocol to use (default: TLS) |-ap, --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 -with sstableloader to point the tool to the cassandra.yaml with the -relevant server_encryption_options (e.g., truststore location, -algorithm). This will work better than passing individual ssl options -shown above to sstableloader on the command line. +The sstableloader tool connects to the Cassandra server's native port to fetch cluster metadata and to the storage +(internode) port to stream SSTables. If SSL encryption is required only for the native port, you can provide the +necessary SSL options directly via the command line. However, if SSL encryption is required for both native and +internode (storage) ports, it is recommended to use the `--conf-path` option with sstableloader to specify a +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: