dsetool utility

Use the dsetool utility for creating system keys, encrypting sensitive configuration information, and performing Cassandra File System (CFS) and Hadoop-related tasks, such as checking the CFS, and listing node subranges of data in a keyspace.

Use the dsetool utility for creating system keys, encrypting sensitive configuration, and performing Cassandra File System (CFS) and Hadoop-related tasks, such as checking the CFS, and listing node subranges of data in a keyspace.

JMX authentication is supported for dsetool commands. You can also authenticate with the configured Cassandra user on some commands.

Synopsis and dsetool command arguments

Synopsis

$ dsetool [-f config_file] [-l username -p password] [-a jmx_username -b jmx_password]  [-h=hostname] [-s=Solr_port] [-j=jmx_port] command args

Legend
Syntax conventions	Description
`Italics`	Variable value. Replace with a user-defined value.
`[ ]`	Optional. Square brackets ( `[ ]` ) surround optional command arguments. Do not type the square brackets.
`( )`	Group. Parentheses ( `( )` ) identify a group to choose from. Do not type the parentheses.
`\|`	Or. A vertical bar ( `\|` ) separates alternative elements. Type any one of the elements. Do not type the vertical bar.
`[ -- ]`	Separate the command line options from the command arguments with two hyphens ( `--` ). This syntax is useful when arguments might be mistaken for command line options.

You can provide user credentials in several ways, see internal authentication. When using SSL client-to-node encryption, see Client-to-node encryption using SSL.

This table describes the dsetool arguments that are supported for all dsetool commands:

Short form	Long form	Description
`-f`		Path to configuration file that stores credentials. The credentials in this configuration file override the ~/.dserc credentials.
`-l`	--username	User name for authenticating with the configured Cassandra user.
`-p`	--password	Password to authenticate with the configured Cassandra user.
`-a`	--jmxusername `arg`	User name for authenticating with secure JMX.
`-b`	--jmxpassword `arg`	Password for authenticating with secure JMX.
`-c`	--cassandra_port	Cassandra port number.
`-h`	--host `arg`	Node hostname or IP address.
`-j`	--jmxport `arg`	Remote JMX agent port number.
`-s`	--port	Solr port number.
`-u`	--use_hadoop_config	Get Cassandra host from Hadoop configuration files.

dsetool commands

autojt: Elects Job Trackers for a specified datacenter, or for all datacenters when none is specified. Automatically manage Job Tracker selection and remove manual selections. If the current manually selected tracker is up, the manually selected Job Tracker continues to be used.

checkcfs: Checks a single CFS file or the whole CFS. See checking the CFS using dsetool.

cleanup_leases: Deletes stale leaders and assigned candidates.

create_core keyspace.table [option ...]

Supports Cassandra password authentication with

[-l username -p
       password]

Creates the Solr core and optionally generates resources automatically. This command preserves the case of keyspace and table names. You must use the correct case for the keyspace and table names. The Solr core is created with the specified keyspace and table name and following options:

schema=path - Path of the UTF-8 encoded schema file (solrconfig.xml) that is used for creating the core. Cannot be specified when generateResources=true.
solrconfig=path - Path of the solrconfig.xml file that is used for creating the core. Cannot be specified when generateResources=true.
distributed=true|false - Default: true
When distributed=true, the Solr core is created on all datacenters, but only data from the local datacenter is reindexed.
deleteAll=true|false - Default: false
recovery=true|false
- true = if the Solr core is unable to load due to corrupted index, recovers it by deleting and recreating the index. The deleteAll flag is set based on the recovery flag unless deleteAll is specifically set.
- false = no recovery
reindex=true|false - Observed only on auto-core creation (generateResources=true); otherwise, always reindexes on core creation. Default: false
generateResources=true|false - Default: false. Cannot be used with schema= and solrconfig=.
coreOptions - Path to the options file when generateResources=true

To create a core when using SSL Client-to-node encryption using SSL, the common name (CN) in the certificate must be the hostname or IP address of the node that issues the dsetool create_core command.

createsystemkey algorithm[/mode/padding] secret_key_strength [file] [-k=kmip_groupname [-t kmip_template] [-n namespace]]

Creates a global encryption key, called a system key, for SSTable encryption using the following options:

algorithm[/mode/padding]
          secret_key_strength

- When Java Cryptography Extension (JCE) is installed, the cipher_algorithm options and acceptable secret_key_strength values for the algorithms are:

cipher_algorithm	secret_key_strength
AES/CBC/PKCS5Padding	128, 192, or 256
AES/ECB/PKCS5Padding	128, 192, or 256
DES/CBC/PKCS5Padding	56
DESede/CBC/PKCS5Padding	112 or 168
Blowfish/CBC/PKCS5Padding	32-448
RC2/CBC/PKCS5Padding	40-128

Key strength is not required for HMAC algorithms.

file - Specify the name of the system key file to create. If no name is specified, the default system key file name is system_key. The default system key file name is not configurable.
-k=kmip_groupname - Use the KMIP connection information to create a remote system key for the KMIP key server group that is defined in the kmip_hosts section in the dse.yaml file. The following options are available only for the specified KMIP key server group:
- -t kmip_template - Uses the specified KMIP server key template.
- -n namespace - Specifies the namespace to create the system key with.

See Encryption/compression options and algorithm sub-options and Encrypting sensitive property values.

encryptconfigvalue: Encrypts sensitive configuration information. This command takes no arguments and prompts for the value to encrypt.

get_core_config keyspace.table [current=true|false]: Outputs the latest uploaded solrconfig.xml resource file for the specified core. If current is set to true, returns the current live solrconfig.

get_core_schema keyspace.table [current=true|false]: Supports Cassandra password authentication with [-l username -p password].; Outputs the latest uploaded Solr schema. If current is set to true, returns the current live schema.

infer_solr_schema keyspace.table [coreOptions path_to_options_file]: Supports Cassandra password authentication with [-l username -p password].; Automatically infers and proposes a schema that is based on the specified keyspace and table. Solr cores are not modified. The Solr schema is inferred with the specified coreOptions YAML file.

inmemorystatus [keyspace.table]: Provides the memory size, capacity, and percentage for this node and the amount of memory each table is using. To get information about a single table, specify the keyspace and table. The unit of measurement is MB. Bytes are truncated.

jobtracker: Returns the Job Tracker hostname and port. Returns the Job Tracker that is local to the data center from which you are running the command. See managing the Job Tracker using dsetool commands.

list_subranges keyspace.table keys_per_range start_token, end_token: Divides a token range for a given keyspace/table into a number of smaller subranges of approximately keys_per_range. To be useful, the specified range should be contained by the target node's primary range. See Listing sub-ranges using dsetool.

listjt: Lists all Job Tracker nodes grouped by the datacenter that is local to them.

managekmip subcommand kmip_groupname [command_arguments]

Verifies communication with the specified KMIP key server and lists the KMIP encryption keys on that key server. The follow subcommands are supported:

list kmip_groupname [namespace=key_namespace]: Lists the encryption keys on the specified KMIP host. You can optionally specify the namespace.
expirekey kmip_groupname key_id [datetime]: Specifies an expiration date and time for the specified encryption key. After the specified datetime, no new data will be encrypted with the key. Data can be decrypted with the key after this expire date/time. If an expire date/time is not specified, the key is expired immediately.
Format of datetime is YYYY-MM-DD HH:MM:SS:T. For example, use 2016-04-13 20:05:00:0 to expire the encryption key at 8:05 p.m. on 13 April 2016.
revoke kmip_groupname key_id: Revokes the specified encryption key. After a key is revoked, the key cannot be used to decrypt data.
destroy kmip_groupname key_id: Destroys the specified encryption key. After a key is destroyed, the key cannot be used to decrypt data.

movejt: Moves the Job Tracker and notifies the Task Tracker nodes. This option has been deprecated. Use setjt and setrjt.

node_health

Retrieves a dynamic score between 0 and 1 that describes the health of the specified DataStax Enterprise node. A higher score indicates better node health. Nodes that have a large number of dropped mutations and nodes that are just started have a lower health score.

$ dsetool -h IP_address node_health

where IP_address is the IP address that is output by the

dsetool
       ring

command.

For example:

$ dsetool -h 200.192.10.11 node_health 
Node Health: 0.7

If you do not specify the IP address, the default is the local DataStax Enterprise node.

partitioner: Returns the fully qualified classname of the IPartitioner that is in use by the cluster.

perf subcommand: Modifies performance object settings as described in the subcommand section.

read_resource keyspace.table name=resfilename: Supports Cassandra password authentication with [-l username -p password].; Reads the specified DSE Search resource file.

rebuild_indexes keyspace.table [idx1,idx2,...]: Rebuilds specified secondary indexes for specified keyspace/table. To rebuild all indexes, do not specify indexes and use only rebuild_indexes keyspace.table.

reload_core keyspace.table [option ...]

Supports Cassandra password authentication with

[-l
        username -p password]

Reloads a Solr core with the specified keyspace and table name. This command preserves the case of keyspace and table names. You must use the correct case for the keyspace and table names. The core is reloaded with the following options:

Option	Settings	Default	Description
schema=	`filepath`	n/a	Path of the schema file
solrconfig=	`filepath`	n/a	Path of the solrconfig.xml file
distributed=	true or false	true	true distributes and applies the reload operation to all nodes in the local DC. false applies the reload operation only to the node it was sent to.
reindex=	true or false	false	true re-indexes the data. false does not re-index the data.
deleteAll=	true or false	false	true deletes the already existing index before re-indexing; search results will return either no or partial data while the index is rebuilding. false does not delete the existing index, causing the re-index to happen in-place; search results will return partially incorrect results while the index is updating.

repaircfs: Repairs the CFS from orphan blocks.

ring: Lists the nodes in the ring, including their node type.

setjt IP_address_of_JobTracker_node: Moves the JobTracker to the specified node and notifies the TaskTracker nodes of the change.

setrjt IP_address_of_reserve_JobTracker_node: Moves the reserve JobTracker node to the specified IP address and notifies the TaskTracker nodes of the change.

