natas_hw
/
cassandra
mirror of https://github.com/apache/cassandra
0
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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>
This commit is contained in:
maulin-vasavada 2025-08-04 22:15:51 -07:00 committed by Stefan Miklosovic
parent 223f6d47ff
commit 2d7f0567a0
No known key found for this signature in database
GPG Key ID: 32F35CB2F546D93E
2 changed files with 27 additions and 90 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

78
doc/modules/cassandra/pages/managing/operating/bulk_loading.adoc
View File

@ -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:
[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.
Refer to the sstableloader configuration options at xref:cassandra:/managing/tools/sstable/sstableloader.adoc[sstableloader documentation]
=== A sstableloader Demo

39
doc/modules/cassandra/pages/managing/tools/sstable/sstableloader.adoc
View File

@ -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
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: