Cassandra nodetool Reference

nodetool is the primary command-line interface for managing and monitoring Apache Cassandra nodes. It communicates with the Cassandra process via JMX (Java Management Extensions) to perform administrative operations.

Overview

Connection

nodetool connects to the local Cassandra node via JMX on port 7199:

# Default connection (localhost:7199)
nodetool status

# With authentication (when JMX authentication is enabled)
nodetool -u admin -pw password status

# With password file (recommended for scripts)
nodetool -u admin -pwf /path/to/jmx_password_file status

Local Execution Recommended

By default, Cassandra binds the JMX port (7199) to localhost only. This is the recommended configuration for security reasons. All nodetool commands should be executed locally on each Cassandra node rather than remotely. This approach:

Eliminates JMX network exposure and associated security risks
Removes the need for complex JMX-over-network authentication setup
Simplifies firewall configurations
Aligns with security best practices for JMX management

For cluster-wide operations, use SSH to execute nodetool commands on each node, or use orchestration tools like Ansible.

Connection Options

Option	Description
`-h, --host`	Target host (default: localhost). Use only when JMX is bound to a non-localhost interface.
`-p, --port`	JMX port (default: 7199)
`-u, --username`	JMX username
`-pw, --password`	JMX password
`-pwf, --password-file`	File containing JMX password
`--ssl`	Use SSL for JMX connection

JMX Security

The default JMX binding to localhost is intentional and should not be changed unless absolutely necessary
If remote JMX access is required, enable JMX authentication and SSL encryption
Never expose unauthenticated JMX ports to untrusted networks
Consider using SSH tunneling instead of exposing JMX ports directly

Version Compatibility

Most nodetool commands are available across all Cassandra 4.x and 5.x versions. The tables below list commands introduced in specific versions.

Commands Added in Cassandra 4.1

Command	Description
datapaths	Display data file locations
getauditlog	Get audit log configuration
getauthcacheconfig	Get auth cache configuration
getcolumnindexsize	Get column index size
getdefaultrf	Get default replication factor
invalidatecredentialscache	Invalidate credentials cache
invalidatejmxpermissionscache	Invalidate JMX permissions cache
invalidatenetworkpermissionscache	Invalidate network permissions cache
invalidaterolescache	Invalidate roles cache
listpendinghints	List pending hints
recompress_sstables	Recompress SSTables
setauthcacheconfig	Set auth cache configuration
setcolumnindexsize	Set column index size
setdefaultrf	Set default replication factor

Commands Added in Cassandra 5.0

Command	Description
checktokenmetadata	Check token metadata for inconsistencies
cidrfilteringstats	Display CIDR filtering statistics
dropcidrgroup	Remove CIDR group
forcecompact	Force user-defined compaction
getcidrgroupsofip	Get CIDR groups for an IP
getguardrailsconfig	Get guardrails configuration
invalidatecidrpermissionscache	Invalidate CIDR permissions cache
listcidrgroups	List all CIDR groups
reloadcidrgroupscache	Reload CIDR groups cache
setguardrailsconfig	Set guardrails configuration
updatecidrgroup	Create or update CIDR group

Command Categories

Cluster Information

Commands for viewing cluster state and metadata.

Command	Description
status	Display cluster status and load information
ring	Display token ring information
info	Display node information
describecluster	Display cluster name, snitch, and partitioner
describering	Display token ranges for a keyspace
gossipinfo	Display gossip information
version	Display Cassandra version
getendpoints	Display endpoints for a key
datapaths	Display data file locations
help	Display help information

Cluster Topology

Commands for managing cluster membership.

Command	Description
decommission	Remove node from cluster gracefully
removenode	Remove a dead node from cluster
assassinate	Force remove an unresponsive node
rebuild	Rebuild data from other datacenters
drain	Drain the node before shutdown
stopdaemon	Stop Cassandra daemon
bootstrap	Resume bootstrap operation
join	Join the ring after bootstrap
move	Move node to new token
failuredetector	Display failure detector information
checktokenmetadata	Check token metadata for inconsistencies

Data Management

Commands for managing data and SSTables.

Command	Description
flush	Flush memtables to SSTables
compact	Force compaction
cleanup	Remove data not belonging to this node
scrub	Rebuild SSTables, fixing corruption
verify	Verify SSTable integrity
upgradesstables	Upgrade SSTables to current version
garbagecollect	Remove deleted data from SSTables
import	Import SSTables from directory
refresh	Load newly placed SSTables

SSTable Management

Commands for advanced SSTable operations.

Command	Description
getsstables	List SSTables for a partition key
relocatesstables	Move SSTables to correct disk
recompress_sstables	Recompress SSTables with new settings
rebuild_index	Rebuild secondary indexes

Repair

Commands for anti-entropy repair operations.

Command	Description
repair	Run anti-entropy repair
repair_admin	Manage repair sessions

Snapshots and Backup

Commands for backup and snapshots.

Command	Description
snapshot	Create a snapshot
clearsnapshot	Remove snapshots
listsnapshots	List existing snapshots
enablebackup	Enable incremental backup
disablebackup	Disable incremental backup
statusbackup	Check incremental backup status

Compaction Management

Commands for controlling compaction.

Command	Description
compactionstats	Display compaction statistics
compactionhistory	Display compaction history
setcompactionthroughput	Set compaction throughput
getcompactionthroughput	Get compaction throughput
getcompactionthreshold	Get compaction thresholds
setcompactionthreshold	Set compaction thresholds
enableautocompaction	Enable automatic compaction
disableautocompaction	Disable automatic compaction
statusautocompaction	Check auto-compaction status
forcecompact	Force user-defined compaction
stop	Stop compaction operations

Streaming and Hinted Handoff

Commands for data streaming and hints.

Command	Description
netstats	Display network statistics and streaming
setstreamthroughput	Set streaming throughput
getstreamthroughput	Get streaming throughput
setinterdcstreamthroughput	Set inter-DC streaming throughput
getinterdcstreamthroughput	Get inter-DC streaming throughput
truncatehints	Truncate all hints
enablehandoff	Enable hinted handoff
disablehandoff	Disable hinted handoff
statushandoff	Check hinted handoff status
pausehandoff	Pause hint delivery
resumehandoff	Resume hint delivery
enablehintsfordc	Enable hints for datacenter
disablehintsfordc	Disable hints for datacenter
listpendinghints	List pending hints
sethintedhandoffthrottlekb	Set hint delivery throttle
getmaxhintwindow	Get maximum hint window
setmaxhintwindow	Set maximum hint window

Gossip and Binary Protocol

Commands for gossip and client protocol management.

Command	Description
enablegossip	Enable gossip
disablegossip	Disable gossip
statusgossip	Check gossip status
enablebinary	Enable CQL native transport
disablebinary	Disable CQL native transport
statusbinary	Check native transport status
enableoldprotocolversions	Enable old protocol versions
disableoldprotocolversions	Disable old protocol versions

Diagnostics and Monitoring

Commands for diagnostics and performance analysis.

Command	Description
tpstats	Display thread pool statistics
proxyhistograms	Display coordinator read/write latencies
tablehistograms	Display table latency histograms
tablestats	Display table statistics
toppartitions	Sample top partitions
gcstats	Display garbage collection statistics
clientstats	Display client connection statistics
profileload	Profile read/write operations
sjk	Swiss Java Knife diagnostic tool
rangekeysample	Sample range keys
viewbuildstatus	Check materialized view build status
refreshsizeestimates	Refresh size estimates
replaybatchlog	Replay pending batches

Configuration

Commands for runtime configuration.

Command	Description
setlogginglevel	Set logging level
getlogginglevels	Get logging levels
reloadssl	Reload SSL certificates
gettimeout	Get operation timeout
settimeout	Set operation timeout
setcachecapacity	Set cache capacity
setcachekeystosave	Set cache keys to save
getconcurrentcompactors	Get concurrent compactors
setconcurrentcompactors	Set concurrent compactors
getconcurrentviewbuilders	Get concurrent view builders
setconcurrentviewbuilders	Set concurrent view builders
getconcurrency	Get thread concurrency
setconcurrency	Set thread concurrency
getdefaultrf	Get default replication factor
setdefaultrf	Set default replication factor
getsnapshotthrottle	Get snapshot throttle
setsnapshotthrottle	Set snapshot throttle
getcolumnindexsize	Get column index size
setcolumnindexsize	Set column index size
getseeds	Get seed nodes
reloadseeds	Reload seed nodes
gettraceprobability	Get trace probability
settraceprobability	Set trace probability
getbatchlogreplaythrottle	Get batch log replay throttle
setbatchlogreplaythrottle	Set batch log replay throttle
reloadtriggers	Reload triggers
reloadlocalschema	Reload local schema
resetlocalschema	Reset local schema
getauthcacheconfig	Get auth cache configuration
setauthcacheconfig	Set auth cache configuration
getguardrailsconfig	Get guardrails configuration
setguardrailsconfig	Set guardrails configuration

Cache Management

Commands for cache invalidation.

Command	Description
invalidatekeycache	Invalidate key cache
invalidaterowcache	Invalidate row cache
invalidatecountercache	Invalidate counter cache
invalidatepermissionscache	Invalidate permissions cache
invalidatecredentialscache	Invalidate credentials cache
invalidaterolescache	Invalidate roles cache
invalidatenetworkpermissionscache	Invalidate network permissions cache
invalidatejmxpermissionscache	Invalidate JMX permissions cache

CIDR Filtering

Commands for IP-based access control.

Command	Description
cidrfilteringstats	Display CIDR filtering statistics
listcidrgroups	List all CIDR groups
getcidrgroupsofip	Get CIDR groups for an IP
updatecidrgroup	Create or update CIDR group
dropcidrgroup	Remove CIDR group
invalidatecidrpermissionscache	Invalidate CIDR permissions cache
reloadcidrgroupscache	Reload CIDR groups cache

Audit Logging

Commands for audit log management.

Command	Description
enableauditlog	Enable audit logging
disableauditlog	Disable audit logging
getauditlog	Get audit log configuration

Full Query Logging

Commands for full query log management.

Command	Description
enablefullquerylog	Enable full query logging
disablefullquerylog	Disable full query logging
getfullquerylog	Get full query log configuration
resetfullquerylog	Reset full query log

Command Usage Patterns

Daily Operations

Task	Command
Check cluster health	`nodetool status`
Monitor compactions	`nodetool compactionstats`
Check thread pools	`nodetool tpstats`
View table metrics	`nodetool tablestats <keyspace>`
Check client connections	`nodetool clientstats`

Maintenance Tasks

Task	Command
Flush before backup	`nodetool flush`
Create snapshot	`nodetool snapshot -t <name>`
Run repair	`nodetool repair -pr`
Clean up after topology change	`nodetool cleanup`
Rebuild secondary indexes	`nodetool rebuild_index <ks> <table> <index>`

Troubleshooting

Task	Command
Check streaming	`nodetool netstats`
View latencies	`nodetool proxyhistograms`
Check gossip state	`nodetool gossipinfo`
Find hot partitions	`nodetool toppartitions <ks> <table> 60000`
Check pending hints	`nodetool listpendinghints`
Verify SSTables	`nodetool verify <keyspace>`

Security Operations

Task	Command
Enable audit logging	`nodetool enableauditlog`
Check CIDR filtering	`nodetool cidrfilteringstats`
Invalidate auth cache	`nodetool invalidatepermissionscache`
Reload SSL certificates	`nodetool reloadssl`

Best Practices

Operational Guidelines

Always check status first - Run nodetool status before any operation
One node at a time - For heavy operations, run on one node at a time
Monitor during operations - Watch tpstats and compactionstats
Schedule during low traffic - Run maintenance during off-peak hours
Document changes - Log all nodetool commands run on production

Production Precautions

Never run assassinate without understanding the consequences
Always drain before stopping Cassandra
Test commands in non-production first
Have rollback plans for topology changes

Runtime vs Persistent Settings

Many set* commands modify settings at runtime only. These changes are lost on node restart. To make settings persistent, also update cassandra.yaml. Commands that modify persistent data (like CIDR groups) are noted in their documentation.