sparkmaster [subcommand]

Unless a subcommand is provided, this command returns the address of Spark Master running in a datacenter. Otherwise, this command executes a subcommand related to Spark Master.

cleanup - Drops and recreates the Spark Master recovery table.
cleanup data_center_name - Removes recovery data for the specified datacenter.

sparkworker restart: Manually restarts the Spark Worker on the selected node, without restarting the node.

status: Lists the nodes in their ring, including the node type. Same as the ring command.

token --generate|cancel: Only for Kerberos authentication: obtains or cancels a delegation token. See Using dsetool with Kerberos.

Checking the CFS using dsetool

Use the dsetool checkcfs command to scan the Cassandra File System (CFS) for corrupted files. For example:

$ dsetool checkcfs cfs:///

Use the dsetool checkcfs command to get details about a particular file that has been corrupted. For example:

$ dsetool checkcfs /tmp/myhadoop/mapred/system/jobtracker.info

Listing sub-ranges using dsetool

The dsetool command syntax for listing subranges of data in a keyspace is:

$ dsetool [-h hostname ] list_subranges keyspace table rows_per_subrange start_token end_token

rows_per_subrange - The approximate number of rows per subrange.
start_partition_range - The start range of the node.
end_partition_range - The end range of the node.

Note: Run nodetool repair on a single node using the output of list_subranges. The output must be partition ranges that are used on that node.

Example

$ dsetool list_subranges Keyspace1 Standard1 10000 113427455640312821154458202477256070485 0

Output

The output lists the subranges to use as input to the nodetool repair command. For example:

Start Token                             End Token                               Estimated Size
------------------------------------------------------------------------------------------------
113427455640312821154458202477256070485 132425442795624521227151664615147681247 11264
132425442795624521227151664615147681247 151409576048389227347257997936583470460 11136
151409576048389227347257997936583470460 0                                       11264

Nodetool repair command options

You must use the nodetool utility to work with sub-ranges. The start partition range (-st) and end partition range (-et) options specify the portion of the node that needs repair. You get values for the start and end tokens from the output of dsetool list_subranges command. The nodetool repair syntax for using these options is:

$ nodetool repair keyspace table -st start_token -et end_token

Example

$ nodetool repair Keyspace1 Standard1 -st 113427455640312821154458202477256070485 -et 132425442795624521227151664615147681247 
$ nodetool repair Keyspace1 Standard1 -st 132425442795624521227151664615147681247 -et 151409576048389227347257997936583470460
$ nodetool repair Keyspace1 Standard1 -st 151409576048389227347257997936583470460 -et 0

These commands begins an anti-entropy node repair from the start partition range to the end partition range.

Performance object subcommands

The self-explanatory dsetool perf command subcommands are:

Note: Enabling or disabling with the performance object subcommands does not persist between reboots and is useful only for short-term diagnostics. To make these settings permanent, see CQL Performance Service options.

Subcommand name	Possible values	Description
clustersummary	- enable\|disable	Toggle cluster summary statistics. See Collecting database summary diagnostics.
cqlslowlog	- `threshold` - enable\|disable	Set the CQL slow log threshold. Toggle the CQL slow log. See Collecting slow queries.
cqlsysteminfo	- enable\|disable	Toggle CQL system information statistics. See Collecting system level diagnostics.
dbsummary	- enable\|disable	Toggle database summary statistics. See Collecting database summary diagnostics.
histograms	- enable\|disable	Toggle table histograms. See Collecting table histogram diagnostics.
resourcelatencytracking	- enable\|disable	Toggle resource latency tracking. See Collecting system level diagnostics.
solrcachestats	- enable\|disable	Toggle Solr cache statistics.
solrindexingerrorlog	- enable\|disable	Toggle Solr indexing error log.
solrindexstats	- enable\|disable	Toggle Solr index statistics.
solrlatencysnapshots	- enable\|disable	Toggle Solr latency snapshots.
solrrequesthandlerstats	- enable\|disable	Toggle Solr request handler statistics.
solrslowlog	- enable\|disable	Toggle Solr slow sub-query log. See Collecting slow Solr queries.
solrupdatehandlerstats	- enable\|disable	Toggle Solr update handler statistics.
userlatencytracking	- enable\|disable	Toggle user latency tracking. See Collecting user activity diagnostics.

Using dsetool with Kerberos

To use dsetool with Kerberos, use one of these methods:

Using the ~/.dserc file
Create or edit the ~/.dserc file in your DataStax Enterprise home directory and add the following entries:
```
sasl_protocol=service_name
login_config=path_to_login_config
```
Command line options
Specify the service name and JAAS configuration file on the command line:
```
-Ddse.sasl.protocol=service_name
-Djava.security.auth.login.config=path_to_login_config
```
where:
- - service_name is the service name component of the service_principal that is defined in the dse.yaml file
  - path_to_login_config is the JAAS configuration file with the following options declared in it:
```
DseClient {
            com.sun.security.auth.module.Krb5LoginModule required
            useTicketCache=true
            renewTGT=true;
        };
```